Mcp Codebase Index

mcp-codebase-index

AI 支援開発向けの MCP サーバーを備えた、構造ベースのコードベースインデクサーです。実行時依存関係はゼロです。Python の解析には Python の ast モジュールを使用し、TypeScript／JS、Go、Rust、C# の解析には正規表現ベースのパーサーを使用します。Python 3.11 以降が必要です。

機能

ソースファイルを解析して、関数、クラス、インポート、依存関係グラフ、ファイル間の呼び出しチェーンなどの構造メタデータに変換し、コードベースをインデックス化します。その後、Model Context Protocol 経由で 18 個のクエリツールを提供し、Claude Code やその他の MCP クライアントがファイル全体を読み込まずに、効率的にコードベースを参照できるようにします。

インデックスの自動差分更新： Git リポジトリでは、インデックスは自動的に最新の状態に保たれます。クエリのたびに、サーバーが git diff と git status を確認します（約 1～2 ミリ秒）。ファイルに変更があった場合は、変更されたファイルのみを再解析し、依存関係グラフを再構築します。編集、ブランチ切り替え、プルの後に、手動で reindex を呼び出す必要はありません。

ディスクへの永続キャッシュ： インデックスはビルドのたびに pickle キャッシュファイル（.codebase-index-cache.pkl）へ保存されます。次回以降のサーバー起動時には、キャッシュを読み込み、現在の Git HEAD と照合して検証します。参照先が一致すれば、起動は瞬時に完了します。変更されたファイルが少数（≤20）の場合は、最初から再構築する代わりに、キャッシュ済みインデックスを読み込んで差分更新します。これにより、Claude Code セッションの再起動、MCP サーバーの再起動、またはコンテキスト圧縮後の作業再開時に発生するコールドスタートの遅延を解消します。

対応言語

言語	方法	抽出する情報
Python（.py）	AST 解析	関数、クラス、メソッド、インポート、依存関係グラフ
TypeScript/JS（.ts、.tsx、.js、.jsx）	正規表現ベース	関数、アロー関数、クラス、インターフェース、型エイリアス、インポート
Go（.go）	正規表現ベース	関数、メソッド（レシーバーベース）、構造体、インターフェース、型エイリアス、インポート、ドキュメントコメント
Rust（.rs）	正規表現ベース	関数（pub／async／const／unsafe）、構造体、列挙型、トレイト、impl ブロック、use 文、属性、ドキュメントコメント、macro_rules
C#（.cs）	正規表現ベース	クラス、インターフェース、構造体、列挙型、レコード、メソッド、コンストラクター、using ディレクティブ、[Attributes]、/// XML ドキュメントコメント
Markdown／テキスト（.md、.txt、.rst）	見出し検出	セクション（# 見出し、下線、番号付き、すべて大文字）
その他	汎用	行数のみ

インストール

pip install "mcp-codebase-index[mcp]"

[mcp] extra には MCP サーバーの依存関係が含まれます。プログラム API のみが必要な場合は、省略してください。

開発用（ローカルクローンから）：

pip install -e ".[dev,mcp]"

MCP サーバー

実行

# As a console script
PROJECT_ROOT=/path/to/project mcp-codebase-index

# As a Python module
PROJECT_ROOT=/path/to/project python -m mcp_codebase_index.server

PROJECT_ROOT はインデックス化するディレクトリを指定します。デフォルトは現在の作業ディレクトリです。

永続キャッシュ

Git リポジトリでは、サーバーはプロジェクトのルートにある .codebase-index-cache.pkl にインデックスを自動的にキャッシュします。起動時の動作は次のとおりです。

1. キャッシュヒット（完全一致）： キャッシュされた Git ref が現在の HEAD と一致する場合、インデックスはディスクから即座に読み込まれます。解析もファイルの走査もありません。
2. キャッシュヒット（小規模な変更セット）： キャッシュされた ref 以降に変更されたファイルが 20 個以下の場合、キャッシュされたインデックスが読み込まれ、最初のクエリ時に差分更新されます。
3. キャッシュミス： 変更セットが大きい場合、またはキャッシュが存在しない場合は、全体を再構築して新しいキャッシュを保存します。

.codebase-index-cache.pkl を .gitignore に追加してください。これはローカル専用のビルド成果物です。

OpenClaw での設定

OpenClaw の実行環境にパッケージをインストールします。

# Local install
pip install "mcp-codebase-index[mcp]"

# Or inside a Docker container / remote VPS
docker exec -it openclaw bash
pip install "mcp-codebase-index[mcp]"

MCP サーバーを OpenClaw のエージェント設定（openclaw.json）に追加します。

{
  "agents": {
    "list": [{
      "id": "main",
      "mcp": {
        "servers": [
          {
            "name": "codebase-index",
            "command": "mcp-codebase-index",
            "env": {
              "PROJECT_ROOT": "/path/to/project"
            }
          }
        ]
      }
    }]
  }
}

OpenClaw を再起動し、接続を確認します。

openclaw mcp list

18 個すべてのツールをエージェントで利用できます。

