Graphlens Mcp

graphlens-mcp

コーディングエージェント（Claude Code、Cursor、および互換性のあるクライアント）に、プロジェクトのセマンティックコードグラフを提供する、無料のMITライセンスのMCPサーバーです。シンボル、ファイル間の呼び出し、参照、インポート、言語間の境界を把握できます。

ファイルを上から順に読んだり、名前をgrepしたりする代わりに、エージェントは構造をたどります。この関数を呼び出すのは誰か、これは何に依存しているのか、シグネチャを変更したら何が壊れるのかを調べられます。これはgraphlens分析エンジン上に構築された薄いランタイムレイヤーです。graphlensは仕組み（解析、安定したノード識別子、リゾルバー）を提供し、graphlens-mcpはストレージ、最新状態の維持、エージェント向けのインターフェースを担います。

📖 ドキュメント： https://neko1313.github.io/graphlens-mcp/

ステータス：初期段階です。コアとなるナビゲーションは機能します。既知の制限をご覧ください。

理由

コーディングエージェントは、grep、glob、ファイルを1つずつ読むという遅いやり方で構造を把握します。本来の作業に取りかかる前に、呼び出し経路を手作業で再構築しているのです。その動機は、ほかのコードコンテキストツールと同じです。エージェントにgrepをさせないこと。 graphlensを際立たせるのは、そのアプローチです。

多くのツールは、独自のコードモデルを構築することでこの問題に対応します。ヒューリスティックをつなぎ合わせた場当たり的なグラフでは、ツールごとにコードベースの捉え方が少しずつ異なり、どれも決定版とはなりません。graphlensは逆の道を選びます。言語本来の実際の解析エンジン、つまりrust-analyzer、gopls、TypeScriptコンパイラー、同梱のty型エンジンを基盤にしています。いずれも、業界ですでに信頼されているLSP品質のツールです。その結果、独自に作り上げた近似ではなく、プロジェクトの安定した実際の姿（ファイルや言語をまたいで、実際に何が何を呼び出しているのか）が得られます。安定した基盤があれば、その上に構築できます。変更の重要な部分にコンテキストを付与し、セマンティックなクラスターを自動抽出し、影響に関する質問に確実に答えられます。

その基盤となるのがgraphlensエンジンです。解析、安定したノード識別子、リゾルバーを提供します。graphlens-mcpはその上に構築された、エージェント向けのスマートなレイヤーであり、率直に言えば、エンジンの使い方を示す実例でもあります。グラフを永続化して（全体をメモリ上に保持せずに済むようにし）、その上にセマンティックおよびクラスタリングのレイヤーを追加し、編集に応じて最新状態を保ち、ナビゲーションツールと同梱のスキルとしてエージェントに公開します。この実例から、自立したシステムへと発展しています。市場の大手と比べても、安定性と再現性のある結果を目指しています。得意な分野もあれば不得意な分野もありますが、その違いについて率直に示します（比較をご覧ください）。

比較

graphlens-mcp には、再現可能な A/B ベンチマーク（benchmarks/）が同梱されています。同じエージェントを、互換性のある3つのコードコンテキスト MCP サーバー（graphlens、semble（セマンティック検索）、codegraph（グラフインデックス））と、各サーバーがモデル自身の記憶にどれだけ情報を追加するかを測る ツールなしの対照群に対して実行します。実際の Go／Rust／Python／TypeScript のコードベースを対象に実行し、LLM による判定は使わず、オラクルの正解データに照らして回答を 決定論的に採点します。SIMPLE の検索と、HARD の影響範囲／複数ファイルにまたがる質問に分けて評価し、精度だけでなくトークン数／ツール呼び出し数／費用も報告します。同じ精度なら、より安価な方式が優れているためです。

📊 結果（10 リポジトリ・3 モデル、強いモデルから本当に弱いモデルまで・採点対象約2,400回の実行 — 詳細な内訳、有意差検定、再現手順は ドキュメント：ベンチマークを参照してください）：

	SIMPLE の精度	HARD の精度	HARD のトークン数（中央値）	HARD の完了率
graphlens	0.980 – 1.000	0.899 – 0.921	22.4k – 34.1k	すべてのモデルで ≥ 0.959
codegraph	0.912 – 0.990	0.655 – 0.939	23.2k – 70.0k	最弱モデルでは 0.765 まで低下
semble	0.647 – 0.961	0.555 – 0.850	21.6k – 74.9k	最弱モデルでは 0.688 まで低下
なし（対照群）	0.366 – 0.681	0.453 – 0.685	0.1k – 0.9k	—

