Rarefaction

Rarefaction — AI コーディングエージェント向け LSP 呼び出しグラフ MCP サーバー

Rarefaction は、プロジェクトの言語サーバー（Language Server Protocol、LSP）から、1つのシンボルの呼び出しグラフとコードコンテキストをコーディングエージェントに直接提供する Model Context Protocol（MCP）サーバーです。関数、メソッド、型について尋ねると、1回の呼び出しで、シグネチャとドキュメント、本文、呼び出し元（テストには印が付きます）、呼び出し先、実装元、そのシンボルに到達するテスト、変更の影響を受ける可能性があるファイルの簡潔なリストを取得できます。エージェントはファイル全体を開いて検索する代わりにこれを読み取るため、コンテキストウィンドウを小さく保ち、調査に使うトークンを減らせます。

Claude Code、Codex、および stdio 経由の任意の MCP クライアントで動作します。プロファイルは Swift、Rust、C/C++、TypeScript/JavaScript、Python、WebAssembly テキスト（WAT）に対応しています。

同梱の TypeScript フィクスチャ（fixtures/SampleTypeScript）に対して実行します。

# scale — engine.ts:2:17

```
function scale(value: number): number
```

Double one input sample.

## Callers (2, 1 in tests)
- render — render.ts:2 (calls at 3)
- · testScale — engine.test.ts:2 (calls at 3) [test]

## Tests that reach it (1)
- testScale — engine.test.ts:2

Run only these:
```
npm test -- "engine.test.ts"
```

## Live files (3 of 3)
- engine.test.ts
- engine.ts
- render.ts

_11 LSP requests, 6430 ms (includes language-server cold start); index on-open_

言語サーバーのインデックス作成が完了すると、呼び出しにかかる時間は1秒未満です（ripgrep では中央値 80 ms、800ファイルの IronRDP ワークスペースでは 220 ms）。これらのプロジェクトでは、サーバーの初回起動に 6〜16 s かかりますが、セッションごとに1回だけです。

役立つ場面

• AI コーディングエージェントのトークン使用量を削減します。 範囲を限定した1つの回答で、ファイル全体の読み込みや検索を何度も行う必要がなくなります。ripgrep と IronRDP の実際のコミット50件で測定したところ、回答のバイト数は、回答に記載されたファイルを一度読む場合の中央値で6〜7%でした。エージェントのセッション全体でどれだけ節約できるかは、まだ測定していません。ライブセットの不足点など、詳しくはdocs/measurement.mdを参照してください。
• 呼び出しグラフと影響分析。 「この関数を呼び出すのは何か、変更すると何が壊れるか」を確認できます。デフォルトでは、呼び出し元を2階層、呼び出し先を1階層に加え、実装と型階層も取得します。すべて範囲が制限され、切り詰められた場合は印が付きます。
• 実行するテストの選定。 そのシンボルに到達するテストと、プロジェクトのテストランナーでそれらだけを実行するコマンドを確認できます。
• 不慣れなコードベースの把握。 単純な名前、修飾名、正確な path:line:column 位置を指定できます。曖昧さがある場合は推測せず、正確な位置の一覧を返します。
• カバレッジについて正直な回答を得られます。 インデックスが古い場合、サーバーがまだインデックスを作成中の場合、呼び出し階層に対応していない場合も、隠さず回答内で報告します。

LSP 呼び出しグラフに MCP サーバーが必要な理由

言語サーバーはすでに呼び出しグラフを正確に把握しています。「参照を検索」と「呼び出し階層」がまさにそれです。エディターや LSP ツールでは一度に 1 ホップずつ取得するため、エージェントはホップごとにツール呼び出しとコンテキストのやり取りが必要になります。エージェントに必要なのは、プロジェクト内に絞り込み、テストを見分けたうえで、一度に読み切れるサイズにまとめた、数ホップ以内のすべての情報、つまり閉包です。このサーバーは、その組み合わせを実現します。意図的に言語に依存しない設計で、コアは LSP のみを扱い、それ以外は扱いません。各言語に必要なのは、小さなプロファイルだけです。

関連するツールとの比較：

アプローチ	エージェントが得られるもの
ファイルの読み込みと grep	ファイル全体。呼び出しではなく、テキストの一致
リクエストごとの LSP ツール（定義、参照、呼び出し階層）	正確な回答。ただし、ツール呼び出しごとに 1 ホップ
Serena	LSP を介したシンボルナビゲーションとセマンティック編集。このツールと併用できます
Rarefaction	1 回の呼び出しで、1 つのシンボルに関する範囲を限定した複数ホップの呼び出しグラフ、テスト、開いているファイル