パフォーマンスに関する注意： サーバーは各クエリの前に git diff でファイルの変更を自動検出し（約 1～2 ms）、変更された部分のみを差分で再インデックス化します。ただし、OpenClaw のデフォルトの MCP 統合では、mcporter がツール呼び出しごとに新しいサーバープロセスを起動するため、メモリ内のインデックスが破棄され、毎回全体が再構築されます（小規模なプロジェクトで約 1～2 秒、大規模なプロジェクトではさらに長くかかります）。永続キャッシュにより、コールドスタートは大幅に高速化されました。サーバーはコードベース全体を再解析する代わりに、ディスクキャッシュから読み込みます。永続接続を使用して（キャッシュの読み込みによるオーバーヘッドも避けて）サーバーを実行し続けるには、起動時に一度だけ接続する openclaw-mcp-adapter プラグインを使用してください。

pip install openclaw-mcp-adapter

Claude Code での設定

プロジェクトの .mcp.json に追加します。

{
  "mcpServers": {
    "codebase-index": {
      "command": "mcp-codebase-index",
      "env": {
        "PROJECT_ROOT": "/path/to/project"
      }
    }
  }
}

または、Python モジュールを直接使用します（仮想環境にインストールしている場合に便利です）。

{
  "mcpServers": {
    "codebase-index": {
      "command": "/path/to/.venv/bin/python3",
      "args": ["-m", "mcp_codebase_index.server"],
      "env": {
        "PROJECT_ROOT": "/path/to/project"
      }
    }
  }
}

フックによるツール使用の徹底

Claude Code は、codebase-index が利用可能な場合でも、組み込みの Glob／Grep／Read ツールをデフォルトで使う傾向があります。CLAUDE.md の指示（下記を参照）に加えて、すべてのプロンプトで実行されるフックを追加し、この動作を徹底できます。.claude/settings.local.json に次の内容を追加します。

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'CRITICAL REMINDER: Use codebase-index MCP tools FIRST for ALL code navigation (find_symbol, get_function_source, search_codebase, get_dependencies, etc). Only fall back to Glob/Grep/Read for non-code files.'"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Use codebase-index MCP tools first for code navigation.'"
          }
        ]
      }
    ]
  }
}

フックの標準出力は、Claude が応答する前に参照するコンテキストとして挿入されます。SessionStart は起動時、再開時、コンテキストの圧縮時に実行されます。UserPromptSubmit は各ターンで実行されます。

重要：AI にインデックス付きツールを実際に使わせる

デフォルトでは、AI アシスタントはインデックス付きツールを無視し、Glob／Grep／Read を使ってファイル全体を読む方法に戻ります。「優先する」のような曖昧な表現は、都合よく解釈されてしまいます。必須であることを明示した表現を使い、プロジェクトの CLAUDE.md（または同等の指示ファイル）に次の内容を追加します。

## Codebase Navigation — MANDATORY

You MUST use codebase-index MCP tools FIRST when exploring or navigating the codebase. This is not optional.

- ALWAYS start with: get_project_summary, find_symbol, get_function_source, get_class_source,
  get_structure_summary, get_dependencies, get_dependents, get_change_impact, get_call_chain, search_codebase
- Only fall back to Read/Glob/Grep when codebase-index tools genuinely don't have what you need
  (e.g. reading non-code files, config, frontmatter)
- If you catch yourself reaching for Glob/Grep/Read to find or understand code, STOP and use
  codebase-index instead

「優先する」という言葉では弱すぎます。モデルはそれを提案として受け取り、使い慣れたツールをデフォルトで使います。動作を実際に変えるには、明確なフォールバック条件を含む必須の表現が必要です。

利用可能なツール（18）

ツール	説明
get_project_summary	ファイル数、パッケージ、主要なクラス／関数
list_files	任意のグロブフィルターを指定して、インデックス化されたファイルを一覧表示します
get_structure_summary	ファイルまたはプロジェクト全体の構造
get_functions	名前、行番号、パラメーターを含む関数の一覧
get_classes	名前、行番号、メソッド、基底クラスを含むクラスの一覧
get_imports	モジュール、名前、行番号を含むインポートの一覧
get_function_source	関数／メソッドのソース全体
get_class_source	クラスのソース全体
find_symbol	シンボルが定義されている場所（ファイル、行番号、種類）を検索します
get_dependencies	シンボルが呼び出す／使用するもの
get_dependents	シンボルを呼び出す／使用するもの
get_change_impact	直接および推移的な依存元
get_call_chain	最短の依存経路（BFS）
get_file_dependencies	指定したファイルがインポートするファイル
get_file_dependents	指定したファイルからインポートするファイル
search_codebase	すべてのファイルを対象に正規表現で検索します（最大100件）
reindex	インデックス全体を強制的に再作成します（通常は不要です。git リポジトリでは増分更新が自動的に行われます）
get_usage_stats	セッションの効率統計：ツール呼び出し回数、返された文字数とソース全体の文字数、推定トークン削減量

ベンチマーク

小規模なプロジェクトから CPython 自体（110万行）まで、実際の4つのプロジェクトで、M シリーズ MacBook Pro を使ってテストしました。

