内容
# 代码索引-MCP
**为您的AI编码助手提供即时、精准的搜索功能，跨越整个代码库 — 让它在毫秒级找到所需代码，而不是浪费时间和令牌阅读整个文件。**
代码索引-MCP是一个快速的**本地优先**搜索索引，适用于您的代码。它与Claude Code和其他AI助手（通过模型上下文协议，即“MCP”）连接，让它们几乎可以立即查找您的代码库中的任何符号或搜索任何文本 — 而无需将您的代码离开您的机器。
> **新用户？** 从 [入门指南](docs/GETTING_STARTED.md) 开始。
>
> **状态：** v1.3.1 稳定表面准备 — MCP 工具（`search_code`、`symbol_lookup`）是主要接口；FastAPI 管理网关可用于诊断。
> **稳定表面准备状态：** 本指南针对仓库拥有的 `1.3.1` 版本准备，MCP STDIO 仍然是主要LLM表面，FastAPI仍然是次要的管理表面。 2026年7月10日的碰撞检查发现没有活跃的 `index-it-mcp==1.3.1`，因此本指南使用源代码和本地轮廓证明，而不是声称准备好的 `1.3.1` 表面已发布。
## 项目状态
**版本**: 1.3.1（仓库拥有的准备表面；截至 2026 年 7 月 10 日未发布）
**Python 发行版**: `index-it-mcp`
**容器镜像**: `ghcr.io/viperjuice/code-index-mcp`
**主要表面**: MCP 工具（`search_code`、`symbol_lookup`）通过 STDIO 运行器，当仓库准备就绪时为 `ready`
**次要表面**: FastAPI 管理 REST 网关，用于诊断和脚本 — 请参见下面的“管理 REST 接口（次要）”。
**核心功能**: 本地索引、符号/文本搜索、基于注册表的语言覆盖；请参见 [docs/SUPPORT_MATRIX.md](docs/SUPPORT_MATRIX.md)
**可选功能**: 语义搜索（需要 Voyage AI 或本地 vLLM 端点）、GitHub Artifacts 索引同步
**性能**: 索引仓库的符号查找时间低于 100 毫秒，搜索时间低于 500 毫秒（以此代码库为基准；结果因仓库大小和语言混合而异）
**GA 决策**: 请参见 [docs/validation/ga-final-decision.md](docs/validation/ga-final-decision.md)；当前的产品决策是 `ship GA`，而安装表面声明仍受 [docs/status/public-package-identity.md](docs/status/public-package-identity.md) 的限制。
**GA 准备合同**: 请参见 [docs/validation/ga-readiness-checklist.md](docs/validation/ga-readiness-checklist.md)，了解冻结的发布边界、支持层标签、证据所有权和回滚预期，这些在发布前适用。
## 为什么存在
当AI助手在大型代码库中工作时，它通常会读取大量的文件内容，只是为了找到它需要的东西。这很慢，而且它读取的每个文件都会消耗令牌（金钱）。代码索引-MCP建立了一个本地索引，以便助手可以直接跳转到正确的函数、类或行 — **降低令牌成本，使答案更快、更准确**。
## 适用人群
使用AI编码助手在真实的大型代码库中开发的开发者和团队，他们希望获得 **更快、更便宜、更准确** 的结果 — 并希望他们的代码保持 **私有，位于自己的机器上**。
## 您将获得
- **⚡️ 即时查找** — 索引仓库中的符号查找时间低于 100 毫秒，搜索时间低于 500 毫秒。
- **🔒 本地优先和私有** — 索引在您的机器上运行；您的代码不会被发送到云端。
- **💸 更低的令牌成本** — 助手 *搜索* 而不是读取整个文件（请参见下面的图表）。
- **🧠 语义搜索（可选）** — 通过嵌入的自然语言代码搜索。
- **🌐 多种语言、多个仓库** — 一个服务器可以索引多个具有混合语言的仓库。
- **🔌 基于插件和可扩展** — 无需修改核心即可添加语言支持。
## 看看它的实际效果
此仓库中的基准测试显示，当助手使用代码索引-MCP搜索而不是直接读取文件时，令牌和成本会大幅减少：
*（图表由 `reports/` 中的基准测试生成；数字因仓库大小和语言混合而异。）*
## 🎯 主要功能
- **🚀 本地优先架构**：所有索引都在本地进行，以提高速度和隐私。
- **📂 本地索引存储**：所有索引存储在 `.indexes/`（相对于 MCP 服务器）。
- **🔌 基于插件的设计**：可轻松扩展，支持语言特定的插件。
- **🔍 语言支持**：分层语言/运行时支持记录在 [docs/SUPPORT_MATRIX.md](docs/SUPPORT_MATRIX.md) 中。
- **⚡️ 实时更新**：文件系统监视，实现索引的即时更新。
- **🧠 语义搜索**：使用 Voyage AI 嵌入的 AI 代码搜索。
- **📊 丰富的代码智能**：符号解析、类型推断、依赖跟踪。
- **🚀 增强性能**：100 毫秒以下的查询，超时保护和 BM25 绕过。
- **🔄 Git 同步**：自动索引更新，跟踪仓库更改。
- **📦 便携式索引管理**：通过 GitHub Artifacts 实现零成本索引共享。
- **🔄 自动索引同步**：克隆时拉取索引，变更时推送。
- **🎯 智能结果重新排序**：多策略重新排序，提高相关性。
- **🎯 查询意图路由**：符号模式查询（`class Foo`、`def bar`、CamelCase）绕过 BM25，直接命中符号表，实现 5 毫秒以下的查找。
- **🔒 安全感知导出**：从共享索引中自动过滤敏感文件。
- **🔍 混合搜索**：BM25 + 语义搜索，具有可配置的融合。
- **🔐 索引所有内容本地**：在您的机器上搜索 `.env` 文件和机密。
- **🚫 共享时智能过滤**：`.gitignore` 和 `.mcp-index-ignore` 模式仅在导出期间应用。
- **🌐 多语言索引**：索引具有混合语言的整个仓库。
## 🏗️ 架构
代码索引-MCP 遵循模块化、基于插件的架构，旨在可扩展和高效：
### 系统层
1. **🌐 系统上下文（第 1 级）**
- 开发人员与 Claude Code 或其他 LLM 交互
- MCP 协议提供标准化的工具接口
- 本地优先处理，可选云功能
- 性能 SLA：<100ms 符号查找，<500ms 搜索
2. **📦 容器架构（第 2 级）**
```
┌─────────────────┐ ┌──────────────┐ ┌─────────────┐
│ API 网关 │────▶│ 分发器 │────▶│ 插件 │
│ （FastAPI） │ │ │ │ （语言） │
└─────────────────┘ └──────────────┘ └─────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌──────────────┐ ┌─────────────┐
│ 本地索引 │ │ 文件监视器 │ │ 嵌入服务 │
│ （SQLite+FTS5） │ │ （Watchdog） │ │ │
└─────────────────┘ └──────────────┘ └─────────────┘
```
3. **🔧 组件详情（第 3 级）**
- **网关控制器**：RESTful API 端点
- **分发器核心**：插件路由和生命周期
- **插件基础**：所有插件的标准接口
- **语言插件**：专门的解析器和分析器
- **索引管理器**：用于快速搜索的 SQLite 和 FTS5
- **监视器服务**：实时文件监视
## 🔐 安全
代码索引-MCP 实施了纵深防御安全强化（第 15 阶段）：
- **插件沙箱**：插件在具有基于能力的限制的隔离工作进程中执行。参见 [docs/security/sandbox.md](docs/security/sandbox.md)。
- **工件证明**：已发布的索引使用 GitHub SLSA 证明并在下载时验证。参见 [docs/security/attestation.md](docs/security/attestation.md)。
- **路径遍历保护**：搜索结果已验证，以防止超出配置的仓库根目录。参见 [docs/security/path-guard.md](docs/security/path-guard.md)。
- **令牌验证**：在启动时，GitHub 令牌会验证所需的范围（`contents:read`、`metadata:read`、`actions:read`、`actions:write`、`attestations:write`）。参见 [docs/security/token-scopes.md](docs/security/token-scopes.md)。
- **指标身份验证**：`/metrics` 端点需要 bearer 令牌身份验证。
`MCP_CLIENT_SECRET` 仅是本地 STDIO 握手保护。它不是网关的管理/调试 bearer 令牌身份验证，并且在存储库继续延迟远程 MCP 传输时，不会实施远程 MCP 授权。
有关综合运营商手册，请参见 [docs/operations/user-action-runbook.md](docs/operations/user-action-runbook.md)。
## 📁 项目结构
该项目遵循干净、有序的结构。有关详细布局，请参见 [docs/PROJECT_STRUCTURE.md](docs/PROJECT_STRUCTURE.md)。
关键目录：
- `mcp_server/` - 核心 MCP 服务器实现
- `scripts/` - 开发和实用脚本
- `tests/` - 全面的测试套件，包含夹具
- `docs/` - 文档和指南
- `architecture/` - 系统设计和图表
- `docker/` - Docker 配置文件和 compose 文件
- `mcp-index-kit/` - 共享的 MCP 索引工具包和示例
- `docs/status/` - 保存在版本控制下的持久证据笔记
## 🛠️ 语言支持
当前的稳定表面支持合同集中在 [docs/SUPPORT_MATRIX.md](docs/SUPPORT_MATRIX.md)。
它区分了专门的插件、通用 Tree-sitter 注册表覆盖、默认沙箱支持、可选的额外功能、语义/重新排序设置以及已知的 alpha 限制。不要假设每个注册表语言都具有相同的符号质量或默认沙箱行为。
## 🚀 快速入门
发布前支持的安装路径是使用 `uv sync --locked` 的原生 Python/STDIO，使用本地构建的 `index-it-mcp` 轮，以及使用本地构建的 `ghcr.io/viperjuice/code-index-mcp:local-smoke` 镜像。准备好的 `v1.3.1` 容器命令仅在保护主发布后生效。
语言覆盖范围受 [docs/SUPPORT_MATRIX.md](docs/SUPPORT_MATRIX.md) 限制，
GA强化证据所有权冻结在 [docs/validation/ga-readiness-checklist.md](docs/validation/ga-readiness-checklist.md)，
回滚程序位于 [docs/operations/deployment-runbook.md](docs/operations/deployment-runbook.md)。
不要将此准备好的稳定表面视为通用语言支持声明；行级支持层仍然存在于支持矩阵中。
### 🎯 Claude Code/Desktop 自动设置（推荐）
```bash
# 自动为您的环境配置 MCP
./scripts/setup-mcp-json.sh
# 或交互模式
./scripts/setup-mcp-json.sh --interactive
```
这会自动检测您的环境并创建适当的 `.mcp.json` 配置文件。
### 🐳 Docker 设置（发布前）
从此检出构建本地烟雾镜像。`v1.3.1` GHCR 候选版本已准备但未发布，因此安装程序也默认为 `local-smoke`。
#### 选项 1：基本搜索（无 API 密钥）- 2 分钟
```bash
# 构建并验证本地镜像
make release-smoke-container
# 索引当前目录
docker run -it -v $(pwd):/workspace ghcr.io/viperjuice/code-index-mcp:local-smoke
```
#### 选项 2：AI 增强搜索
```bash
# 设置您的 API 密钥（在 https://www.voyageai.com 获取 - 免费层可用）
export VOYAGE_API_KEY=your-key
# 运行语义搜索启用
docker run -it -v $(pwd):/workspace -e SEMANTIC_SEARCH_ENABLED=true -e VOYAGE_API_KEY ghcr.io/viperjuice/code-index-mcp:local-smoke
```
### 💻 环境特定设置
#### 🪟 Windows（原生）
```powershell
# PowerShell
.\scripts\setup-mcp-json.ps1
# 或使用 Docker Desktop 手动操作
docker run -it -v ${PWD}:/workspace ghcr.io/viperjuice/code-index-mcp:local-smoke
```
#### 🍎 macOS
```bash
# 安装 Docker Desktop 或使用 Homebrew
brew install --cask docker
# 运行设置
./scripts/setup-mcp-json.sh
```
#### 🐧 Linux
```bash
# 安装 Docker（不需要 Desktop）
curl -fsSL https://get.docker.com | sh
# 运行设置
./scripts/setup-mcp-json.sh
```
#### 🔄 WSL2（Windows 子系统 Linux）
```bash
# 集成 Docker Desktop
./scripts/setup-mcp-json.sh # 自动检测 WSL+Docker
# 无 Docker Desktop
cp .mcp.json.templates/native.json .mcp.json
uv sync --locked
```
#### 📦 嵌套容器（开发容器）
```bash
# 对于 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
```
### Windows 路径长度回退
跟踪的仓库路径保持在 160 个字符的跟踪路径限制以下，并且 REPOCLEAN 审计还检查安装的 `site-packages` 成员的轮廓内容路径深度。如果 Windows 签出仍然因为深度嵌套的克隆位置或第三方工具而遇到路径长度边缘，请使用 `git config --global core.longpaths true` 作为回退，而不是作为主要缓解措施。
### 📋 MCP.json 配置文件示例
设置脚本为您的环境创建适当的 `.mcp.json` 文件。手动示例：
#### 原生 Python（开发容器/本地）
```json
{
"mcpServers": {
"code-index-native": {
"command": "python",
"args": ["-m", "mcp_server.cli.stdio_runner"],
"cwd": "${workspace}"
}
}
}
```
#### Docker（Windows/Mac/Linux）
```json
{
"mcpServers": {
"code-index-docker": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-v", "${workspace}:/workspace",
"ghcr.io/viperjuice/code-index-mcp:local-smoke"
]
}
}
}
```
### 发布烟雾测试
```bash
make release-smoke
make release-smoke-container
```
## 对多个仓库进行索引
从单个运行的服务器实例索引多个无关的仓库。
**前提条件**：在启动服务器之前，将 `MCP_ALLOWED_ROOTS` 设置为以操作系统路径分隔符分隔的绝对目录路径列表（Unix 上为 `:`，Windows 上为 `;`）：
```bash
export MCP_ALLOWED_ROOTS=/abs/a:/abs/b
```
**启动服务器**（使用 `op run` 或纯 `mcp-index stdio` 进行密钥管理）：
```bash
op run --env-file=.mcp.env -- mcp-index stdio
```
**注册每个仓库** — 每个 Git 公共目录注册一个工作树。稳定的 `repo_id` 来自一级 `git rev-parse --git-common-dir`，因此同一仓库的兄弟工作树共享身份，不会被独立索引：
```bash
mcp-index repository register /abs/a
mcp-index repository register /abs/b
```
**每个仓库的查询范围** — 在 `search_code` / `symbol_lookup` 中传递 `repository=<name>`（已注册的名称或路径）：
```
search_code(query="def parse", repository="my-repo")
symbol_lookup(symbol="Parser", repository="my-repo")
```
**Python 客户端（测试版本地 API）**：对于与已注册仓库在同一台机器上的本地脚本和应用程序，请使用 `mcp_server.client` 代替启动 STDIO 或调用 FastAPI。MCP 工具仍然是首选的 LLM 接口：
```python
from mcp_server.client import open_client
from mcp_server.client_types import ClientSearchOptions
with open_client(workspace_root="/path/to/repo") as client:
result = client.search_code(
ClientSearchOptions(
query="TODO",
source_type="friction",
friction_categories=("todo",),
include_source_metadata=True,
)
)
if result.index_unavailable:
print(result.index_unavailable.safe_fallback)
else:
print(result.results[0].file)
```
支持的 Python 客户端接口仅限本地使用：`search_code`、`symbol_lookup`、`reindex` 和 `get_status` 与 MCP `search_code` 工具共享相同的具有就绪感知功能的服务。它是一个本地程序化 API，而不是远程服务客户端。
摩擦模式元数据作为 `search_code` 的附加过滤器提供。使用 `source_type="friction"` 和可选的 `friction_categories=["todo", "fixme", "hack", "workaround", "wish", "extraction_hint"]`。设置 `include_source_metadata=true` 以将存储的 `search_source_metadata.v1` 信封附加到返回的结果中。普通的无过滤词法调用保留旧的结果形状；无效的摩擦类别返回元数据验证错误而不是静默空结果。
历史 GitHub 问题上下文使用相同的元数据信封和搜索接口。运行 `mcp-index history ingest --repo owner/repo` 以摄取元数据问题文档，然后使用 `source_type="history"` 和可选的 `history_labels=["reflection"]` 或 `history_repos=["owner/repo"]` 进行过滤。HISTORY 合同在测试中由固定装置支持，无需实时 GitHub 凭证，默认情况下不会持久化原始问题正文。
**索引跟踪**：每个仓库的跟踪/默认分支由 `MultiRepositoryWatcher`（`RefPoller` 每 30 秒）跟踪。同一仓库的多个工作树和非默认分支查询在 v3 路由中不受支持：它们返回 `index_unavailable`，并带有 `safe_fallback: "native_search"` 和就绪补救措施，而不是重用另一个检出的索引。检查 `get_status` 或 `mcp-index repository list -v`，并在就绪状态为 `ready` 时信任索引的 MCP 结果。
**路径沙盒**：工具 `search_code`、`symbol_lookup`、`summarize_sample` 和 `reindex` 拒绝 `MCP_ALLOWED_ROOTS` 之外的路径，错误代码为 `path_outside_allowed_roots`。已注册的仓库名称绕过检查。
**选项：**
- 在服务器环境中设置 `MCP_AUTO_INDEX=false` 以跳过后台自动索引，并手动调用 `reindex` MCP 工具（建议用于非常大的仓库）。
- 在目标仓库的 `.mcp-index.json` 中添加 `{"enabled": false}` 以完全禁用该仓库的索引。
- 在完整重新索引或代码更改后，调用 `reindex` MCP 工具按需重建索引。
**语义配置文件：** BM25 搜索无需额外配置。对于语义（向量）搜索，服务器会自动从其自己的安装目录加载 `code-index-mcp.profiles.yaml` — 无需复制到每个仓库。要覆盖自定义配置文件，请在服务器环境中设置 `MCP_PROFILES_PATH=/abs/path/to/your-profiles.yaml`。要覆盖个别端点 URL，无需编辑 YAML，请使用文件中的环境变量（例如 `VLLM_EMBEDDING_BASE_URL`、`VLLM_SUMMARIZATION_BASE_URL`）。
### ⚡️ 启用语义搜索
BM25 关键字搜索无需配置即可使用。要添加向量（语义）搜索，请选择以下路径之一：
**选项 A — 航海 AI（推荐）：**
```bash
export VOYAGE_API_KEY=your-key # 在 voyageai.com 上提供免费层
```
会自动激活 `commercial_high` 配置文件。重启 MCP 服务器 — 启动日志将确认语义搜索已激活。
**选项 B — 本地开源（Qwen3-Embedding-8B，无需 API 密钥）：**
```bash
export VLLM_EMBEDDING_BASE_URL=http://localhost:8000/v1
# 启动 vLLM（需要约 20GB VRAM 或共享 CPU 且 --dtype float32）：
docker run -p 8000:8000 vllm/vllm-openai --model Qwen/Qwen3-Embedding-8B
```
配置文件和集合名称均在 `code-index-mcp.profiles.yaml` 中定义，可以自定义。
`code-index-mcp.profiles.yaml` 是一个仓库附带的配置文件名，而不是 pip 安装目标。
### 成本和可选功能
文档中提到的容器包是 `ghcr.io/viperjuice/code-index-mcp`。BM25 代码搜索无需提供商凭证即可使用。语义搜索、重新排序、工件同步和监控依赖于额外项、环境变量和服务配置。请参阅 [docs/SUPPORT_MATRIX.md](docs/SUPPORT_MATRIX.md) 获取语言/运行时支持的详细信息。
## 🚀 快速入门（Python）
### 前提条件
- Python 3.12+
- Git
### 安装
#### 选项 1：使用仓库拥有的源代码安装（推荐）
```bash
# 克隆仓库
git clone https://github.com/ViperJuice/Code-Index-MCP.git
cd Code-Index-MCP
# 安装锁定项目依赖项
uv sync --locked
# 验证规范 CLI 入口点
uv run mcp-index --version
```
#### 选项 2：构建本地轮
```bash
# 从仓库根目录
uv run --extra dev python -m build --wheel
python -m pip install dist/index_it_mcp-1.3.1-py3-none-any.whl
index-it-mcp --version
```
规范的 Python 分发名称仍为 `index-it-mcp`，但当前的 PyPI 没有发布此仓库的准备好的 `1.3.1` 接口。请在稍后发布证据阶段重新验证实时包一致性之前，使用上述本地轮或源代码安装。
### 安装后快速启动
```bash
# 认证 GitHub 工件访问一次
gh auth login
# 在开始工作之前检查仓库/工件就绪状态
mcp-index preflight
# 拉取此仓库的最新发布的索引基准
mcp-index artifact pull --latest
# 仅协调本地漂移以进行恢复
mcp-index artifact sync
# 恢复的文件在本地适用于 MCP 运行时使用：
# - code_index.db
# - .index_metadata.json
# - vector_index.qdrant/
# 检查索引状态
mcp-index index status
# 启动 MCP STDIO 运行器（LLM 通过 .mcp.json 使用的主要接口）
mcp-index stdio
# 或启动 FastAPI 管理 REST 网关（次要，仅用于诊断）；
# 这不是仓库的 MCP 流式 HTTP 传输
mcp-index serve
mcp-index serve --port 9123 # 替代端口
```
从 LLM（Claude Code、Cursor 等）注册 STDIO 运行器在 `.mcp.json` 中，并作为 MCP 工具调用索引器。两个主要工具是 `search_code`（模式/关键字/语义搜索，<500 毫秒）和 `symbol_lookup`（精确类/函数查找，<100 毫秒）。调用 `get_status` 以确认仓库就绪状态为 `ready`，或使用原生搜索处理查询响应，返回 `code: "index_unavailable"` 和 `safe_fallback: "native_search"`，同时遵循返回的补救措施，例如 `reindex`：
```json
{
"tool": "search_code",
"arguments": {
"query": "def parse",
"limit": 20,
"semantic": false
}
}
```
```json
{
"tool": "symbol_lookup",
"arguments": {
"symbol": "parse_file"
}
}
```
这两个工具都接受可选的 `"repository"` 参数（已注册的仓库名称或 `MCP_ALLOWED_ROOTS` 内的绝对路径），用于多仓库范围。请参阅上面的“对多个仓库进行索引”部分。准备好的索引如果没有匹配结果，将返回普通无匹配结果（`search_code` 为 `results: []` 或 `symbol_lookup` 为 `result: "not_found"`），并带有就绪元数据；不可用的索引返回 `index_unavailable` 代替。
STDIO `tools/list` 接口是确定性的，现在为每个公共工具提供丰富的 MCP 元数据：稳定的 `title` 值、显式 JSON 模式输入契约（`required`、默认值和 `additionalProperties` 立场）、只读与变异行为的注释以及实现拥有的 `outputSchema` 草案。STDIO `tools/call` 接口现在返回 SDK 原生 `CallToolResult` 对象，带有对象形状的 `structuredContent`、为旧客户端保留的 JSON 文本回退内容（在 `content` 中），以及在拒绝和错误分支上的 `isError`。像普通词法搜索命中这样的旧阵列样式有效载荷在 `structuredContent.results` 下包装，而就绪失败仍然带有 `index_unavailable` 和 `safe_fallback: "native_search"`，其中已经应用了该契约。
`reindex` 和 `write_summaries` 还通过 SDK 原生 MCP 任务接口支持任务增强执行。两个工具都宣传 `execution.taskSupport = "optional"`，因此客户端可以保留当前同步路径或在 `tools/call` 中包含 `task` 对象，然后使用 `tasks/get`、`tasks/list`、`tasks/result` 和 `tasks/cancel` 进行进度、终端有效载荷检索和尽力取消。在创建任何任务之前，准备就绪的拒绝、路径沙盒失败、冲突范围错误和汇总器不可用的预检查仍然会同步失败。
当前验证的 MCP 客户端状态在 [MCP 兼容性矩阵](docs/status/MCP_COMPATIBILITY_EVALUATION.md) 中总结。阶段拥有的直接烟雾测试是官方 Python SDK 通过 STDIO；Claude Code 和其他 STDIO 启动器针对相同的服务器契约进行文档化，而远程流式 HTTP MCP 仍被推迟。
### 🔧 配置
为配置创建 `.env` 文件：
```env
# 语义配置文件设置 — 设置 VOYAGE_API_KEY（在 voyageai.com 上免费）以启用向量搜索
VOYAGE_API_KEY=your_api_key_here
# 使用 127.0.0.1 进行本地推理，或使用 Tailscale/SSH 隧道 IP 进行远程 GPU
OPENAI_API_BASE=http://127.0.0.1:8001/v1
QDRANT_PATH=vector_index.qdrant
# 服务器设置
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 # 克隆时自动下载
```
发布的工件现在包含完整的词法基准和两个语义配置文件：
- 使用 `voyage-code-3` 的 `commercial_high`
- 使用 `Qwen/Qwen3-Embedding-8B` 的 `oss_high`
这些配置文件存储在工件的单独 Qdrant 集合中，消费者可以拉取一个基准并在本地使用任一配置文件。
**专业提示：开源配置的远程推理**
如果您的本地机器缺乏运行开源配置的 GPU 能力（例如，通过 vLLM 或 Ollama），您可以运行推理的远程机器，并将 MCP 服务器指向它：
- **Tailscale/VPN：** 设置 `OPENAI_API_BASE=http://<tailnet-ip>:8001/v1`
- **SSH 隧道：** 运行 `ssh -L 8001:localhost:8001 user@remote-gpu-machine`，默认配置 `127.0.0.1:8001` 将直接隧道到您的推理服务器。
生成的索引文件不打算存在于 git 历史记录中。仓库跟踪代码、工作流程和配置以构建/发布它们；GitHub 工件分发实际的运行时基准，MCP 在本地恢复。
### 本地工作区管理
```bash
# 检查所有已注册的仓库及其就绪状态
mcp-index repository list -v
# 检查所有已注册的仓库及其本地工件/运行时就绪状态
mcp-index artifact workspace-status
# 在恢复或重建本地索引后刷新就绪状态
mcp-index artifact reconcile-workspace
# 在不要求远程发布的情况下准备每个仓库的本地工件有效载荷
mcp-index artifact publish-workspace
```
MRREADY 冻结了这些命令的面向发布的解释：
- `mcp-index repository list -v`、`mcp-index repository status` 和 `mcp-index artifact workspace-status` 现在为每个仓库显示一个发布状态：`ready`、`local_only`、`publish_failed`、`wrong_branch`、`stale_commit`、`missing_index` 或 `partial_index_failure`。
- 查询工具仍然是一个单独的封闭曲面。如果就绪状态不是 `ready`，MCP 搜索返回 `index_unavailable`，带有 `safe_fallback: "native_search"`，而不是将状态行视为查询成功。
- 当前的多仓库判决仍然是`仅限受控发布`，而多仓库和 STDIO 接口仍处于测试阶段。
### 🔐 隐私和 GitHub 工件同步
控制代码索引的共享方式：
```json
// .mcp-index.json
{
"github_artifacts": {
"enabled": false, // 完全禁用同步
"auto_upload": false, // 仅手动上传
"auto_download": true, // 仍然获取团队索引
"exclude_patterns": [ // 附加排除项
"internal/*",
"proprietary/*"
]
}
}
```
**隐私功能：**
- 索引自动过滤 `.gitignore`
- 通过 `.mcp-index-ignore` 添加模式
- 审计日志显示排除的内容
- 默认情况下，在 Docker 最小版本中禁用同步
## 🆕 高级功能
### 搜索结果重新排序
三种重新排序器可用，通过 `RERANKER_TYPE` 环境变量配置：
| 值 | 重新排序器 | 备注 |
|---|---|---|
| `flashrank` | FlashRank | 开源，本地，快速（~1-5 毫秒开销） |
| `cross-encoder` | Cross-Encoder | 开源，本地，最高质量 |
| `voyage` | Voyage Reranker | 云 API，需要 `VOYAGE_API_KEY` |
| `none` | 禁用 | 默认 |
```bash
export RERANKER_TYPE=flashrank # 或 cross-encoder、voyage、none
```
重新排序仅适用于语义检索路径。BM25/FTS 结果不会被重新排序。
实现：`mcp_server/dispatcher/reranker.py`
### LLM 代码块摘要
语义代码块可以用 LLM 生成的摘要增强检索，提高基于意图的查询。按配置文件在 `code-index-mcp.profiles.yaml` 中配置：
```yaml
summarization:
enabled: true
mode: lazy # lazy（首次查询）| comprehensive（索引时）
provider: openai_compatible
model_name: gpt-4o-mini
base_url: "https://api.openai.com/v1"
api_key_env: OPENAI_API_KEY
prompt_template: "用 2 个简洁的句子描述此代码块的输入、输出和用途。"
```
> ⚠️ **安全**：不要使用云 LLM 总结不受信任的代码。注释中的隐藏指令可以被总结器执行。请参阅 [安全说明](#-security-notes) 部分。
实现：`mcp_server/indexing/summarization.py`
### 安全感知索引共享
防止意外共享敏感文件：
```bash
# 分析当前索引的安全问题
python scripts/utilities/analyze_gitignore_security.py
# 创建安全索引导出（过滤 gitignored 文件）
python scripts/utilities/secure_index_export.py
# 安全导出将：
# - 排除所有 gitignored 文件
# - 删除敏感模式（*.env、*.key 等）
# - 创建排除文件的审计日志
```
### BM25 混合搜索
将传统全文搜索与语义搜索相结合：
```python
# 系统在可用时自动使用混合搜索
# 在设置中配置权重：
HYBRID_SEARCH_BM25_WEIGHT=0.3
HYBRID_SEARCH_SEMANTIC_WEIGHT=0.5
HYBRID_SEARCH_FUZZY_WEIGHT=0.2
```
## 🔧 分发器配置
### 增强型分发器（默认）
增强型分发器包含超时保护和自动故障转移：
```python
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 仅搜索的性能：
```python
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))
```
### 配置选项
通过环境变量配置调度器行为：
```env
# 调度器设置
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）
# 自动索引（跨仓库使用）
MCP_AUTO_INDEX=true # 设置为 false 以跳过首次运行的后台自动索引
MCP_AUTO_INDEX_MAX_FILES=100000 # 如果仓库超过此文件数，则跳过自动索引
MCP_PROFILES_PATH= # 指向自定义配置文件 YAML 的绝对路径（覆盖内置）
```
# 端点覆盖（无需编辑 profiles.yaml）
VLLM_EMBEDDING_BASE_URL= # 覆盖 vLLM 嵌入端点（默认：http://ai:8001/v1）
VLLM_SUMMARIZATION_BASE_URL= # 覆盖摘要端点（默认：http://win:8002/v1）
## 🗂️ 索引管理
### 集中式索引存储
所有索引现在都集中存储在 `.indexes/`（相对于 MCP 项目）以实现更好的组织并防止意外提交：
```
.indexes/
├── {repo_hash}/ # 每个存储库的唯一哈希
│ ├── main_abc123.db # main 分支在提交 abc123 处的索引
│ ├── main_abc123.metadata.json
│ └── current.db -> main_abc123.db # 到活动索引的符号链接
├── qdrant/ # 语义搜索嵌入
│ └── main.qdrant/ # 集中式 Qdrant 数据库
```
**好处：**
- 索引永远不会意外提交到 git
- 可在同一存储库的多个克隆之间重用
- 代码和索引之间的清晰分离
- 基于 git 远程的自动发现
**迁移：**
对于具有本地索引的现有存储库：
```bash
python scripts/move_indexes_to_central.py
```
### 对于此存储库
该项目使用 GitHub Actions Artifacts 进行高效的索引共享，因此大多数用户从发布的索引基准开始，而不是在本地重建。
```bash
# 首次设置 - 拉取最新索引
mcp-index artifact pull --latest
# 拉取后，仅协调您的分支/工作树差异
mcp-index artifact sync
# 与团队共享索引
mcp-index artifact push
# 检查同步状态
mcp-index artifact sync
# 可选：安装 git 钩子以自动同步
mcp-index hooks install
# 现在索引会在 git push 时自动上传
# 并在 git pull 时自动下载
```
### 适用于任何存储库（MCP 索引工具包）
在任何存储库中启用可移植的索引管理，无需 GitHub 计算成本：
#### 快速安装
```bash
npm install -g mcp-index-kit
mcp-index init
```
#### 工作原理
1. **零成本架构**：
- 所有索引都在开发人员机器上进行
- 索引存储为 GitHub Artifacts（公共存储库免费）
- 克隆时自动下载，推送时自动上传
- 无需 GitHub Actions 计算
2. **可移植设计**：
- 任何存储库的单个命令设置
- 由 MCP 服务器和工具自动检测
- 语言/运行时行为遵循 `docs/SUPPORT_MATRIX.md` 中的明确支持层级
- 按存储库启用/禁用
3. **用法**：
```bash
# 在您的存储库中初始化
cd your-repo
mcp-index init
# 在本地构建索引
mcp-index build
# 推送到 GitHub Artifacts
mcp-index push
# 拉取最新索引
mcp-index pull
# 自动同步
mcp-index sync
```
#### 配置
##### 语义搜索配置
要启用语义搜索功能，您需要一个 Voyage AI API 密钥。从 [https://www.voyageai.com/](https://www.voyageai.com/) 获取一个。
**方法 1：Claude Code 配置（推荐）**
在项目根目录中创建或编辑 `.mcp.json`：
```json
{
"mcpServers": {
"code-index-mcp": {
"command": "mcp-index",
"args": ["stdio"],
"env": {
"VOYAGE_API_KEY": "your-voyage-ai-api-key-here",
"SEMANTIC_SEARCH_ENABLED": "true"
}
}
}
}
```
服务器标签 `code-index-mcp` 在这些示例中是客户端本地的 MCP 服务器 ID，而不是 Python 分发名称。
**方法 2：Claude Code CLI**
```bash
claude mcp add code-index-mcp -e VOYAGE_API_KEY=your_key -e SEMANTIC_SEARCH_ENABLED=true -- mcp-index stdio
```
**方法 3：环境变量**
```bash
export VOYAGE_API_KEY=your_key
export SEMANTIC_SEARCH_ENABLED=true
```
**方法 4：.env 文件**
在项目根目录中创建一个 `.env` 文件：
```
VOYAGE_API_KEY=your_key
SEMANTIC_SEARCH_ENABLED=true
```
**检查配置**
验证您的语义搜索设置：
```bash
mcp-index index check-semantic
```
##### 索引配置
编辑存储库中的 `.mcp-index.json`：
```json
{
"enabled": true,
"auto_download": true,
"artifact_retention_days": 30,
"github_artifacts": {
"enabled": true,
"max_size_mb": 100
}
}
```
查看 [mcp-index-kit](./mcp-index-kit/) 以获取完整文档
# 查看构件详情
mcp-index artifact info 12345
#### 索引管理
```bash
# 检查索引状态
mcp-index index status
# 检查兼容性
mcp-index index check-compatibility
# 仅在 artifact sync 无法跟上时在本地重建索引
mcp-index index rebuild
# 创建备份
mcp-index index backup my_backup
# 从备份中恢复
mcp-index index restore my_backup
```
### GitHub Actions 集成
- **拉取请求**：验证开发人员提供的索引（无需重建）
- **合并到主分支**：将验证的索引提升为构件
- **成本效益高**：使用免费的 GitHub Actions Artifacts 存储
- **自动清理**：旧构件在 30 天后被清理
### 存储和成本
- **GitHub Actions Artifacts**：公共存储库免费，包含在私有存储库配额中
- **保留期**：PR 构件 7 天，主分支 30 天
- **大小限制**：每个构件 500MB（压缩后）
- **自动压缩**：~70% 大小减少，使用 tar.gz
### 开发人员工作流程
1. **克隆存储库**
```bash
git clone https://github.com/yourusername/Code-Index-MCP.git
cd Code-Index-MCP
```
2. **获取最新索引**
```bash
gh auth login
mcp-index artifact pull --latest
```
- 这会下载当前的完整 GitHub 构件快照。
- 然后 `mcp-index artifact sync` 仅协调本地分支/工作树差异。
3. **进行更改**
- 像往常一样编辑代码
- 索引通过文件监视器自动更新
4. **共享更新**
```bash
# 您的索引已经在本地更新
mcp-index artifact push
```
### 嵌入模型兼容性
系统跟踪嵌入模型版本以确保兼容性：
- **`commercial_high`**: `voyage-code-3` — 2048 维，点积，float32
- **`oss_high`**: `Qwen/Qwen3-Embedding-8B` — 4096 维，点积，l2 归一化
- **自动检测**：系统在下载前检查配置文件兼容性
可以在以下位置提供多配置文件语义配置：
- `SEMANTIC_PROFILES_JSON`（环境变量），或
- `code-index-mcp.profiles.yaml`（存储库根目录）。
### 构件策略
- GitHub 构件拉取是完整的快照下载，而不是部分远程补丁获取。
- 当前压缩的构件足够小，全量下载比远程增量协议更简单
- 效率来自本地增量索引恢复：
- 拉取最新的完整构件
- 将恢复的构件提交与本地 `HEAD` 进行比较
- 让监视器或本地增量重新索引协调添加、修改、
删除和重命名的文件
- 分支特定的远程构件是可选的。默认策略是使用
最新 `main` 构件作为基准，并在本地协调分支差异。
### 简单语义设置（Docker-first）
使用自动本地 Qdrant 启动运行初始化：
```bash
mcp-index setup semantic
```
设置优先级（从高到低）：
1. CLI 标志（对于单个命令运行）
2. 环境变量 / `.env`
3. `code-index-mcp.profiles.yaml`
4. `SEMANTIC_PROFILES_JSON`
5. 内置默认值
常见控件：
```bash
# 仅预检查
mcp-index setup semantic --dry-run
# 严格模式：如果语义堆栈未就绪，则命令失败
mcp-index setup semantic --strict
# 覆盖本地嵌入端点
mcp-index setup semantic --openai-api-base http://127.0.0.1:8001/v1
```
插件加载默认使用快速存储库语言检测进行自动优化：
- `MCP_AUTO_DETECT_LANGUAGES=true`
- `MCP_LANGUAGE_DETECT_MAX_FILES=5000`
- `MCP_LANGUAGE_DETECT_MIN_FILES=2`
对于启动敏感的环境，请启用：
- `MCP_FAST_STARTUP=true`（使用延迟插件加载并跳过文件监视器启动）
当 `MCP_AUTO_DETECT_LANGUAGES=true` 时，自动检测优先于 `plugins.yaml`。
设置 `MCP_AUTO_DETECT_LANGUAGES=false` 以强制 `plugins.yaml` 语言选择。
对于双配置文件设置（Voyage + 本地 vLLM/Qwen），设置：
- `VOYAGE_API_KEY`
- `OPENAI_API_BASE`（例如 `http://127.0.0.1:8000/v1`）
- `OPENAI_API_KEY`（本地 vLLM 设置的占位符接受）
如果您使用不同的嵌入模型，系统将检测不兼容性并在本地使用您的配置重建。
## 💻 开发
### 创建新语言插件
1. **创建插件结构**
```bash
mkdir -p mcp_server/plugins/my_language_plugin
cd mcp_server/plugins/my_language_plugin
touch __init__.py plugin.py
```
2. **实现插件接口**
```python
from mcp_server.plugin_base import PluginBase
class MyLanguagePlugin(PluginBase):
def __init__(self):
self.tree_sitter_language = "my_language"
def index(self, file_path: str) -> Dict:
# 解析和索引文件
pass
def getDefinition(self, symbol: str, context: Dict) -> Dict:
# 查找符号定义
pass
def getReferences(self, symbol: str, context: Dict) -> List[Dict]:
# 查找符号引用
pass
```
3. **注册插件**
```python
# 在 dispatcher.py 中
from .plugins.my_language_plugin import MyLanguagePlugin
self.plugins['my_language'] = MyLanguagePlugin()
```
### 运行测试
```bash
# 运行所有测试
pytest
# 运行特定测试
pytest test_python_plugin.py
# 衡量当前本地/外包覆盖率基准
make coverage-baseline
# 生成本地/外包覆盖率报告
make coverage
# 拒绝跟踪或暂存的生成的覆盖率输出
make coverage-artifact-guard
```
覆盖率合同是本地/外包优先：`make coverage` 会发出终端
缺失行输出和 `coverage.xml`，而 `make agent-full` 负责例行
覆盖率生成。README 徽章在有信任事件
生成真实上传证据之前保持延迟。
### 架构可视化
```bash
# 查看 C4 架构图
docker run --rm -p 8080:8080 \
-v "$(pwd)/architecture":/usr/local/structurizr \
structurizr/lite
# 在浏览器中打开 http://localhost:8080
```
## 管理 REST 接口（辅助）
> 规范接口是 MCP 工具调用（`search_code`、`symbol_lookup`
> 等）通过 STDIO 运行程序 - 请参见上面的“快速入门”部分。 本文档中记录的 FastAPI REST 网关是一个辅助管理接口，用于
> 诊断、脚本编写和无法使用 MCP 的客户端。 其端点
> 不是 LLM 驱动的工作流的推荐路径。
### 管理 REST 端点
#### `GET /symbol`
获取符号定义（管理/调试界面 - 优先使用 `symbol_lookup` MCP 工具）：
```
GET /symbol?symbol_name=parseFile&file_path=/path/to/file.py
```
查询参数：
- `symbol_name`（必填）：要查找的符号名称
- `file_path`（可选）：要搜索的特定文件
#### `GET /search`
搜索代码模式（管理/调试界面 - 优先使用 `search_code` MCP 工具）：
```
GET /search?query=async+def.*parse&file_extensions=.py,.js
```
查询参数：
- `query`（必填）：搜索模式（支持正则表达式）
- `file_extensions`（可选）：逗号分隔的扩展名列表
- `source_type`（可选）：`friction` 或 `history`
- `friction_categories`（可选）：逗号分隔的摩擦类别
- `history_labels`（可选）：逗号分隔的历史问题标签
- `history_repos`（可选）：逗号分隔的属主/存储库过滤器，用于历史问题文档
- `include_source_metadata`（可选）：在匹配结果上包含 `search_source_metadata.v1`
记录
### Python 客户端 API（测试版本地 API）
在同一台机器和注册的检出中使用 Python 客户端时，请使用本地程序matic 访问。 在助理需要主 LLM 工具表面时，请使用 MCP 工具。
```python
from mcp_server.client import open_client
from mcp_server.client_types import ClientSearchOptions
with open_client(workspace_root="/path/to/repo") as client:
search = client.search_code(ClientSearchOptions(query="Reflection issue"))
symbol = client.symbol_lookup("IndexItClient")
status = client.get_status()
```
准备就绪状态保持关闭。 未就绪的存储库返回类型化
`index_unavailable` 数据，带有 `safe_fallback="native_search"` 而不是
调度与过时索引对抗。 测试版 Python 客户端故意没有
远程服务客户端。
### 响应格式
所有 API 响应都遵循一致的 JSON 结构：
**成功响应：**
```json
{
"status": "success",
"data": { ... },
"timestamp": "2024-01-01T00:00:00Z"
}
```
**错误响应：**
```json
{
"status": "error",
"error": "错误消息",
"code": "错误代码",
"timestamp": "2024-01-01T00:00:00Z"
}
```
## 🚢 部署
### Docker 部署选项
该项目包含多个 Docker 配置文件，适用于不同的环境：
**开发（默认）：**
```bash
# 使用 docker-compose.yml + Dockerfile
docker-compose up -d
# - SQLite 数据库
# - Uvicorn 开发服务器
# - 代码更改的卷挂载
# - 启用调试日志
```
**生产环境：**
```bash
# 使用 docker-compose.production.yml + Dockerfile.production
docker-compose -f docker-compose.production.yml up -d
# - PostgreSQL 数据库
# - Gunicorn + Uvicorn 工作进程
# - 多阶段优化构建
# - 安全强化（非 root 用户）
# - 生产日志
```
**增强开发：**
```bash
# 使用两个 compose 文件进行开发覆盖
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d
# - 开发基础 + 增强调试
# - 源代码卷挂载
# - 读写代码访问
```
### 容器重启行为
**重要提示**：默认情况下，`docker-compose restart` 使用 **开发** 配置：
- `docker-compose restart` → 使用 `docker-compose.yml`（开发）
- `docker-compose -f docker-compose.production.yml restart` → 使用生产环境
### 生产环境部署
对于生产环境，我们提供：
1. **多阶段 Docker 构建**，具有安全强化
2. **PostgreSQL 数据库**，支持异步操作
3. **Redis 缓存**，用于性能优化
4. **Qdrant 矢量数据库**，用于语义搜索
5. **Prometheus + Grafana** 监控堆栈
6. **Kubernetes 清单**，位于 `k8s/` 目录中
7. **nginx 反向代理** 配置
参见我们的 [部署指南](docs/DEPLOYMENT-GUIDE.md)，获取详细说明，包括：
- Kubernetes 部署配置
- 自动扩展设置
- 数据库优化
- 安全最佳实践
- 监控和可观察性
### 系统要求
- **最低要求**：2GB RAM，2 CPU 核心，10GB 存储空间
- **推荐配置**：8GB RAM，4 CPU 核心，50GB SSD 存储空间
- **大型代码库**：16GB+ RAM，8+ CPU 核心，100GB+ SSD 存储空间
## 📦 版本和预构建索引
### 使用预构建索引
要快速设置，请从我们的 GitHub 版本中下载预构建索引：
```bash
# 列出可用版本
python scripts/download-release.py --list
# 下载当前的预构建索引工件
python scripts/download-release.py --latest
# 下载特定版本的索引工件
python scripts/download-release.py --tag v2024.01.15 --output ./my-index
```
### 创建版本
维护人员可以使用预构建索引创建新版本：
```bash
# 从功能分支准备或更新发布 PR
gh workflow run "Release Automation" --ref <release-branch> -f mode=prepare -f version=v1.3.1 -f auto_merge=false
# 在 PR 合并后，仅在受保护的主分支上发布
gh workflow run "Release Automation" --ref main -f mode=publish -f version=v1.3.1 -f auto_merge=false
```
### 自动索引同步
该项目包含用于自动索引同步的 git 钩子：
- **预推送**：将索引更改上传到 GitHub 构件
- **合并后**：拉取兼容索引后下载
使用以下命令安装钩子：`mcp-index hooks install`
## 🤝 贡献
我们欢迎贡献！请参阅我们的 [贡献指南](CONTRIBUTING.md) 获取详细信息。
### 开发流程
1. **复刻存储库**
2. **创建功能分支** (`git checkout -b feature/amazing-feature`)
3. **进行更改**
4. **添加测试**（目标覆盖率 90%+）
5. **更新文档**
6. **提交拉取请求**
### 代码风格
- 遵循 Python 代码的 PEP 8
- 为所有函数使用类型提示
- 编写描述性文档字符串
- 保持函数小且专注
## 📈 性能
### 基准测试
| 操作 | 性能目标 | 当前状态 |
|-----------|-------------------|----------------|
| 符号查找 | <100ms (p95) | ✅ 实现 - 所有查询 < 100ms |
| 代码搜索 | <500ms (p95) | ✅ 实现 - BM25 搜索 < 50ms |
| 文件索引 | 10K 文件/分钟 | ✅ 实现 - 152K 文件索引 |
### 矩阵基准测试（2026-04-01）
| 指标 | 仅 BM25 | voyage-code-3 | Qwen3-Embedding-8B |
|---|:---:|:---:|:---:|
| Top-1（无重新排序） | 12/17（70.6%） | **17/17（100%）** | **17/17（100%）** |
| Top-1（闪存排序） | 13/17（76.5%） | **17/17（100%）** | **17/17（100%）** |
| Top-1（跨编码器） | — | **17/17（100%）** | **17/17（100%）** |
| Top-1（航程重新排序） | — | 15/17（88.2%） | — |
| BM25 符号查询 p50 | ~1–5 毫秒 | — | — |
| 语义查询 p50（混合） | — | ~50–400 毫秒 | ~50–280 毫秒 |
完整结果：`docs/benchmarks/matrix_benchmark.md` / `.json`
## 🏗️ 架构概述
系统遵循 C4 模型架构模式：
- **工作空间定义**：在 `architecture/workspace.dsl` 中定义，并使用 Structurizr CLI 验证
- **系统上下文（L1）**：Claude Code 通过 MCP 子代理与 STDIO 主界面集成
- **容器级别（L2）**：8 个主要容器，包括增强的 MCP 服务器和用户文档
- **组件级别（L3）**：插件系统、内存管理和跨仓库协调
- **代码级别（L4）**：43 张 PlantUML 图表，记录了所有系统组件和流程
有关详细的架构文档，请参阅 [architecture/](architecture/) 目录。
## 🗺️ 开发路线图
请参阅 [ROADMAP.md](ROADMAP.md) 以获取详细的开发计划和当前进度。
**当前状态**：1.3.1 硬化表面已准备就绪；protected-main 发布仍在等待中
- ✅ **核心索引**：使用 SQLite + FTS5 实现快速本地搜索
- ✅ **多语言**：专门的语言支持和注册表支持；请参阅 `docs/SUPPORT_MATRIX.md`
- ✅ **MCP 协议**：通过 STDIO 验证官方 Python SDK 兼容性；请参阅 `docs/status/MCP_COMPATIBILITY_EVALUATION.md` 以获取命名客户端姿势
- ✅ **性能**：使用 BM25 优化的子 100ms 查询
- 🔄 **索引同步**：通过 GitHub Artifacts 提供测试版支持
- 🔄 **语义搜索**：需要 Voyage AI API 的可选功能
**近期改进**：
- **⚡ 调度器优化**：超时保护和 BM25 绕过以提高可靠性
- **🔄 混合搜索**：BM25 + 语义搜索，具备优雅降级功能
- **📊 结果排名**：通过分数归一化提高相关性
- **🔧 CLI 工具**：用于索引管理的全功能 `mcp-index` 命令
### 优化提示
性能优化功能已实现并可用：
1. **启用缓存**：Redis 缓存已实现，可通过环境变量配置
2. **调整批次大小**：可通过 `INDEXING_BATCH_SIZE` 环境变量配置
3. **使用 SSD 存储**：显著提高索引速度
4. **限制文件大小**：可通过 `INDEXING_MAX_FILE_SIZE` 环境变量配置
5. **并行处理**：可通过 `INDEXING_MAX_WORKERS` 配置多工作线程索引
## 🔒 安全
- **本地优先**：默认情况下，所有处理都在本地进行
- **路径验证**：防止目录遍历攻击
- **输入净化**：所有查询都经过净化处理
- **机密检测**：自动删除检测到的机密信息
- **插件隔离**：插件在受限环境中运行
- **⚠️ 语义摘要风险**：如果启用 LLM 生成的语义摘要（延迟或综合），请注意 **提示注入漏洞**。恶意行为者可能会在代码注释中（例如，在开源依赖项中）放置隐藏指令，这些指令可能会被摘要 LLM 执行。请始终审查生成的索引元数据，如果摘要未受信任的代码。
## 📄 许可证
该项目在 MIT 许可证下获得许可 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
## 🙏 致谢
- [Tree-sitter](https://tree-sitter.github.io/) 用于语言解析
- [Jedi](https://jedi.readthedocs.io/) 用于 Python 分析
- [FastAPI](https://fastapi.tiangolo.com/) 用于 API 框架
- [Voyage AI](https://www.voyageai.com/) 用于嵌入
- [Anthropic](https://www.anthropic.com/) 用于 MCP 协议
## 📬 联系方式
- **问题**：[GitHub 问题](https://github.com/ViperJuice/Code-Index-MCP/issues)
- **讨论**：[GitHub 讨论](https://github.com/ViperJuice/Code-Index-MCP/discussions)
<p align="center">❤️ 为开发者社区而建</p>
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器