How MCP Integration Works with AI Coding Assistants in code-review-graph

The MCP integration in code-review-graph works by exposing a local MCP server that provides 30+ tools for querying code knowledge graphs, automatically configuring platform-specific JSON files to connect AI assistants including Claude Code, Cursor, and GitHub Copilot via stdio or HTTP transports.

The code-review-graph project bridges static code analysis and AI-assisted development through a Model Context Protocol (MCP) implementation. This architecture allows diverse AI coding assistants to interact with repository knowledge graphs using standardized tool definitions, eliminating the need for platform-specific plugins while maintaining portable configuration across different environments.

Platform-Specific MCP Configuration

The integration begins with automatic detection of installed AI assistants and generation of appropriate configuration files. This process ensures each assistant receives the correct connection parameters without manual setup.

Detecting AI Assistants and Generating Configs

In code_review_graph/skills.py, the install_platform_configs() function discovers which AI assistants are present in a repository by evaluating the global PLATFORMS dictionary. Each platform entry contains a detect callback that identifies specific marker files or directories:

• Claude Code: .claude/settings.json
• Cursor: .cursor/ directory
• VS Code: .vscode/ directory
• Kiro: .kiro/ directory

When the user runs code-review-graph install, the function builds a platforms_to_install map containing only the detected assistants. For repositories with multiple AI tools, the system generates separate configuration files appropriate to each platform's expected location (such as .mcp.json for Claude Code or .cursor/mcp.json for Cursor).

Handling Shared Configuration Contracts

The platform detection logic includes deduplication for assistants that share identical MCP contracts. Claude Code and CodeBuddy use the same configuration format, so the system creates a shared alias to avoid redundant server definitions:

# code_review_graph/skills.py

if claude and codebuddy:
    same_contract = (
        claude["config_path"](repo_root) == codebuddy["config_path"](repo_root)
        and all(
            claude[field] == codebuddy[field]
            for field in ("key", "format", "needs_type")
        )
    )
    if same_contract:
        shared_aliases["claude"] = ("codebuddy",)
        del platforms_to_install["codebuddy"]

The generated configuration files always contain a servers array pointing to the portable command uvx code-review-graph serve, ensuring the setup works across different machines without absolute path dependencies.

MCP Tools Architecture

The MCP server exposes knowledge graph functionality through decorated Python functions that handle repository context resolution and error management automatically.

Tool Registration and Decorators

All public functions available to AI assistants reside in code_review_graph/main.py and use the @mcp.tool() decorator. This wrapper provides:

• Automatic repo-root resolution via _resolve_repo_root()
• Standardized error handling and provenance tagging
• Async compatibility for long-running operations like embedding generation

The precedence order for repository resolution follows: client argument > --repo flag > current working directory, ensuring consistent context across all tool invocations.

Core Knowledge Graph Tools

The server exposes over 30 tools for graph interaction. Key implementations include:

• list_graph_stats_tool – Returns aggregate statistics (nodes, edges, languages) for health monitoring
• get_impact_radius_tool – Performs weighted BFS from changed nodes to calculate impact scope
• semantic_search_nodes_tool – Executes vector-based semantic search over node embeddings
• detect_changes_tool – Identifies VCS changes and translates them into file lists for downstream analysis

Each tool follows a consistent signature pattern:

@mcp.tool()
def list_graph_stats_tool(repo_root: Optional[str] = None) -> dict:
    """Get aggregate statistics about the code knowledge graph."""
    root = _resolve_repo_root(repo_root)
    return with_provenance(list_graph_stats(repo_root=root), root)

Repository Context Resolution

The _resolve_repo_root() function ensures every tool executes within the correct repository context. This prevents AI assistants from accidentally querying the wrong codebase when working across multiple projects or monorepo structures.

Integration Lifecycle for AI Assistants

The connection between AI assistants and the knowledge graph follows a standardized lifecycle from installation to tool consumption.

Installation and Configuration

Users initialize the integration by running:

code-review-graph install --target=all

