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

⭐ 如果你觉得这个项目有用，请给仓库点个星！