代码库索引

Name: 代码库索引
Author: NgoTaiCo

作者：NgoTaiCo10 星标更新：2025-11-21

安装使用来源：spider==github.com

项目介绍

MCP 代码库索引服务器

在 GitHub Copilot、Kiro 和其他兼容 MCP 的编辑器中使用 AI 驱动的语义搜索功能。

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

支持的编辑器：

✅ VS Code 与 GitHub Copilot
✅ VS Code 与 Roo Cline
✅ 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个环境变量

🚀 快速开始

先决条件

Gemini API 密钥 - 在 Google AI Studio 免费获取
Qdrant Cloud 账户 - 在 cloud.qdrant.io 免费注册

安装

选择您的环境：

VS Code 用户：按照以下步骤操作或参阅 Roo Cline 设置

Copilot CLI 用户：参阅 Copilot CLI 设置指南

Gemini CLI 用户：参阅 Gemini CLI 设置指南

Kiro 用户：参阅 Kiro 设置指南

步骤 1：在 VS Code 中打开 MCP 配置

打开 GitHub Copilot 聊天 (Ctrl+Alt+I / Cmd+Alt+I)
点击设置图标 → MCP 服务器 → MCP 配置 (JSON)

步骤 2：将此配置添加到 mcp.json：

{
  "servers": {
    "codebase": {
      "command": "npx",
      "args": ["-y", "@ngotaico/mcp-codebase-index"],
      "env": {
        "REPO_PATH": "/绝对路径/到/你的项目",
        "GEMINI_API_KEY": "AIzaSyC...",
        "QDRANT_URL": "https://你的集群.gcp.cloud.qdrant.io:6333",
        "QDRANT_API_KEY": "eyJhbGci..."
      },
      "type": "stdio"
    }
  }
}

步骤 3：重启 VS Code

服务器将自动：

连接到 Qdrant Cloud
索引您的代码库
监控文件更改

📖 详细说明：

📖 使用方法

搜索您的代码库

询问 GitHub Copilot：

"查找身份验证逻辑"
"展示数据库连接是如何处理的"
"错误日志在哪里实现？"

可视化您的代码库

询问 GitHub Copilot：

"可视化我的代码库"
"展示我的代码是如何组织的"
"可视化身份验证代码"

📖 完整指南： 向量可视化指南

查看索引状态

"查看索引状态"
"显示详细的索引进度"

📖 更多示例： 测试指南

📊 向量可视化

在2D/3D空间中查看您的代码库 - 通过视觉方式了解语义关系和代码组织。

什么是向量可视化？

向量可视化将您代码库的 768维嵌入 转换为使用UMAP降维的交互式 2D或3D可视化。这允许您：

🎨 探索语义关系 - 类似的代码聚在一起
🔍 理解架构 - 一眼看到代码库结构
🎯 调试搜索结果 - 视觉化为什么某些代码被检索
📈 跟踪代码组织 - 识别模块、模式和异常值

快速开始

可视化整个代码库：

用户："可视化我的代码库"

结果：交互式聚类显示：
- API 控制器及路由 (28%)
- 数据库模型 (23%)
- 身份验证 (19%)
- 业务逻辑 (18%)
- 测试套件 (12%)

导出为HTML：

用户："导出可视化为HTML"

结果：独立的HTML文件包含：
- 交互式悬停、缩放、平移
- 点击聚类以高亮显示
- 现代渐变UI
- 离线可用

理解可视化

颜色和聚类：

每种颜色代表一个语义聚类（模块/功能）
靠近的点表示相似的意义
距离反映语义相似度
异常值表示独特/专业化的代码

常见的聚类模式：

蓝色：前端/UI组件
橙色：API端点和路由
绿色：数据库模型和查询
红色：身份验证和安全
紫色：测试和验证
灰色：实用工具和辅助程序

使用案例

🏗️ 架构理解
- 可视化以查看模块边界
- 识别紧密耦合的代码
- 发现重构机会
🔍 代码发现
- 通过视觉方式定位相关功能
- 查找所有涉及某个特性的代码
- 发现跨切面关注点
🐛 搜索调试
- 了解为什么检索了这些结果
- 查看语义关系
- 根据可视化优化查询
👥 团队入职
- 导出HTML供新开发者使用
- 代码库结构的视觉指南
- 交互式探索工具
✅ 重构验证
- 重构前后可视化
- 验证改进的代码组织
- 跟踪架构演变

性能

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

技巧：

使用2D以加快处理速度（比3D快40%）
对于大型代码库限制最大向量数
导出HTML以便离线探索

📖 学习更多

包括详细文档：

完整工具参考
解释指南
技术细节（UMAP，聚类）
故障排除
最佳实践
高级用例

参见： 向量可视化指南

🎯 提示增强（可选）

简而言之： 提示增强是一种透明的后台工具，自动提高搜索质量。只需自然地提问——无需在提示中提到“增强”。

快速概述

启用后 (PROMPT_ENHANCEMENT=true)，AI 自动：

增强您的搜索查询，加入代码库上下文
搜索使用改进后的查询
继续进行您的原始请求（实现、修复、解释等）

好的提示 ✅

✅ "查找身份验证逻辑并添加双因素认证支持"
✅ "定位支付流程并解决超时问题"
✅ "搜索个人资料功能并添加生物信息字段"

为什么这些有效： 明确的目标（查找 + 行动）→ 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个块/秒

📖 性能详情： 主要文档

🐛 故障排除

服务器未出现？

检查 Copilot 聊天 → 设置 → 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/                    # 所有文档
│   ├── 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 问题
讨论： GitHub 讨论
邮件： ngotaico.flutter@gmail.com

**⭐ 如果您觉得