代码索引MCP
项目介绍
Code-Index-MCP (本地优先代码索引器)
模块化、可扩展的本地优先代码索引器，旨在增强Claude Code和其他LLMs的深度代码理解能力。基于Model Context Protocol (MCP)构建，实现与AI助手的无缝集成。
实现状态
当前完成度：100%（生产就绪，已完成全面验证）
系统复杂度：5/5（高 - 136k行代码，语义搜索，分布式架构）
生产就绪：是 - 所有系统已验证，查询性能低于100毫秒，文档齐全
🎯 关键特性
- 🚀 本地优先架构：所有索引都在本地进行以提高速度和隐私
- 📂 本地索引存储：所有索引存储在
.indexes/（相对于MCP服务器） - 🔌 插件式设计：通过语言特定插件轻松扩展
- 🔍 支持48种语言：完全集成Tree-sitter并支持语义搜索
- ⚡ 实时更新：文件系统监控实现即时索引更新
- 🧠 语义搜索：使用Voyage AI嵌入的AI驱动代码搜索
- 📊 丰富的代码智能：符号解析、类型推断、依赖跟踪
- 🚀 增强性能：低于100毫秒的查询，带有超时保护和BM25绕过
- 🔄 Git同步：自动索引更新以跟踪仓库更改
- 📦 可移植索引管理：通过GitHub Artifacts零成本共享索引
- 🔄 自动索引同步：克隆时拉取索引，在更改时推送
- 🎯 智能结果重新排序：多策略重新排序以提高相关性
- 🔒 安全意识导出：自动过滤敏感文件从共享索引中
- 🔍 混合搜索：BM25 + 语义搜索，具有可配置融合
- 🔐 本地一切索引：搜索你的机器上的.env文件和密钥
- 🚫 智能过滤分享：仅在导出期间应用.gitignore和.mcp-index-ignore模式
- 🌐 多语言索引：索引整个混合语言的仓库
🏗️ 架构
Code-Index-MCP遵循模块化、插件式架构，旨在实现可扩展性和性能：
系统层级
-
🌐 系统上下文（第1层）
- 开发者与Claude Code或其他LLMs交互
- MCP协议提供标准化工具接口
- 本地优先处理，可选云功能
- 性能SLA：符号查找<100毫秒，搜索<500毫秒
-
📦 容器架构（第2层）
┌─────────────────┐ ┌──────────────┐ ┌─────────────┐ │ API网关 │────▶│ 调度器 │────▶│ 插件 │ │ (FastAPI) │ │ │ │ (语言) │ └─────────────────┘ └──────────────┘ └─────────────┘ │ │ │ ▼ ▼ ▼ ┌─────────────────┐ ┌──────────────┐ ┌─────────────┐ │ 本地索引 │ │ 文件监视器 │ │ 嵌入服务 │ │ (SQLite+FTS5) │ │ (Watchdog) │ │ │ └─────────────────┘ └──────────────┘ └─────────────┘ -
🔧 组件细节（第3层）
- 网关控制器：RESTful API端点
- 调度核心：插件路由和生命周期
- 插件基础：所有插件的标准接口
- 语言插件：专用解析器和分析器
- 索引管理器：使用SQLite和FTS5进行快速搜索
- 监视服务：实时文件监控
📁 项目结构
项目遵循清晰、组织良好的结构。参见docs/PROJECT_STRUCTURE.md以获取详细布局。
关键目录：
mcp_server/- 核心MCP服务器实现scripts/- 开发和实用脚本tests/- 包含测试用例的综合测试套件docs/- 文档和指南architecture/- 系统设计和图表docker/- Docker配置和组合文件data/- 数据库文件和索引logs/- 应用程序和测试日志reports/- 生成的性能报告和分析analysis_archive/- 历史分析和存档研究
🛠️ 语言支持
✅ 完整支持的语言（总计46+）
生产就绪功能：
- 动态插件加载：按需加载语言以优化性能
- Tree-sitter解析：准确的AST符号提取，具有语言特定查询
- 查询缓存：通过缓存的Tree-sitter查询提升性能
- 语义搜索：可选的AI驱动代码搜索（当Qdrant可用时）
- 跨语言搜索：在所有支持的语言中查找符号和模式
语言类别：
| 类别 | 语言 | 功能 |
|---|---|---|
| 专用插件 | Python, JavaScript, TypeScript, C, C++, Dart, HTML/CSS | 增强分析，框架支持 |
| 系统语言 | Go, Rust, C, C++, Zig, Nim, D, V | 内存安全，性能分析 |
| JVM语言 | Java, Kotlin, Scala, Clojure | 包分析，构建工具集成 |
| Web技术 | JavaScript, TypeScript, HTML, CSS, SCSS, PHP | 框架检测，捆绑器支持 |
| 脚本语言 | Python, Ruby, Perl, Lua, R, Julia | 动态类型，REPL集成 |
| 函数式语言 | Haskell, Elixir, Erlang, F#, OCaml | 模式匹配，类型推断 |
| 移动开发 | Swift, Kotlin, Dart, Objective-C | 平台特定API |
| 基础设施 | Dockerfile, Bash, PowerShell, Makefile, CMake | 构建自动化，CI/CD |
| 数据格式 | JSON, YAML, TOML, XML, GraphQL, SQL | 模式验证，查询优化 |
| 文档 | Markdown, LaTeX, reStructuredText | 交叉引用，格式化 |
实现状态：生产就绪 - 所有语言通过增强调度器支持：
- ✅ 动态插件加载（延迟初始化）
- ✅ 健壮的错误处理和回退机制
- ✅ 复杂项目结构的路径解析
- ✅ 当外部服务不可用时优雅降级
🚀 快速开始
🎯 自动设置Claude Code/桌面（推荐）
# 自动配置MCP环境
./scripts/setup-mcp-json.sh
# 或交互模式
./scripts/setup-mcp-json.sh --interactive
这会自动检测您的环境并创建适当的.mcp.json配置。
🐳 Docker环境设置
选项1：基本搜索（无API密钥）- 2分钟
# 使用Docker安装MCP索引
curl -sSL https://raw.githubusercontent.com/Code-Index-MCP/main/scripts/install-mcp-docker.sh | bash
# 索引当前目录
docker run -it -v $(pwd):/workspace ghcr.io/code-index-mcp/mcp-index:minimal
选项2：AI驱动搜索
# 设置您的API密钥（在https://voyageai.com 获取）
export VOYAGE_AI_API_KEY=your-key
# 运行带语义搜索
docker run -it -v $(pwd):/workspace -e VOYAGE_AI_API_KEY ghcr.io/code-index-mcp/mcp-index:standard
💻 环境特定设置
🪟 Windows（原生）
# PowerShell
.\scripts\setup-mcp-json.ps1
# 或手动使用Docker Desktop
docker run -it -v ${PWD}:/workspace ghcr.io/code-index-mcp/mcp-index:minimal
🍎 macOS
# 安装Docker Desktop或使用Homebrew
brew install --cask docker
# 运行设置
./scripts/setup-mcp-json.sh
🐧 Linux
# 安装Docker（无需Desktop）
curl -fsSL https://get.docker.com | sh
# 运行设置
./scripts/setup-mcp-json.sh
🔄 WSL2（Windows子系统Linux）
# 配合Docker Desktop集成
./scripts/setup-mcp-json.sh # 自动检测WSL+Docker
# 不使用Docker Desktop
cp .mcp.json.templates/native.json .mcp.json
pip install -e .
📦 嵌套容器（开发容器）
# 对于VS Code/Cursor开发容器
# 选项1：使用容器内的原生Python
cp .mcp.json.templates/native.json .mcp.json
# 选项2：使用Docker侧车（避免依赖冲突）
docker-compose -f docker/compose/development/docker-compose.mcp-sidecar.yml up -d
cp .mcp.json.templates/docker-sidecar.json .mcp.json
📋 MCP.json配置示例
设置脚本会为您创建适当的.mcp.json。手动示例如下：
原生Python（开发容器/本地）
{
"mcpServers": {
"code-index-native": {
"command": "python",
"args": ["scripts/cli/mcp_server_cli.py"],
"cwd": "${workspace}"
}
}
}
Docker（Windows/Mac/Linux）
{
"mcpServers": {
"code-index-docker": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-v", "${workspace}:/workspace",
"ghcr.io/code-index-mcp/mcp-index:minimal"
]
}
}
}
💰 成本及功能
| 功能 | 最小 | 标准 | 全部 | 成本 |
|---|---|---|---|---|
| 代码搜索 | ✅ | ✅ | ✅ | 免费 |
| 48种语言 | ✅ | ✅ | ✅ | 免费 |
| 语义搜索 | ❌ | ✅ | ✅ | ~$0.05/1M令牌 |
| GitHub同步 | ❌ | ✅ | ✅ | 免费 |
| 监控 | ❌ | ❌ | ✅ | 免费 |
🚀 快速开始（Python）
先决条件
- Python 3.8+
- Git
- Docker（可选，用于架构图）
安装
选项1：使用预构建索引快速启动
下载我们的发布中的预构建索引来立即开始：
# 下载最新发布
python scripts/download-release.py --latest
# 或下载特定版本
python scripts/download-release.py --tag v2024.01.15
选项2：从源码构建
-
克隆仓库
git clone https://github.com/yourusername/Code-Index-MCP.git cd Code-Index-MCP -
安装依赖项
# 创建虚拟环境 python -m venv venv source venv/bin/activate # 在Windows上：venv\Scripts\activate # 安装需求 pip install -r requirements.txt -
构建索引（或下载预构建）
# 为当前目录构建索引，支持完整（SQL + 语义） python scripts/index_repositories.py --mode full # 或使用特定模式： # SQL-only（快速，不需要API密钥）： python scripts/index_repositories.py --mode sql # 语义-only（需要VOYAGE_AI_API_KEY）： python scripts/index_repositories.py --mode semantic # 或从GitHub工件下载（如果可用） python scripts/index-artifact-download-v2.py --latest -
启动服务器
# 启动MCP服务器 uvicorn mcp_server.gateway:app --reload --host 0.0.0.0 --port -
测试API
# 检查服务器状态 curl http://localhost:8000/status # 搜索代码 curl -X POST http://localhost:8000/search \ -H "Content-Type: application/json" \ -d '{"query": "def parse"}'
🔧 配置
创建一个.env文件进行配置：
# 可选：Voyage AI用于语义搜索
VOYAGE_AI_API_KEY=your_api_key_here
# 服务器设置
MCP_SERVER_HOST=0.0.0.0
MCP_SERVER_PORT=8000
MCP_LOG_LEVEL=INFO
# 工作区设置
MCP_WORKSPACE_ROOT=.
MCP_MAX_FILE_SIZE=10485760 # 10MB
# GitHub工件同步（隐私设置）
MCP_ARTIFACT_SYNC=false # 设置为true启用
AUTO_UPLOAD=false # 手动上传
AUTO_DOWNLOAD=true # 克隆时自动下载
🔐 隐私及GitHub工件同步
控制您的代码索引如何共享：
// .mcp-index.json
{
"github_artifacts": {
"enabled": false, // 完全禁用同步
"auto_upload": false, // 手动上传
"auto_download": true, // 仍然获取团队索引
"exclude_patterns": [ // 额外排除模式
"internal/*",
"proprietary/*"
]
}
}
隐私功能：
- 自动根据.gitignore过滤索引
- 通过.mcp-index-ignore添加额外模式
- 审计日志显示被排除的内容
- 默认在Docker最小版本中禁用工件同步
🆕 高级功能
搜索结果重新排序
系统包括多种重新排序策略以提高搜索相关性：
# 在搜索中配置重新排序
from mcp_server.indexer.reranker import RerankConfig, TFIDFReranker
config = RerankConfig(
enabled=True,
reranker=TFIDFReranker(), # 或CohereReranker(), CrossEncoderReranker()
top_k=20
)
# 使用重新排序搜索
results = await search_engine.search(query, rerank_config=config)
可用的重新排序器：
- TF-IDF：使用词频的快速本地重新排序
- Cohere：基于云的神经重新排序（需要API密钥）
- Cross-Encoder：基于本地变压器的重新排序
- 混合：结合多个重新排序器并具有回退
安全意识索引共享
防止意外共享敏感文件：
# 分析当前索引的安全问题
python scripts/utilities/analyze_gitignore_security.py
# 创建安全索引导出（过滤.gitignored文件）
python scripts/utilities/secure_index_export.py
# 安全导出将：
# - 排除所有.gitignored文件
# - 移除敏感模式（*.env, *.key等）
# - 创建被排除文件的审计日志
BM25混合搜索
结合传统的全文搜索和语义搜索：
# 系统在可用时自动使用混合搜索
# 在设置中配置权重：
HYBRID_SEARCH_BM25_WEIGHT=0.3
HYBRID_SEARCH_SEMANTIC_WEIGHT=0.5
HYBRID_SEARCH_FUZZY_WEIGHT=0.2
🔧 调度器配置
增强调度器（默认）
增强调度器包括超时保护和自动回退：
from mcp_server.dispatcher.dispatcher_enhanced import EnhancedDispatcher
from mcp_server.storage.sqlite_store import SQLiteStore
store = SQLiteStore(".indexes/YOUR_REPO_ID/current.db")
dispatcher = EnhancedDispatcher(
sqlite_store=store,
semantic_search_enabled=True, # 如果Qdrant可用则启用
lazy_load=True, # 按需加载插件
use_plugin_factory=True # 使用动态插件加载
)
# 使用自动优化搜索
results = list(dispatcher.search("your query", limit=10))
简单调度器（轻量级替代方案）
对于仅使用BM25搜索的最大性能：
from mcp_server.dispatcher.simple_dispatcher import create_simple_dispatcher
# 超快BM25搜索，无插件开销
dispatcher = create_simple_dispatcher(".indexes/YOUR_REPO_ID/current.db")
results = list(dispatcher.search("your query", limit=10))
配置选项
通过环境变量配置调度器行为：
# 调度器设置
MCP_DISPATCHER_TIMEOUT=5 # 插件加载超时（秒）
MCP_USE_SIMPLE_DISPATCHER=false # 使用简单调度器
MCP_PLUGIN_LAZY_LOAD=true # 按需加载插件
# 性能调整
MCP_BM25_BYPASS_ENABLED=true # 启用直接BM25绕过
MCP_MAX_PLUGIN_MEMORY=1024 # 插件最大内存（MB）