Codebase RAG MCP

ローカルファースト、API Key不要のコードベース検索MCPサーバー。指定されたリポジトリをスキャンし、コードウィンドウでチャンク分割し、BM25、シンボル名、ファイルパス、完全一致によるハイブリッドランキングを実行。Codexに直接接続可能で、ChatGPTの知識検索シナリオ向けに標準の search / fetch ツールも提供します。

機能

• 優先的に git ls-files を使用し、リポジトリのネストされた .gitignore に従います。Git以外のディレクトリではファイルシステムスキャンを使用します。

• TypeScript、JavaScript、Python、Go、Rust、Java、C/C++、C#、Ruby、Shell、SQL、Markdown、Vue、Svelteなど、一般的なテキストコード形式をサポートします。

• camelCase、snake_case、パス単語を自動分割し、「ユーザーログイン認証」のような一般的な中国語コードクエリ拡張をサポートします。

• 正確なファイルパス、行番号、行番号付きコードスニペット、一致理由、読み取り継続可能な安定したIDを返します。

• パス読み取りは設定されたリポジトリルートディレクトリ内に制限されます。デフォルトでシンボリックリンク、バイナリ、秘密鍵、環境変数ファイル、圧縮コード、大容量ファイルをスキップします。

• ローカルの stdio とステートレスなStreamable HTTP /mcp の両方を同時にサポートします。

クイックスタート

Node.js 20 以降が必要です。

GitHubからプロジェクトを取得：

git clone https://github.com/sudoriaa/codebase-rag-mcp.git
cd codebase-rag-mcp

依存関係をインストールしてビルド：

npm install
npm run build
node dist/cli.js --root C:/path/to/your-repository

最後のコマンドでstdio MCPサーバーが起動し、MCPクライアントの接続を待機します。そのため、ターミナルが実行中のままになるのは正常な動作です。

Codexへの接続

以下をユーザーレベルの %USERPROFILE%/.codex/config.toml、または信頼されたリポジトリの .codex/config.toml に配置します：

[mcp_servers.codebase-rag]
command = "C:/Program Files/nodejs/node.exe"
args = [
  "C:/absolute/path/codebase-rag-mcp/dist/cli.js",
  "--root",
  "C:/absolute/path/your-repository"
]
cwd = "C:/absolute/path/codebase-rag-mcp"
startup_timeout_sec = 60
tool_timeout_sec = 120

WindowsのTOMLパスは / を使用することを推奨します。command には実行可能プログラムのみを記述し、その他の引数は args に個別に配置します。デスクトップアプリケーションが継承する PATH はPowerShellとは異なる可能性があるため、長期間使用する場合は node.exe の絶対パスを記述することを推奨します。

CLIで登録することも可能：

codex mcp add codebase-rag -- "C:\Program Files\nodejs\node.exe" "C:\absolute\path\codebase-rag-mcp\dist\cli.js" --root "C:\absolute\path\your-repository"
codex mcp get codebase-rag --json

設定後、CodexデスクトップアプリケーションまたはIDE拡張機能を再起動します。設定例は examples/codex-config.toml を参照してください。

HTTP MCPの起動

node dist/cli.js --root C:/path/to/your-repository --transport http --host 127.0.0.1 --port 3000

エンドポイント：

• MCP：http://127.0.0.1:3000/mcp

• ヘルスチェック：http://127.0.0.1:3000/health

• ソースファイル参照：http://127.0.0.1:3000/source/:documentId

デフォルトではローカルホストのみをリッスンします。他のマシンにデプロイする場合は、リバースプロキシ層でTLS、認証、アクセス制御を追加し、--public-base-url でモデルがアクセス可能な正規アドレスを設定する必要があります。

0.0.0.0 や他のローカルホスト以外のアドレスを直接リッスンする場合、サービスはBearer Tokenの設定を要求します：

$env:CODEBASE_MCP_TOKEN = "replace-with-a-long-random-token"
node dist/cli.js --root C:/path/to/your-repository --transport http --host 0.0.0.0 --port 3000

その後、クライアントは /mcp および /health に対して Authorization: Bearer <token> を送信する必要があります。サービスが返す参照アドレスには自動的にHMAC署名が付与されるため、ユーザーは対応する /source リンクを直接開くことができます。手動で未署名の /source アドレスにアクセスする場合もBearer Tokenが必要です。ローカルのリバースプロキシ経由で公開する場合、サービスは引き続き 127.0.0.1 をリッスンし、プロキシが外部認証を担当するようにできます。

MCP ツール

推奨される呼び出し順序：

1. search_code を使用して実装と関連スニペットを検索します。

2. get_code_context を使用して高スコアのスニペットを展開します。

3. 定義を正確に特定する必要がある場合は find_symbol を使用します。

4. 本当に完全なファイルが必要な場合のみ fetch を使用します。

検索方式

インデックスは完全にローカルメモリ上で動作します：

1. コードファイルは最大120行、20行のオーバーラップでスライスされます。

2. 一般的な言語宣言からclass、interface、type、enum、function、methodなどのシンボルを抽出します。

3. 本文はBM25で再現性を高め、シンボルとパスは個別にランキングされます。

4. reciprocal-rank fusionを使用して、本文、シンボル、パス、完全一致のスコアを統合します。

5. デフォルトでは、各ファイルから最大2つのスニペットを返し、重複するテンプレートコードで結果が埋め尽くされるのを防ぎます。

このバージョンには外部ベクトルデータベースはなく、ソースコードがアップロードされることもありません。大規模なマルチリポジトリ、クロスランゲージセマンティック検索の場合は、既存の CodebaseIndex.search の前後にembedding再現性やrerankerを追加できます。MCPツールの契約は変更する必要はありません。

設定

--root PATH
--transport stdio|http
--host HOST
--port PORT
--public-base-url URL
--max-file-bytes N
--max-files N

対応する環境変数：

CODEBASE_ROOT
CODEBASE_TRANSPORT
CODEBASE_HOST
CODEBASE_PORT
CODEBASE_PUBLIC_BASE_URL
CODEBASE_MCP_TOKEN
CODEBASE_MAX_FILE_BYTES
CODEBASE_MAX_FILES

デフォルトの単一ファイル上限は1 MiB、ファイル数上限は20,000です。

開発と検証

npm run build
npm test

テストは、インデックス構築、.gitignore、中国語クエリ拡張、シンボルとパスのフィルタリング、パス範囲外、標準の search/fetch、メモリMCP、実際のstdioサブプロセス、Streamable HTTPをカバーしています。

MCP Inspectorを使用してHTTPサービスを直接検査することも可能：

npx @modelcontextprotocol/inspector

その後、Streamable HTTPを選択し、http://127.0.0.1:3000/mcp を入力します。

実装は OpenAI公式MCPサーバーガイド および標準の search / fetch データ形状 に従っています。

現在の制限

• インデックスはプロセス再起動後に再構築され、永続化キャッシュはありません。

• GitリポジトリはGit無視ルールに完全に従います。Git以外のディレクトリは現在、ルートディレクトリの .gitignore を読み取ります。

• シンボル抽出は軽量な宣言解析を使用し、完全なコンパイラASTとは同等ではありません。

• ファイル変更後は refresh_index を呼び出します。現在のバージョンではファイル監視は有効になっていません。

ライセンス

MIT