code-graph-mcp

A high-performance code knowledge graph server implementing the Model Context Protocol (MCP). Indexes codebases into a structured AST knowledge graph with semantic search, call graph traversal, and HTTP route tracing — designed to give AI coding assistants deep, structured understanding of your code.

Features

• Multi-language parsing — Tree-sitter AST extraction across tiers of depth:
  • Full (calls + imports + inheritance): TypeScript/TSX, JavaScript, Go, Python, Rust, Java. HTTP route extraction additionally covers TypeScript/TSX + JavaScript (Express/Connect), Go (net/http), Python (Flask/FastAPI), and Rust axum (.route() chains with inline .nest() prefixes; named handlers only) — actix/rocket and Java Spring are not yet route-extracted
  • Smoke-tested (calls + imports + inheritance): C#, Kotlin, Ruby, PHP, Swift, Dart
  • Limited (functions + calls + #include imports + gtest test markers + C++ base-class inheritance + Class::method scope qualification): C, C++
  • Scripting: Bash (functions + commands + source/. imports), Markdown (headings)
  • File-FTS only (no AST symbol extraction): HTML, CSS, JSON
  • Test markers — detected from the AST for Rust (#[test] / #[cfg(test)]), JavaScript/TypeScript/TSX (describe/it/test blocks and their callbacks) and C/C++ (gtest TEST macros). Go, Python, Java and the rest fall back to path/name heuristics (tests/, src/test/java/, *_test.*, *.test.js, test_*, *Test)
  • Value/type references — a references relation for symbols that are used without being called, imported or inherited (path-qualified constants, type-position uses, functions passed as values): Rust, TypeScript/TSX, JavaScript, Python, Go, Java, C, C++
• Semantic code search — Hybrid BM25 full-text + vector semantic search with Reciprocal Rank Fusion (RRF), powered by sqlite-vec
• Call graph traversal — Recursive CTE queries to trace callers/callees with cycle detection
• HTTP route tracing — Map route paths to backend handler functions (Express, Flask/FastAPI, Go net/http, Rust axum)
• Dead code detection — Find unreferenced symbols with smart Orphan/Exported-Unused classification
• Impact analysis — Determine the blast radius of code changes by tracing all dependents
• Incremental indexing — Merkle tree change detection with file system watcher for real-time updates. Smart event filtering skips metadata-only changes (chmod, xattr)
• Context compression — Token-aware snippet extraction for LLM context windows (L0→full code, L1→summaries, L2→file groups, L3→directory overview). Every MCP tool except ast_search takes compact: true, which drops code bodies from the response; what else it trims is per-tool (get_ast_node keeps the signature, module_overview drops it), and how much it saves depends on the tool and the repo, so no fixed figure is quoted here
• Embedding model — Optional local embedding via Candle (feature-gated embed-model). Context reordered to prioritize structural relations over code for better embedding quality
• Self-healing — Automatic SQLite corruption recovery with rebuild. Startup repair for incomplete indexing (Phase 3 failures)
• MCP protocol — JSON-RPC 2.0 over stdio, plug-and-play with Claude Code, Cursor, Windsurf, and other MCP clients
• Claude Code Plugin — First-class plugin with skills (explore, index), a code-explorer agent, auto-indexing hooks, StatusLine integration, and self-updating

Why code-graph-mcp?

Unlike naive full-text search or simple AST dumps, code-graph-mcp builds a structured knowledge graph that understands the relationships between symbols across your entire codebase.

Incremental by Design

BLAKE3 Merkle tree tracks every file's content hash. On re-index, only changed files are re-parsed — unchanged directory subtrees are skipped entirely via mtime cache. When a function signature changes, dirty propagation automatically regenerates context for all downstream callers across files.

Hybrid Search, Not Just Grep

Combines BM25 full-text ranking (FTS5) with vector semantic similarity (sqlite-vec) via Reciprocal Rank Fusion (RRF) with raw score blending — so searching "handle user login" finds the right function even if it's named authenticate_session. Results are auto-compressed to fit LLM context windows.

Scope-Aware Relation Extraction

The parser doesn't just find function calls — it tracks them within their proper scope context. Extracts calls, imports, inheritance, interface implementations, exports (ESM export and CommonJS module.exports = { … } / exports.name = …), value/type references, and HTTP route bindings. Same-file targets are preferred over cross-file matches to minimize false-positive edges.

HTTP Request Flow Tracing

Unique to code-graph-mcp: trace from GET /api/users → route handler → service layer → database call in a single query. Supports Express/Connect, Flask/FastAPI, Go net/http, and Rust axum.

Zero External Dependencies at Runtime

Single binary, embedded SQLite, bundled sqlite-vec extension, optional local embedding model via Candle — no database server, no cloud API, no Docker required. Runs entirely on your machine.

Built for AI Assistants

Every design decision — from token-aware compression to node_id-based snippet expansion — is optimized for LLM context windows. Works out of the box with Claude Code, Cursor, Windsurf, and any MCP-compatible client.

Performance

Every row below is a line code-graph-mcp benchmark prints, measured on this repository (283 files, 5,311 nodes, 11,215 edges) with a release build — median of three consecutive runs on an otherwise idle machine. Run the same command on your own project: the numbers that matter are yours, and these scale with tree size and machine.

benchmark line	This repo, v0.129.0
F