Code GraphRAG MCP Server

A Model Context Protocol server for source-code introspection. It keeps a local-first knowledge graph for your repositories: Tree-sitter derived symbols and relations, AST-aligned chunks, EmbeddingGemma vectors stored in sqlite-vec, and graph traversal through bfsvtab. Wheels ship the native extensions, so the server starts instantly with uvx.

Features

• Hybrid retrieval combining vector search and breadth-first graph expansion over code relations
• Live repository sync via filesystem watcher and job queue
• Deterministic provenance for every symbol, relation, and chunk
• Bundled sqlite-vec and bfsvtab binaries—no manual compilation required

Installation

uvx code-graph-rag-mcp serve --config /workspace/config.yaml

MCP manifest example

{
  "mcpServers": {
    "code-graph": {
      "command": "uvx",
      "args": ["code-graph-rag-mcp", "serve", "--config", "/workspace/config.yaml"],
      "env": {
        "CODE_GRAPH_RAG_WATCH_DIR": "/workspace/repo",
        "CODE_GRAPH_RAG_DB_PATH": "/workspace/data/code.sqlite"
      }
    }
  }
}

This manifest block works for Claude Desktop (claude_desktop_config.json), Cursor (~/.cursor/mcp.json), or any other MCP host.

Configuration

Minimal config.yaml

watch:
  dir: "/workspace/repo"
database:
  sqlite_path: "/workspace/data/code.sqlite"

Environment overrides

Available tools

Architecture overview

1. Watcher → queue – watchfiles monitors the repo and enqueues jobs on create/modify/delete.
2. Indexer – Tree-sitter adapters extract symbols/relations; the chunker builds AST-aligned snippets; EmbeddingGemma generates embeddings.
3. SQLite – files, nodes, edges, chunks, and vectors live in sqlite-vec tables; bfsvtab enables efficient BFS traversal.
4. MCP surface – tools expose ingest, search, and introspection over stdio to any MCP client.

Example workflow

1. Start the server with uvx and point it at your repository.
2. Call ingest_repo to seed the database.
3. Use hybrid_search to find relevant code; responses include semantic scores plus graph neighbors.
4. Inspect specific nodes with explain_symbol or symbol_lookup.
5. Work normally—the watcher reindexes files as they change.

Development

python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
pytest

Rebuild the bundled sqlite-vec/bfsvtab binaries (only if needed) with:

python scripts/build_sqlite_extensions.py

Support

• File issues or feature requests in this repository.
• Learn more about MCP at modelcontextprotocol.io.
• License: MIT.