cgraphy

cgraphy – コードナレッジグラフ MCP サーバー

論文（DOI）： https://doi.org/10.5281/zenodo.21422935
PyPI： https://pypi.org/project/cgraphy/
GitHub： https://github.com/pmgarg/cgraphy

cgraphy は、Claude Code、Codex CLI、Cursor、Gemini CLI などの AI コーディングエージェント向けの、Python コードナレッジグラフおよび Model Context Protocol（MCP）サーバーです。

cgraphy はあらゆるコードベースをナレッジグラフにインデックス化します。関数、クラス、ファイルをノードとし、呼び出し、インポート、継承、Git の共変更履歴をエッジとして扱います。そして、Model Context Protocol を通じて、トークン予算に合わせたコンパクトなグラフの一部を AI アシスタントに提供します。プロンプトのたびに状況を把握するために何十ものファイルを読み直す代わりに、エージェントはグラフに問い合わせ、数千トークンで関連するサブグラフを取得できます。

• あらゆる言語に対応。 Python、TypeScript/JavaScript、Java、Go、C、C++、Rust では完全な情報（呼び出し、インポート、継承）を抽出します。tree-sitter を使って、さらに 20 以上の言語から定義レベルの情報を汎用的に抽出します。設定ファイルやドキュメントファイルも要約を通じて参加します。
• 重要度順にランク付け。 コードグラフ上の PageRank により、各回答で重要なシンボルが優先されます。
• トークン予算に対応。 cgraphy_context はシンボルを中心にグラフを貪欲に展開し、指定したトークン予算に達した時点で正確に停止します。コストはリポジトリの大きさではなく、質問の内容に応じて変わります。
• Git を考慮。 --git-history はコミット履歴を調べ、一緒に変更されるファイル（論理的な結合）を特定します。これは静的解析では検出できないエッジの種類です。
• API キー不要。 意味的な要約は、エンリッチループを通じてホストエージェント自身が作成します。要約はコンテンツハッシュによって再インデックス後も保持されます。
• インフラ不要。 .cgraphy/ 内に SQLite ファイルが 1 つあるだけです。サービス、デーモン、ベクトルデータベースは不要です。
• エンドツーエンドで実証済み。 SWE-bench Lite での 400 回以上の管理されたエージェント実行において、デプロイ構成は実際の GitHub の課題 57 件中 14 件対 8 件を解決しました（公式 Docker ハーネスを使用）。kubernetes（ファイル 26K 件、ノード 219K 個）を 49 秒でインデックス化し、1.6 秒のサイクルで最新状態を維持し、クエリには 1～152ms で回答します。すべてのベンチマークと予測はこのリポジトリにあります（研究論文とベンチマーク）。

インストール

pip install cgraphy        # or: uv tool install cgraphy

クイックスタート

cd your-repo
cgraphy init          # one command: MCP config + agent steering + index

cgraphy init は次の 3 つを行います。

1. プロジェクト専用の .mcp.json を書き込みます。これは Claude Code のすべての形態（CLI、VSCode 拡張機能、デスクトップアプリ）で自動的に読み込まれます。
2. CLAUDE.md と AGENTS.md にエージェントへグラフを参照するよう指示するガイダンスブロックを追記します（ファイルを読む前に cgraphy_overview → cgraphy_search → cgraphy_context を使用します）。これにより、グラフが大量のファイル読み込みに実際に取って代わります。（エージェントを強制することはできず、誘導することしかできません。指示ファイル、説得力のあるツールの説明、そしてツールが実際により高速であることがその仕組みであり、効果を発揮します。）
3. Git の共変更履歴を使ってインデックスを構築します。

または、アシスタントに MCP サーバーを手動で登録します。

Claude Code

claude mcp add cgraphy -- uvx cgraphy serve /path/to/repo

Codex CLI（~/.codex/config.toml）

[mcp_servers.cgraphy]
command = "uvx"
args = ["cgraphy", "serve", "/path/to/repo"]

Gemini CLI（~/.gemini/settings.json）／Cursor（.cursor/mcp.json）

{"mcpServers": {"cgraphy": {"command": "uvx",
                            "args": ["cgraphy", "serve", "/path/to/repo"]}}}

8 つのツール

読み取り／全体把握：

ツール	返される内容	エージェントが使うタイミング…
cgraphy_overview	リポジトリのマップ：サブシステム、重要度順の主要シンボル、すべてのファイル	最初に、全体を把握するためにファイルを読む代わりに
cgraphy_search	file:line と概要を含む、順位付けされた一致結果（[semantic] エクストラがインストールされている場合は、語彙検索とセマンティック検索を組み合わせます）	grep／ディレクトリ一覧の前に
cgraphy_context	トークン予算内でのシンボル周辺のサブグラフ（呼び出し元、呼び出し先、インポート、同時変更）	ファイル全体を読む代わりに
cgraphy_read	1 つのシンボルのソースのみ。行番号付きで、予算に応じた範囲	ファイル全体を読む代わりに

