codetopo — code graph for AI agents MCP server

codetopo

Registry identity: mcp-name: io.github.nrupala/codetopo

See your codebase the way an agent sees it. codetopo turns a source repository into a queryable code graph — symbols, calls, references, and structure — with JSON answers an AI coding agent can act on directly.

codetopo holds the OpenSSF Best Practices Passing badge — 100% of 67 criteria.

You are here because an agent just touched your codebase and you want to answer structural questions fast: what calls this function? what breaks if I change this? how are these two modules connected? codetopo indexes the tree once and answers those questions as data — counts first, full lists only when asked — over a CLI, an HTTP API, or the MCP tools your agent already speaks.

It is deliberately domain-blind: no scoring, no rankings, no opinions about what the code means. It answers structural questions about source trees, and only that. Domain meaning belongs to the agents and teams composing on top.

Live demo: codetopo.aimlds.org — codetopo's real map of this repository, drawn by codetopo itself and refreshed on every push to main.

60-second quickstart

Requires a stable Rust toolchain (install via rustup).

# Install the four binaries: codetopo (CLI), codetopo-server (HTTP API),
# codetopo-mcp (stdio MCP server), codetopo-acp (stdio ACP agent).
# The packages must be named — a bare install URL fails because the
# repository contains multiple binary packages.
cargo install --git https://github.com/nrupala/codetopo codetopo-cli codetopo-server codetopo-mcp codetopo-acp

# Index a repository (Rust and TypeScript/JavaScript are parsed via tree-sitter)
codetopo index ~/my-project --db graph.db

# Find a symbol's id by name (every surface has this discovery step)
codetopo search connect --db graph.db

# Ask what calls what (the package prefix is your directory's name,
# exactly as indexed — hyphen included)
codetopo descendants my-project::net::Client::connect --db graph.db --expand

That's the whole loop: index once, query as data. Aggregate-first output — totals before lists — keeps token budgets and pipes sane by default; --expand brings the full list when you want it.

Example queries

Against the fixture repository used in the project's own end-to-end verification (docs/phase-2-verification.md) — output shown is the real output of the CLI:

$ codetopo index crates/codetopo-server/tests/fixture-repo --db graph.db
files indexed: 3
files failed: 0
symbols: 6
nodes: 15
edges: 23
diagnostics: 2

$ codetopo stats --db graph.db
nodes: 15
  package: 1
  module: 3
  file: 3
  function: 6
  external: 2
edges: 23
  calls: 5
  contains: 12
  reads: 6

$ codetopo descendants fixture-repo::alpha::entry --db graph.db --expand
2 descendants of fixture-repo::alpha::entry
fixture-repo::alpha::helper_a
fixture-repo::alpha::helper_b

A few more things you can ask (same engine, same data):

codetopo ancestors <node-id> --db graph.db     # what depends on this node
codetopo blast-radius <node-id> --db graph.db  # what a failure here would take with it
codetopo path <from-id> <to-id> --db graph.db  # shortest typed path between two nodes
codetopo verify --db graph.db                  # verify the hash-chained audit log
codetopo snapshot --db graph.db --out g.json   # portable frozen JSON export of the whole graph
codetopo restore --snapshot g.json --db g2.db  # restore a snapshot into a fresh database

Shortened. The full README is on GitHub.