slimdex-mcp

slimdex-mcp

エージェントは、1つの関数を変更するために900行のファイルを読み込み、その後の各ターンでもそのファイルの料金を再び支払います。 会話全体が毎回再送信されるため、最初に読み込んだファイルも一度きりのコストではありません。継続して料金がかかります。

SlimdexはローカルのMCPサーバーで、コーディングエージェントに代わりに必要な部分だけを取得する機能を提供します。ファイルの概要、1つのシンボルの本体、それを呼び出す箇所、変更した場合に壊れるものを取得できます。また、セッションをまたいで記憶を保持するため、次のチャットではリポジトリをゼロから再調査せず、情報を把握した状態で開始できます。

claude mcp add slimdex -- npx -y slimdex-mcp

日常的な利用でトークンを約50%削減します。ナビゲーション中心の作業では約55～60%、出力中心の作業では約45%、そしてSlimdexが想定する最悪のケース（6,200行のファイル1つを、全体を4回読む代わりに、スケルトンと12個のシンボル本体から調査するケース）では85～90%削減します。

ステータス：1.1.0。npmで公開済み、MCP Registryにも登録済みです。 数値は、実際に実行したリポジトリで単一セッションを使って自己計測したもので、独立した検証は受けていません。また、statsが数えているのはトークンではなく文字数です。 利用する前に実際に検証済みの内容をご確認ください。 | ツール | 返される内容 | |------|-----------------| | index_repo | 永続的なシンボル＋インポートインデックスを構築／更新します。変更されたファイルのみを再解析します | | outline_file | 1つのファイルの宣言を行番号付きで返します | | get_file_skeleton | 本文を省略し、ネストを維持したシグネチャを返します | | read_lines | 1つの行範囲を返します。デフォルトでは継続行付きで6,000文字までです。さらに必要な場合は maxChars を設定します | | get_symbol_context | 1つの関数／クラスの本文と前後2行を返します。maxLines で上限を設定できます。names:[...] を使うと1回の呼び出しで複数の本文を取得できます | | search_code | path:line:col と、キャレットで強調表示された一致行を返します。limit／offset／カーソルによるページネーションに対応しています | | find_definition | シンボルの定義箇所を path:line:col 形式で返します | | search_symbols | シンボル名をあいまい検索し、完全一致→前方一致→部分一致→部分列一致の順に順位付けします | | search_intent | シンボルを対象にBM25で順位付けする自然言語クエリです（埋め込みは使用しません）。処理内容からコードを検索します | | context_pack | 1回の呼び出しで、トピックに関連するシンボルを順位付けし、それらのつながりを示して、予算内で上位の本文をまとめます。探索全体を1往復で完了できます | | find_references | テキスト上の参照を path:line:col と、それを囲む関数とともに返します | | find_tests | シンボルへの参照のうち、テストファイルにあるものを返します。該当する参照がない場合は警告を返します | | replace_symbol | 名前で指定したシンボルの本文を上書きします（以前のコードを再送する必要はありません）。最初にスナップショットを作成し、その後インデックスを再構築します | | get_context | 1回の呼び出しで、定義／シグネチャ／呼び出し元／インポート／依存先を任意に選択して、予算内で取得します | | repo_map | ディレクトリ単位のファイル数／行数／シンボル数を返します。path: でディレクトリ内の最大ファイルを調べられます | | changed_files | 変更されたファイルと、各差分の適用先となるシンボルを返します | | dep_graph | imports／dependents／Mermaid図（root＋depth の幅優先探索）を返します | | stats | ツールごとの呼び出し回数と応答サイズを文字数で返し、読み取りの内訳と書き込みの状況も示します | | batch | 1つのリクエストで複数の呼び出しを実行します | | recap | サーバーのツール呼び出しジャーナルから過去のセッションのアクティビティを自動的に再構成します。何も保存されていなくても機能します | | brief | 簡潔なセッション開始用のまとめです。リポジトリの概要、ジャーナルから導出した注目点、ライブインデックスと照合した最近の結論（✓ 最新／⚠ 古い可能性あり）を返します。detail:"full" を指定すると、まとめとメモのプレビューを詳しく表示します | | digest_save / digest_get | リポジトリのアーキテクチャを簡潔にまとめたチートシートを一度保存し、対象ファイルごとの鮮度判定付きで読み戻します。次回のセッションでは探索を省略できます | | snapshot | 未コミットのファイルを .slimdex/snapshots/ にコピーします（変更のあるツリーに対して index_repo を実行すると、1時間ごとにも自動実行されます）。誤ったリセットに備えるためのもので、コミットの代わりにはなりません | | memory_save/search/list/delete | .slimdex/memory.json に永続的なメモを保存します |

以下の情報検索ガイダンスは、サーバーのMCP instructions にも含まれているため、 クライアントはこれをモデルのコンテキストに自動的に挿入します。

推奨されるエージェントのフロー

