Model Context Protocol (MCP)
Relevant source files
The following files were used as context for generating this wiki page:
The Model Context Protocol (MCP) implementation in Arbor serves as the AI Bridge, allowing Large Language Models (LLMs) like Claude to navigate and understand a codebase as a semantic graph rather than unstructured text. By exposing the underlying code property graph through standardized tools, the MCP server enables AI agents to perform structural analysis, trace execution paths, and predict the impact of changes with deterministic certainty.
Sources: crates/arbor-mcp/README.md:14-18, README.md:143-145
Architecture and Core Components
The MCP system is built as a specialized server layer that interacts with the arbor-graph and arbor-server crates. It operates primarily over stdio for integration with desktop AI clients but can also be launched alongside a visualizer stack.
McpServer Structure
The core logic resides in the McpServer struct, which holds a reference to the shared graph and an optional handle for the "Spotlight" feature.
Communication Flow
The server implements the JSON-RPC 2.0 protocol over standard input/output. When a request is received, it is dispatched to specific tool handlers that query the ArborGraph.
Sources: crates/arbor-mcp/src/lib.rs:63-120
MCP Tools and Capabilities
Arbor exposes several high-level tools to AI agents for deep codebase inspection. These tools go beyond simple keyword matching by traversing the graph's edges (calls, imports, and inheritance).
| Tool Name | Description | Parameters |
|---|---|---|
get_logic_path | Traces the call graph to find dependencies and usage. Returns an "Architectural Brief". | start_node: Name/ID of function or class. |
analyze_impact | Analyzes the blast radius of changing a node, providing upstream and downstream effects. | node_id: String, max_depth: Integer (default 5). |
find_path | Calculates the shortest path between two specific nodes using A* algorithm. | start_node: String, end_node: String. |
get_context | (Legacy/README reference) Retrieves semantic neighborhood of a node. | node: String. |
Sources: crates/arbor-mcp/src/lib.rs:163-205, crates/arbor-mcp/README.md:20-25, CHANGELOG.md:19-21
Tool Execution Logic
When a tool like analyze_impact is called, the server performs the following steps:
- Node Resolution: Converts the provided name or ID into a graph index.
- Graph Traversal: Calls
graph.analyze_impactto compute affected nodes. - Metadata Calculation: Derives confidence levels and architectural roles (e.g., Entry Point, Core Logic).
- Spotlight Sync: If a visualizer is connected, it centers the view on the analyzed node.
Sources: crates/arbor-mcp/src/lib.rs:240-285, crates/arbor-cli/src/commands.rs:434-445
Spotlight Integration
A unique feature of Arbor's MCP implementation is the "Spotlight" capability. This allows the AI agent to provide visual feedback to the user by highlighting nodes in the Arbor GUI while the agent performs its analysis.
Implementation Details
Response Formatting
The server generates rich text content for the AI, often including Markdown tables for structured data like dependencies and usage. This is facilitated by the generate_context function.
// Example of the "Architectural Brief" generation
let mut brief = String::new();
brief.push_str(&format!("# Architectural Brief: `{}`\n\n", node.name));
brief.push_str("| Property | Value |\n|----------|-------|\n");
brief.push_str(&format!("| **Type** | {} |\n", node.kind));
// ... includes tables for Callees and Callers
Sources: crates/arbor-mcp/src/lib.rs:380-420
Error Handling
The server utilizes a structured JsonRpcError format to communicate failures to the AI client, such as method non-existence (-32601) or invalid parameters (-32602).
Sources: crates/arbor-mcp/src/lib.rs:27-31, crates/arbor-mcp/src/lib.rs:145-149
Integration and Usage
The MCP server is typically invoked via the Arbor CLI using the bridge command. This command initializes the graph, starts the MCP listener on stdio, and optionally launches the Flutter-based visualizer.
arbor bridge --viz
Configuration for AI Clients
To use Arbor with Claude Desktop, the following configuration is used in the claude_desktop_config.json:
{
"mcpServers": {
"arbor": {
"command": "arbor",
"args": ["bridge"]
}
}
}
Sources: crates/arbor-mcp/README.md:38-48, crates/arbor-cli/src/commands.rs:336-345
Summary
The MCP implementation is the primary vehicle for "Graph-Native Intelligence" in Arbor. By exposing structural certainty to AI agents through the arbor-mcp crate, it allows for deterministic code analysis that surpasses traditional text-based RAG systems. It bridges the gap between raw AST data and actionable AI insights while providing visual synchronization through the Spotlight system.