Summary: This MCP server indexes source repositories into a local code-graph database, then lets you query and verify the graph through read-only structural tools.
Index a repository: codetopo_index builds a graph database from repo_path, with optional package and required db_path.
Traverse dependencies: codetopo_descendants, codetopo_ancestors, codetopo_blast_radius, codetopo_path, and codetopo_neighborhood explore calls, imports, and impact.
Find and inspect symbols: codetopo_search_symbols searches names; codetopo_get_symbol returns one node’s kind, location, tier, defines, and refs.
Get graph stats: codetopo_stats returns node and edge totals with per-kind breakdowns.
Verify integrity: codetopo_verify checks the tamper-evident audit chain.
Export the graph: codetopo_snapshot writes the whole graph as a portable snapshot bound to the audit head.
Learn the schema: codetopo_describe_schema reports node/edge kinds, tier rules, and query vocabulary without a database.
Safety profile: all query/inspection tools are read-only; only codetopo_index creates/writes an index database.
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.
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.
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 --expandThat'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.
Related MCP server: code-analyze-mcp
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_bA 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 databaseThe path answer renders as typed steps, e.g. a --calls--> x --imports--> b
(illustrative; exact ids depend on your index).
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"Eight endpoints under /v1, one index operation plus seven read-only
queries: POST /v1/index, GET /v1/graphs/{id}/{descendants, ancestors, blast-radius, path, stats, verify, snapshot, neighborhood, symbol, search}, 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.
codetopo-mcp)A stdio JSON-RPC server exposing the same handler layer as twelve tools —
the eight query/integrity tools (codetopo_index, codetopo_descendants,
codetopo_ancestors, codetopo_blast_radius, codetopo_path,
codetopo_stats, codetopo_verify, codetopo_snapshot) 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" } } }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.
┌─────────────┐ tree-sitter ┌──────────────┐
│ source tree │ ───────────────► │ codetopo- │ extract symbols,
└─────────────┘ Rust, TS/JS │ 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 |
| Graph model, node/edge kinds, all traversal queries, snapshots |
| tree-sitter extractors (Rust, TypeScript/JavaScript) |
| SQLite persistence + tamper-evident, hash-chained audit log |
|
|
|
|
|
|
|
|
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/render.md — deterministic render: the frozen layout spec (JSON) + SVG rules behind codetopo render
docs/protocol-proof.md — MCP/ACP conformance evidence: strict stdio clients + official-schema validation
docs/scale-gate.md — the 10,000-file scale gate and its measured record
Dockerfile + docker-compose.yml — self-hosted container: the HTTP API over your own indexes
docs/phase-2-design.md — API design: endpoints, auth, metering, aggregate-first discipline
docs/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 guarantee
docs/phase-3-acp-verification.md — ACP verification report
docs/quickstart-verification.md — clean-machine verification of the quickstart and example queries above
schemas/README.md — the two agent-facing contracts and where the spec departs from the design doc
CODE_SCHEMA.md — the graph schema (§6 sets the aggregate-first rule)
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.
Engine (codetopo-* crates): AGPL-3.0-or-later (see LICENSES/)
Agent-facing contracts (schemas/: OpenAPI 3.1 spec, MCP tool catalogue): Apache-2.0 (see schemas/LICENSE-APACHE)
Owned by Nrupal Akolkar · Built with Muse by Meta — join Muse, then redeem code 101EEK in Settings within 48 hours of joining and we both earn tokens.
Nodes from which a node is transitively reachable over calls and imports edges.
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | Node id to walk up from. | |
| limit | No | Maximum members to return. Default 20. | |
| expand | No | Return full node objects instead of ids. Default false. | |
| db_path | Yes | Path to the index database. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly, non-destructive, closed-world), so the description's job is to add what they cannot. It does: the traversal is transitive and restricted to calls and imports edges, which tells the agent exactly what relationships are followed. It omits any mention that results are capped or truncated, which would be useful for a walk that can explode on cyclic graphs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with zero filler that front-loads the core relationship definition. Nothing redundant and nothing that could be trimmed without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should hint at what comes back and how it is bounded. It explains the traversal but not that results are limited by `limit`, that `expand` changes the return shape, or what happens on cycles in a bidirectional graph, leaving real gaps for a graph-walk tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so db_path, node, limit (default 20) and expand (default false) are all already documented in the schema. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a precise graph-theoretic definition of the operation: nodes from which the target is transitively reachable, scoped to calls and imports edges. That distinguishes it well from codetopo_descendants (the inverse walk) even though it never names the sibling explicitly. It is clear but relies on the title for the verb.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to use this versus codetopo_descendants, codetopo_blast_radius, or codetopo_neighborhood, all of which operate on the same graph. Usage is only inferable from the direction of the relationship, which is weak guidance for a family of twelve sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Nodes that break if a node changes: dependents, overriders, and implementers.
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | Node id whose blast radius to compute. | |
| limit | No | Maximum members to return. Default 20. | |
| expand | No | Return full node objects instead of ids. Default false. | |
| db_path | Yes | Path to the index database. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description is not obligated to cover safety. It does add semantic value by defining what 'blast radius' concretely returns — dependents, overriders, implementers — but says nothing about cost, ordering, or whether the queried node is included in the result.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with zero filler; the core definition comes before any qualifiers. Nothing in it is redundant with the title or schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only traversal over an indexed graph with a fully documented 4-parameter schema, the description covers the concept but not the operational edges an agent needs — traversal direction, whether transitive depth is bounded, and whether the source node appears in results are all left open with no output schema to fall back on.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: node, limit (default 20) and expand (full objects vs ids) are all documented in the schema itself. The description adds no parameter-level meaning such as how limit interacts with traversal order. Baseline 3 is appropriate when the schema does all the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific analytical result ('nodes that break if a node changes') and enumerates the relationship kinds it collects (dependents, overriders, implementers). This is far more specific than a tautology and implicitly differentiates it from the generic graph-walk siblings like codetopo_descendants, though it never names them outright.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to reach for this tool versus codetopo_descendants, codetopo_ancestors, or codetopo_neighborhood, all of which walk the same graph. No prerequisites (e.g. index must exist) or exclusion conditions are given, so the agent must infer selection from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Nodes transitively reachable from a node over calls and imports edges.
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | Node id to walk down from. | |
| limit | No | Maximum members to return. Default 20. | |
| expand | No | Return full node objects instead of ids. Default false. | |
| db_path | Yes | Path to the index database. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context by specifying that traversal follows calls and imports edges, but it omits traversal semantics such as cycle handling, whether the start node is included, or ordering.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler. Every word carries information about what is returned and which edges are traversed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema covers parameters and return-format toggling via expand, and annotations cover safety, so the core is present. However, for a traversal tool sitting among ancestors, blast_radius, neighborhood, and path siblings, the description omits the routing guidance an agent needs and says nothing about cycles or result scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so node, limit, expand, and db_path are already documented in the schema. The description adds no additional parameter meaning, which is the expected baseline when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb-like result ('nodes transitively reachable from a node') plus the exact edge types traversed ('calls and imports'), so an agent knows this is a downward graph walk. It does not name or contrast with the obvious siblings (codetopo_ancestors, codetopo_blast_radius, codetopo_neighborhood), so differentiation is left to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance at all. With siblings like codetopo_ancestors (inverse direction), codetopo_blast_radius, codetopo_neighborhood, and codetopo_path, the agent is given no condition for selecting this tool over those alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The schema this server speaks: node and edge kinds, tier rules, and the query vocabulary. Needs no database.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the burden is lower. The description adds one genuinely useful behavioral fact, that no database is required, but says nothing about the size/shape of the response or cost of calling it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very short and front-loaded: the resource is named first, then the payload contents, then the no-database constraint as a fragment. Nothing is wasted, though the trailing fragment is slightly telegraphic rather than a full clause.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must hint at what comes back, and it does so by listing node/edge kinds, tier rules, and query vocabulary. For a zero-param introspection tool this is nearly complete; a sentence on how to use the returned vocabulary would make it fully self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is no parameter semantics to document; baseline 4 applies. Schema coverage is 100% and the description correctly implies a call with no arguments.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific resource, 'the schema this server speaks', and enumerates its contents (node and edge kinds, tier rules, query vocabulary), which distinguishes it from the sibling query tools like codetopo_index or codetopo_path. The verb is only implicit ('describe' lives in the name/title), and it never explicitly contrasts itself against siblings, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Needs no database' implies this can be called before any index exists, which is a usable contextual cue. However, it never states when an agent should reach for this versus codetopo_index or codetopo_stats, nor any exclusions, so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One node in full: kind, location, tier, defines and refs. Errors when the id is unknown.
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | Node id to fetch. | |
| db_path | Yes | Path to the index database. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description still adds real behavioral value by listing the returned fields and disclosing the failure mode ('Errors when the id is unknown'), which annotations do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact sentence that front-loads the essential fact (full node) and appends the error condition. Terse to the point of mild crypticness ('defines and refs'), but no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter lookup with no output schema, the description covers the returned payload fields and the error case, which is sufficient for correct invocation. It omits any notion of cost, pagination, or node-id provenance, but nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters, so the schema already documents node and db_path. The description only indirectly confirms node is an id via the unknown-id error case and says nothing extra about db_path, matching the baseline for fully documented schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (one node) and enumerates what 'in full' means: kind, location, tier, defines and refs. Clear against list-oriented siblings like codetopo_search_symbols, though it does not name any sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: fetch a single known node id. There is no guidance on when to prefer this over codetopo_search_symbols, codetopo_neighborhood, or codetopo_descendants, leaving the agent to infer the id-lookup vs exploration split.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Index a repository into a codetopo graph database.
| Name | Required | Description | Default |
|---|---|---|---|
| db_path | Yes | Path of the database to create. | |
| package | No | Package name. Defaults to the repository directory name. | |
| repo_path | Yes | Path to the repository to index. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this is a non-readOnly, non-destructive, closed-world write operation. The description adds essentially no behavioral context beyond that: it doesn't say whether an existing database is overwritten, whether indexing is incremental or full, how long it takes, or what permissions are needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no wasted words. It is appropriately terse, though it leaves out information a mutation tool of this kind would benefit from.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool that creates/writes a database, the description omits the operational context an agent needs: ordering relative to the query tools, overwrite/incremental behavior, and error or rate-limit expectations. Annotations cover safety and the schema covers parameters, but the usage and lifecycle picture remains incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all three parameters are documented in the schema itself. The description adds no syntax, format, or default details beyond what the schema already provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Index) and resource (repository) plus the target artifact (codetopo graph database), which is clear and distinct from the query-oriented siblings. It does not explicitly name any sibling or scope condition, but the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to run this versus the other codetopo_* tools, no prerequisites (e.g., must it run before queries), and no indication of alternatives. The only context is implied by the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The subgraph within a few hops of a node, in both directions (contains/defines excluded).
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | Node id at the center. | |
| depth | No | Hops to walk (default 1). | |
| db_path | Yes | Path to the index database. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that by disclosing edge-type filtering (contains/defines excluded) and bidirectional traversal, but says nothing about result size, depth limits, or traversal cost.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single tight sentence with no filler, and the scoping qualifier is front-loaded. The only flaw is that it reads as a sentence fragment rather than a complete clause, which slightly impairs immediate comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description needn't explain return values, and annotations carry the safety profile. For a traversal tool with three fully documented parameters, though, it is terse: it omits any sense of graph size, result limits, or how the neighborhood relates to the ancestor/descendant tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so node, depth, and db_path are already documented, including the depth default of 1. The description's 'within a few hops' and 'at the center' loosely restate the schema semantics without adding format or constraints, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource ('the subgraph within a few hops of a node') and its bidirectional scope, which is specific enough to separate it from single-direction traversal. However, it is a noun fragment with no verb, and it never names the siblings (descendants/ancestors) it overlaps with, so differentiation is only implied by the 'contains/defines excluded' clause.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use statement or named alternative. The parenthetical exclusion of contains/defines edges weakly hints that containment traversal belongs to codetopo_descendants/codetopo_ancestors, but the agent must infer that routing on its own.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Shortest typed path between two nodes, or the reason there is none.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Node id to reach. | |
| from | Yes | Node id to start from. | |
| db_path | Yes | Path to the index database. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description needn't restate that. It does add genuine behavioral facts beyond annotations: the result is the *shortest* path, edges are *typed*, and a no-path case yields an explanatory reason rather than an empty result. It says nothing about path representation, node-vs-edge output, or cost limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the core operation and closed with the failure clause. Nothing is padding and nothing important is buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only query with fully documented params this is thin but workable. The notable gap is that no output schema exists, so the description should describe what a returned path looks like (ordered nodes? typed edges?) — 'or the reason there is none' hints at an error string but leaves the success shape undefined.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — every parameter (db_path, from, to) has its own description — so the schema carries the parameter burden and the baseline is 3. The description's only added semantic is that paths are 'typed', which does not clarify the id format or what 'from'/'to' resolve against.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource: computes the shortest typed path between two named nodes, and additionally signals failure semantics ('or the reason there is none'). It is distinguishable from graph siblings like codetopo_neighborhood or codetopo_descendants by its pairwise from-to framing, though it never names those siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use, when-not-to-use, or alternative routing. The only implicit hint is that the tool is worth calling even when connectivity is doubtful, since it reports why no path exists. An agent still has to infer this tool's place among twelve graph siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find symbols by name (case-insensitive substring of the label) - the discovery step before the exact-id queries.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum results (default 20). | |
| query | Yes | Name fragment to search for. | |
| db_path | Yes | Path to the index database. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral detail: matching is case-insensitive and substring-based on the label, which tells the agent a fuzzy query will match many symbols. It doesn't discuss result ordering or how limit truncates output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, fully front-loaded: behavior first, then the workflow position. Nothing is redundant with the title, and every clause adds information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only search with a fully documented 3-parameter schema, the description covers what the tool does and where it sits in the workflow. With no output schema, return shape (what a matched symbol looks like beyond its label) is left implicit, which is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description nonetheless sharpens the meaning of `query` beyond the schema's generic "Name fragment to search for" by specifying case-insensitivity and that matching is against the label field.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ("Find symbols by name") and immediately nails the matching semantics (case-insensitive substring of the label). It also positions itself against the exact-id queries, so an agent can distinguish it from codetopo_get_symbol without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase "the discovery step before the exact-id queries" gives a clear role in the workflow and implies the alternative (get_symbol by id). It stops short of naming that sibling explicitly or stating when not to use this tool, so it's clear context rather than full routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export the whole graph as a portable snapshot, bound to the audit head.
| Name | Required | Description | Default |
|---|---|---|---|
| db_path | Yes | Path to the index database. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful scope context ('whole graph') and the audit-head binding, but does not describe output format, snapshot destination, or any resource cost. Adds some value beyond annotations, but not rich behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the core action and scope, with no wasted words. The audit-head qualifier adds context without bloating the definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter, read-only export tool with annotations covering safety, the description is adequate but leaves notable gaps: it does not explain what a 'portable snapshot' contains, where it is written, or what the audit head binding implies for the caller. With no output schema, some return/side-effect expectation would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single db_path parameter is already documented in the schema. The description adds no additional parameter meaning, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Export) and resource (whole graph as a portable snapshot), which is clear and distinguishable from the query-oriented siblings. It stops short of explicitly differentiating itself from sibling tools like codetopo_stats or codetopo_verify, so it is not a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no when-to-use guidance, no prerequisites, and no alternatives to consider. An agent must infer from the verb alone that this is the tool for exporting a snapshot.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Node and edge totals for an index, with per-kind breakdowns.
| Name | Required | Description | Default |
|---|---|---|---|
| db_path | Yes | Path to the index database. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds something the annotations do not: the shape of the result (node and edge totals plus per-kind breakdowns), which matters especially since there is no output schema. It omits any cost/latency hint for large indexes, keeping it below 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence fragment that names the resource and the payload with no filler; every clause carries information. It is appropriately minimal for a one-parameter read-only tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one fully documented parameter and clear annotations, the description gives enough to call it correctly and to anticipate the return content despite the absence of an output schema. The main missing piece is context about when an index exists or how expensive the stats call is.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single parameter (db_path) and schema description coverage is 100%, so the schema already documents it fully. The description adds no syntax, format, or defaulting detail beyond the schema, which is the expected baseline of 3 for high-coverage schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (an index) and a specific output (node and edge totals with per-kind breakdowns), so an agent can immediately tell this is the counting/summary tool. It does not explicitly contrast itself with siblings like codetopo_index or codetopo_describe_schema, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no stated prerequisite (e.g. that an index must already be built), and no mention of alternatives among the dozen sibling codetopo tools. Usage is only inferable from the noun 'index' and the word 'totals'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify the tamper-evident audit chain of an index.
| Name | Required | Description | Default |
|---|---|---|---|
| db_path | Yes | Path to the index database. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the chain is 'tamper-evident', implying a hash/chain integrity check, but says nothing about what a failed verification means, whether it raises or returns, or whether it is expensive to run.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with the object of verification front-loaded and no filler. It is appropriately sized for the operation, though one clause more of substance would not have hurt.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one fully documented parameter and clear read-only annotations, the tool is simple enough that the definition is nearly sufficient. The gap is the return contract: no output schema exists, so the description should at least indicate that verification yields a pass/fail or chain-status result, which it does not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single db_path parameter, and the description adds no additional semantics (e.g. whether the path is to an index root or a database file). Baseline 3 applies when the schema already carries the parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (verify) and a specific resource (the tamper-evident audit chain of an index), so the agent knows this is an integrity check rather than an indexing or traversal operation. It does not, however, distinguish itself from any named sibling or reference the index it operates on in terms of a sibling relationship.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisites (e.g. must the index be built first?), and no mention of alternatives such as codetopo_stats or codetopo_snapshot. The agent must infer the trigger condition for verification entirely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
codetopo_ancestorscodetopo_blast_radiuscodetopo_descendantscodetopo_describe_schemacodetopo_get_symbolcodetopo_indexcodetopo_neighborhoodcodetopo_pathcodetopo_search_symbolscodetopo_snapshotcodetopo_statscodetopo_verifyThis server cannot be deployed
Scored across 12 tools
Most tools target clearly distinct operations: indexing, traversal in one direction, blast-radius calculation, pathfinding, symbol lookup, schema description, export, and audit verification. The main potential confusion is between traversal tools like descendants, ancestors, neighborhood, and blast_radius, since all involve following graph edges, but the descriptions provide enough detail to distinguish their specific semantics.
All tool names use a consistent codetopo_ prefix and snake_case formatting, which makes them easy to scan. The naming mixes noun-style names (descendants, ancestors, path, stats, neighborhood) with verb-style and verb_noun names (index, verify, snapshot, get_symbol, search_symbols, describe_schema), but the pattern remains predictable and readable.
Twelve tools is a well-scoped set for a code graph database server, covering indexing, several complementary graph queries, schema introspection, snapshot export, and audit verification. Each tool appears to earn its place without obvious redundancy or filler.
The surface covers the core lifecycle: creating an index, discovering and inspecting symbols, traversing relationships, pathfinding, blast-radius analysis, schema description, export, and audit verification. Minor gaps might include listing or deleting existing indexes, but the read/query side is strongly covered for the stated purpose.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Hosted code graph over MCP: exact callers, dependencies, and cross-repo blast radius for AI agents.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
