codetopo — code graph for AI agents

codetopo

レジストリ ID：mcp-name: io.github.nrupala/codetopo

エージェントの視点でコードベースを確認できます。 codetopo はソースリポジトリをクエリ可能なコードグラフに変換します。シンボル、呼び出し、参照、構造を JSON で返すため、AI コーディングエージェントがそのまま活用できます。

codetopo は OpenSSF Best Practices Passing バッジを取得しています。67 項目の基準すべてを満たしています。

エージェントがコードベースを変更したばかりで、構造に関する疑問にすぐ答えたい場合に、ここをご覧ください。この関数を呼び出しているのは何ですか？これを変更すると何が壊れますか？この 2 つのモジュールはどうつながっていますか？ codetopo はツリーを一度インデックス化し、CLI、HTTP API、またはエージェントがすでに使っている MCP ツールを通じて、こうした疑問にデータとして答えます。まず件数を返し、求められた場合にのみ全件を表示します。

意図的にドメインに依存しない設計です。構造上の事実について、その測定方法を明示した件数やランキングを報告し、コードの品質を評価したり、コードの意味について見解を示したりすることはありません。ソースツリーの構造に関する疑問だけに答えます。ドメイン上の意味付けは、その上に構築するエージェントやチームに委ねられます。

codetopo は AIMLDS（2351485 ALBERTA INC.）のプロダクトです。AIMLDS は Conduit を運営しており、すべての呼び出しをルーティングし、使用量を計測して、記録を残すマネージド MCP コネクター基盤を提供しています。

ライブデモ： codetopo.aimlds.org — 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

これで一連の操作は完了です。一度インデックス化すれば、データとしてクエリできます。 集約を優先する出力では、一覧より先に合計を表示するため、トークン予算とパイプをデフォルトで適切に保てます。全件を表示したい場合は --expand を指定します。

クエリの例

プロジェクト独自のエンドツーエンド検証で使用するフィクスチャリポジトリ（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 はインデックスによって異なります）。

エージェントに渡す

HTTP API（codetopo-server）

同じクエリを JSON 経由で実行できます。Bearer API キー認証とリクエストごとの使用量計測に対応しており、あらゆるクライアント、あらゆる言語で使える 1 つのトランスポートです。

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 個のエンドポイントがあります。インデックス操作が 1 つ、読み取り専用クエリが 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 です。API の完全な仕様は schemas/openapi.yaml（OpenAPI 3.1.0）にあります。環境変数（CODETOPO_BIND、CODETOPO_DATA_DIR、CODETOPO_KEYS_FILE、CODETOPO_METERING_LOG）については schemas/README.md に記載されています。

MCP（codetopo-mcp）

17 個のツールと同じハンドラーレイヤーを公開する、stdio JSON-RPC サーバーです。内訳は、13 個のクエリ／整合性ツール（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）です。これにより、プロセス内の エージェントは一つのインターフェースを学ぶだけで、両方を利用できます。MCP の応答が HTTP の応答と 常に同一なのは、どちらも同じ codetopo-core クエリを呼び出す設計だからです。

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

ACP（codetopo-acp）

Agent Client Protocol を話す stdio エージェントです。ツールを呼び出すのではなく、 エージェントと対話するエディターやクライアント向けです。作業ディレクトリで セッションを開き、コード構造について自然な言葉で質問できます。

→ {"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 クエリを直接呼び出します。 LLM、ネットワーク、ファイルへの書き込みはありません。編集リクエストには、読み取り専用であることを正直に伝えて拒否します。stdout にはプロトコルフレームのみが出力され、診断情報は stderr に出力されます。

ホステッド API（codetopo Hosted）

当社が常時稼働させる、同じ HTTP API です。インデックスは当社がホストします。リポジトリ（公開 git URL またはアーカイブのアップロード）を送信すれば、ローカルへのインストールもサーバーの実行も不要で、キーを使ってどこからでもグラフにクエリできます。

1 キーあたり月額 US$19。

含まれる内容
有効なインデックス	25
クエリ	月 10,000 件
リポジトリのサイズ	1 インデックスあたり最大 50,000 ファイル

利用方法：

1. 申し込む — 決済は Stripe が処理します。
2. 支払い後、キーの請求ページが表示されます。そこで API キーを取得してください。 キーは一度しか表示されないため、表示されたら保存してください。
3. Authorization: Bearer <key_id>:<secret> を指定して、 https://codetopo-api.aimlds.org の API を呼び出します。セルフホスト型サーバーと同じ仕様です （schemas/ を参照）。

Stripe の領収書に記載されたリンクからいつでも解約できます。キーは有料期間の終了まで有効で、 その後失効します。

これは同じ製品をホステッド形式で提供するものです。このリポジトリのローカル CLI、MCP サーバー、 ACP エージェントは、引き続き無料のオープンソース（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    └──────────────┘              └──────────────┘

クレート	役割
codetopo-core	グラフモデル、ノード／エッジの種類、すべてのトラバーサルクエリ、スナップショット
codetopo-extract	tree-sitter 抽出器（Rust、TypeScript/JavaScript）
codetopo-store	SQLite 永続化 ＋ 改ざんを検知できるハッシュチェーン監査ログ
codetopo-cli	codetopo ヘッドレス CLI — クエリインターフェースのリファレンス
codetopo-server	codetopo-server axum HTTP API（core の薄いアダプター）
codetopo-mcp	codetopo-mcp stdio MCP サーバー（core の薄いアダプター）
codetopo-acp	codetopo-acp stdio ACP エージェント — 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 準拠の証拠：厳格な stdio クライアントと公式スキーマによる検証
• 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 エージェントの設計：ワイヤープロトコル、インテントのルーティング、読み取り専用の保証
• docs/phase-3-acp-verification.md — ACP 検証レポート
• docs/quickstart-verification.md — 上記のクイックスタートとサンプルクエリをクリーンなマシンで検証したレポート
• schemas/README.md — エージェント向けの 2 つの契約と、仕様が設計ドキュメントから逸脱している箇所
• CODE_SCHEMA.md — グラフスキーマ（§6 で集約優先のルールを定めています）

プライバシーポリシー

codetopo はすべてお使いのマシン上で動作します。MCP サーバー（codetopo-mcp）、CLI、およびこれらが作成するインデックスデータベースは、コード、クエリ、使用状況データを外部に送信することは一切ありません。アカウントも API キーもテレメトリーもなく、実行時のネットワーク通信もありません。インデックス作成時に読み取るのは指定したリポジトリのみで、書き込むのは指定したデータベースのパスのみです。データを削除するには、インデックスデータベースファイル（.db ファイル、または HTTP サーバーのデータディレクトリ）を削除してください。サーバー上には何も保存されないため、ほかの場所で消去するデータはありません。データを持ち出すには、snapshot コマンドでエクスポートしてください。グラフ全体を 1 つのポータブルな JSON ファイルとして書き出します。プライバシーに関するお問い合わせ：[email protected]。

ライセンス

• エンジン（codetopo-* クレート）：AGPL-3.0-or-later（LICENSES/ を参照）
• エージェント向け契約（schemas/：OpenAPI 3.1 仕様、MCP ツールカタログ）：Apache-2.0（schemas/LICENSE-APACHE を参照）

所有者：Nrupal Akolkar · Muse by Meta で構築 — Muse に参加し、参加後 48 時間以内に Settings でコード 101EEK を引き換えると、双方がトークンを獲得できます。