codegraph MCP server

Start in the terminal

export PYTHONPATH=/path/to/codegraph
python -m codegraph.cli --repo <repo> index
python -m codegraph.cli --repo <repo> ontology
python -m codegraph.cli --repo <repo> advise
python -m codegraph.cli --repo <repo> view --serve

Then look at it

Nine views over the same graph, each on its own number key. Double-click any node to open that file in your editor at the right line. ~ opens a console with the same commands as the CLI.

What it builds

1. Parse — tree-sitter over .py .js .jsx .mjs .cjs .ts .tsx .go .rs. Patterns compile one at a time, so a grammar that rejects a pattern loses that pattern, not the whole run.
2. Graph — files and symbols as nodes; defines, imports, calls as edges. Imports resolve through relative paths, package roots, index files and tsconfig paths aliases. Unresolvable bare specifiers count as external packages, not as failures.
3. Ontology — typed entities (Repository, Module, File, Symbol, Role) and typed relations (CONTAINS, DEFINES, IMPORTS, CALLS, DEPENDS_ON, PLAYS, TESTS, ENTRY_OF) with provenance.
4. Analysis — PageRank on the reversed graph, Louvain communities, cycles, churn risk, dependency depth.
5. Answers — token-budgeted context packs, impact analysis, and a ranked next move.

On a 422-file TypeScript repo: 3030 symbols, 3916 call edges, 3588 ontology entities, 9063 relations, indexed in seconds.

Roles are inferred, not configured

Every module gets an architectural role from three kinds of evidence — path vocabulary, dependency direction, and test markers — each with a confidence score and the reasons behind it. A module nothing imports that imports plenty is an entry point. A module with no outgoing edges that many depend on is support. Unclassifiable modules become component with confidence 0 rather than being forced into a wrong bucket.

Override the vocabulary per repo in codegraph.rules.json under roles.

Commands

Command	Answers
index	build the graph, write CODEGRAPH.json
ontology	what kind of system is this, what plays what role
advise	what should I do next, ranked payoff over effort
map --budget N	ranked structural overview that fits a prompt
symbol <name>	definition, callers, callees, file siblings
def <name> / refs <name>	where defined / everywhere referenced
impact <target>	blast radius before touching anything
flow	role-to-role flow plus a mermaid chart
rules --init / rules --strict	declare and enforce an architecture contract
view --serve	live viewer in the browser
tui	terminal UI
serve	MCP server over stdio

Viewer

view --serve runs a loopback server with nine views, each on its own number key:

1 folders · 2 tree · 3 flow · 4 imports · 5 calls · 6 layers · 7 treemap · 8 matrix · 9 radial

Double-click any node to open that file in your editor at the right line. Right-click runs impact on it. ~ opens a console with the same commands as the CLI. The server watches the repo, re-indexes on change, and pushes updates over SSE, keeping node positions so the layout does not jump while you read it.

MCP

serve exposes the graph to any MCP client: repo_map, symbol_context, definition, references, impact, search_symbols, hotspots, cycles, ontology, ontology_entity, flow, next_move, architecture_check, reindex. Repo resolves from CODEGRAPH_ROOT, then --repo, then the working directory.

Architecture contract

codegraph.rules.json declares layers, allowed dependencies, size limits and roles. rules --strict exits non-zero on violations, so it works as a CI gate.

{
  "layers": {"app": ["src/app/**"], "domain": ["src/core/**"], "infra": ["src/db/**"]},
  "allow": {"app": ["domain", "infra"], "domain": ["infra"], "infra": []},
  "forbid_cycles": true,
  "max_file_lines": 500
}

Requirements

Python 3.10+, tree-sitter, tree-sitter-language-pack, networkx. mcp only for serve.

Known limits

• Call resolution is name-based; same-named methods on different classes can merge. The index reports ambiguous_calls so the size of that error stays visible.
• Dynamic await import() appears as a reference, not as a call edge.
• Role inference is a heuristic. Check role_confidence before treating a role as fact.