内容
# cocoindex 中间件
一个中间件服务器，逐步将**代码仓库**和**文档**索引到 Postgres + pgvector 存储中，使用 [CocoIndex](https://cocoindex.io)，并对其进行语义搜索。
处理流程是 `源 → 提取（格式注册表）→ 分段 → 嵌入 → 存储`：
- **源** (`src/mcp_coco/sources.py`) — 目前是本地文件系统，有两种配置文件：
`repo`（代码感知，排除已有的目录）和 `document`（markdown/文本/pdf，文章分段）。
- **格式** (`src/mcp_coco/formats.py`) — 一个将文件映射到标准化文本的注册表。
PDF（通过 `pymupdf`）只是一个处理程序；添加格式只需注册一个即可。
- **索引器** (`src/mcp_coco/indexer.py`) — CocoIndex 应用程序：分段 + 嵌入
(`sentence-transformers`) 并声明一行到 `doc_embeddings` 表中。
- **搜索** (`src/mcp_coco/db.py`) — 嵌入查询并运行 pgvector 相似性搜索。
CocoIndex 在本地 LMDB 文件 (`COCOINDEX_DB`) 中跟踪其增量状态，因此重新索引只会重新处理更改的内容，并删除已删除文件的行。
## 先决条件
- [uv](https://docs.astral.sh/uv/)（Python 包管理器）
- [just](https://github.com/casey/just)（任务运行器，可选但方便）
- 带有 [pgvector](https://github.com/pgvector/pgvector) 的 Postgres 实例
- [Docker](https://www.docker.com/)（如果您想通过附带的 compose 文件运行 pgvector）
## 快速入门（本地）
### 1. 启动 pgvector 数据库
如果您已经有一个带有 pgvector 的 Postgres 实例，请跳过此步骤并相应地设置
`DATABASE_URL`。
否则，请使用附带的 compose 文件：
```bash
docker compose up -d
```
这会在 `localhost:5432` 上启动 pgvector，用户名/密码/数据库均设置为 `cocoindex`。
### 2. 安装依赖项
```bash
uv sync
```
### 3. 配置
```bash
cp .env.example .env
```
编辑 `.env` 并设置 `DATABASE_URL` 以指向您的 Postgres 实例。对于基于 Docker 的数据库：
```
DATABASE_URL=postgresql://cocoindex:cocoindex@localhost:5432/cocoindex
```
可选设置：
| 变量 | 默认值 | 描述 |
|---|---|---|
| `EMBED_MODEL` | `sentence-transformers/all-MiniLM-L6-v2` | 用于索引和搜索的嵌入模型 |
| `RERANK_MODEL` | `cross-encoder/ms-marco-MiniLM-L-6-v2` | 用于结果重新排序的交叉编码器模型 |
| `COCO_TABLE_NAME` | `doc_embeddings` | Postgres 表名 |
| `COCOINDEX_DB` | `/data/cocoindex/state.db` | CocoIndex 增量状态存储的路径 |
### 4. 验证数据库连接
```bash
just init
```
### 5. 索引内容
```bash
just index ./path/to/repo repo
just index ./path/to/docs document
```
第一次运行会从 Hugging Face 下载嵌入模型（约 80 MB）。
### 6. 搜索
```bash
just search "how does authentication work"
```
## 与编码代理一起使用
将中间件服务器添加到您的 Claude Code 设置中
（全局为 `~/.claude/settings.json`，或项目中的 `.claude/settings.json`）：
```json
{
"mcpServers": {
"cocoindex": {
"command": "uv",
"args": ["run", "--directory", "/absolute/path/to/cocoindex-mcp", "mcp-coco-server"],
"env": {
"DATABASE_URL": "postgresql://cocoindex:cocoindex@localhost:5432/cocoindex",
"COCOINDEX_DB": "/absolute/path/to/cocoindex-mcp/.cocoindex/state.db"
}
}
}
}
```
将 `/absolute/path/to/cocoindex-mcp` 替换为此仓库的实际路径。
如果您的 Postgres 实例在其他地方（例如云托管数据库），请相应地调整
`DATABASE_URL`。强烈建议通过环境变量传递身份验证信息，请勿在连接字符串中硬编码！
配置完成后，Claude Code 可以使用这些工具：
| 工具 | 描述 |
|---|---|
| `index_repo(path)` | 索引代码仓库 |
| `index_documents(path)` | 索引文档集合 |
| `search(query, limit, source_kind)` | 语义搜索 — 返回浓缩的摘要和 `results_file` 路径 |
| `read_search_results(results_file, indices, rerank)` | 检索特定结果的完整详细信息 |
### 两阶段搜索
为了保持上下文精简，`search` 会将完整结果写入临时 JSON 文件
并仅内联返回浓缩的摘要（约 80 个字符的摘录）。调用者
从摘要中进行分类，然后使用 `read_search_results` 提取实际需要的完整结果。
默认情况下，`read_search_results` 使用交叉编码器模型
（`cross-encoder/ms-marco-MiniLM-L-6-v2`）对选定的结果进行重新排序，以获得更准确的相关性排序。您可以通过设置 `rerank=false` 来禁用此功能。模型可通过环境变量 `RERANK_MODEL` 进行配置。
## 开发（devcontainer）
1. 在 VS Code 中打开此文件夹并 **在容器中重新打开** （Dev Containers）。
`db` 服务会自动启动，与应用程序容器一起。
2. 运行预检查：
```bash
just install
just init
```
将 `.env.example` 复制到 `.env` 以自定义设置。在 devcontainer
中，数据库主机名为 `db`（默认值）。
## `just` 命令
```
just index <path> [repo|document|auto] # 索引路径
just index-repo <path> # 作为代码仓库索引
just index-docs <path> # 作为文档集合索引
just search "query" [limit] # 语义搜索
just drop <path> [repo|document|auto] # 从索引中删除源
just visualize_index # 显示索引映射
just serve # 通过 stdio 运行中间件服务器
just test # 运行测试
just lint # 运行 ruff
```