セッションの開始直後に、まず brief を実行します。リポジトリの概要、最近のセッションで調査されていた箇所、コードとまだ一致している保存済みの結論（古くなったものには印が付きます）を、1 回の呼び出しで確認できます。これにより、新しいチャットを白紙の状態ではなく、必要な情報を把握した状態で始められます。次に get_context("Foo") を実行すれば、「これは何か、誰が呼び出しているか、何に依存しているか」が 1 回の応答でわかります。1 つのシンボルではなく、まとまった 領域 全体を理解したい場合は、context_pack("how does auth work") が調査全体をサーバー側で実行し、関連するシンボル、それらのつながり、主要な本体をまとめた、サイズ上限のある単一のパッケージを返します。これにより、10 回ではなく 1 回の呼び出し、1 件のトランスクリプト項目で済みます。名前はわからず、機能だけわかっている場合は、search_intent("parse the config file") を使います。埋め込みを使わず、BM25 で意図に基づいてシンボルをランク付けします。1 つの本体を確認するには get_symbol_context を使います（ファイルがインデックスから変化している場合はその旨を示すため、確認のために再度読み込む必要はありません）。ファイルの構成を確認するには get_file_skeleton、ソースを正確に確認する必要がある場合は read_lines を使います。シンボルを編集する前に、そのシンボルに対して find_tests を実行し、どのテストが対象にしているかを確認します。関数全体を書き換える場合は replace_symbol を使います（新しい本体だけを送信すればよく、編集箇所を特定するために古いコードを再送する必要はありません）。複数の検索をまとめるには batch を使います。すべての検索ツールは limit（デフォルトは 20）と offset を受け取ります。

応答のサイズ調整： get_context の各セクションは include で任意に指定できます（デフォルトは definition、signature、callers、imports です。body や dependents を明示的に追加できます）。呼び出し元の数は callerLimit で制限され、応答は maxChars（デフォルトは 12,000）で上限が設定されます。上限に達した場合は、データが黙って削られるのではなく、明示的な通知（showing 3 of 68、truncated at maxChars=...）が表示されます。同様に、get_symbol_context は maxLines で範囲を制限します。また、memory_list は特に指定がなければ最新の 50 件の情報を、全文ではなく約 150 文字のプレビューとして返します（memory_get ids:[...] で展開でき、full:true を指定するとすべて表示されます）。18 件の情報を保存したストアの場合、これは毎回セッションの最初に行う呼び出しで約 4,100 文字に収まるか、約 18,600 文字になるかの違いです。

設定：<root>/.slimdex.json（任意）

{
  "ignoreDirs": ["fixtures", "backend/src/main/resources/static/assets"],
  "extensions": [".astro", ".vue"],
  "suffixes": [".stories.mdx"],
  "exclude": ["generated/", "legacy/vendor"],
  "maxFileBytes": 2000000
}

suffixes は、拡張子だけでは識別できないファイル形式に対して、ファイル名の末尾を照合します。Salesforce のメタデータサイドカーは標準で対応しています。AccountSvc.cls-meta.xml、panel.js-meta.xml、Account.object-meta.xml はインデックスされますが、pom.xml、web.xml、manifest/package.xml は対象外です。extensions に .xml を追加すると、リポジトリ内のあらゆる設定ツリーまで取り込まれてしまうためです。サフィックスに一致するファイルは、検索と読み取りの対象としてインデックスされますが、シンボルは対象になりません。

標準の無視リスト（node_modules、dist、.venv、.svelte-kit、Pods、.pytest_cache、…）に追加されます。ignoreDirs の項目には、どの階層でも同名のディレクトリに一致する単独の名前か、リポジトリのルートを基準とし、ディレクトリ境界を考慮する / を含むパスを指定します（src/gen を指定しても src/generated は無視されません）。index_repo は読み込んだ設定を表示し、不明なキー、型の誤り、無効な JSON について警告します。そのため、設定の入力ミスが、設定がない状態と区別できないままになることはありません。

ビルド出力の場合、通常は設定不要です。 ディレクトリ一覧に加えて、1 行が約 5,000 文字を超えるファイルは、圧縮されたビルド出力として扱われ、インデックスから除外されます。バンドラーは改行を削除しますが、手書きのソースがこのような形になることはありません。この方法なら、名前の一覧だけでは構造的に判別できないもの、たとえば assets というディレクトリ内にあるハッシュ名のバンドル（index-B7xK2p9q.js）も検出できます。実際のソースが含まれるため、assets、public、static は名前だけを理由に意図的に無視されません。index_repo は skipped(minified build output): N として件数を報告します。

トークンを節約できる仕組み

圧縮の仕掛けがあるわけではありません。節約は動作によるものです。これらのツールを使うと、エージェントはファイル全体ではなく、概要や範囲、位置情報を取得できます。また、インデックスが永続化されるため、同じ情報を再度調べる際はファイルを読み直すのではなく、キャッシュ済みのクエリを利用できます。

異なるモデルが異なる形状のリポジトリで実行した後続の2つのセッションで、元のレポートに実環境の数値が加わりました。

複数ファイルのウェブアプリ、バグ修正セッション（GPT-5.3-Codex）。 Slimdex を使った場合、報告されたクレジット数は19でした。同じ範囲の作業を Slimdex なしで行った場合のモデル自身による推定は、45～70クレジットです。計算式：19/45 → 19/70 ≈ 58～73％安くなります。反実仮想の数値はモデルによる推定であり、実測のA/B比較ではありません。あくまで傾向を示すものです。

