shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

mcp-codebase-index

一个基于MCP协议的代码库语义搜索服务器，利用Gemini嵌入和Qdrant向量存储，为AI编辑器提供代码理解和搜索功能。

article

README

🚀 MCP代码库索引服务器

MCP代码库索引服务器借助Google的Gemini嵌入技术和Qdrant向量存储，让AI编辑器能够对代码库进行搜索和理解，为开发者提供强大的代码语义搜索功能，支持GitHub Copilot、Kiro等多种编辑器，极大提升开发效率。

npm version License: MIT

这是一个基于模型上下文协议（MCP）的服务器，它利用Google的Gemini嵌入技术和Qdrant向量存储，使AI编辑器能够搜索和理解你的代码库。

支持的编辑器：

  • ✅ 集成GitHub Copilot的VS Code
  • ✅ 集成Roo Cline的VS Code
  • ✅ GitHub Copilot CLI
  • ✅ Google Gemini CLI
  • ✅ Kiro AI编辑器
  • ✅ 任何支持MCP的编辑器

🚀 快速开始

📚 快速导航

💻 开发者相关

🔧 资源

🔍 前提条件

  1. Gemini API密钥 - 可在Google AI Studio免费获取。
  2. Qdrant云账户 - 可在cloud.qdrant.io免费注册。

📦 安装指南

选择你的环境：

步骤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云。
  • 索引你的代码库。
  • 监控文件更改。

📖 详细说明：

✨ 主要特性

  • 🔍 语义搜索 - 按代码含义而非关键词进行搜索。
  • 🎯 智能分块 - 自动将代码分割为逻辑函数/类。
  • 🔄 增量索引 - 仅重新索引更改的文件（节省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. ✅ 重构验证
    • 在重构前后进行可视化。
    • 验证代码组织是否得到改善。
    • 跟踪架构演变。

性能

| 集合大小 | 处理时间 | 建议的最大向量数 | |----------------|-----------------|------------------------| | 小 (<500向量) | ~1秒 | 500 | | 中 (500 - 2K) | ~4秒 | 1000 | | 大 (2K - 10K) | ~15秒 | 2000 | | 非常大 (>10K) | ~30秒 | 3000 |

提示：

  • 使用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

📊 性能

| 指标 | 值 | |--------|-------| | 索引速度 | ~25个文件/分钟 | | 搜索延迟 | <100毫秒 | | 增量节省 | 节省90%以上的时间 | | 并行处理 | 25个块/秒 |

📖 性能详情： 主文档

🐛 故障排除

服务器未显示？

  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所有。

📞 支持

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

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端