# codetopo — code graph for AI agents [Health: Active]

**Category:** 🧬 Biology & Bioinformatics  
**Repository:** https://github.com/nrupala/codetopo  
**GitHub Stars:** 1  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/codetopo-code-graph-for-ai-agents

## Description
Domain-blind code graphs for AI agents: symbols, calls, blast radius, proof-checked snapshots.

## Claude Desktop Quick Installation
No confirmed install details yet, so no config is published. Follow the setup steps in the repository above.

## Documentation

## What codetopo — code graph for AI agents does

codetopo — code graph for AI agents converts a source tree into a stored graph containing packages, modules, files, functions, external nodes, and typed relationships such as calls, containment, reads, and imports. It is domain-blind: the system reports structural facts and does not score code, rank components, or infer business meaning.

The graph supports questions such as which functions depend on a symbol, which nodes are downstream, what lies in a failure's blast radius, and how two nodes are connected. Query results are aggregate-first by default, returning counts before expanded lists. This helps keep responses and command pipelines bounded until a caller requests full detail.

## How it works

Indexing parses Rust and TypeScript/JavaScript with tree-sitter and writes the extracted graph to a SQLite-backed store. The shared `codetopo-core` layer supplies the graph model, traversal queries, and snapshot operations used by the command-line, HTTP, and MCP surfaces.

The MCP package runs as a stdio JSON-RPC process. Its twelve tools cover indexing, graph traversal, discovery, integrity checks, snapshots, and schema description. The MCP handlers and HTTP API use the same core query implementation, so equivalent requests produce the same answers.

The stored data includes a hash-chained audit log. `codetopo_verify` checks that log, while snapshot and restore operations provide a portable JSON representation and a way to load it into another database. The separate ACP binary is a read-only stdio agent with deterministic routing for common structural questions; it is not the MCP server itself.

## Setup and configuration

A stable Rust toolchain is required. The repository provides separate packages for the CLI, HTTP server, MCP server, and ACP agent. Install the binaries by naming the packages explicitly, then start `codetopo-mcp` from the MCP client's configuration.

A minimal stdio configuration is:

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

For CLI use, index a repository into a database before querying it. A typical sequence is `codetopo index <repository> --db graph.db`, followed by symbol discovery and a traversal query. Symbol identifiers include the indexed directory's package prefix, so callers should use the identifier returned by search rather than assume a shorter name.

The HTTP binary listens on `127.0.0.1:8080` by default and uses Bearer API-key authentication. Its documented configuration variables are `CODETOPO_BIND`, `CODETOPO_DATA_DIR`, `CODETOPO_KEYS_FILE`, and `CODETOPO_METERING_LOG`. The HTTP API contract is described by the repository's OpenAPI schema.

## Tools and capabilities

The MCP tool set includes:

- `codetopo_index` to create a graph from a repository
- `codetopo_search_symbols` and `codetopo_get_symbol` for discovery
- `codetopo_descendants` and `codetopo_ancestors` for dependency traversal
- `codetopo_blast_radius` for downstream impact analysis
- `codetopo_path` for shortest typed paths between nodes
- `codetopo_stats` for graph counts
- `codetopo_neighborhood` for local graph context
- `codetopo_verify` for audit-log validation
- `codetopo_snapshot` for a frozen JSON export
- `codetopo_describe_schema` for the graph schema

These capabilities make codetopo — code graph for AI agents suitable for coding agents that need read-only structural context before editing or reviewing a repository. The CLI offers corresponding commands, including restore from a snapshot, while the HTTP surface exposes the same handler layer through JSON endpoints.

## Limitations and notes

The extractor support described here covers Rust and TypeScript/JavaScript. The project intentionally does not provide domain interpretation, code-quality opinions, rankings, or edits. The MCP process communicates over stdio, so its host must support configuring a local stdio MCP server. ACP is also read-only and refuses edit requests. The HTTP deployment adds API-key management and metering requirements that do not apply to the basic stdio configuration.

_Full upstream README: https://allmcps.com/mcp/codetopo-code-graph-for-ai-agents/readme_