巨大な単一ファイル（folio-app：6,200行、313 KB の app.js が1つ）。 Slimdex の統計では、8回の呼び出しで約34,000文字、約9～10kトークンです。まずスケルトン（213個のシグネチャ）を取得し、その後、関連する関数約12個の本文だけを取得しました。そのうち9個は、1回の get_symbol_context names:[...] 呼び出しで取得しています。単純な方法では、313 KB は約78～85kトークンに相当し、強制的にファイル全体を3～4回読み取ることになります。計算式：約10k 対 約80k ≈ 約70kトークンの節約、探索時に85～90％削減。バグの原因（対応するインポートパスのないエクスポートパス）は、本文を一つも開く前に、スケルトンのシグネチャから判明しました。

これらを合わせると、拡張性の傾向が見えてきます。節約量は、単純な方法で不要なコードをどれだけ読み込むことになるかに応じて増減します。 巨大な単一ファイルは最も効果が大きいケースです。通常のリポジトリでは約半分から3分の2のコスト削減となり、小さなファイルばかりのリポジトリでは損益が均衡します。ここにある他の数値と同様、注意点があります。統計が数えているのはトークンではなく文字数（÷3.5～4）であり、単一セッションはベンチマークではなく、あくまで根拠の一つです。

上記の2つの数値が測っているのは、コストの低い半分にあたる読み取りだけです。 出力コストは入力の約4～5倍です。そのため、無計画な編集は無計画な読み取りよりも無駄が大きくなります。汎用編集ツールを使って関数全体を書き換える場合、ツールが置き換え箇所を見つけられるよう、古い本文をすべて再送信することになります。replace_symbol なら名前で対象を指定できるため、そのコストがなくなります。stats は読み取りの内訳とあわせてこれを報告します。そうしなければ、この漏れは見えません。コストの高い方法でも編集自体は正しく行われるため、余計なコストがかかったことに気づけるものがないからです：

write discipline:
  replace_symbol: 0 call(s), 0 symbol(s) rewritten by name
  changed outside slimdex: 12 file(s)
  pre-edit checks (find_tests/dep_graph/get_context/changed_files): 0

外部編集は、2回の index_repo 実行の間でコンテンツハッシュが変化したことから推定されます。そのため、この数値が示す範囲には限界があります。バイトが変更されたことは検知できますが、どのツールが変更したかはわかりません。また、別のウィンドウで人が編集した場合も数に含まれます。

ワークフロー全体で現実的に見込める範囲

上記の数値は、特定のシナリオでの探索に関するものです。単純な方法で最も多くの不要なコードを読み込むことになる、最も効果が大きいケースです。探索の部分だけでなく、実際の一日の作業全体で平均すると、この範囲はもう少し低くなります。

• 約55～60％ は、コードベースの読み取りや理解など、ナビゲーション中心の作業での数値です。ファイル全体の読み取りを、必要な範囲だけの取得に置き換える機会が最も多い作業です。
• 約45％ は、新しいコードを次々と書くなど、出力中心の作業での数値です。コストの多くはサーバーが関与しないコード生成で発生します（ただし、replace_symbol によって書き込み側のコストも削減されるようになりました）。
• 日々の通常の使用で平均すると約50％ です。セッションで使うほど節約効果が積み重なります。brief とメモリにより、新しいチャットを開始するたびにリポジトリをゼロから調べ直すのではなく、情報を得た状態で始められるためです。

効果を最大限に得るには、IDE で複数のセッションにわたって定期的に使用してください。

これらはベンチマークではなく、一つのデータポイントとして扱ってください。 リポジトリは一つ、タスクは一つ、自己測定によるA/B実行は各1回で、反復もばらつきの測定もありません。実際にエージェントが範囲を絞ったツールを使うのか、それともファイルの読み取りに戻るのかによって、実際の結果は大きく異なります。これはクライアントやモデルによって変わります。方法自体は再現可能です。確認したい場合は、同じタスクを2つの新しいセッションで実行し、一方には Slimdex のみを使うよう指示し、もう一方には Slimdex を使わないよう指示してから、/status の cache-write を比較してください。

---

実際に検証されていること

README の残りは誤解されやすいため、明確にしておきます。

ユニットテストでカバーされている内容（npm test は23ファイル、224件のテストを実行します）：

• JS/TS（クラスやオブジェクトリテラルのメソッドを含む）におけるシンボル抽出、コメントのスキップ — symbols.test.ts

• JS の import／require／export-from、Python、Rust のインポート抽出

• 文字列やコメント（引用符、テンプレート、//、/* */、行全体の #）を認識した、波括弧スコープとインデントスコープによるブロック抽出 — extractBlock.test.ts

• インポート解決、外部モジュールの分類、逆方向エッジの依存先、Mermaid の出力、ルートからの BFS による深さのスコープ設定 — graph.test.ts

