codegraph-mcp

A code knowledge graph you can query from an agent. Index a repository once, then ask structural questions — who calls this, what breaks if I change it, which tests cover it, which service calls this endpoint, what does the architecture look like — through an MCP server or a CLI, instead of grepping and reading whole files.

It parses 27 programming languages plus Vue / Svelte components, Jupyter notebooks, Dockerfiles, docker-compose, Kubernetes, Kustomize, Terraform and Makefiles. Everything lives in one SQLite file under .codegraph/ in the repo you index: no daemon, no service, no network access, and no embeddings unless you opt in.

Version 0.2 merges the feature sets of code-review-graph and codebase-memory-mcp into this codebase; see THIRD_PARTY.md.

Why

Agents burn tokens re-discovering the same facts about a codebase: opening files to find callers, tracing imports by hand, guessing which tests matter. A graph answers those in a few hundred tokens with exact path:line locations, turns a diff into a ranked list of "these symbols have many callers and no tests — look here first", and connects things grep cannot: an HTTP client call to the route that serves it, a Kafka producer to its consumers, a Kubernetes Service to the Deployment it selects.

Related MCP server: code-graph-mcp

Install

uv pip install git+https://github.com/mooyee0929/codegraph-mcp
# optional: vector search with sentence-transformers
uv pip install "codegraph-mcp[embeddings] @ git+https://github.com/mooyee0929/codegraph-mcp"
# or, from a clone
uv pip install -e ".[dev]"

Requires Python 3.11+. Grammars come from tree-sitter-language-pack; nothing is downloaded at run time.

Quick start

codegraph index                  # build or refresh .codegraph/graph.db (incremental)
codegraph architecture           # languages, layers, entry points, routes, communities
codegraph review --base main     # risk-ranked symbols touched by your branch
codegraph install                # register the MCP server with Claude Code

Every command accepts --root <dir> (default: cwd) and --json. Targets can be a full qname (pkg.billing.Invoice.total), a bare name when it is unique (total), a suffix (Invoice.total), or a location (pkg/billing.py:10).

CLI

codegraph <command> --help documents each one. A few examples:

codegraph query callers_of Invoice.total
codegraph trace charge --direction inbound --depth 3
codegraph cypher "MATCH (r:Route)-[:HANDLES]->(f) WHERE r.name STARTS WITH 'POST' RETURN r.name, f.qname"
codegraph find --kind method --min-fan-in 5 --untested
codegraph grep "TODO" --file "src/*"
codegraph semantic "retry failed payment"
codegraph routes --method GET
codegraph hotspots
codegraph visualize && open .codegraph/graph.html

MCP server

codegraph-mcp --root /path/to/repo                 # stdio transport
codegraph-mcp --root . --watch --auto-index        # keep the graph fresh while serving
codegraph-mcp --root . --tools get_node,trace_path,search_graph   # expose only these

codegraph install registers the server with Claude Code (through claude mcp add when the CLI is present, otherwise by merging .mcp.json); --hooks also adds a project-level PostToolUse hook that re-indexes after edits, --dry-run shows the plan, and codegraph uninstall removes exactly what was added. Manual setup:

{
  "mcpServers": {
    "codegraph": { "command": "codegraph-mcp", "args": ["--root", ".", "--auto-index"] }
  }
}

Tools

62 tools. With many clients each tool schema costs context, so --tools / CODEGRAPH_TOOLS lets you expose a subset.

Prompts

review_changes, pre_merge_check, debug_issue, architecture_map and onboard_developer walk the agent through the right tools in order. A typical review: detect_changes_tool → get_change_impact → get_review_context on the riskiest symbols → get_impact_radius on anything with high fan-in.

How it works

source files ──parse──▶ nodes + edges ──store──▶ SQLite (+FTS5)
                 │                                   │
   python: ast   │                          link ◀───┤ unique-name resolution,
   js/ts + 25 more: tree-sitter                      │ test-coverage inference
   infra: yaml / hcl / dockerfile parsers            │
                                            passes ◀─┘ routes, channels, clones,
                                                       history, communities, flows,
                                                       search index, related edges

Nodes are modules, classes (any named type: struct, interface, trait, enum), functions, methods, routes (route:GET /users/{id}), channels (channel:orders) and infrastructure resources (resource:k8s/Deployment/web). Code qnames come from the file path (pkg/billing.py → pkg.billing).

Edges are defines, imports, calls, inherits and tests from parsing, plus derived ones: handles (route → handler), http_calls (client → route), emits / listens_on (function → channel), similar_to (near-clones), semantically_related, co_changes (files committed together) and depends_on (infrastructure). Heuristic edges carry a confidence and a short detail.

Resolution. Parsers resolve what the file's own imports tell them; go.mod, Cargo.toml and package.json workspaces map package names to repo paths. Anything else is stored as a bare name and linked only when exactly one definition has that name. Ambiguous names stay unresolved rather than guessed, and the CLI marks them.

Passes run after linking, in order, whenever the index changed:

Skip any with codegraph index --skip-pass NAME.

Risk in review is a small additive score: many callers, no covering tests, high fan-out, large hunks. change-impact adds the flows and communities a diff touches. Both are meant to order your attention, not to judge the change.

Incremental indexing hashes file contents; unchanged files are skipped, deleted files are removed, and linking and passes re-run only when something changed. The database is a cache: when its schema version changes it is rebuilt from source.

Configuration

Team snapshot. codegraph snapshot export writes .codegraph/graph.db.gz and marks it binary merge=ours in .gitattributes. Commit it, and teammates' --auto-index restores it and only re-parses their local changes.

ADRs and notes. codegraph adr keeps architecture decision records as markdown in docs/adr/ (or the directory named in .adr-dir); codegraph note stores question and answer pairs in .codegraph/notes/ so later sessions can search them.

Limits

• No type inference. self.client.send() and obj.method() resolve only when the method name is unique across the repo and not a common library name (get, run, send, execute, ...). Until then they show as *.send and are flagged unresolved.

• Dynamic dispatch, decorators that rewrite functions, getattr, runtime-built routes and re-exports are invisible. Route and channel detection is pattern-based.

• JS default imports bind to the module qname, so def.run() becomes <module>.run.

• Communities come from single-resolution Louvain, so one can be internally disconnected; bridge scores above 400 nodes are estimated from a sample.

• The Cypher subset has no write clauses, UNWIND, UNION, CASE or parameters.

• Passes re-run only when indexed files change; after editing only .proto files or pulling new history, run codegraph index --force.

• One repository per database; qnames are rooted at the index root. The registry and cross_repo_* tools join several.

Development

uv venv && uv pip install -e ".[dev]"
uv run pytest -q
uv run ruff check . && uv run ruff format --check . && uv run mypy codegraph

Feature code plugs in without touching the core: a module in codegraph/passes/ that defines PASS, in codegraph/tools/ that defines register(server, ctx), or in codegraph/commands/ that defines register(add) is discovered automatically.

License

MIT. Ideas and designs ported from the two upstream projects are credited in THIRD_PARTY.md.