codegraph-mcp

Claude Code（CLI および VS Code拡張機能）に、コードベースの検索可能なモデルを提供するローカルMCPサーバー。どこで何が定義され、誰が何を呼び出し、何が何に依存し、以前のセッションでどのような決定が下されたかを扱います。これがないと、エージェントは毎セッションgrepとファイル単位の読み取りでアーキテクチャを再発見することになります。これがあれば、構造に関する質問には構造的な答えが返ります：

• より安全な変更 — 関数に手を加える前に、エージェントは影響範囲（analyze_impact）、全呼び出し箇所（find_callers）、全参照箇所（find_references）、依存する全モジュール（who_imports）を確認します。grepがたまたま見つけたコードを編集するのではありません。

• より速い把握 — 1回のrepo_map呼び出しで、インポート中心性によってプロジェクトを把握できます。find_symbolやsemantic_search（「auth tokenはどこで検証されているか」）は、適切なコードに直接到達します。

• 継続性 — save_note / recall_notesが、決定事項や注意点をセッションをまたいでリポジトリ単位で引き継ぎます。

• より低コストな探索 — 上記の結果として、エージェントはファイル全体ではなくシグネチャを読み取るようになり（file_skeleton、read_symbol）、透過的なプロキシが会話履歴をワイヤーレベルで圧縮します。usage_statsで削減効果を報告します。

100%ポータブル: 純粋なJavaScript + WASM文法。node-gypもネイティブコンパイルも不要です。npm installはWindows、macOS、Linuxでまったく同じ動作をします。

エージェントに公開されるツール

理解とナビゲーション

変更の安全性

目的を絞った読み取り

メモリと運用

対応言語：JavaScript、TypeScript、TSX、Python、Go、Rust、Java、Ruby、C、C++、C#、PHP、GDScript。インデクサーが抽出できなかったファイルはrepo_mapでカウント・報告されるため、部分的なカバレッジも常に把握できます。

Related MCP server: MCP Context Manager

インストール

Node.js ≥ 20とClaude Codeが必要です。Windows / macOS / Linuxで同じ手順です：

git clone https://github.com/denzharkov/codegraph-mcp
cd codegraph-mcp && npm install
node bin/codegraph-mcp.js install     # registers in Claude Code (user scope)

これだけです — サーバーはclaude mcp addコマンドを実行するだけで、CLI と VS Code拡張機能の両方で動作します（MCP構成を共有します）。claude mcp listまたはClaude Code内の/mcpで確認できます。

サーバーは起動されたディレクトリ（Claude CodeはプロジェクトディレクトリでMCPサーバーを起動します）、または--root / CODEGRAPH_ROOTで指定されたパスをインデックス化します。ユーザースコープではなく単一プロジェクトに限定するには、そのプロジェクトに.mcp.jsonを追加してください：

{
  "mcpServers": {
    "codegraph": {
      "command": "node",
      "args": ["/absolute/path/to/codegraph-mcp/bin/codegraph-mcp.js"]
    }
  }
}

削除するには：node bin/codegraph-mcp.js uninstall を実行します。

ゼロ設定

CLAUDE.mdの編集やプロンプトの調整は不要です。サーバーは使い方のガイダンス（「関数を変更する前にanalyze_impactを実行」「grepの代わりにfind_symbol」「ファイルを読む前にfile_skeleton」など）をMCPのinstructionsフィールドで提供し、Claude Codeが接続時にエージェントのコンテキストへ自動的に注入します。インストール、登録、完了です。

透明プロキシ（削減の保証）

上記のMCPツールは、エージェントが使うことを選択した場合にのみトークンを削減します。プロキシレイヤーはその逆の働きをします — ContextForgeと同様に、Claude CodeとAnthropic APIの間に位置し、エージェントの挙動に関係なくトラフィックを圧縮します：

• 履歴の重複排除: 会話に同一のツール結果が含まれている場合（同じファイルを2回読んだ、繰り返されるコマンド出力など）、最初の1回を除くすべての項目は、リクエストがマシンの外部に出る前に短いスタブに置き換えられます。最初の1回はそのまま保持されるため、モデルが実際に利用できる情報が失われることはありません。また、プロンプトキャッシュのプレフィックスは維持されます（常に新しい末尾だけが書き換えられるため、重複排除が古いターンでキャッシュミスを引き起こすことはありません）。

• 古い読み取りのスケルトン化: ファイルが読まれ、編集され、再度読み取られた場合、履歴内の古い完全コピーはtree-sitterシグネチャスケルトン（行範囲付きの imports + 宣言）に置き換えられます。直近の読み取りは無造作にそのまま残ります。非コードファイルは先頭＋末尾の切り詰めにフォールバックします。クラッシュの変換はコンテンツの純関数であるため、同じリクエストは同じバイト列を生成し、プロンプトキャッシュは1回の書き換えで再安定します。