• 検索結果の形式、重複のないページネーション、行ごとの出現回数カウント、正確な合計数、正規表現のエスケープ／拒否 — search.test.ts

• 不透明なカーソルの往復変換と不正なカーソルの拒否、パーサーバックエンドへのフォールバック — pagination.test.ts

• 制御フローと区別したアウトライン宣言の検出 — outline.test.ts

• get_symbol_context の maxLines による予算設定と切り詰め通知

• 文字列／コメントのマスキングと波括弧の深さ追跡 — lexer.test.ts

• 対応する全 12 言語での言語別抽出 — languages.test.ts

• インデックスキャッシュは、インデックスが書き換えられるまで同じオブジェクトを返します

• .slimdex.json の読み込み：すべてのキーを実際のインデックス構築に適用し、無効な JSON、不明なキー、誤った型という各失敗モードでは、警告を出さずに処理するのではなく、表示可能な警告を生成します — config.test.ts

• 実際の一時 git リポジトリを使った changed_files：ハンクからシンボルへの帰属、未追跡ファイル、明示的なベース参照、フォーマットを検証し、git がインストールされていない場合は正常にスキップします — git.test.ts

• 実際の fs イベントを使ったファイルウォッチャー：保存がデバウンスされ、再インデックスされ、ディスク上のインデックスに反映されます — watch.test.ts

• インポート以外のグラフエッジ：インポートのないコードにおける名前参照エッジ（クラス→使用されるクラス、インターフェース→実装（依存先経由）、トリガー→ハンドラー）と、リポジトリ XML における宣言的な配線エッジ（メタデータバインディング→クラス）。コメントや文字列内の言及は除外され、ビルドごとにキャッシュされます — apexgraph.test.ts

• インメモリファイルキャッシュは、繰り返しの読み込みでは再読み込みせずにキャッシュを返し、ディスク上の変更後は常に最新の内容を返します — fscache.test.ts

• JS/TS/Python/Go/Ruby/Java/C# の規約に基づくテストファイル検出。Windows の区切り文字は正規化され、通常のソースファイル（latest.ts、Contest.java）は誤ってテストファイルとして判定されません — testlink.test.ts

• 書き込み処理：シンボルのブロックを置換し、後続のコードを保持し、CRLF と LF の改行を維持して、編集によってファイル全体の差分が発生しないようにします — edit.test.ts

• メモリの陳腐化：存在するシンボル／ファイルを指す事実は最新と判定され、コード内での言及がすべてなくなった場合にのみ古い情報としてフラグが立ち、文章についてはフラグが立ちません。簡潔な情報の構成も検証します — brief.test.ts

• 意図検索：camelCase／snake_case のトークン分割と、意図を表す語を使って名前の異なるシンボルを上位表示する BM25 ランキングを検証し、無関係なクエリのスコアがゼロになることも確認します — intent.test.ts

• 最新性：インデックス作成時の mtime より新しいファイルは古い情報として読み込まれ（行番号がずれる可能性があります）、mtime が一致する場合は最新と判断され、ファイルが存在しない場合に古い情報として誤検出されないことを検証します — freshness.test.ts

• context_pack の組み立て：ヘッダー、ランキングされたシンボル、本文を 1 つのバンドルにまとめ、該当項目がない場合のメッセージ、最初の本文を必ず含める文字数予算の制御、シンボル数の上限を検証します — pack.test.ts

• アーキテクチャダイジェスト：ダイジェストの読み込み後に変更された対象ファイルは古い情報として扱われ、新しいダイジェストは問題なしと判断されます。また、対象範囲とディレクトリプレフィックスによるフィルタリング、最新／古い情報の判定結果の出力も検証します — digest.test.ts 実際の MCP サーバーを通じたエンドツーエンドのテスト（integration.test.ts は一時的なフィクスチャリポジトリに対して、stdio 経由でサーバーを起動し、出力を検証します）： index_repo、repo_map、read_lines、get_file_skeleton、outline_file、 get_symbol_context、find_definition、find_references、find_tests（ヒット時とカバレッジなしの警告）、 search_intent（意図に基づく順位付け）、context_pack（1 回の呼び出しで取得する一式）、 digest_save／digest_get（鮮度判定を含む往復）、get_context（maxChars の上限を含む）、 dep_graph（インポートと mermaid）、batch、search_code、search_symbols、 stats、brief、replace_symbol（書き込み後にクエリする往復と、未知のシンボルへの拒否）、 memory_save/search/list/delete の往復、パス逸脱のガード、見つからない場合のパスをテストします。

CI では Ubuntu と Windows、Node 20 と 22 でビルドと両方のテストスイートを実行します。

ウォッチャーテストに関する注意： 再帰的な fs.watch はプラットフォームに依存するため、 イベントが一度も届かないファイルシステムでは、watch.test.ts はログにスキップを記録します。これはウォッチャー自体と同じ動作です。Windows、macOS、現行の Linux では、保存から再インデックスまでの経路をすべて検証します。

npm run smoke も引き続き利用できますが、パイプラインが動作していることしか確認しません。正しさの検証は integration.test.ts にあります。

