code-graph-rag-mcp 0.1.2

Local-first code knowledge graph MCP server

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

Variable	Description
CODE_GRAPH_RAG_CONFIG	Alternate path to the YAML config.
CODE_GRAPH_RAG_WATCH_DIR	Override repository directory to watch.
CODE_GRAPH_RAG_WATCH_DEBOUNCE_MS	Debounce delay (ms) for watcher events.
CODE_GRAPH_RAG_DB_PATH	Override SQLite database location.
CODE_GRAPH_RAG_EXTENSIONS_DIR	Directory containing custom sqlite-vec/bfsvtab binaries.
CODE_GRAPH_RAG_SQLITE_VEC / CODE_GRAPH_RAG_BFSVTAB	Explicit extension paths.
CODE_GRAPH_RAG_RETRIEVAL_K	Default semantic top-k.
CODE_GRAPH_RAG_RETRIEVAL_HOPS	Graph expansion hop count.
CODE_GRAPH_RAG_EMBED_MODEL / CODE_GRAPH_RAG_EMBED_ENDPOINT	Embedding model overrides.

Available tools

Tool	Purpose
ingest_repo	Full ingest or reingest of the repository.
refresh_path	Reindex a single file.
purge_path	Remove a file and its graph artifacts.
hybrid_search	Semantic + graph search returning chunks with BFS neighbors.
symbol_lookup	Fuzzy lookup of symbols by name.
explain_symbol	Show metadata, owning chunk, and outgoing edges for a node ID.
status	Report ingest counts and extension readiness.

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.