This command invokes install_platform_configs() to create the appropriate .mcp.json files for each detected assistant. The configuration instructs the assistant to launch the CRG server automatically when opening the project.

Server Initialization

When an AI assistant opens a configured repository, it reads the local .mcp.json and spawns the server process. The server supports two transport modes:

1. stdio – For CLI-based assistants like Claude Code
2. HTTP – For GUI-based editors at the /mcp/ endpoint

The server runs via uvx code-review-graph serve, providing a sandboxed environment that manages dependencies independently of the host project's Python environment.

Tool Invocation Flow

AI assistants communicate with the server using JSON-RPC requests. For example, to retrieve graph statistics:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "list_graph_stats_tool",
  "params": {}
}

The server executes the corresponding Python function, wraps results with provenance metadata (including the resolved repo root), and returns compact JSON payloads. Because tools support async operations, heavy computations like semantic_search_nodes_tool run in thread pools without blocking the assistant's UI—critical for preventing hangs on Windows MCP clients.

Assistants consume these results for review context generation, impact analysis, or semantic code search, displaying data directly in chat interfaces or using it for internal reasoning chains.

Extending Support for New AI Assistants

Adding compatibility for additional AI coding assistants requires minimal changes to code_review_graph/skills.py:

1. Add an entry to the PLATFORMS dictionary with:

   • A detect function identifying the assistant's presence
   • A config_path lambda returning the platform's configuration location
   • MCP contract fields: key, format, and needs_type

2. Optionally define shared aliases if the new assistant reuses an existing contract (similar to the Claude/CodeBuddy relationship).

3. Update install_platform_configs() logic if special handling is required for the new platform's initialization sequence.

The MCP server, tool decorators, and graph-building pipeline remain unchanged when adding new assistants, maintaining a clean separation between transport configuration and business logic.

Summary

• code-review-graph exposes a local MCP server providing 30+ tools for knowledge graph interaction via code_review_graph/main.py.
• Platform detection in code_review_graph/skills.py automatically generates .mcp.json configurations for Claude Code, Cursor, GitHub Copilot, and other supported assistants.
• Shared aliases prevent duplicate configurations when multiple assistants (like Claude Code and CodeBuddy) use identical MCP contracts.
• Async-compatible tools ensure responsive AI assistant interfaces even during computationally expensive graph operations.
• Transport flexibility supports both stdio (for CLI tools) and HTTP (for GUI editors) without modifying core graph logic.

Frequently Asked Questions

What AI coding assistants are currently supported by code-review-graph?

The repository supports Claude Code, CodeBuddy, Cursor, Qoder, GitHub Copilot, and Kiro through the PLATFORMS dictionary in code_review_graph/skills.py. Each assistant is detected via filesystem markers like .claude/settings.json or .cursor/ directories, and the system can be extended to support additional tools by adding new platform definitions.

How does the MCP server handle multiple AI assistants in the same repository?

When multiple assistants are detected, install_platform_configs() creates separate configuration files for each platform (such as .mcp.json for Claude and .vscode/mcp.json for VS Code), all pointing to the same server command. If assistants share identical MCP contracts (like Claude Code and CodeBuddy), the system creates shared aliases to avoid redundant server definitions while reporting both platforms as configured.

Can I query the MCP server manually without an AI assistant?

Yes. You can start the server with code-review-graph serve and send JSON-RPC requests via HTTP or stdio. For example, using curl to query impact analysis:

curl -X POST http://localhost:8000/mcp/ \
    -d '{"jsonrpc":"2.0","id":1,"method":"get_impact_radius_tool","params":{"changed_files":["src/main.py"]}}'

Or via Python subprocess for stdio mode, mimicking how assistants communicate with the server.

What makes the MCP integration portable across different development environments?

The generated configuration files use the command uvx code-review-graph serve rather than absolute Python paths. This allows the MCP server to run in any environment where uvx is available, regardless of the user's Python installation location or virtual environment structure, making the configuration files safe to commit to version control.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}