コードの確認による検証： src/ にネットワーク呼び出しはありません。コードがマシンの外部に出ることはありません。こちらでご自身でも確認できます： grep -rE "fetch\(|https?://|axios|http\.request" src/。

詳細ドキュメント

docs/ 内にあります：

• tool-guide.md — すべてのツールを、技術的な説明と平易な説明の両方で、それぞれ例とともに解説します。組み合わせて使うワークフローと、mtime ベースの永続化の仕組みも説明します
• tool-guide.html — 同じガイドを、ブラウザーで使えるスタイル付きの自己完結型ページにしたものです
• token-savings-report.md — 最初の A/B 測定、その方法、再実行の手順を記載しています
• agent-brain.md — 運用上の規律をすべて、読みやすいドキュメントにまとめたものです
• agent-brain-slim.md — リポジトリに配置するものです。CLAUDE.md / AGENTS.md として使えます。自己完結した 1 ページのドキュメントで、節約の段階、質問→ツールの表、メモリの扱い、セッションの衛生管理、誠実な制限事項、環境設定をまとめています。ツールのルールを、サーバーがすでに挿入する段落ではなく高密度な表にすることで、完全版と同じ内容を約 30% の文章量で網羅しています。

言語の対応状況

フィクスチャだけではほとんど証明にならないため、2 種類の測定を行っています。

フィクスチャ — 各言語につき 1 つ用意し、開発者が実際にたどる宣言を数えています：65/65 件を検出、誤検出は 0 件。test/languages.test.ts で固定されています。

実際のサードパーティーコード — 数百の実際のパッケージ（React、Babel、Remix、Socket.io、Playwright、Three.js、Emotion、zod、ajv など）から約 11,800 ファイルを抽出し、宣言に該当するものを判定するために独立して作成したヒューリスティックと比較しました：再現率 95.9%。ご自身で再現できます：

npm run audit -- ./node_modules            # or any directory of code you didn't write

この数値は成績ではなく下限値です。正解を判定するヒューリスティックが宣言ではないものも数えているため、実際の再現率はもう少し高くなります。この測定の目的は、リグレッションを検出し、次に埋めるべき実際の不足を見つけることです。

フレームワークについて

監査に失敗したもののうち、フレームワーク固有のものはほとんどありませんでした。フレームワークはアノテーション、デコレーター、規約を追加しますが、独自の構文を生み出すことはほとんどありません。言語に対応すればフレームワークも扱えます。fflib の Application／Domain／Selector／Service／UnitOfWork レイヤーも、fflib 専用のルールを一つも使わずに完全に抽出できます（宣言は129件）。

本当の例外は、テスト DSLです。vitest／jest／mocha／RSpec のファイルにはトップレベルの宣言がないことが多く、以前はテストディレクトリ全体をインデックス化しても何も得られないことがありました。現在は describe／it／test のタイトルを test 種別としてインデックス化するため、テストファイルで実際にナビゲートする対象を扱えます。

リポジトリ内のどこかに参照先がある場合、フレームワークのセマンティクスは、グラフに追加された2種類のエッジソースを通じて復元されます。

• 名前参照エッジ：インポート文を持たない言語（例：Apex）向けです。あるファイルのコード（コメントと文字列をマスクしたもの）が、別のファイルで定義されたトップレベルの型に言及していれば、それがエッジになります。これにより、implements に対して「このインターフェースを実装しているのは誰か」と答えられ、トリガーから new で生成されるハンドラークラスにもリンクできます。
• 宣言的な配線エッジ：フレームワークがコードではなく設定に保持するバインディング（カスタムメタデータレコード、フロー定義など）は、多くの場合、型名を要素値として持つ XML としてリポジトリに保存されています。リポジトリ内の XML を既知の型名でスキャンし（XML コメントは除外）、一致する箇所ごとに metadata-file → class エッジを作成するため、dependents は「これを配線しているのは何か」に答えられます。

どちらのスキャンもインデックスのビルドごとにキャッシュされ、該当ファイルがないリポジトリではコストがかかりません。apexgraph.test.ts によって固定されています。静的リーダーでは確認できないのは、稼働中のシステムにのみ存在するバインディングです。実行中の組織やデータベースで設定されていて、リポジトリに一度も取得されていないものが該当します。どのような形でもリポジトリに存在しなければ、描画できるエッジはありません。その場合は型名を検索してください。

