codetopo — code graph for AI agents

codetopo

注册表标识：mcp-name: io.github.nrupala/codetopo

像 Agent 一样查看代码库。 codetopo 会将源代码仓库转换为可查询的代码图谱——包含符号、调用、引用和结构，并以 JSON 返回答案，供 AI 编码 Agent 直接使用。

codetopo 持有 OpenSSF Best Practices Passing 徽章——67 项标准中有 100% 达标。

你来到这里，是因为某个 Agent 刚刚操作了你的代码库，而你想快速回答一些结构性问题：什么在调用这个函数？如果我修改它，哪些部分会出问题？这两个模块是如何关联的？ codetopo 会为代码树建立一次索引，并将这些问题作为数据来回答——优先提供计数，只有在需要时才给出完整列表。你可以通过 CLI、HTTP API，或 Agent 已经使用的 MCP 工具进行查询。

它有意不涉及领域知识：只报告度量结果——结构事实的数量和排名，并说明每项结果的计算方法；它从不评估代码质量，也不对代码含义作出判断。它只回答有关源代码树的结构性问题。领域含义应由基于它构建的 Agent 和团队来处理。

codetopo 是 AIMLDS（2351485 ALBERTA INC.）的产品——该公司也是 Conduit 背后的团队，Conduit 是一套托管式 MCP 连接器基础设施，可路由、计量并记录每一次调用。

在线演示： codetopo.aimlds.org——codetopo 对本仓库生成的实时地图，由 codetopo 自行绘制，并在每次推送到 main 时刷新。

60 秒快速入门

需要稳定版 Rust 工具链（通过 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

整个流程就是这样：建立一次索引，以数据形式查询。 默认采用聚合优先的输出方式——先给出总数，再列出具体内容——让 token 预算和管道都保持合理；需要完整列表时，可使用 --expand。

查询示例

以下查询针对项目端到端验证所用的 fixture 仓库（docs/phase-2-verification.md）执行——所示输出为 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

你还可以询问其他内容（使用相同的引擎和数据）：

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

path 答案会以带类型的步骤呈现，例如 a --calls--> x --imports--> b（仅作示意；具体 ID 取决于你的索引）。

提供给你的 Agent 使用

HTTP API（codetopo-server）

通过 JSON 提供相同的查询，使用 Bearer API 密钥进行身份验证，并按请求计量——一种传输方式即可适用于任何客户端和任何语言：

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"

/v1 下共有 17 个端点：一个索引操作和 16 个只读查询：POST /v1/index、GET /v1/graphs/{id}/{descendants, ancestors, blast-radius, path, stats, verify, snapshot, neighborhood, symbol, search, diagnostics, rank, diff, metrics, history}、GET /v1/schema。完整规范见 schemas/openapi.yaml（OpenAPI 3.1.0）；环境变量配置项（CODETOPO_BIND、CODETOPO_DATA_DIR、CODETOPO_KEYS_FILE、CODETOPO_METERING_LOG）的说明见 schemas/README.md。

MCP（codetopo-mcp）

一个 stdio JSON-RPC 服务，公开与十七个工具相同的处理层 — 十三个查询／完整性工具（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_search_symbols、codetopo_get_symbol、 codetopo_neighborhood、codetopo_describe_schema）— 因此进程内 Agent 只需熟悉一个接口，就能获得两者。MCP 的回答与 HTTP 回答完全一致，这是由构造方式决定的：两者都调用相同的 codetopo-core 查询。

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

ACP（codetopo-acp）

一个通过 stdio 通信、使用 Agent Client Protocol 的 Agent — 面向与 Agent 对话而非调用工具的编辑器和客户端。在一个 工作目录上开启会话，然后用自然语言提出代码结构相关问题：

→ {"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 — …"}}

确定性的意图路由（后代／祖先／影响范围／路径／统计／快照／验证）直接调用相同的 codetopo-core 查询 — 无需大模型、无需网络、不会写入文件。对于编辑请求，会如实拒绝，只读访问。stdout 仅承载协议帧；诊断信息写入 stderr。

托管 API（codetopo Hosted）

由我们运行、始终在线的同一 HTTP API。索引由我们托管；你提交一个 代码仓库（公开 git URL 或归档上传），然后使用密钥从任何地方查询图谱 — 无需本地安装，也无需运行服务。

每个密钥每月 19 美元。

