codetopo — code graph for AI agents

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: it reports measurements — counts and rankings of structural facts, each with its method stated — and it never scores code quality or holds 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.

codetopo is a product of AIMLDS (2351485 ALBERTA INC.) — the house behind Conduit, managed MCP connector rails where every call is routed, metered, and receipted.

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

From crates.io, install the same packages by name — `cargo install

codetopo-cli for the CLI, cargo install codetopo-mcp` for the MCP

server. There is no crate named codetopo.

Index a repository (Rust, TypeScript/JavaScript, and Python 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 --db graph.db # what a failure here would take with it codetopo path --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

The path answer renders as typed steps, e.g. a --calls--> x --imports--> b (illustrative; exact ids depend on your index).

Giving it to your agent

HTTP API (codetopo-server)

The same queries over JSON, behind Bearer API-key auth, with per-request metering — one transport for any client, any language:

KEY="demo-key:$(openssl rand -hex 16)"   # a fresh random secret, generated exactly as docker-compose does — never a published example value

echo "$KEY" > api_keys && chmod 600 api_keys codetopo-server # listens on 127.0.0.1:8080 by default

curl -H "Authorization: Bearer $KEY" -X POST localhost:8080/v1/index \ -H 'Content-Type: application/json' -d '{"repo_path": "~/my-project"}'

{"index_id": " ", "files_indexed": 3, "files_failed": 0, "nodes": 15, "edges": 23, "diagnostics": 2}

curl -H "Authorization: Bearer $KEY" \ "localhost:8080/v1/graphs/ /descendants?node= &expand=true"

Twenty endpoints under /v1, one index operation plus nineteen read-only queries: POST /v1/index, GET /v1/graphs/{id}/{descendants, ancestors, blast-radius, path, stats, verify, snapshot, neighborhood, symbol, search, diagnostics, rank, diff, metrics, history, communities, topo-sort, render}, GET /v1/schema. Full contract in schemas/openapi.yaml (OpenAPI 3.1.0), env knobs (CODETOPO_BIND, CODETOPO_DATA_DIR, CODETOPO_KEYS_FILE, CODETOPO_METERING_LOG) documented in schemas/README.md.

MCP (codetopo-mcp)

A stdio JSON-RPC server exposing the same handler layer as twenty tools — the sixteen query/integrity tools (codetopo_index, codetopo_descendants, codetopo_ancestors, codetopo_blast_radius, codetopo_path, codetopo_stats, codetopo_verify, codetopo_snapshot, codetopo_diagnostics, codetopo_rank, codetopo_diff, codetopo_metrics, codetopo_history, codetopo_communities, codetopo_topo_sort, codetopo_render) plus discovery (codetopo_search_symbols, codetopo_get_symbol, codetopo_neighborhood, codetopo_describe_schema) — so an in-process agent learns one surface and gets both. MCP answers are identical to the HTTP answers by construction: both call the same codetopo-core queries.

{ "mcpServers": { "codetopo": { "command": "codetopo-mcp" } } }

ACP (codetopo-acp)

A stdio agent speaking the Agent Client Protocol — for editors and clients that converse with agents instead of calling tools. Open a session on a working directory and ask code-structure questions in plain language:

→ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}

← {"jsonrpc":"2.0","id":1,"result":{"agent":"codetopo","protocolVersion":"1.0", "agentCapabilities":{"read_only":true,"code_structure":true},"agentInfo":{"name":"codetopo"}}} → {"jsonrpc":"2.0","id":2,"method":"session/new","params":{"cwd":"/path/to/repo"}} → {"jsonrpc":"2.0","id":3,"method":"session/prompt", "params":{"sessionId":" ","prompt":"blast radius of auth::login"}} ← {"jsonrpc":"2.0","id":3,"result":{"answer":"Blast radius of 'auth::login': 14 nodes — …"}}

Deterministic intent routing (descendants / ancestors / blast-radius / path / stats / snapshot / verify) straight to the same codetopo-core queries — no LLM, no network, no file writes. Edit requests get an honest read-only refusal. stdout carries only protocol frames; diagnostics go to stderr.

Hosted API (codetopo Hosted)

The same HTTP API, run by us, always on. We host the index; you send a repository (public git URL or archive upload) and query the graph from anywhere with your key — no local install, no server to run.

Pricing

Included limits, by tier:

How it works:

1. Subscribe — Team · Guardrails — checkout is handled by Stripe.
2. After payment you land on a claim page. Claim your API key there — it is shown exactly once, so save it when it appears.
3. Call the API at https://codetopo-api.aimlds.org with Authorization: Bearer : , the same contract as the self-hosted server (see schemas/).

Cancel any time from the Stripe receipt link; the key stays active until the end of the paid period and is then revoked.

The hosted tiers are this same product, served: the local tools stay free and open source and are unchanged — a hosted tier is for when you want the graph served, not installed.

Architecture

        ┌─────────────┐   tree-sitter    ┌──────────────┐

│ source tree │ ───────────────► │ codetopo- │ extract symbols, └─────────────┘ Rust, TS/JS, Py │ extract │ calls, references └──────┬───────┘ ▼ ┌──────────────┐ │ codetopo-core│ graph model: │ │ nodes, edges, │ │ traversal queries └──────┬───────┘ ▼ ┌──────────────┐ │ codetopo- │ SQLite store + │ store │ hash-chained │ │ audit log └──────┬───────┘ │ ┌──────────────────────────────────┼─────────────────────────────┐ ▼ ▼ ▼ ▼ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ codetopo │ │ codetopo- │ Bearer auth │ codetopo- │ stdio │ codetopo- │ stdio │ (CLI) │ │ server │ JSONL │ mcp │ JSON-RPC │ acp │ ACP └──────────────┘ └──────────────┘ metering └──────────────┘ └──────────────┘

The CLI, HTTP, MCP, and ACP surfaces are all