MCP代码库索引服务器
在GitHub Copilot、Kiro和其他兼容MCP的编辑器中，对您的代码库进行人工智能语义搜索
一个模型上下文协议（MCP）服务器，使AI编辑器能够使用谷歌的Gemini嵌入和Qdrant向量存储来搜索和理解您的代码库。
支持的编辑器：
- ✅ VS代码与GitHub Copilot
- ✅ VS代码与Roo Cline
- ✅ GitHub Copilot命令行界面
- ✅ 谷歌Gemini CLI
- ✅ Kiro AI编辑
- ✅ 任何兼容MCP的编辑器
______________________________________________________________________
📚 快速导航
🚀 入门指南
- 📖 全部文件 -完整的文档
- ⚙️ 安装指南-VS代码 -VS代码副本的安装
- 🖥️ 安装指南-CLI -GitHub Copilot CLI的安装
- 🤖 安装指南-Gemini CLI -Google Gemini CLI的安装
- 🎯 设置指南-Kiro -Kiro AI编辑器的安装
- 🦘 安装指南-Roo Cline -Roo-Cline的安装（VS代码）
- ⚡ 快速参考 -命令备忘单
- 🗺️ 导航指南 -快速找到任何文档
💻 对于开发者
🔧 资源
______________________________________________________________________
✨ 特性
- 🔍 语义搜索 -按含义查找代码，而不仅仅是关键字
- 🎯 智能分块 -自动将代码拆分为逻辑函数/类
- 🔄 增量索引 -仅重新索引更改的文件（节省90%以上的时间）
- 💾 自动保存检查点 -每10个文件保存一次进度，随时恢复
- 📊 实时进度 -使用ETA和性能指标跟踪索引
- ⚡ 并行处理 -通过批处理执行，索引速度提高了25倍
- 🔄 实时观察 -文件更改时自动更新索引
- 🌐 多语言 -支持15种以上编程语言
- ☁️ 矢量存储器 -使用Qdrant进行持久存储
- 🤖 快速增强 -人工智能驱动的查询改进（可选）
- � 矢量可视化 -代码库的2D/3D UMAP可视化
- 🏗️ 模块化架构 -清洁处理器分离，便于维护
- �📦 简单设置 -只有4个环境变量
______________________________________________________________________
🚀 快速开始
先决条件
- Gemini API密钥 -免费获取 谷歌人工智能工作室
- Qdrant云帐户 -免费注册 cloud.qdrant.io
安装
选择您的环境： - VS代码用户：请按照以下步骤操作或参阅 Roo临床设置 - Copilot CLI用户：参见 Copilot CLI安装指南 - Gemini CLI用户：参见 Gemini CLI安装指南 - Kiro用户：参见 Kiro安装指南
第一步： 在VS代码中打开MCP配置
- 打开GitHub Copilot聊天(
Ctrl+Alt+I/Cmd+Alt+I) - 单击设置图标→ MCP服务器→ MCP配置（JSON）
第二步： 将此配置添加到 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代码
服务器将自动：
- 连接到Qdrant Cloud
- 索引你的代码库
- 注意文件更改
📖 详细说明：
______________________________________________________________________
📖 用法
搜索您的代码库
询问GitHub Copilot：
"Find the authentication logic"
"Show me how database connections are handled"
"Where is error logging implemented?"可视化您的代码库
询问GitHub Copilot：
"Visualize my codebase"
"Show me how my code is organized"
"Visualize authentication code"📖 完整指南： 矢量可视化指南
检查索引状态
"Check indexing status"
"Show me detailed indexing progress"📖 更多示例： 测试指导
📊 矢量可视化
在2D/3D空间中查看您的代码库 -直观地理解语义关系和代码组织。
什么是矢量可视化？
矢量可视化转换您的代码库 768维嵌入 进入互动 2D或3D可视化 使用UMAP降维。这使您能够：
- 🎨 探索语义关系 -相似的代码聚集在一起
- 🔍 了解架构 -一目了然地查看您的代码库结构
- 🎯 调试搜索结果 -可视化检索特定代码的原因
- 📈 轨道代码组织 -识别模块、模式和异常值
快速开始
可视化整个代码库：
User: "Visualize my codebase"
Result: Interactive clusters showing:
- API Controllers & Routes (28%)
- Database Models (23%)
- Authentication (19%)
- Business Logic (18%)
- Test Suites (12%)导出为HTML：
User: "Export visualization as HTML"
Result: Standalone HTML file with:
- Interactive hover, zoom, pan
- Click clusters to highlight
- Modern gradient UI
- Works offline理解可视化
颜色和簇：
- 每种颜色代表一个语义集群（模块/功能）
- 点靠近=意义相似
- 距离反映语义相似性
- 异常值表示唯一/专用代码
常见集群模式：
- 蓝色：前端/UI组件
- 橙子：API端点和路由
- 绿色：数据库模型和查询
- 红：身份验证和安全
- 紫色：测试和验证
- 格雷：公用设施和助手
用例
- 🏗️ 架构理解
- 可视化以查看模块边界 - 识别紧密耦合的代码 - 寻找重构的机会
- 🔍 代码发现
- 直观地定位相关功能 - 查找所有涉及某个功能的代码 - 发现跨领域问题
- 🐛 搜索调试
- 了解检索结果的原因 - 查看语义关系 - 基于可视化优化查询
- 👥 团队入职培训
- 为新开发人员导出HTML - 代码库结构的可视化指南 - 交互式探索工具
- ✅ 重构验证
- 重构前后可视化 - 验证改进的代码组织 - 跟踪架构演变
演出
| 集合大小 | 处理时间 | 建议的最大矢量 |
|---|---|---|
| 小（\10K） | ~300s | 3000 |
提示：
- 使用2D进行更快的处理（比3D快40%）
- 限制大型代码库的maxVectors
- 导出HTML以进行离线探索
📖 了解更多
详细文档包括：
- 完整的工具参考
- 口译指南
- 技术细节（UMAP、集群）
- 故障排除
- 最佳实践
- 高级用例
请参阅： 矢量可视化指南
______________________________________________________________________
🎯 快速增强（可选）
太长，读不下去了 提示增强是一种透明的背景工具，可以自动提高搜索质量。只需自然提问，无需在提示中提及“增强”。
快速概览
启用时(PROMPT_ENHANCEMENT=true)，AI自动：
- 增强 带有代码库上下文的搜索查询
- 搜索 使用改进的查询
- 继续 根据您的原始请求（实现、修复、解释等）
好提示✅
✅ "Find authentication logic and add 2FA support"
✅ "Locate payment flow and fix the timeout issue"
✅ "Search for profile feature and add bio field"为什么这些工作： 明确目标（发现+行动）→ AI知道该做什么
不良提示❌
❌ "Enhance and search for authentication"
❌ "Use prompt enhancement to find profile"这些失败的原因： 没有明确的行动→ 搜索后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
______________________________________________________________________
📊 演出
| 度量 | 值 |
|---|---|
| 索引速度 | 约25个文件/分钟 |
| 搜索延迟 | \<100ms |
| 增量节省 | 时间减少90%以上 |
| 并行处理 | 25块/秒 |
📖 性能详情： 主要文件
______________________________________________________________________
🐛 故障排除
服务器未出现？
- 查看副驾驶聊天→ 设置→ MCP服务器→ 显示输出
- 验证是否已设置所有4个环境变量
- 确保
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/ # All documentation
│ ├── README.md # Main documentation
│ ├── SETUP.md # Setup guide
│ ├── CHANGELOG.md # Version history
│ ├── NAVIGATION.md # Navigation guide
│ ├── guides/ # Detailed guides
│ └── planning/ # Development planning
│
├── src/ # Source code
│ ├── core/ # Core business logic
│ ├── storage/ # Data persistence
│ ├── enhancement/ # Prompt enhancement
│ ├── visualization/ # Vector visualization
│ ├── mcp/ # MCP server
│ │ ├── server.ts # Server orchestration (1237 lines)
│ │ ├── handlers/ # Modular handlers (1045 lines)
│ │ ├── templates/ # HTML templates
│ │ └── types/ # Handler types
│ ├── types/ # Type definitions
│ └── index.ts # Entry point
│
├── config/ # Configuration files
├── .data/ # Runtime data (gitignored)
├── package.json
└── README.md # This file______________________________________________________________________
🔧 发展
构建
npm run build在本地运行
npm run dev测试
npm test📖 开发指南： 源代码结构
______________________________________________________________________
🤝 贡献
欢迎投稿！查看：
______________________________________________________________________
📄 许可证
MIT© NgoTaiCo
______________________________________________________________________
📞 支持
- 问题：
- 讨论：
- 电子邮件： ngotaico.flutter@gmail.com
______________________________________________________________________
⭐ 如果你觉得这很有用，请在repo上加星！