インストール

Node 22.22.2 以降が必要です。macOS と Linux で使用しています（CI は Ubuntu で実行）が、Windows ではテストしていません。TypeScript と Python の言語サーバーがバンドルされています。必要なその他の言語サーバーをインストールし、クライアントが起動時に使用する PATH に追加してください。言語と設定を参照してください。Swift には、Xcode を備えた macOS（または sourcekit-lsp を含む Swift ツールチェーン）が必要です。

プラグインとして使用（Claude Code と Codex）

プラグインには、npx -y rarefaction-lsp-mcp で起動するサーバーと、ファイル全体を読み込む前に status と orient を、編集前に scope を呼び出すようエージェントに指示する orient-first スキルがバンドルされています。

# Claude Code
claude plugin install rarefaction --marketplace ip2k/rarefaction

# Codex
codex plugin marketplace add ip2k/rarefaction
codex plugin add rarefaction@rarefaction

Claude Code のセッションでは、/plugin install rarefaction --marketplace ip2k/rarefaction でも同じことができます。その後、セッションを再起動するか、再接続してください。

MCP サーバーとして使用

claude mcp add --scope user --transport stdio rarefaction -- npx -y rarefaction-lsp-mcp
codex mcp add rarefaction -- npx -y rarefaction-lsp-mcp

rust-analyzer または wat_server がクライアントの PATH 以外の場所にある場合は、-- の前に --env PATH="$HOME/.local/bin:$HOME/.cargo/bin:$PATH" を追加してください。ツールは status、orient、scope です（Claude Code では mcp__rarefaction__status、mcp__rarefaction__orient、mcp__rarefaction__scope）。3 つとも読み取り専用なので、繰り返しプロンプトが表示されないよう、権限で許可できます。Codex では、最初のインデックス作成に時間をかけられるよう、~/.codex/config.toml に次のように指定してください。

[mcp_servers.rarefaction]
startup_timeout_sec = 20
tool_timeout_sec = 180

サーバーには --root <path> と --profile <id> を指定できます。明示的に指定した --root が最優先され、次に Claude Code の CLAUDE_PROJECT_DIR、その次に作業ディレクトリが使用されます。すべてのプロジェクトで対応するすべてのプロファイルを使用できるよう、ユーザー全体に適用する登録では、どちらも設定しないでください。MCP のドキュメントについては、Claude Code と Codex を参照してください。

クローンから使用

独自の変更を実行するには、ビルドしてコンパイル済みのエントリを登録してください。

git clone https://github.com/ip2k/rarefaction.git
cd rarefaction
npm ci && npm run build
claude mcp add --scope user --transport stdio rarefaction -- "$(command -v node)" "$PWD/dist/index.js"

サーバーを変更した後は再ビルドし、クライアントセッションを再起動するか、再接続してください（/mcp）。

動作確認

プロジェクトで新しいチャットを開始し、エージェントに status を呼び出してから、既知のシンボルに対して orient を呼び出すよう依頼してください。status.root がプロジェクトと一致し、status.profiles で選択されたエントリが ok: true になっている必要があります。1 つの登録で、対応するすべての言語を扱えます。各言語サーバーは必要になったときに起動します。

エージェントへのガイダンス

プラグインのスキルには、この内容が含まれています。プラグインを使わない場合は、~/.claude/CLAUDE.md、AGENTS.md、またはプロジェクトの指示ファイルに以下を追加してください。

新しいプロジェクトでは rarefaction の status ツールを 1 回使い、ファイル全体を読む前に関連するシンボルに対して orient を、シンボルを編集する前に scope を使ってください（参考情報として、一覧にあるファイル以外も確認してください）。複数の言語が混在するリポジトリでは profile、またはワークスペース相対の path:line:column を指定してください。ワークスペースのメンバーではないネストされたパッケージでは project を指定してください。まずデフォルトのグラフ範囲を使用し、必要な場合にのみ拡張してください。鮮度とカバレッジに関する助言に従い、該当する場合は FFI／生成されたバインディングを個別に確認してください。

Xcode プロジェクト