言語	拡張子	認識される要素
JavaScript / TypeScript	.js .jsx .mjs .cjs .ts .tsx .vue .svelte	クラス、インターフェース、型、列挙型、関数、トップレベルのアロー関数、クラスおよびオブジェクトリテラルのメソッド
Apex	.cls .trigger	クラス、内部クラス、メソッド（@AuraEnabled、global、ジェネリックな戻り値を含む）、トリガー
Java	.java	クラス、インターフェース、列挙型、メソッド、先頭に <T> があるジェネリックメソッド
C#	.cs	クラス、インターフェース、構造体、非同期メソッドおよびジェネリックメソッド、仮想メンバー
Kotlin	.kt	クラス、データクラス、インターフェース、object、fun、suspend fun
Swift	.swift	クラス、構造体、列挙型、プロトコル、func、static func
Python	.py	クラス、def、async def、dunder メソッドおよびデコレーター付きメソッド
Go	.go	関数、レシーバーメソッド、構造体型およびインターフェース型
Rust	.rs	構造体、列挙型、トレイト、fn、pub async fn、impl メソッド
Ruby	.rb	クラス、モジュール、def、def self.x、attr_accessor/reader/writer
PHP	.php	クラス、インターフェース、トレイト、メソッド、関数
Scala	.scala	クラス、ケースクラス、トレイト、オブジェクト、修飾子付きの def
C / C++ / Objective-C	.c .h .cpp .hpp .cc .m .mm	クラス、構造体、列挙型、自由関数（K&R 形式の波括弧、ポインターを返す関数を含む）、クラス外で定義された Foo::bar、コンストラクター／デストラクター、名前空間、関数形式の #define マクロ、typedef struct {…} Name、@interface／@implementation／@protocol

パフォーマンス

コールドインデックスは全ファイルを解析し、ウォームインデックスではファイルごとに mtime を確認します。Windows、Node 24 で測定しました。

リポジトリ	ファイル数	シンボル数	コールドインデックス	ウォームインデックス	通常のクエリ
Salesforce DX org	56	344	0.1 s	15 ms	< 10 ms
Java + React アプリ	356	1,713	0.42 s	26 ms	3–57 ms
合成ストレステスト	5,000	50,000	1.5 s	0.24 s	5–22 ms

インデックスはメモリ上に保持され、インデックスファイルの mtime によって無効化されます。このキャッシュがなければ、ツールを呼び出すたびにインデックス全体を再読み込みして解析することになり、5,000 ファイルのリポジトリでは呼び出しごとに約 20 ms の無駄が生じ、リポジトリが大きくなるほど増加します。

find_references はインデックス検索ではなくテキストスキャンを行うため、大規模環境では最も遅いツールです。ただし、検索対象の名前がファイルの生ソースに含まれていない場合、リテラルによる事前フィルターで行分割と行ごとの正規表現処理をスキップするようになりました。通常のリポジトリでは、大半のファイルがこれに該当します。おおよその検索場所がわかっている場合は、pathPrefix で範囲を絞り、残りのファイル読み込みを減らしてください。

ファイルの内容も、バイト数に上限を設けたメモリ上の LRU（64 MB、ヒットごとに mtime+size で検証）から提供されます。そのため、リポジトリの2回目のスキャンや、エージェントが1つのファイルに対して実際に行う skeleton→read_lines→context の一連の処理では、読み込みの代わりに stat() が実行されます。

セッションをまたぐメモリ

memory_save は <root>/.slimdex/memory.json に書き込みます。このファイルはプロセス終了後も保持されるため、あるチャットで保存した情報は、再起動後に別のクライアントから次のチャットで読み取れます。チャットとエディターが同じストアを共有するのは、両方が同じ SLIMDEX_ROOT を参照している場合のみです。

情報が自動的に記録されることはありません。サーバーは会話を認識しないため、何を保存する価値があるかはエージェントが判断する必要があります。付属の instructions は、新しいセッションでは最初にメモリを読み取り、学習した決定事項、制約、注意点を保存するよう指示しています。ただし、これはモデルへのガイダンスであり、保証ではありません。

既知の制限事項

• シンボルの抽出は正規表現ベースのヒューリスティックであり、パーサーや LSP ではありません。一般的でない宣言を見落とすことがあり、find_references はテキスト上の一致を返すため、同名の無関係な識別子が含まれる場合があります。
• シンボルとアウトラインの抽出は、各行の文字列とコメントの内容を空白に置き換えたマスク済みコピーを対象に実行されるようになりました。そのため、テンプレートリテラル内の宣言のような文章がコードとしてインデックスされることはありません。また、宣言は深さを考慮して処理されます。関数本体内のローカル変数はナビゲーションの対象ではないため、const x = () => … や type X = … はトップレベルにある場合のみ対象になります。クラスメソッドは引き続き、ネストの深さに関係なくインデックスされます。
• 波括弧を含む Python のインライン # コメントは、ブロック抽出を誤らせる場合があります（# は JS のプライベートフィールドを示す記号でもあるため、無条件に削除できません）。
• changed_files は変更箇所を直前にある最も近い宣言に割り当てます。通常の関数本体では適切ですが、宣言と宣言の間にあるコードでは概算になります。呼び出しグラフではなく、影響範囲として扱ってください。
• search_code は正確な合計件数を報告しますが、結果が非常に多い場合は内部スキャン上限で停止し、誤った数を断定する代わりに N+ (scan cap reached) と表示します。
• 言語サポートにはばらつきがあり、JS/TS が最も充実しています。以前はサポートが特に薄かった C 系言語と Ruby には、専用ルール（フリー関数、Foo::bar の定義、関数形式のマクロ、attr_*）が追加されました。残る弱点は、高度な C++ の構文、つまり複数行に分かれたテンプレートや演算子のオーバーロードです。
• LSP 相当の精度が必要な場合は、パーサーを tree-sitter または言語サーバーに置き換えてください。src/parser.ts がその接続点です。SLIMDEX_PARSER によって選択される Parser インターフェイスを備えており、付属する実装は正規表現パーサーのみです。ツールやインデックス形式に手を加えることなく、tree-sitter バックエンドをここに追加できます。これは実装されていません。言語ごとの文法を導入すると、「すぐにインストールでき、オフラインで動作し、設定不要」という特長が失われるためです。