インデックス構築のパフォーマンス

プロジェクト	ファイル数	行数	関数	クラス	インデックス作成時間	最大メモリ使用量
RMLPlus	36	7,762	237	55	0.9s	2.4 MB
FastAPI	2,556	332,160	4,139	617	5.7s	55 MB
Django	3,714	707,493	29,995	7,371	36.2s	126 MB
CPython	2,464	1,115,334	59,620	9,037	55.9s	197 MB

永続キャッシュを使用すると、2回目以降の起動では全体の構築を完全にスキップできます。キャッシュの読み込み時間は解析時間と比べて無視できるほどです。CPython でキャッシュがヒットした場合、インデックス全体を56sではなく1秒未満で復元できます。

クエリ応答サイズとソース全体の比較

4100万文字のソースコードを含む CPython にクエリを実行します。

クエリ	応答	ソース全体	削減率
find_symbol("TestCase")	67 chars	41,077,561 chars	99.9998%
get_dependencies("compile")	115 chars	41,077,561 chars	99.9997%
get_change_impact("TestCase")	16,812 chars	41,077,561 chars	99.96%
get_function_source("compile")	4,531 chars	41,077,561 chars	99.99%
get_function_source("run_unittest")	439 chars	41,077,561 chars	99.999%

find_symbol が返す文字数は、プロジェクトが7K行であっても110万行であっても、54～67文字です。応答サイズはコードベースではなく、回答の規模に応じて変わります。

CPython で get_change_impact("TestCase") を実行すると、0.45ms で直接の依存元154件と推移的な依存元492件が見つかりました。これは依存関係グラフなしでは不可能なクエリです。トークンの予算に合わせて出力を制限するには、max_direct と max_transitive を使用してください。

クエリ応答時間

対象を絞ったクエリはすべて、CPython の110万行に対しても、1ミリ秒未満で応答します。

クエリ	RMLPlus	FastAPI	Django	CPython
find_symbol	0.01ms	0.01ms	0.03ms	0.08ms
get_dependencies	0.00ms	0.00ms	0.00ms	0.01ms
get_change_impact	0.02ms	0.00ms	2.81ms	0.45ms
get_function_source	0.01ms	0.02ms	0.03ms	0.10ms

ベンチマークを自分で実行するには、python benchmarks/benchmark.py を実行してください。

LSP との違い

LSP が答えるのは「この関数はどこにありますか？」ですが、mcp-codebase-index が答えるのは「これを変更すると何が起きますか？」です。LSP は、1 つのシンボル、1 つのファイル、1 つの位置に対するポイントクエリです。LLMClient の定義場所や、これを参照している箇所は教えてくれます。しかし、「LLMClient をリファクタリングすると、推移的に何が壊れますか？」と尋ねても、LSP には答えがありません。このツールは 1 回の呼び出しで、直接の依存先 11 件と推移的な影響 31 件を返します。わずか 204 文字です。LSP から同じ答えを得るには、AI が参照箇所の検索を数十回再帰的に連鎖させ、各段階でファイルを読み込み、依存関係グラフがすでに把握している情報を再構成するために数千トークンを消費する必要があります。

また、LSP を使うには、プロジェクト内の言語ごとに別の言語サーバーをインストールする必要があります。Python 用の pyright、TypeScript 用の vtsls、Go 用の gopls などです。それぞれが、独自の依存関係と設定を持つ重量級のバイナリです。mcp-codebase-index は依存関係が不要で、Python、TypeScript／JS、Go、Rust、C#、Markdown を最初からサポートし、すべての応答にトークン予算の制御（max_results、max_lines）が組み込まれています。LSP は IDE 向けに作られました。これは AI 向けに作られています。

プログラムからの使用

from mcp_codebase_index.project_indexer import ProjectIndexer
from mcp_codebase_index.query_api import create_project_query_functions

indexer = ProjectIndexer("/path/to/project", include_patterns=["**/*.py"])
index = indexer.index()
query_funcs = create_project_query_functions(index)

# Use query functions
print(query_funcs["get_project_summary"]())
print(query_funcs["find_symbol"]("MyClass"))
print(query_funcs["get_change_impact"]("some_function"))

開発

pip install -e ".[dev,mcp]"
pytest tests/ -v
ruff check src/ tests/

参考資料

構造インデクサーは、再帰的言語モデルフレームワークの実装であるRMLPlusプロジェクトの一部として、もともと開発されました。

ライセンス

このプロジェクトは、デュアルライセンスで提供されています。

• オープンソースでの使用には AGPL-3.0 を適用します。詳細は LICENSE をご覧ください。
• プロプライエタリな用途には Commercial License を適用します。詳細は COMMERCIAL-LICENSE.md をご覧ください。

開発用途で mcp-codebase-index を単独の MCP サーバーとして使用する場合、AGPL-3.0 ライセンスが無償で適用されます。プロプライエタリ製品に組み込む場合、またはホスト型サービスの一部として提供する場合は、商用ライセンスが必要です。詳細は COMMERCIAL-LICENSE.md をご覧ください。