MCP Codebase Index

🚀 MCP Codebase Index Server

AIによるセマンティック検索を、GitHub Copilot、Kiro、その他のMCP互換エディタでコードベースに適用できます。

このModel Context Protocol (MCP) サーバーは、GoogleのGemini埋め込みとQdrantベクトルストレージを使用して、AIエディタがコードベースを検索および理解できるようにします。

対応エディタ:

• ✅ GitHub Copilot付きのVS Code
• ✅ Roo Cline付きのVS Code
• ✅ GitHub Copilot CLI
• ✅ Google Gemini CLI
• ✅ Kiro AIエディタ
• ✅ 任意のMCP互換エディタ

🚀 クイックスタート

📚 クイックナビゲーション

🚀 始める前に

• 📖 完全なドキュメント - 完全なドキュメント
• ⚙️ セットアップガイド - VS Code - VS Code Copilot用のインストール方法
• 🖥️ セットアップガイド - CLI - GitHub Copilot CLI用のインストール方法
• 🤖 セットアップガイド - Gemini CLI - Google Gemini CLI用のインストール方法
• 🎯 セットアップガイド - Kiro - Kiro AIエディタ用のインストール方法
• 🦘 セットアップガイド - Roo Cline - Roo Cline (VS Code) 用のインストール方法
• ⚡ クイックリファレンス - コマンドチートシート
• 🗺️ ナビゲーションガイド - すべてのドキュメントをすばやく見つける方法

💻 開発者向け

• ソースコード構造 - コードの組織化
• MCPサーバーガイド - 独自のMCPサーバーを構築する方法
• ロードマップ - 将来の計画

🔧 リソース

• Qdrantセットアップ - Qdrantの資格情報を取得する方法
• テストガイド - 検索機能をテストする方法
• プロンプトエンハンスメントガイド - プロンプトエンハンスメントを効果的に使用する方法
• ベクトル可視化ガイド - コードベースを可視化する方法
• 変更履歴 - バージョン履歴

✨ 主な機能

• 🔍 セマンティック検索 - キーワードだけでなく、意味に基づいてコードを検索できます。
• 🎯 スマートチャンキング - コードを論理的な関数やクラスに自動的に分割します。
• 🔄 インクリメンタルインデックス作成 - 変更されたファイルのみを再インデックス化するため、90%以上の時間を節約できます。
• 💾 自動保存チェックポイント - 10ファイルごとに進捗を保存し、いつでも再開できます。
• 📊 リアルタイム進捗 - ETAとパフォーマンスメトリクスでインデックス作成の進捗を追跡できます。
• ⚡ 並列処理 - バッチ実行により、インデックス作成速度が25倍向上します。
• 🔄 リアルタイムウォッチ - ファイルの変更を自動的に検出し、インデックスを更新します。
• 🌐 多言語対応 - 15種類以上のプログラミング言語をサポートしています。
• ☁️ ベクトルストレージ - Qdrantを使用して永続的なストレージを提供します。
• 🤖 プロンプトエンハンスメント - AIによるクエリの改善機能（オプション）
• 🎨 ベクトル可視化 - コードベースの2D/3D UMAP可視化が可能です。
• 🏗️ モジュール化アーキテクチャ - 保守性を高めるためにハンドラーを明確に分離しています。
• 📦 簡単なセットアップ - たった4つの環境変数で設定できます。

🚀 クイックスタート

前提条件

1. Gemini APIキー - Google AI Studio で無料で取得できます。
2. Qdrant Cloudアカウント - cloud.qdrant.io で無料でサインアップできます。

インストール

⚠️ 重要提示

環境に合わせて以下のガイドを参照してください。

• VS Codeユーザー: 以下の手順に従うか、Roo Clineセットアップ を参照してください。
• Copilot CLIユーザー: Copilot CLIセットアップガイド を参照してください。
• Gemini CLIユーザー: Gemini CLIセットアップガイド を参照してください。
• Kiroユーザー: Kiroセットアップガイド を参照してください。

ステップ1: VS CodeでMCP設定を開く

1. GitHub Copilotチャットを開きます (Ctrl+Alt+I / Cmd+Alt+I)。
2. 設定アイコンをクリックし、MCP Servers → MCP Configuration (JSON) を選択します。

ステップ2: mcp.json に以下の設定を追加します。

{
  "servers": {
    "codebase": {
      "command": "npx",
      "args": ["-y", "@ngotaico/mcp-codebase-index"],
      "env": {
        "REPO_PATH": "/absolute/path/to/your/project",
        "GEMINI_API_KEY": "AIzaSyC...",
        "QDRANT_URL": "https://your-cluster.gcp.cloud.qdrant.io:6333",
        "QDRANT_API_KEY": "eyJhbGci..."
      },
      "type": "stdio"
    }
  }
}

ステップ3: VS Codeを再起動します。