あえて実装しなかったもの

評価したうえで却下したアイデアとその理由です。これらは設計上の意見であり、測定結果ではありません。

• シンボル ID 辞書（S42 → パス） — MCP にはクライアント側で展開するレイヤーがないため、モデルは不透明なトークンを受け取り、解決するためにもう 1 回呼び出す必要があります。
• トークン予算マネージャー／コスト推定ツール — chars/4 による推定はトークナイザーごとの差が大きく、誤った推定に基づく自動圧縮で、モデルが必要としていたデータが失われる可能性があります。
• 差分／「送信済みなので応答 #5 を参照」というキャッシュ — コンテキストが圧縮されると以前のペイロードは失われるため、参照先は何も指さなくなります。
• 埋め込み／セマンティック検索 — 依存関係の規模が大きくなります。将来的に任意で有効にできるフラグとしては考えられますが、デフォルトにはしません。
• tree-sitter パーサーバックエンド — これを使えば残る約 4％を改善できます。曖昧な見積もりではなく、コストを算出したうえで判断しました。web-tree-sitter は WASM なのでネイティブコンパイルは不要ですが、文法（tree-sitter-wasms）を展開すると 51.7 MB になり、現在のインストール全体の約 4.5 MB と比べて大きくなります。測定再現率 95.9％の時点で採用を見送りました。「すぐにインストールでき、オフラインで動作し、設定不要」であることこそ、このサーバーが実現するために存在する特性だからです。計算が変わった場合に備え、src/parser.ts は差し替え箇所として残しています。バックエンドは、ツールやインデックス形式に手を加えず、そこに追加できます。

---

インストール

npm では slimdex-mcp として公開されており、 MCP Registry には io.github.Siddhukaushik/slimdex-mcp として登録されています。ビルドは不要です。クライアントの接続先に次を指定してください。

npx slimdex-mcp

ソースから使う場合は、こちらです。

git clone https://github.com/Siddhukaushik/slimdex-mcp
cd slimdex-mcp
npm install
npm run build      # produces dist/index.js
npm test           # vitest unit suite

リポジトリに対してエンドツーエンドで動作することを確認します。

npm run smoke                                # this repo
node smoke-test.mjs "C:/path/to/some/repo"   # any other

環境変数

変数	効果
SLIMDEX_ROOT	インデックス対象のリポジトリ（または最初の CLI 引数として指定します。デフォルトは cwd です）
SLIMDEX_WATCH	1 に設定すると、ファイル保存時に自動で再インデックスします（ネイティブのウォッチャーを使用し、依存関係はありません）
SLIMDEX_PARSER	パーサーバックエンド。現在は regex のみです
SLIMDEX_PRETTY	1 に設定すると、詳細で人間が読みやすい表示に戻します。search_code、find_definition、search_symbols、find_references、repo_map、read_lines、outline_file のヘッダーが長くなり、列にパディングが加わります。デフォルトは簡潔な表示です。パディングも後続のすべてのターンでモデルが消費するコンテキストになるためです。SLIMDEX_TERSE=0 でも同じ設定になります。
SLIMDEX_PROFILE	lean にすると、29 個ではなく 15 個のツールが公開され、毎ターン再送されるツールスキーマを約 22,300 文字から約 12,600 文字に削減できます。残りの 14 個（get_context、changed_files、find_tests、dep_graph、outline_file、search_symbols、recap、memory_list、memory_search、memory_delete、digest_save、digest_get、snapshot、stats）も引き続き利用でき、batch 経由で呼び出せます。また、このプロファイルではサーバーの指示にそれらのツールが記載されるため、モデルは batch 専用のツールを自力で見つけるのではなく、そのようなツールとして認識できます。デフォルトは full です。
SLIMDEX_NO_DEDUPE	1 に設定すると、同じ応答の抑制を無効にします（変更されていないファイルに対する 2 回目の同一の read_lines／get_file_skeleton／outline_file は本文ではなく先行する呼び出しへの参照を返し、3 回目の同一呼び出しでは全文を再出力します）。

永続キャッシュ

Slimdex はリポジトリごとに <repo>/.slimdex/ へ書き込みます。

• index.json — コードインデックス（ファイルごとに mtime で無効化され、インデックス形式のバージョンが変わると全体を破棄するため、古い抽出器で作成された古いインデックスが再利用されることはありません）
• memory.json — 保存されたメモリ情報
• stats.json — ツールごとの使用回数カウンター

このディレクトリは自身を無視します。内部に * を記述した .gitignore が作成されるため（node_modules/.cache と同じ手法です）、git status に表示されず、リポジトリ本体の .gitignore に手を加える必要もありません。キャッシュをコミットしたい場合は、内部のファイルを削除してください。

---

