内容
# Zvec MCP 桥接器
该仓库包含一个本地 MCP 桥接器，它将项目源文件索引到 Zvec 矢量数据库中，并通过 MCP 工具提供语义搜索功能。
## 桥接器功能
当前实现是一个基于标准输入输出的 MCP 服务器，它：
- 在项目根目录中创建或打开一个本地 Zvec 集合，位于 `.zvec/knowledge.db`；
- 使用 Hugging Face Transformers 特性提取管道嵌入文本块，使用的模型是 `Xenova/all-MiniLM-L6-v2`；
- 在启动时遍历项目树以构建初始索引；
- 监视文件添加、更改、删除事件并自动更新索引；
- 提供四个 MCP 工具用于搜索、重新索引、单个文件索引和状态检查。
## 要求
- Node.js 18 或更新版本
- 项目 package 文件中的 npm 依赖
- 首次使用时下载本地模型（桥接器使用 Hugging Face Transformers 管道）
## 安装
从仓库根目录执行：
```bash
npm install
```
## 运行桥接器
直接运行桥接器：
```bash
PROJECT_ROOT=/绝对路径/到/你的/项目 node zvec-mcp-bridge.js
```
如果未提供 `PROJECT_ROOT`，桥接器将使用当前工作目录。
## MCP 配置示例
此桥接器不限于 Google Antigravity；它与任何可以启动标准输入输出进程的 MCP 兼容客户端配合使用。
```json
{
"mcpServers": {
"zvec-project-knowledge": {
"command": "node",
"args": ["/绝对路径/到/zvec-mcp-bridge.js"],
"env": {
"PROJECT_ROOT": "/绝对路径/到/你的/项目"
}
}
}
}
```
## 支持的文件
桥接器索引以下文件扩展名：
- `.js`、`.jsx`、`.ts`、`.tsx`
- `.kt`、`.erl`、`.hrl`
- `.py`、`.go`、`.java`、`.cs`、`.rb`、`.php`
- `.cpp`、`.c`、`.h`、`.hpp`、`.rs`、`.swift`、`.scala`
它跳过常见的配置文件和锁定文件，如 `package.json`、`package-lock.json`、`tsconfig.json`、`vite.config.*` 等类似文件。它还忽略生成的目录或依赖项繁重的目录，如 `node_modules`、`.git`、`dist`、`build`、`.cache`、`.next` 和 `.vscode`。
## MCP 工具
### `search_project_knowledge`
在本地 Zvec 知识库中搜索相关的代码片段。
输入：
- `query`（必填）：自然语言搜索请求
- `exclude_paths`（可选）：从结果中排除的路径子字符串
- `include_paths`（可选）：结果中必须存在的路径子字符串
行为：
- 桥接器为查询创建嵌入；
- 它运行矢量搜索，`topk: 15`；
- 结果在 JavaScript 中使用关键字和路径启发式进行筛选和重新排序；
- 每个结果都包含一个简短的解释和匹配的代码块。
### `initialize_project_knowledge`
初始化知识库并索引项目内容。
输入：
- `force_rebuild`（可选）：如果为 `true`，则在重新索引之前清除现有的索引
### `index_file`
立即索引或刷新单个文件。
输入：
- `file_path`（必填）：文件的相对或绝对路径
### `get_knowledge_status`
返回当前数据库状态信息，例如：
- 数据库路径
- 数据库是否存在
- 文档数量
- 初始化状态
- 项目根目录
## 索引详情
- 文本被分成大约 1000 个字符的块，带有 200 个字符的重叠；
- 桥接器将每个块存储为一个文档，包含 `text_content`、`file_path` 和 `language` 字段；
- 嵌入矢量字段名为 `code_embedding`。
## 示例提示
LLM 的一个有用示例提示可以在 [AGENTS.md](AGENTS.md) 中找到。