編集／レビュー — グラフを変更ループに組み込むツール：

ツール	返される内容	エージェントが使うタイミング…
cgraphy_impact	影響範囲：直接および推移的な依存先、影響を受けるテスト、過去に同時変更されたファイル	共有コードを変更する前に
cgraphy_diff_context	作業中の git diff を、変更対象のシンボル、その利用箇所、関連するテストに対応付けたもの	コミット前／作業再開時

情報の充実化：

ツール	返される内容	エージェントが使うタイミング…
cgraphy_enrich	1 行の概要がまだ必要なシンボルのバッチ	「グラフを充実させて」と依頼されたとき
cgraphy_store_summaries	保存の確認と残りの件数	作成した概要を保存するとき

取得は利用状況を考慮します。エージェントが繰り返し問い合わせるシンボルには、今後のコンテキスト展開で小さな上限付きの加点が適用されます（テレメトリーはローカルの SQLite ファイル内に保管され、マシンの外部に送信されません）。

セマンティック検索（任意）

pip install "cgraphy[semantic]"

軽量な静的埋め込み（model2vec、CPU のみ、torch 不使用）を追加し、相互順位融合によって FTS5 と組み合わせます。課題形式の文章（「ログインが壊れている」）とコード識別子（validate_jwt）の語彙の隔たりを埋めます。

グラフは自動修復されます。ツールは古いファイルを検出し、回答する前に変更されたファイルのみを対象としてインデックスを増分更新します。

グラフの充実化

構造は自動的に抽出されますが、意味は概要から得られます。エージェントに一度だけ伝えてください。

cgraphy グラフを充実させて

すべてのシンボルに 1 行のセマンティックな概要が付くまで、cgraphy_enrich → cgraphy_store_summaries を繰り返します。概要は各シンボルのソースのハッシュに紐付けられるため、関数を 1 つ編集しても無効になるのはその関数の概要だけです。

CI では、cgraphy index --summarize を使うと、自分の Anthropic API キーで概要を事前生成できます（pip install cgraphy[summarize] を実行し、ANTHROPIC_API_KEY を設定してください）。

ビューアー

cgraphy view .        # http://localhost:8787

依存関係のないローカルページです（Cytoscape.js をバンドル）。検索、種類別の色分け、クリックによる詳細表示、ダブルクリックによる近傍の展開ができ、同時変更を表すエッジは破線で表示されます。

削減効果の測定

python scripts/benchmark.py /path/to/repo "your question"

cgraphy を使って全体を把握する際（概要＋検索＋コンテキスト）にエージェントが消費するトークン数と、すべてのコードファイルを読む場合のトークン数、および削減率を出力します。

ローカライズベンチマーク（研究用ハーネス）

python scripts/eval_localization.py /path/to/repo 50

リポジトリの履歴から修正に関連するコミットを抽出します（件名をクエリとして使い、変更されたファイルを正解データとし、同時変更の抽出では評価対象のコミットを除外します）。その後、アブレーションの段階 — FTS のみ、+PageRank、+グラフ展開、±同時変更エッジ — の性能を、hit@5／hit@10／MRR とトークンコストで評価します。LLM の呼び出しも人手による採点も不要で、完全に再現可能です。結果と論文の草稿は paper/ にあります。

動作の仕組み

1. cgraphy index はリポジトリを走査し（.gitignore と .cgraphyignore を尊重します）、各ファイルを tree-sitter で解析して、ノードと エッジを .cgraphy/graph.db（SQLite + FTS5）に保存します。再インデックスは コンテンツハッシュに基づいて差分のみ処理します。
2. リゾルバーは、修飾名を使ってファイル間の参照（呼び出し、インポート、継承）を 可能な範囲で解決します。未解決の名前は保持し、削除しません。
3. PageRank はエッジグラフ上で実行され、すべてのクエリで重要なシンボルが 優先して表示されます。検索では、FTS5 の関連度とランクを組み合わせます。
4. cgraphy serve は、stdio 経由で 5 つの MCP ツールを公開します。
5. 任意：--git-history を指定すると、git log から抽出した重み付きの共変更エッジが 追加されます。

設計の詳細：docs/superpowers/specs/2026-07-08-cgraphy-design.md

cgraphy の引用

研究やツールで cgraphy を使用する場合は、論文を引用してください。

@misc{garg2026cgraphy,
  author = {Garg, Prateek Mohan},
  title  = {Which Graph Signals Pay for Their Tokens? cgraphy: A Token-Budgeted
            Code Knowledge Graph as a Portable Context Layer for AI Coding Agents},
  year   = {2026},
  doi    = {10.5281/zenodo.21422935},
  url    = {https://doi.org/10.5281/zenodo.21422935},
  note   = {Preprint}
}

ライセンス

MIT

mcp-name: io.github.pmgarg/cgraphy