サーバーは自動的に以下の処理を行います。

• Qdrant Cloudに接続します。
• コードベースをインデックス化します。
• ファイルの変更を監視します。

📖 詳細な手順:

• VS Codeセットアップガイド
• Copilot CLIセットアップガイド

💻 使用例

コードベースを検索する

GitHub Copilotに以下のように問いかけます。

"認証ロジックを探す"
"データベース接続の処理方法を教えて"
"エラーロギングが実装されている場所を教えて"

コードベースを可視化する

GitHub Copilotに以下のように問いかけます。

"コードベースを可視化する"
"コードの構成方法を教えて"
"認証コードを可視化する"

📖 完全なガイド: ベクトル可視化ガイド

インデックス作成の状態を確認する

"インデックス作成の状態を確認する"
"詳細なインデックス作成の進捗を教えて"

📖 詳細な例: テストガイド

📊 ベクトル可視化

2D/3D空間でコードベースを可視化しましょう - セマンティックな関係とコードの構成を視覚的に理解できます。

ベクトル可視化とは何ですか？

ベクトル可視化は、UMAP次元削減を使用して、コードベースの768次元の埋め込みをインタラクティブな2Dまたは3Dの可視化に変換します。これにより、以下のことが可能になります。

• 🎨 セマンティックな関係を探索する - 類似したコードがクラスター化されます。
• 🔍 アーキテクチャを理解する - コードベースの構造を一目で把握できます。
• 🎯 検索結果をデバッグする - 特定のコードが取得された理由を可視化できます。
• 📈 コードの構成を追跡する - モジュール、パターン、および外れ値を特定できます。

クイックスタート

コードベース全体を可視化する:

ユーザー: "コードベースを可視化する"

結果: 以下を示すインタラクティブなクラスターが表示されます。
- APIコントローラーとルート (28%)
- データベースモデル (23%)
- 認証 (19%)
- ビジネスロジック (18%)
- テストスイート (12%)

HTMLとしてエクスポートする:

ユーザー: "可視化をHTMLとしてエクスポートする"

結果: 以下の機能を持つスタンドアローンのHTMLファイルが生成されます。
- インタラクティブなホバー、ズーム、パン機能
- クラスターをクリックしてハイライト表示
- モダンなグラデーションUI
- オフラインでも動作する

可視化の理解

色とクラスター:

• 各色はセマンティックなクラスター（モジュール/機能）を表します。
• 近くにある点は意味が類似しています。
• 距離はセマンティックな類似性を反映しています。
• 外れ値は独自の/特殊なコードを示しています。

一般的なクラスターパターン:

• 青: フロントエンド/UIコンポーネント
• オレンジ: APIエンドポイントとルート
• 緑: データベースモデルとクエリ
• 赤: 認証とセキュリティ
• 紫: テストと検証
• 灰色: ユーティリティとヘルパー

ユースケース

1. 🏗️ アーキテクチャの理解

   • 可視化を使用してモジュールの境界を確認します。
   • 密結合のコードを特定します。
   • リファクタリングの機会を見つけます。

2. 🔍 コードの発見

   • 関連する機能を視覚的に見つけます。
   • 特定の機能に関連するすべてのコードを見つけます。
   • 横断的な関心事を発見します。

3. 🐛 検索のデバッグ

   • 結果が取得された理由を理解します。
   • セマンティックな関係を確認します。
   • 可視化に基づいてクエリを改善します。

4. 👥 チームのオンボーディング

   • 新しい開発者向けにHTMLをエクスポートします。
   • コードベースの構造を視覚的にガイドします。
   • インタラクティブな探索ツールとして使用します。

5. ✅ リファクタリングの検証

   • リファクタリング前後の可視化を比較します。
   • 改善されたコードの構成を確認します。
   • アーキテクチャの進化を追跡します。

パフォーマンス

💡 使用建议

• 処理速度を速くするには2Dを使用してください（3Dより40%速い）。
• 大きなコードベースの場合はmaxVectorsを制限してください。
• オフラインでの探索にはHTMLをエクスポートしてください。

📖 詳細を学ぶ

以下の詳細なドキュメントを参照してください。

• 完全なツールリファレンス
• 解釈ガイド
• 技術的な詳細 (UMAP、クラスタリング)
• トラブルシューティング
• ベストプラクティス
• 高度なユースケース

参照先: ベクトル可視化ガイド

🎯 プロンプトエンハンスメント (オプション)

要約: プロンプトエンハンスメントは、検索品質を自動的に向上させる透明なバックグラウンドツールです。自然に問いかけるだけで、プロンプトに "エンハンス" と言う必要はありません。

概要

有効にすると (PROMPT_ENHANCEMENT=true)、AIは自動的に以下の処理を行います。

1. コードベースのコンテキストを使用して検索クエリを強化します。
2. 改善されたクエリで検索を行います。
3. 元の要求（実装、修正、説明など）を続行します。