包含项目
活跃索引	25
查询次数	每月 10,000 次
仓库大小	每个索引最多 50,000 个文件

工作方式：

1. 订阅 — 通过 Stripe 结账。
2. 付款后，你会进入密钥领取页面。在那里领取 API 密钥 — 密钥仅显示一次，因此请在出现时保存。
3. 使用 Authorization: Bearer <key_id>:<secret> 调用 https://codetopo-api.aimlds.org 上的 API，其约定与 可自托管的服务相同（参见 schemas/）。

可随时通过 Stripe 收据链接取消；密钥会一直有效到已付费周期结束，之后将被撤销。

这是同一产品的托管版本。本仓库中的本地 CLI、MCP 服务 和 ACP Agent 仍然免费且开源（AGPL-3.0），并且没有变化 — 托管套餐适用于希望由服务提供图谱，而非自行安装的场景。

架构

        ┌─────────────┐   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	作用
codetopo-core	图模型、节点／边类型、所有遍历查询、快照
codetopo-extract	tree-sitter 提取器（Rust、TypeScript/JavaScript）
codetopo-store	SQLite 持久化 + 防篡改哈希链审计日志
codetopo-cli	无头 CLI codetopo — 参考查询接口
codetopo-server	codetopo-server axum HTTP API（基于 core 的轻量适配器）
codetopo-mcp	codetopo-mcp stdio MCP 服务（基于 core 的轻量适配器）
codetopo-acp	codetopo-acp stdio ACP Agent — 通过 Agent Client Protocol 提供对话式会话（基于 core 的轻量适配器）

CLI、HTTP、MCP 和 ACP 接口都是相同处理程序上的轻量适配器 — 因此不会出现不一致。schemas/ 保存机器可读契约（OpenAPI 3.1、MCP 工具目录），并会根据运行中的 服务进行校验。存储层的审计日志遵循本产品系列采用的信任原语模式：采用哈希链的只追加记录，通过 codetopo verify / GET …/verify 验证。

文档

• 开发日志 — 用通俗易懂的语言介绍 codetopo 的发展历程和未来方向（随版本发布维护；演示网站也有链接）
• docs/render.md — 确定性渲染：codetopo render 背后的冻结布局规范（JSON）和 SVG 规则
• docs/protocol-proof.md — MCP/ACP 一致性证据：严格的标准输入输出客户端与官方规范验证
• docs/scale-gate.md — 10,000 个文件的规模门槛及其测量记录
• Dockerfile + docker-compose.yml — 可自托管容器：基于你自己的索引提供 HTTP API
• docs/phase-2-design.md — API 设计：端点、身份验证、计量，以及聚合优先原则
• docs/phase-2-verification.md — 端到端验证报告（上文的测试数据来自此处）
• docs/phase-3-acp-design.md — ACP Agent 设计：线路协议、意图路由、只读保证
• docs/phase-3-acp-verification.md — ACP 验证报告
• docs/quickstart-verification.md — 在干净环境中对快速入门和上文示例查询进行的验证
• schemas/README.md — 两份面向 Agent 的契约，以及规范与设计文档的差异
• CODE_SCHEMA.md — 图谱架构（§6 规定了聚合优先规则）

隐私政策

codetopo 完全在你的机器上运行。MCP 服务（codetopo-mcp）、CLI 及其创建的索引数据库绝不会将你的代码、查询或任何使用数据发送到任何地方：没有账户、没有 API 密钥、没有遥测，也不会在运行时发起网络调用。索引只会读取你指定的代码库，并且只会写入你提供的数据库路径。要删除数据，请删除索引数据库文件（.db 文件或 HTTP 服务的数据目录）——没有数据存放在任何服务上，因此无需在其他地方删除。要带走数据，请使用 snapshot 命令导出；该命令会将整个图谱写入一个可移植的 JSON 文件。如有隐私相关问题，请联系：[email protected]。

许可证

• 引擎（codetopo-* crates）：AGPL-3.0-or-later（参见 LICENSES/）
• 面向 Agent 的契约（schemas/：OpenAPI 3.1 规范、MCP 工具目录）：Apache-2.0（参见 schemas/LICENSE-APACHE）

归 Nrupal Akolkar 所有 · 使用 Muse by Meta 构建 — 加入 Muse 后，在加入的 48 小时内于 Settings 中兑换代码 101EEK，我们双方都能获得代币。