MCP Codebase Index

🚀 MCP代碼庫索引服務器

MCP代碼庫索引服務器藉助Google的Gemini嵌入技術和Qdrant向量存儲，讓AI編輯器能夠對代碼庫進行搜索和理解，為開發者提供強大的代碼語義搜索功能，支持GitHub Copilot、Kiro等多種編輯器，極大提升開發效率。

這是一個基於模型上下文協議（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憑證
• 測試指南 - 測試搜索功能
• 提示增強指南 - 有效使用提示增強功能
• 向量可視化指南 - 可視化你的代碼庫
• 更新日誌 - 版本歷史記錄

🔍 前提條件

1. Gemini API密鑰 - 可在Google AI Studio免費獲取。
2. Qdrant雲賬戶 - 可在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服務器 → MCP配置（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雲。
• 索引你的代碼庫。
• 監控文件更改。

📖 詳細說明：

• VS Code設置指南
• Copilot CLI設置指南

✨ 主要特性

• 🔍 語義搜索 - 按代碼含義而非關鍵詞進行搜索。
• 🎯 智能分塊 - 自動將代碼分割為邏輯函數/類。
• 🔄 增量索引 - 僅重新索引更改的文件（節省90%以上的時間）。
• 💾 自動保存檢查點 - 每處理10個文件保存一次進度，可隨時恢復。
• 📊 即時進度跟蹤 - 通過預計完成時間和性能指標跟蹤索引進度。
• ⚡ 並行處理 - 通過批量執行，索引速度提高25倍。
• 🔄 即時監控 - 文件更改時自動更新索引。
• 🌐 多語言支持 - 支持15種以上的編程語言。
• ☁️ 向量存儲 - 使用Qdrant進行持久存儲。
• 🤖 提示增強（可選） - 由AI驅動，自動改進搜索查詢。
• 📊 向量可視化 - 以2D/3D UMAP可視化你的代碼庫。
• 🏗️ 模塊化架構 - 清晰的處理程序分離，便於維護。
• 📦 簡單設置 - 僅需設置4個環境變量。

💻 使用示例

搜索代碼庫

向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%）。
• 對於大型代碼庫，限制最大向量數。
• 導出HTML文件進行離線探索。

📖 瞭解更多： 如需詳細文檔，包括：

• 完整工具參考
• 解釋指南
• 技術細節（UMAP、聚類）
• 故障排除
• 最佳實踐
• 高級用例

請查看： 向量可視化指南

🎯 提示增強（可選）

簡而言之：提示增強是一個透明的後臺工具，可自動提高搜索質量。你只需自然地提問，無需在提示中提及“增強”。

快速概述

啟用提示增強功能 (PROMPT_ENHANCEMENT=true) 後，AI將自動執行以下操作：

1. 增強：結合代碼庫上下文，改進你的搜索查詢。
2. 搜索：使用改進後的查詢進行搜索。
3. 繼續執行：繼續處理你原來的請求（實現、修復、解釋等）。

好的提示示例 ✅

✅ "查找身份驗證邏輯並添加2FA支持"
✅ "定位支付流程並修復超時問題"
✅ "搜索配置文件功能並添加生物信息字段"

原因：明確的目標（查找 + 操作）→ AI知道要做什麼。

不好的提示示例 ❌

❌ "增強並搜索身份驗證"
❌ "使用提示增強查找配置文件"

原因：沒有明確的操作 → AI在搜索後停止。

關鍵原則

提示增強是無形的基礎設施。

你只需告訴AI你想要完成的任務，它將在後臺自動使用提示增強功能來提高搜索質量。

可以將其視為自動補全：你不會說“使用自動補全”，只需輸入內容，它會自動提供幫助。

📖 瞭解更多： 如需詳細指南，包括：

• 技術細節和架構
• 配置選項
• 實際示例（TypeScript、Python、Dart等）
• 性能提示和優化
• 故障排除和常見問題解答
• 高級用例

請查看： 提示增強指南

🎛️ 配置

必需變量

{
  "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/                   # 運行時數據 (已添加到.gitignore)
├── package.json
└── README.md               # 本文件

📖 詳細結構： 項目結構 | 源代碼結構

🔧 開發

構建

npm run build

本地運行

npm run dev

測試

npm test

📖 開發指南： 源代碼結構

🤝 貢獻

歡迎貢獻代碼！請查看：

• 改進計劃 - 路線圖
• 問題列表 - 詳細的功能文檔
• 源代碼 - 代碼結構

📄 許可證

本項目採用MIT許可證，版權歸NgoTaiCo所有。

📞 支持

• 問題反饋：GitHub問題
• 討論交流：GitHub討論
• 電子郵件：ngotaico.flutter@gmail.com

⭐ 如果你覺得這個項目有用，請給倉庫點個星！