良いプロンプト ✅

✅ "認証ロジックを見つけて2FAサポートを追加する"
✅ "支払いフローを見つけてタイムアウト問題を修正する"
✅ "プロファイル機能を検索してバイオフィールドを追加する"

なぜうまくいくのか: 明確な目標（見つける + アクション） → AIが何をすべきかを理解できます。

悪いプロンプト ❌

❌ "強化して認証を検索する"
❌ "プロンプトエンハンスメントを使用してプロファイルを見つける"

なぜ失敗するのか: 明確なアクションがない → AIは検索後に停止します。

重要な原則

プロンプトエンハンスメントは目に見えないインフラストラクチャです。

AIに何を達成したいかを伝えるだけで、自動的にエンハンスメントを使用して検索品質を改善します。

自動補完のように考えてください: 「自動補完を使用する」と言わないように、自然に入力するだけで自動的に支援されます。

📖 詳細を学ぶ

以下の詳細なガイドを参照してください。

• 技術的な詳細とアーキテクチャ
• 設定オプション
• 実際の例 (TypeScript、Python、Dartなど)
• パフォーマンスのヒントと最適化
• トラブルシューティングとFAQ
• 高度なユースケース

参照先: プロンプトエンハンスメントガイド

🎛️ 設定

必須変数

{
  "env": {
    "REPO_PATH": "/Users/you/Projects/myapp",
    "GEMINI_API_KEY": "AIzaSyC...",
    "QDRANT_URL": "https://xxx.gcp.cloud.qdrant.io:6333",
    "QDRANT_API_KEY": "eyJhbGci..."
  }
}

オプション変数

{
  "env": {
    "QDRANT_COLLECTION": "my_project",
    "WATCH_MODE": "true",
    "BATCH_SIZE": "50",
    "EMBEDDING_MODEL": "text-embedding-004",
    "PROMPT_ENHANCEMENT": "true"
  }
}

📖 完全な設定ガイド: セットアップガイド

🌍 対応言語

Python • TypeScript • JavaScript • Dart • Go • Rust • Java • Kotlin • Swift • Ruby • PHP • C • C++ • C# • Shell • SQL • HTML • CSS

📊 パフォーマンス

📖 パフォーマンスの詳細: メインドキュメント

🐛 トラブルシューティング

サーバーが表示されない場合

1. Copilotチャット → 設定 → MCPサーバー → 出力を表示してください。
2. すべての4つの環境変数が設定されていることを確認してください。
3. REPO_PATH が絶対パスであることを確認してください。

Qdrantに接続できない場合

curl -H "api-key: YOUR_KEY" \
  https://YOUR_CLUSTER.gcp.cloud.qdrant.io:6333/collections

インデックス作成が遅い場合

• 大きなリポジトリの場合は、最初の実行に5-10分かかることがあります。
• その後の実行では、変更されたファイルのみをインデックス化するため、90%以上高速になります。

📖 詳細なトラブルシューティング: メインドキュメント

📁 プロジェクト構造

mcp-codebase-index/
├── docs/                    # すべてのドキュメント
│   ├── README.md           # メインドキュメント
│   ├── SETUP.md            # セットアップガイド
│   ├── CHANGELOG.md        # 変更履歴
│   ├── NAVIGATION.md       # ナビゲーションガイド
│   ├── guides/             # 詳細なガイド
│   └── planning/           # 開発計画
│
├── src/                     # ソースコード
│   ├── core/               # コアビジネスロジック
│   ├── storage/            # データ永続化
│   ├── enhancement/        # プロンプトエンハンスメント
│   ├── visualization/      # ベクトル可視化
│   ├── mcp/                # MCPサーバー
│   │   ├── server.ts      # サーバーオーケストレーション (1237行)
│   │   ├── handlers/      # モジュール化ハンドラー (1045行)
│   │   ├── templates/     # HTMLテンプレート
│   │   └── types/         # ハンドラータイプ
│   ├── types/              # 型定義
│   └── index.ts            # エントリポイント
│
├── config/                  # 設定ファイル
├── .data/                   # ランタイムデータ (gitignored)
├── package.json
└── README.md               # このファイル

📖 詳細な構造: プロジェクト構造 | ソースコード構造

🔧 開発

ビルド

npm run build

ローカルで実行

npm run dev

テスト

npm test

📖 開発ガイド: ソースコード構造

🤝 コントリビューション

コントリビューションを歓迎します！以下を参照してください。

• 改善計画 - ロードマップ
• 問題 - 詳細な機能ドキュメント
• ソースコード - コード構造

📄 ライセンス

MIT © NgoTaiCo

📞 サポート

• 問題報告: GitHub Issues
• ディスカッション: GitHub Discussions
• メール: ngotaico.flutter@gmail.com

⭐ このプロジェクトが役に立った場合は、スターをつけてください！