MCP クライアントへの接続

MCP は共通規格なので、同じサーバーを MCP 対応クライアントならどれにでも接続できます。プロジェクトのルートは SLIMDEX_ROOT（または最初の CLI 引数）で渡します。

実際に動作確認したのは Claude Code と Claude Desktop のみです。 以下のほかのクライアントの設定例は、各クライアントのドキュメントに記載された形式に基づく標準的な設定です。ここではテストしていないため、調整が必要な場合があります。

1.0.0 以降は、npx -y slimdex-mcp が最も簡単な接続方法です。クローンもビルドも不要で、常に最新の状態が保たれます。以下の例では、ソースから実行する場合に備えて node <ABS_PATH> 形式を使っています。公開済みのパッケージを使うには、"command": "node", "args": ["<ABS_PATH>"] を "command": "npx", "args": ["-y", "slimdex-mcp"] に置き換えてください。

<ABS_PATH> はビルド出力に置き換えてください。例：C:\path\to\slimdex-mcp\dist\index.js。<REPO> はインデックス対象のリポジトリに置き換えてください。

調整は不要です。 重要な節約機能はすべてのクライアントでデフォルトで有効です。メモリの事実はプレビューとして一覧表示され、応答は簡潔になり、変更のないファイルを再度読み込むと本文ではなくポインターが返され、複数のシンボル編集を 1 回の呼び出しで実行できます。以下の環境変数は、これらの機能を無効にする場合、または lean を使う場合のものです。lean は、ツールの 3 分の 1 を batch 経由でルーティングする代わりに、ターンあたりさらに約 8,700 文字を削減します。そのため、意図的にデフォルトにはしていません。

Claude Code（CLI）— テスト済み

claude mcp add slimdex --env SLIMDEX_ROOT=<REPO> -- npx -y slimdex-mcp

ソースから実行する場合：-- node <ABS_PATH>。

Claude Desktop — テスト済み

%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "slimdex": {
      "command": "npx",
      "args": ["-y", "slimdex-mcp"],
      "env": { "SLIMDEX_ROOT": "<REPO>" }
    }
  }
}

Codex CLI — テスト済み

~/.codex/config.toml

[mcp_servers.slimdex]
command = 'C:\Program Files\nodejs\node.exe'
args = ['<ABS_PATH>']
startup_timeout_sec = 30

このようにグローバルに登録すると、slimdex はすべての Codex タスクに接続され、そのタスクの作業ディレクトリをリポジトリのルートとして使います。SLIMDEX_ROOT は不要です。Codex は制限された環境でサーバーを起動するため、PATH に頼らず、command には node の絶対パスを指定してください。

Cursor — 未テスト

.cursor/mcp.json（プロジェクト）または ~/.cursor/mcp.json（グローバル）

{
  "mcpServers": {
    "slimdex": {
      "command": "node",
      "args": ["<ABS_PATH>"],
      "env": { "SLIMDEX_ROOT": "${workspaceFolder}" }
    }
  }
}

Windsurf — テスト済み

~/.codeium/windsurf/mcp_config.json — Cursor と同じ mcpServers 形式です。

VS Code（Copilot／MCP）— テスト済み

.vscode/mcp.json

{
  "servers": {
    "slimdex": {
      "command": "node",
      "args": ["<ABS_PATH>"],
      "env": { "SLIMDEX_ROOT": "${workspaceFolder}" }
    }
  }
}

Cline（VS Code 拡張機能）— テスト済み

Cline の設定 → MCP サーバー → 追加：

{
  "slimdex": {
    "command": "node",
    "args": ["<ABS_PATH>"],
    "env": { "SLIMDEX_ROOT": "<REPO>" }
  }
}

Zed — テスト済み

settings.json → context_servers

{
  "context_servers": {
    "slimdex": {
      "command": { "path": "node", "args": ["<ABS_PATH>"], "env": { "SLIMDEX_ROOT": "<REPO>" } }
    }
  }
}

ワークスペースフォルダーを公開するクライアント（Cursor、VS Code）では、 ${workspaceFolder} を使うと、開いているリポジトリが Slimdex の対象になります。

典型的なエージェントのワークフロー

1. 最初に index_repo を 1 回実行します（次回以降は高速になります）。続いて brief を実行すると、古くなったメモにフラグが付いた状態で、過去のセッションの続きから始められます。
2. repo_map → 全体像を把握します。
3. 対象ファイルに対して outline_file を実行し、行範囲を選びます。
4. その範囲だけ read_lines で読み込みます。
5. find_definition／find_references／dep_graph でコードをたどります。
6. シンボルを編集する前に find_tests を実行します。replace_symbol を使うと、古い本文を再送せずに書き換えられます。
7. 判断事項や注意点を memory_save で保存し、次のセッションに情報を引き継ぎます。

ライセンス

MIT © 2026 Kael VK Inc.（事業者番号 751569161 RC0001）— LICENSE を参照してください。

現状有姿で提供され、保証およびサポートはありません。ビルドできない、実行できない、またはお使いの環境で動作しない場合は、ご自身で対処してください。ライセンスの免責事項を参照してください。