精度だけでは、請求額に関わる重要な数値、つまり タスクあたりの有料トークン数が見えません。HARD レベルで graphlens が消費するトークン数は、実行モデルが強くても弱くても一定（22k～34k）です。一方、codegraph と semble は最弱モデルで 70k を超え、graphlens の上限の2倍以上に膨らみます。それでも回答は改善せず、むしろ悪化します。graphlens だけが、ツールなしの対照群を明確に上回り、すべてのモデル層で完了率を0.95超に保ちます。テストした最弱モデル（gpt-oss-20b）でも、codegraph の約半分のトークン費用で HARD の精度0.900を維持します。タスクごとに対応付けたペアワイズのウィルコクソン符号順位検定により、弱いモデルでの差は統計的に有意であり、一部の外れ値タスクによるものではないことが確認されています。モデルごとの p 値と効果量はノートブックを参照してください。

インストール

Python ≥ 3.13 が必要です（graphlens から引き継いだ制約です）。

uv tool install graphlens-mcp      # or: pipx install graphlens-mcp

Python の言語解析はすぐに利用できます（型エンジンの ty が依存関係として同梱されています）。ほかの言語はすぐに解析できますが、ファイル間のセマンティクスを完全に利用するには、各言語のツールチェーンが必要です（TypeScript の場合は Node、Go の場合は Go ツールチェーンなど）。ツールチェーンがない場合、その言語は degraded と報告されますが、init が妨げられることはありません。

クイックスタート（2つのコマンド）

uv tool install graphlens-mcp        # 1. install
cd your-project && graphlens-mcp init  # 2. index + configure your agent

init はプロジェクトの言語を検出し、コードをローカルグラフにインデックス化して、エージェントの設定に MCP サーバーのエントリーを書き込み、ナビゲーションスキルをインストールします。自分で serve を実行する必要はありません。エージェントが設定から起動します。エージェントを再起動して、「create_order のシグネチャを変更すると、何が壊れますか？」のような質問をしてみてください。

コマンド

コマンド	処理内容
graphlens-mcp init	言語を検出 → ツールチェーンを診断 → 全体をインデックス化 → エージェントを設定 → スキルをインストール
graphlens-mcp serve	stdio 経由で MCP サーバーを起動します。あなたではなく、エージェントが起動します
graphlens-mcp status	検出された言語、ツールチェーンの状態、グラフのサイズ／鮮度を表示します
graphlens-mcp reindex	全体を再構築します（新しいツールチェーンをインストールした後など）
graphlens-mcp remove	エージェントから登録を解除し、（--purge-db を指定した場合は）ローカルグラフを削除します

便利な init フラグ：--root <dir>、--agent claude_code --agent cursor（繰り返し指定可能）、--no-agent、--no-skills、--db <path>。

グラフは <project>/.graphlens/graph.db（SQLite）に保存されます。再生成可能なキャッシュなので、安全に削除できます。reindex で再構築できます。同梱の init フローではコミットしないことを前提としているため、.graphlens/ を VCS の ignore 対象に追加してください。

サポート対象言語

言語	エンジン	初期状態
Python	ty（バンドル済み）	すぐに完全なセマンティクスを利用可能
TypeScript	Node ブリッジ	Node がない場合は degraded、Node をインストールすると完全なセマンティクスを利用可能
Go	Go ツールチェーン	ツールチェーンがない場合は degraded
Rust	SCIP / rust-analyzer	ツールチェーンがない場合は degraded
PHP	PHP パーサー	ツールチェーンがない場合は degraded

graphlens-mcp status は、言語ごとの実際のリゾルバーの状態を報告します。ツールチェーンがない場合、その言語はインストール方法のヒントとともに degraded（構造は解析済みですが、呼び出しや型は完全には解決されていません）と報告されます。init が妨げられることはありません。

エージェントツール

3 つのツールを使えば、シンボルやファイルに必要な情報をすべて、たどって調べられるグラフのノードとして取得できます。検索結果の行だけで終わることはありません。各レスポンスにはグラフ品質のステータス（ok | degraded）が含まれるため、エージェントが不完全な回答を完全なものと誤認することはありません。また、バックグラウンドでの再インデックスが実行中（その間、エッジが一時的に不完全になる可能性があります）であることを示す indexing フラグ（true）も含まれます。

