Code Index MCP

Code Index MCP

概要

Code Index MCP は、AI モデルと複雑なコードベースをつなぐ Model Context Protocol サーバーです。インテリジェントなインデックス作成、高度な検索機能、詳細なコード分析を提供し、AI アシスタントがプロジェクトを効果的に理解し、ナビゲートできるよう支援します。

次の用途に最適です： コードレビュー、リファクタリング、ドキュメント生成、デバッグ支援、アーキテクチャ分析。

クイックスタート

🚀 推奨セットアップ（ほとんどのユーザー向け）

MCP 対応アプリケーションで最も簡単に使い始める方法です。

前提条件： Python 3.10+ と uv

1. MCP の設定に追加します（例：claude_desktop_config.json または ~/.claude.json）：

   {
     "mcpServers": {
       "code-index": {
         "command": "uvx",
         "args": ["code-index-mcp"]
       }
     }
   }
   

   任意：args 配列に --project-path /absolute/path/to/repo を追加すると、サーバーはそのリポジトリを自動的に初期化します（起動後に set_project_path を呼び出す場合と同じです）。

2. アプリケーションを再起動します – uvx がインストールと実行を自動的に処理します。

3. 使い始めましょう（AI アシスタントに次のプロンプトを入力します）：

   Set the project path to /Users/dev/my-react-app
   Find all TypeScript files in this project  
   Search for "authentication" functions
   Analyze the main App.tsx file
   

   --project-path を指定して起動した場合は、上記の最初のコマンドを省略できます。サーバーはすでにプロジェクトの場所を認識しています。

Codex CLI の設定

Anthropic の Codex CLI を使用している場合は、サーバーを ~/.codex/config.toml に追加します。 Windows では、ファイルは C:\Users\<you>\.codex\config.toml にあります。

[mcp_servers.code-index]
type = "stdio"
command = "uvx"
args = ["code-index-mcp"]

args リストに --project-path C:/absolute/path/to/repo を追加すると、起動時にプロジェクトを自動設定できます（set_project_path ツールを実行する場合と同じ効果です）。

Windows では、uvx が動作するには標準のプロファイルディレクトリが存在している必要があります。 MCP が確実に起動するよう、環境変数の上書き設定は同じブロック内に置いてください。

env = {
  HOME = "C:\\Users\\<you>",
  APPDATA = "C:\\Users\\<you>\\AppData\\Roaming",
  LOCALAPPDATA = "C:\\Users\\<you>\\AppData\\Local",
  SystemRoot = "C:\\Windows"
}

Linux と macOS では、必要な XDG パスと HOME がすでに設定されているため、通常は env テーブルを省略できます。 制限付きコンテナ内で CLI を実行する場合にのみ、上書き設定を追加してください。

FastMCP とディスカバリーマニフェスト

• fastmcp run fastmcp.json を実行すると、正しいソースのエントリーポイントと依存関係のメタデータを使って、FastMCP 経由でサーバーを起動できます。正しいリポジトリを対象にインデックスを初期化するため、--project-path を渡すか、起動後に set_project_path ツールを呼び出してください。
• 標準に準拠した MCP マニフェストを共有するには、.well-known/mcp.json を公開するか、コピーしてください。.well-known 規約に対応するクライアント（例：Claude Desktop、Codex CLI）は、設定を手動で作成する代わりに、このファイルを直接インポートできます。
• より豊富な LLM Feed メタデータを公開する場合は、.well-known/mcp.llmfeed.json を公開してください。このファイルは、同じ code-index サーバー定義にドキュメントとソースへのリンクを加えたものを参照し、レジストリで説明、タグ、機能を自動的に表示しやすくします。

マニフェストを共有する際は、意図したリポジトリをサーバーがインデックス化できるよう、利用者に --project-path を指定するか、set_project_path を呼び出すよう伝えてください。

典型的なユースケース

コードレビュー：「古い API を使用している箇所をすべて探す」
リファクタリングの支援：「この関数はどこから呼び出されていますか？」
学習用プロジェクト：「この React プロジェクトの主要なコンポーネントを表示する」
デバッグ：「エラー処理に関連するコードをすべて検索する」

主な機能

🔍 インテリジェントな検索と分析

• デュアル戦略アーキテクチャ：10 の主要言語には専用の tree-sitter 解析を使用し、50 種類以上のファイル形式にはフォールバック戦略を使用します
• tree-sitter との直接統合：専用言語では正規表現によるフォールバックはありません。明確なエラーを表示して即座に失敗します
• 高度な検索：利用可能な最適なツール（ugrep、ripgrep、ag、grep）を自動検出して使用します
• あらゆるファイル形式に対応：高度な AST 解析から基本的なファイルインデックス作成まで、幅広く対応します
• ファイル分析：build_deep_index の実行後に、構造、インポート、クラス、メソッド、複雑度の指標を詳しく確認できます

🗂️ 多言語対応