Xcode プロジェクトでは、sourcekit-lsp がコンパイラーフラグを取得できるよう、ビルドサーバー設定が必要です（SwiftPM パッケージでは不要です）。

brew install xcode-build-server
cd /path/to/App && xcode-build-server config -project App.xcodeproj -scheme App
echo buildServer.json >> .gitignore

次に、Xcode または xcodebuild で一度ビルドします。インデックスの鮮度は最後にビルドした時点に依存し、ソースファイルのほうが新しい場合は orient がその旨を示します。保存したソースの編集内容は、後続のクエリの前に開いている LSP ドキュメントへ送信されますが、Xcode プロジェクトでは、ファイル間インデックスを更新するために、引き続き新たなビルドが必要です。

ツール

ツール	内容
orient	{symbol, profile?, project?, up?, down?, max_nodes?, include_body?, max_body_lines?} — 上記の情報をまとめて返します。symbol には updateLocation、Engine.updateLocation、path/File.swift:204:10 を指定できます。名前が曖昧な場合は、正確な位置を列挙したエラーが返されます。
scope	{symbol, profile?, project?, up?, down?, max_nodes?} — そのシンボルへの変更に関係する作業範囲です。orient の呼び出しグラフに含まれるファイルに加え、そのシンボルのファイルまたは呼び出しグラフ内のファイルと、過去のコミットで同時に変更されたファイル（git 履歴から取得）を、それぞれの理由とともに示します。参考情報として、読むべきものと確認すべきものを列挙します。無視しても安全なものを示すものではありません（測定済みの網羅率）。
status	{profile?, project?} — サーバーが確認できる情報です。プロファイルの一覧と選択中のプロファイル、ビルドサーバー設定などの前提条件、インデックスの鮮度、サーバーが提供する LSP 機能を示します。orient で何も見つからない場合は、最初にこれを呼び出してください。

予定：impacted_tests（テストに限定した上方向の探索を、実行可能な選択として返します）。

言語と設定

プロファイル	言語サーバー	前提条件／対象範囲
swift	sourcekit-lsp	Xcode または Swift ツールチェーン。SwiftPM、またはビルドサーバー設定を含む Xcode
rust	rust-analyzer	Cargo.toml または rust-project.json。組み込み／no_std／Wasm ターゲット設定に対応。プロジェクトでツールチェーンを固定している場合は、rustup component add rust-analyzer --toolchain <channel> が必要です（status に表示されます）
c	clangd	C／C++。正確なインクルードパスと定義には compile_commands.json または compile_flags.txt が必要です
typescript	typescript-language-server	TypeScript／JavaScript、TSX／JSX。サーバーと TypeScript は依存関係として同梱されています
python	Pyright	Python とスタブ。同梱されています。環境に合わせてインタープリター／インポートパスを設定してください
wasm	wat_server	WebAssembly の .wat テキスト。PATH 上にビルド済みサーバーをインストールしてください

サーバーは各言語サーバーの機能を確認します。呼び出し階層がない場合、 orient は参照とそれを含むシンボルを報告しますが、それらの参照が 呼び出しであるとは示しません。WebAssembly 向けにコンパイルされた ネイティブの Rust／C ソースには rust／c を使用します。.wasm バイナリには .wat への逆アセンブルが必要です。WAST テストスクリプト、 ベンダーアセンブリ、間接的なランタイムディスパッチ、言語間の FFI エッジは、 統合グラフとしてインデックス化されません。

ワークスペースのルートにある任意の .rarefaction.json で、各プロファイルを 設定できます。project、プロファイルの root、相対位置クエリのパスは、 そのワークスペースを基準とします。project を指定しない位置クエリは、 ファイルのクレートを取り込む最外層の Cargo ワークスペース（メンバー、 package.workspace ポインター、またはルートパッケージのパス依存関係として） から回答されます。それに該当しない場合は、最も近いサポート対象のプロジェクト マーカーから回答されます。この結果、外側のプロジェクトの一部が対象外になる 場合は、その旨と指定すべき project を警告で示します。TypeScript は例外です。 TypeScript 言語サーバーは一度に 1 つの tsconfig.json プロジェクトに回答するため、 パッケージごとに tsconfig.json がある npm、yarn、pnpm のワークスペースでは、 project の指定の有無にかかわらず、ほかのパッケージにある呼び出し元は一覧に 表示されず、警告にもその旨が示されます。検索は .git を含むディレクトリで 停止するため、ワークスペース内にネストされた git worktree、サブモジュール、 その他のチェックアウト内の位置は、そのチェックアウトのみを基準に回答されます。 位置にはそのパスをプレフィックスとして指定し、名前だけの場合は project に そのチェックアウトを指定してください。複数のプロファイルが混在する ワークスペースで名前だけを指定するには、profile または設定済みの default_profile が必要です。

