Model Context Protocol (MCP) Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Model Context Protocol (MCP) integration within code-review-graph serves as the primary bridge between a local-first structural knowledge graph and various AI coding assistants. This integration allows tools like Claude Code, Cursor, and Windsurf to perform token-efficient codebase exploration and risk-aware code reviews by querying a specialized SQLite-backed graph store instead of performing broad file scans.
The system is implemented as a FastMCP server that exposes 30 specialized tools and 5 complex prompt templates. It facilitates a "minimal context" workflow designed to minimize token usage (targeting ≤800 total tokens of graph context) while providing high-fidelity structural data such as call chains, impact radius, and execution flow criticality.
Sources: CLAUDE.md:1-25, code_review_graph/main.py:64-71
Architecture and Core Components
The MCP integration is built on the FastMCP framework, which manages the registration of tools and prompts and handles the communication transport.
Server Implementation
The server entry point in code_review_graph/main.py initializes the FastMCP instance and configures the transport layer. It supports both standard stdio communication and a localhost-bound streamable-http transport.
The server utilizes asyncio.to_thread for long-running operations like full graph builds or community detection to ensure the stdio event loop remains responsive.
Sources: code_review_graph/main.py:100-140, code_review_graph/main.py:760-800
Multi-Platform Support
The system provides automated configuration for a wide range of MCP-compatible platforms. The skills.py module contains logic to detect and write configuration files for specific editors and agents.
| Platform | Configuration File | Registry Key |
|---|---|---|
| Claude Code | .mcp.json | mcpServers |
| Cursor | .cursor/mcp.json | mcpServers |
| Windsurf | ~/.codeium/windsurf/mcp_config.json | mcpServers |
| Zed | settings.json | context_servers |
| Continue | ~/.continue/config.json | mcpServers |
| OpenCode | .opencode.json | mcpServers |
| Gemini CLI | .gemini/settings.json | mcpServers |
Sources: code_review_graph/skills.py:34-118
Tool Ecosystem
The MCP server exposes 30 tools divided into functional domains. All tools follow a strict token-efficiency pattern, favoring a detail_level="minimal" parameter.
Core Exploration Tools
These tools allow the AI to traverse the graph and understand relationships.
query_graph_tool: Traces relationships likecallers_of,callees_of,imports_of, andtests_for.get_impact_radius_tool: Calculates the transitive blast radius of a change set.semantic_search_nodes_tool: Performs hybrid search using FTS5 and vector embeddings.get_minimal_context_tool: The mandatory entry point that provides a ~100-token summary of the task context.
Sources: code_review_graph/main.py:195-230, CLAUDE.md:215-235, code_review_graph/tools/docs.py:12-40
Specialized Analysis Tools
Advanced tools provide architectural insights and risk scoring.
detect_changes_tool: Maps git diffs to risk-scored functions and test gaps.get_affected_flows_tool: Identifies critical execution paths impacted by specific file changes.get_architecture_overview_tool: Provides community-level coupling analysis and warnings.refactor_tool: Facilitates rename previews and dead code detection.
Sources: code_review_graph/main.py:488-530, code_review_graph/main.py:590-620
Workflow and Prompt Templates
The integration includes pre-defined prompt templates that guide the AI through efficient multi-step workflows.
Workflow Sequence
The standard MCP workflow is designed to prevent excessive tool calls.
Implementation of Prompts
The prompts.py module defines 5 standard workflows. Each prompt includes a _TOKEN_EFFICIENCY_PREAMBLE that instructs the AI to target ≤5 tool calls per task.
| Prompt Name | Purpose | Key Tools Used |
|---|---|---|
review_changes | Pre-commit review | detect_changes, get_affected_flows |
architecture_map | Documentation | get_architecture_overview, list_flows |
debug_issue | Root cause analysis | semantic_search_nodes, get_flow |
onboard_developer | Project orientation | list_graph_stats, list_communities |
pre_merge_check | PR readiness | detect_changes, refactor (dead_code) |
Sources: code_review_graph/prompts.py:46-150
Configuration and Installation
The integration is configured via the code-review-graph install command, which manages both MCP server registration and instruction injection.
Instruction Injection
To ensure the AI prioritizes MCP tools over standard file system tools (like Grep or Read), the system injects instructions into platform-specific files such as CLAUDE.md, AGENTS.md, and .cursorrules. These instructions explicitly state: "ALWAYS use the code-review-graph MCP tools BEFORE using Grep/Glob/Read".
Sources: code_review_graph/skills.py:454-520, CLAUDE.md:215-220
Server Launch Logic
The server launch command is dynamically detected based on the environment (Poetry, uv, or standard Python).
# code_review_graph/skills.py:168-171
if _in_poetry_project():
poetry = shutil.which("poetry")
if poetry:
return ("poetry", ["run", "code-review-graph", "serve"])
Sources: code_review_graph/skills.py:155-195
Conclusion
The MCP integration is the core delivery mechanism for code-review-graph. By providing a structured, high-performance interface to the code graph, it transforms AI assistants from simple file readers into context-aware architects capable of understanding complex dependencies and risks with minimal token overhead.