ツール	目的
search	NAME、CONTENT、MEANING でコードを検索します。最初に使うツールです。シグネチャ付きのグラフノードを返すため（追加の呼び出しなしで回答できることもよくあります）、内容は正規表現ではなくリテラルとして照合されます。path_glob で範囲を指定できます（例："tests/*"、"*.ts"、サブツリーを除外する場合は "!tests/*"）。ランク付けされた上位 N 件の代わりに、一致するファイルをすべて列挙するには（上限なし、シグネチャなし）、exhaustive=true を設定します
relations	1 回の呼び出しでシンボルの近傍を取得します。呼び出し元、呼び出し先、実装者／サブクラス、呼び出し以外の参照を、それぞれのシグネチャとともに返します。影響分析用のツールです（「X を変更すると何が壊れるか？」「X を実装しているものは何か？」）
info	特定の対象を読み取ります。シンボル（ノード ID または名前）ならソース、シグネチャ、場所を返し、ファイルパスならシンボルのアウトラインを返します

search と relations は、シンボルの名前またはノード ID を直接受け付けるため、最初にノード ID を調べる必要はありません。どちらもレスポンスサイズに上限があります（ヒット数が多い場合は単純に切り詰めず、バンドルされた小型の埋め込みモデルで関連度順に並べ替えます）。また、リストに上限が適用された場合は実際の件数（callers_total、references_total など）も示すため、エージェントは推測せずに「22 件中 15 件を表示」と把握できます。埋め込みモデルを取得できない場合（初回実行時にネットワークがない場合など）、検索は透過的に名前／内容の照合に切り替わります。

最新状態の維持

グラフを最新の状態に保つ仕組みは 1 つです。ファイルシステムウォッチャーです（serve はデフォルトで起動します。無効にするには --no-watch を指定します）。ディスク上でファイルが変更されると、サーバーは接続されたファイル群（変更されたファイルと、それをインポートするファイルおよびそのファイルがインポートするファイル）を 1 回の完全な解析で再インデックスします。これにより、部分的なまま残すのではなく、ファイル間のエッジが正しく再構築されます。ファイルを削除すると、そのシンボルが除去され、インポーターが更新されます。ポーリングや、構造だけを対象にした「骨格」フェーズはありません。インデックスを作成または再作成するたびに、リゾルバーが生成可能な完全なグラフが作られます。補完策として、ウォッチャーがまだ処理していないファイルにツールがアクセスすると、同じ接続ファイル群の再インデックスが実行されます。

サーバー停止中に作成、削除、編集されたファイルは、イベントベースのウォッチャーでは検出できません。そのため、serve は起動時に 1 回だけ照合を行います。プロジェクトをスキャンし、新しいファイルのインデックスを作成し、なくなったファイルを除去し、変更されたファイルを更新してから、ウォッチャーに引き継ぎます。

既知の制限事項

• 接続セットの再リンク、深い波及： ウォッチャーは変更があったファイルと、その直接のインポーターおよびインポート先からなる 接続セット を再リンクします。プロジェクト全体ではありません。名前変更が複数の間接参照レイヤーに波及する場合、正確なグラフを得るには完全な reindex が必要になることがあります。変更されていない ファイルがすでにインポートしているファイルの作成には対応しています。新しいファイルのインデックス作成後、2 回目のインポーターパスでそのインポーターが再リンクされます。
• 増分編集時の言語間エッジ： 合成された COMMUNICATES_WITH エッジは、再インデックスされたファイルが関係するすべての境界について再合成されるため、新規または移動した公開側／利用側は、完全な reindex を行わなくてもリンクされます。境界から完全に外れる変更（ほかのファイルが引き続き利用しているエンドポイントを、ファイルが公開しなくなる場合）では、正確な言語間ビューを得るために完全な reindex が必要になることがあります。ただし、境界ベースのクエリでは、いずれの場合も接続を解決できます。

アンインストール

graphlens-mcp remove はエージェントからサーバーの登録を解除します。ローカルの .graphlens/ キャッシュも削除するには、--purge-db を追加してください。

開発

uv sync --all-groups   # install lint + test tooling
task check             # ruff + format-check + ty + bandit + pytest (the CI gate)
task docs:serve        # preview the docs site locally (needs Node + pnpm)

設計と不変条件については、ドキュメントサイトのアーキテクチャおよびセマンティック検索のページをご覧ください。

ライセンス

MIT — LICENSEをご覧ください。