{
  "default_profile": "typescript",
  "profiles": {
    "rust": {
      "root": "firmware/rust",
      "initializationOptions": {
        "cargo": { "target": "thumbv7em-none-eabihf", "features": ["board"] }
      }
    },
    "c": { "args": ["--background-index", "-j=2", "--compile-commands-dir=/absolute/local/build"] },
    "python": {
      "initializationOptions": { "python": { "pythonPath": "/absolute/project/.venv/bin/python" } }
    }
  }
}

command、args、env、initializationOptions で各プロファイルの起動設定を 上書きできます。初期化オブジェクトは再帰的にマージされます。 Rust の cargo チェック、ビルドスクリプト、proc マクロは、意図しないコンパイルを 避けるため、デフォルトでは無効です。生成コード／展開後のコードがプロジェクトで 必要な場合は、明示的に有効にしてください。この設定を変更した後は、MCP 接続を 再起動してください。実行ファイルが見つからない場合は、セットアップの案内とともに status に表示されます。

グラフ出力のデフォルトは、方向ごとに 50 ノード、呼び出し元 2 階層、 呼び出し先 1 階層、本文 80 行です。max_nodes、up、down、 または include_body: false を使って、コンテキストサイズを調整できます。 切り詰めが発生した場合は明示されます。ワークスペースのインデックスがない場合、 名前検索は最大 200 個のソースファイルをスキャンします。必要に応じて、 正確な位置またはより小さいプロジェクトを指定してください。

分析用のコンパイルデータベースとターゲットの制限については、 組み込み C、JieLi、WebAssembly のセットアップを参照してください。

Serena と Rarefaction の併用

Serena は、シンボルナビゲーション、 診断、セマンティック編集でこのサーバーを補完します。 docs/serena.md では、バージョンを固定したインストール、 WAT アダプター、プロジェクトの言語設定、制限事項、検証について説明しています。

プライバシー

Rarefaction はすべてお使いのマシン上で動作します。プロジェクトのファイルを読み取り、ローカルの stdio 経由で言語サーバーと通信します。ネットワークリクエストは行わず、テレメトリーも収集しません。起動する言語サーバーの動作は、エディター内での動作と同じです（たとえば、rust-analyzer は cargo metadata を実行し、クレートのインデックスを取得する場合があります）。初回使用時に、npx が npm からパッケージをダウンロードします。

開発

npm ci && npm run build
npm test                        # unit + real LSP integration; external servers skipped if absent
claude plugin validate .        # plugin and marketplace manifests
node scripts/verify-codex.mjs   # exercise the registered MCP through Codex, no model turn
npx tsx scripts/try.ts --root fixtures/SampleTypeScript orient '{"symbol":"scale"}'

ロゴとアイコン（Rosé Pine Moon）は python3 tools/render_logo.py で生成されます。README の図（ライトモード用の Dawn、ダークモード用の Moon）は python3 tools/render_diagrams.py で生成されます。fixtures/ 内のフィクスチャは、各言語につき 1 つ用意された小規模な合成プロジェクトです。CI は clangd と rust-analyzer をインストールしてテストスイートを実行します。リリースワークフロー（v* タグのプッシュ、または main での「Run workflow」）では、すべてのバージョン情報が一致していることを確認し（package.json、server.json、両方のプラグインマニフェスト）、npm と MCP Registry に io.github.ip2k/rarefaction-lsp-mcp として公開した後、GitHub リリースを作成します。docs/measurement.md にはプロジェクトが自らに課しているしきい値が記載されています。docs/decisions.md には、現在の構成に至った理由が記録されています。

ライセンス

Copyright (C) 2026 Sean (ip2k).

このプログラムはフリーソフトウェアです。Free Software Foundation が公開する GNU General Public License の条項に従って、再配布または改変できます。ライセンスのバージョンは 3、または（任意で）それ以降のバージョンです。このプログラムは「現状のまま」提供され、いかなる保証もありません。全文については LICENSE をご覧ください。