AI Tools & ArborQL
Relevant source files
The following files were used as context for generating this wiki page:
AI Tools and ArborQL constitute the intelligence bridge within the Arbor ecosystem, enabling Large Language Models (LLMs) to interact directly with a codebase's semantic dependency graph. By implementing the Model Context Protocol (MCP), Arbor allows AI agents to move beyond simple keyword searches to perform structured graph traversals, impact analysis, and pathfinding.
Sources: README.md:144-149, crates/arbor-mcp/README.md:18-20, PR_DESCRIPTION.md:14-16
Architecture & Communication Flow
The system operates as an MCP server, typically running over stdio. It connects an LLM (such as Claude or Cursor) to the ArborGraph stored in memory or on disk via sled. A unique feature of this architecture is the "Spotlight" capability, which allows the AI to synchronize the visual state of the Arbor GUI with its current analysis focus.
The diagram shows the communication flow between the AI agent, the MCP server, and the visualizer components.
Sources: crates/arbor-mcp/src/lib.rs:43-52, crates/arbor-cli/src/commands.rs:374-386, PR_DESCRIPTION.md:18-20
ArborQL Toolset
ArborQL provides several high-level tools designed for AI context retrieval. These tools allow the AI to "walk" the call graph and understand the structural consequences of code changes.
Available AI Tools
| Tool Name | Purpose | Key Parameters |
|---|---|---|
get_logic_path | Traces call graph to find dependencies and usage | start_node (String) |
analyze_impact | Predicts "blast radius" of changing a node | node_id (String), max_depth (Int) |
find_path | Finds the shortest logic path between two symbols | start_node, end_node (String) |
Sources: crates/arbor-mcp/src/lib.rs:142-178, CHANGELOG.md:18-25
Pathfinding Logic (find_path)
ArborQL implements pathfinding using the A* algorithm to trace logic flows between disparate parts of the codebase. This allows an AI to explain how a high-level API entry point eventually reaches a low-level database or utility function.
Sources: PR_DESCRIPTION.md:19, crates/arbor-mcp/src/lib.rs:275-285
Impact Analysis (analyze_impact)
This tool provides a structured JSON response containing the "blast radius" of a modification. It classifies affected nodes by severity:
- Direct Impact: 1 hop (immediate callers/dependencies).
- Transitive Impact: 2-3 hops.
- Distant Impact: 4+ hops.
Sources: CHANGELOG.md:8-13, crates/arbor-mcp/src/lib.rs:218-250
The Spotlight System
The Spotlight system bridges the gap between AI thought processes and developer visibility. When an AI tool like get_logic_path or analyze_impact is called, the MCP server can trigger a spotlight event.
This sequence illustrates how an AI request automatically updates the developer's visual context.
Sources: crates/arbor-mcp/src/lib.rs:56-71, crates/arbor-cli/src/commands.rs:388-390
Data Models & Serialization
The MCP server handles communication using standard JSON-RPC 2.0. Internal data structures for AI context retrieval include AnalysisResult and ConfidenceExplanation.
Confidence Scoring
ArborQL provides an explainable confidence level for its graph-based answers:
- High: Fully resolved, statically verifiable paths.
- Medium: Potential uncertainty due to polymorphism or partial indices.
- Low: Heuristic or dynamic resolution (e.g., Python dynamic dispatch).
Sources: README.md:154-162, crates/arbor-mcp/src/lib.rs:222-225
Architectural Brief
The get_logic_path tool generates a formatted "Architectural Brief" in Markdown, summarizing:
- Node Properties: Type, File, Signature.
- Impact Level: Calculated via centrality scoring.
- Dependencies (Callees): Symbols the target relies on.
- Usage (Callers): Symbols that rely on the target.
Sources: crates/arbor-mcp/src/lib.rs:350-385
Summary
AI Tools and ArborQL transform Arbor from a static analysis tool into an interactive intelligence layer. By leveraging the Model Context Protocol and graph-native algorithms like A* and BFS, it provides AI agents with deterministic, structural certainty that keyword-based RAG systems cannot match. The integration with the Spotlight system ensures that AI-driven insights are immediately visible to the human developer in the Logic Forest visualizer.
Sources: README.md:126-135, crates/arbor-graph/README.md:10-14