• tree-sitter AST 解析に対応する 10 言語：Python、JavaScript、TypeScript、Java、Kotlin、C#、Go、Objective-C、Zig、Rust
• フォールバック戦略に対応する 50 種類以上のファイル形式：C/C++、Ruby、PHP、その他すべてのプログラミング言語
• ドキュメントと設定ファイル：Markdown、JSON、YAML、XML に適切に対応します
• Web フロントエンド：Vue、React、Svelte、HTML、CSS、SCSS
• Java Web とビルド：JSP/Tag ファイル（.jsp、.jspx、.jspf、.tag、.tagx）、Grails/GSP（.gsp）、Gradle と Groovy のビルド（.gradle、.groovy）、.properties、Protocol Buffers（.proto）
• データベース：SQL の各種形式、NoSQL、ストアドプロシージャ、マイグレーション
• 設定ファイル：JSON、YAML、XML、Markdown
• 対応するファイル形式の一覧

⚡ リアルタイム監視と自動更新

• ファイルウォッチャー：ファイルの変更時にインデックスを自動更新します
• クロスプラットフォーム：OS ネイティブのファイルシステム監視を利用します
• スマートな処理：短時間に発生した変更をまとめ、過剰な再構築を防ぎます
• 浅いインデックスの更新：ファイルの変更を監視してファイル一覧を最新の状態に保ちます。シンボルのメタデータが必要な場合は、ディープビルドを実行してください

⚡ パフォーマンスと効率性

• tree-sitter AST 解析：ネイティブの構文解析により、正確にシンボルを抽出します
• 永続キャッシュ：インデックスを保存し、次回以降のアクセスを大幅に高速化します
• スマートなフィルタリング：ビルドディレクトリや一時ファイルをインテリジェントに除外します
• メモリ効率：大規模なコードベース向けに最適化されています
• 直接依存関係：フォールバック機構はありません。明確なエラーメッセージを表示して即座に失敗します

サポートされているファイル形式

🛠️ 開発環境のセットアップ

コントリビューションまたはローカル開発を行う場合：

1. クローンしてインストール：

   git clone https://github.com/johnhuang316/code-index-mcp.git
   cd code-index-mcp
   uv sync
   

2. ローカル開発用に設定：

   {
     "mcpServers": {
       "code-index": {
         "command": "uv",
         "args": ["run", "code-index-mcp"]
       }
     }
   }
   

3. MCP Inspector でデバッグ：

   npx @modelcontextprotocol/inspector uv run code-index-mcp
   

pip install code-index-mcp

{
  "mcpServers": {
    "code-index": {
      "command": "code-index-mcp",
      "args": []
    }
  }
}

利用可能なツール

🏗️ プロジェクト管理

シンボルレベルのデータが必要な場合は build_deep_index を実行してください。デフォルトの浅いインデックスは、ファイルをすばやく検索するために使用されます。

🔍 検索と探索

🔄 監視と自動更新

🛠️ システムとメンテナンス

使用例

🎯 クイックスタートのワークフロー

1. プロジェクトを初期化する

Set the project path to /Users/dev/my-react-app

コードベースを自動的にインデックス化し、検索可能なキャッシュを作成します

2. プロジェクト構造を確認する

Find all TypeScript component files in src/components

使用するもの：パターン src/components/**/*.tsx を指定した find_files

3. 主要なファイルを分析する

Give me a summary of src/api/userService.ts

使用するもの：関数、インポート、複雑さを表示する get_file_summary ヒント：needs_deep_index という応答が返された場合は、先に build_deep_index を実行してください。

🔍 高度な検索の例

Search for all function calls matching "get.*Data" using `regex=True`

Find authentication-related functions with fuzzy search for 'authUser'

Search for "API_ENDPOINT" only in Python files

Configure automatic index updates when files change

I added new components, please refresh the project index

トラブルシューティング

🔄 自動更新が機能しない

ファイルの変更時にインデックスが自動更新されない場合は、次の方法をお試しください。

• pip install watchdog を実行します（環境の分離に関する問題が解決する場合があります）
• 手動で更新します。ファイルを変更した後に refresh_index ツールを呼び出してください
• ファイル監視の状態を確認します。get_file_watcher_status を使って監視が有効になっているか確認してください

macOS のファイル監視オプション

デフォルトの FSEvents オブザーバーは、ほとんどのプロジェクトで正常に動作します。問題が発生した場合は、configure_file_watcher を使って別のオブザーバーに切り替えられます。

• "auto"（デフォルト）：プラットフォームのデフォルト（macOS では FSEvents）
• "kqueue"：Kqueue オブザーバー（macOS／BSD）
• "fsevents"：FSEvents を強制（macOS のみ）
• "polling"：クロスプラットフォームのポーリングによるフォールバック

注：Kqueue は監視対象のファイルごとにファイルディスクリプターを1つ使用します。kqueue を使う大規模なプロジェクトでは、上限を引き上げる必要がある場合があります。ulimit -n 10240

開発とコントリビューション

🔧 ソースからビルド

git clone https://github.com/johnhuang316/code-index-mcp.git
cd code-index-mcp
uv sync
uv run code-index-mcp

🐛 デバッグ

npx @modelcontextprotocol/inspector uvx code-index-mcp

🤝 コントリビューション

コントリビューションを歓迎します。お気軽にプルリクエストを送信してください。

📜 ライセンス

MIT ライセンス

🌐 翻訳

• 繁體中文
• 日本語