• プロンプトグラウンディング: あなたのメッセージはモデルに届く前に変換されます — これが安全な方向です。言葉が書き換えられることは決してありません。プロキシの代わりに、そのメッセージが言及している識別子に関する、検証可能な事実（種類、file:lines、シンボルグラフからの1行のドキュメント）でラベルされた純正の（明示的な）ブロックを追加します。モデルは、ツールのラウンドトリップで同じ事実を発見するではなく、最初から方向を得てやり始めます。グランドされるのは完全一致の識別子だけ。新しいブロックが追加されるのは最新のメッセージだけ。ブロックはメモ化されるので、履歴はプロンプトキャッシュに対してバイト単位で安定します。

• 認証ヘッダー（APIキーまたはOAuth）はそのまま通過します。プロキシが解析できない場合も、元のまま転送されます。ストリーミング（SSE）は透過的にパイプされます。

codegraph-mcp wrap                 # like 'cf wrap claude': proxy + claude in one command
codegraph-mcp proxy --port 3210    # or run the proxy standalone

VS Code拡張機能の場合は、プロキシを実行し、プロジェクトまたはグローバル設定で拡張機能にそれを指定します：

{ "env": { "ANTHROPIC_BASE_URL": "http://127.0.0.1:3210" } }

累積の削減量は~/.codegraph/proxy-stats.jsonに記録され、プロキシ起動時に表示されます。

CLIの使用

node bin/codegraph-mcp.js index                # index cwd, print stats
node bin/codegraph-mcp.js index --root ~/proj  # index another directory
node bin/codegraph-mcp.js dashboard            # HTML report, opens in browser
node bin/codegraph-mcp.js map                  # interactive architecture map
node bin/codegraph-mcp.js                      # start stdio MCP server (cwd)

アーキテクチャマップ（.codegraph/map.html）は、インデックスから完全に導出された、層状のC4スタイルビューです：

• 概要 — サブシステムカード（トップレベルディレクトリ）とそれらの間の重み付きインポートエッジに加えて、自動導出された出発点（ハツ、エントリポイント、最大モジュール）。

• サブシステム — 1つのディレクトリのファイルと、そのimportエッジに加え、折りたたまれた隣接サブシステムを表示します。ファイルをクリックで依存元・依存先を辿り、もう一度クリックでドリルダウンします。

• ファイル — ファイル内のシンボルを、intra-file呼び出し矢印、インポーター、インポートを操作可能な列として表示します。

どのレベルでも、構造だけでなく明確に**が語られます。説明はコード自身のドキュメントから取得されます — ファイルとシンボルのモジュールドキュメント文字列とヘッダコメント、フォルダーとリポジトリそのもののためのREADME / __init__.py / index.* — そしてフォルダカード、ツールチップ、サイドパネルに表示されます。

各レベルはディープリンク可能で（#d=src、#f=src/proxy.js）、/で検索、表示中、Escで1つ上のレベル、ドラッグでパン、ホイールでズーム。自己完結HTMLでオフライン動作します。

ダッシュボード（ファイル書き出しだけなら--no-open）は.codegraph/dashboard.htmlに出力されます：トークン削減、ツールごとの利用、インデックス化された言語、最もインポートされたファイルです。静的HTML、サーバー不要、ライト/ダーク対応。エージェントがusage_statsでdashboard=trueを要求することで生成することもできます。

仕組み

• ファイルはweb-tree-sitterを介してtree-sitterのWASMグラマラ（tree-sitter-wasmsパッケージ）で解析されます — プラットフォーム固有のバイナリなし。

• 抽出器は、各ASTを1回だけ走査し、定義、呼び出しエッジ、インポートを言語ごとに収集します（src/languages.js）。

• グラフは対象リポジトリ内の.codegraph/index.jsonに永続化されます。更新はインクリメンタル（更新日時＋サイズ）且つスロットル制御されているので、クエリは高速なままです。

• node_modules、ビルド出力、ベンダー化されたファイル、ミニファイされたファイルはスキップされます。シンプルなルート.gitignoreパターンも尊重されます。

• semantic_searchはローカル埋め込みモデル（transformers.js によるall-MiniLM-L6-v2、オプション依存）を使用します。初回利用時に約25MBを~/.codegraph/modelsにダウンロードし、シンボルベクターをリポジトリごとに.codegraph/vectors.binへキャッシュします。オフラインまたは依存がない場合はサイレントにキーワード検索へフォールバックします — 他すべてはその点に関わらず動作します。

自分の.gitignoreにコードグラフ/を追加してください（キャッシュとあなたのプライベートノートです）。

ライセンス

MIT