codetopo MCP server
Commit Nov 15, 2026Turns source repositories into queryable code graphs of symbols, calls, and references for AI coding agents.
Also known as nrupala/codetopo, codetopo
- Stars
- 2
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.9.0
- Last commit
- Nov 15, 2026
- License
- AGPL-3.0
What is codetopo MCP?
codetopo turns source repositories into queryable code graphs of symbols, calls, and references for AI coding agents.
Summary generated from the project's README
About codetopo MCP server
codetopo transforms source code repositories into structured, queryable graphs containing symbols, calls, and references. It is designed for AI coding agents that need to understand the structural relationships within a codebase without relying on LLM reasoning for architectural facts. The system indexes a repository once and provides data-driven answers regarding how modules connect or what might break during a change.
Developers can run this locally using the provided CLI, an HTTP API via codetopo-server, or as a stdio MCP server using codetopo-mcp. It supports Rust, TypeScript, JavaScript, and Python through tree-sitter parsing. For those who prefer not to manage local infrastructure, a hosted API is available via AIMLDS, requiring a Bearer API key for access. The tool focuses strictly on structural measurements and does not attempt to interpret code quality or domain meaning.
What you can do with it
- 1Analyze impact of code changesAn agent can determine the blast radius of a specific node to see what else might fail.
- 2Trace function dependenciesA developer can ask an AI to find all functions that call a specific target.
- 3Map connections between modulesAn agent can find the shortest typed path between two distinct nodes in the graph.
- 4Audit code structure integrityUsers can verify the hash-chained audit log to ensure the graph remains untampered.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablenrupala/codetopo is public and reachablegithub.com/nrupala/codetopo ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)AGPL-3.0spdx.org/licenses/AGPL-3.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-11github.com/nrupala/codetopo ↗Pass
- OpenSSF ScorecardOpenSSF Scorecard 6.0 / 10; weakest: Maintained 0, Code-Review 0, Branch-Protection 0scorecard.dev/viewer/?uri=github.com/nrupala/codetopo ↗Partial 9/15
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubcodetopo
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 <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
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": "<uuid>", "files_indexed": 3, "files_failed": 0, "nodes": 15, "edges": 23, "diagnostics": 2}
curl -H "Authorization: Bearer $KEY" \
"localhost:8080/v1/graphs/<uuid>/descendants?node=<node-id>&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":"<id>","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
| Tier | Price | What it is |
|---|---|---|
| Free | US$0 | The local CLI, MCP server, and ACP agent in this repository — free and open source (AGPL-3.0), run on your own machine. |
| Team | US$19/month per key | The hosted API, run by us. |
| Guardrails | US$49/month per key | The hosted API at the Guardrails service level — the higher of the two hosted tiers. |
Included limits, by tier:
| Included | Team | Guardrails |
|---|---|---|
| Active indexes | 25 | 100 |
| Queries | 10,000 / month | 50,000 / month |
| Repository size | up to 50,000 files per index | up to 250,000 files per index |
How it works:
- Subscribe — Team · Guardrails — checkout is handled by Stripe.
- After payment you land on a claim page. Claim your API key there — it is shown exactly once, so save it when it appears.
- Call the API at
https://codetopo-api.aimlds.orgwithAuthorization: Bearer <key_id>:<secret>, the same contract as the self-hosted server (seeschemas/).
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 └──────────────┘ └──────────────┘
| Crate | Role |
|---|---|
codetopo-core |
Graph model, node/edge kinds, all traversal queries, snapshots |
codetopo-extract |
tree-sitter extractors (Rust, TypeScript/JavaScript, Python) |
codetopo-store |
SQLite persistence + tamper-evident, hash-chained audit log |
codetopo-cli |
codetopo headless CLI — the reference query surface |
codetopo-server |
codetopo-server axum HTTP API (thin adapter over core) |
codetopo-mcp |
codetopo-mcp stdio MCP server (thin adapter over core) |
codetopo-acp |
codetopo-acp stdio ACP agent — conversational sessions over the Agent Client Protocol (thin adapter over core) |
The CLI, HTTP, MCP, and ACP surfaces are all thin adapters over the same
handlers — they cannot disagree. schemas/ keeps the machine-readable
contracts (OpenAPI 3.1, MCP tool catalogue) checked against the running
servers. The store's audit log follows the trust-primitive pattern used
across this product line: a hash-chained, append-only record, verified by
codetopo verify / GET …/verify.
Docs
- Development log — how codetopo got here and where it is going, in plain words (kept with the releases; also linked from the demo site)
docs/render.md— deterministic render: the frozen layout spec (JSON) + SVG rules behindcodetopo renderdocs/protocol-proof.md— MCP/ACP conformance evidence: strict stdio clients + official-schema validationdocs/scale-gate.md— the 10,000-file scale gate and its measured recordDockerfile+docker-compose.yml— self-hosted container: the HTTP API over your own indexesdocs/phase-2-design.md— API design: endpoints, auth, metering, aggregate-first disciplinedocs/phase-2-verification.md— end-to-end verification report (fixture numbers above come from here)docs/phase-3-acp-design.md— ACP agent design: wire protocol, intent routing, read-only guaranteedocs/phase-3-acp-verification.md— ACP verification reportdocs/quickstart-verification.md— clean-machine verification of the quickstart and example queries aboveschemas/README.md— the two agent-facing contracts and where the spec departs from the design docCODE_SCHEMA.md— the graph schema (§6 sets the aggregate-first rule)
Privacy Policy
codetopo runs entirely on your machine. The MCP server (codetopo-mcp), the CLI, and the index databases they create never send your code, your queries, or any usage data anywhere: there are no accounts, no API keys, no telemetry, and no network calls at runtime. Indexing reads only the repositories you point it at and writes only the database paths you give it. To delete your data, delete the index database files (the .db files, or the HTTP server's data directory) — nothing is held on any server, so there is nothing elsewhere to erase. To take your data with you, export it with the snapshot command, which writes the whole graph as one portable JSON file. Questions about privacy: info@aimlds.org.
License
- Engine (
codetopo-*crates): AGPL-3.0-or-later (seeLICENSES/) - Agent-facing contracts (
schemas/: OpenAPI 3.1 spec, MCP tool catalogue): Apache-2.0 (seeschemas/LICENSE-APACHE)
Owned by Nrupal Akolkar · Built with Muse by Meta.
codetopo MCP questions
What languages does codetopo support?
It parses Rust, TypeScript/JavaScript, and Python using tree-sitter.
Is the tool free to use?
Yes, the local CLI, MCP server, and ACP agent are free and open source under the AGPL-3.0 license.
Can I use codetopo without installing it locally?
Yes, you can use the Hosted API which allows you to send a repository and query the graph via an API key.