内容
# MCP RAG
基于SQLite的MCP服务器，具备知识图谱、向量存储和生产级别的RAG流水线。一个静态链接的二进制文件，可从手机到数据中心自动调整——部署层级仅设置默认值；每个参数仍可被覆盖。
使用Zig（0.16）和SQLite C库构建。
## 功能
- **RAG流水线**
- 分块：滑动令牌窗口，**递归**（段落→行→句子→词）和**父子**（小检索块+较大生成上下文）。
- 混合检索：密集向量⊕词典，融合互惠排名融合，可选MMR多样性重新排序。
- **任何规模的正确召回率**：流式top-k平面扫描（有界堆，O(k)内存）取代旧的`LIMIT k`；可选内存**HNSW**索引在较大语料库上提供O(log N)查询。
- **元数据预过滤**：将检索范围限定在文档集内。
- **语义查询缓存**：近似相同的先前查询直接跳过。
- **幂等摄入**：内容哈希去重跳过无操作重新摄入。
- **每查询跟踪**：阶段延迟+候选计数，记录并可选返回。
- **向量量化**：f32 / f16 / int8 / 二进制blob编码，带int8-余弦和二进制-汉明SIMD内核（RAM轴）。
- **运行时嵌入维度**：在不重新编译的情况下提供更高维度的嵌入器（`MCP_EMBED_DIMS`）。
- **知识图谱**：实体/关系/观察CRUD，BFS路径查找，搜索。
- **存储**：STRICT表，`(document_id, ordinal)`索引，原子多语句写入和分层缩放的SQLite PRAGMAs（缓存/mmap/同步/临时存储/WAL）。
- **传输**：stdio（MCP默认）。
> 原生IVF-FLAT和远程嵌入/交叉编码器重新排序/LLM生成阶段正在路线图中，但尚未实现。
## 构建
```bash
zig build # 二进制文件位于zig-out/bin/mcp-rag
zig build test # 单元测试+模糊测试
DATABASE_URL="sqlite:///tmp/mcp_test.db" zig build test # +带条件的集成测试
```
## 运行
```bash
MCP_AUTH_TOKEN="secret" zig-out/bin/mcp-rag # stdio（MCP默认）
MCP_DRY_RUN=1 zig-out/bin/mcp-rag # 打印解析的配置并退出
```
## 部署层级
根据RAM + CPU自动检测（使用`MCP_TIER={mobile|edge|server|dc}`覆盖）。层级设置池大小、SQLite PRAGMAs、向量索引和缓存的默认值；主`MCP_MEM_BUDGET_MB`（默认为RAM的70%）缩放内存范围。
| 层级 | 向量索引 | SQLite缓存 | 查询缓存 | 池最大 |
|---|---|---|---|---|
| `mobile` | 平面 | 2 MB | 关闭 | 2 |
| `edge` | 平面 | 64 MB | 128 | 2·核心数 |
| `server` | HNSW | 2 GB | 512 | 8·核心数 |
| `dc` | HNSW | 16 GB | 4096 | 16·核心数 |
## 配置
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `DATABASE_URL` | `sqlite:///tmp/mcp.db` | SQLite数据库路径 |
| `MCP_STDIO` | `false` | 传输（stdio） |
| `MCP_TIER` | 自动检测 | `mobile`/`edge`/`server`/`dc`（覆盖检测） |
| `MCP_MEM_BUDGET_MB` | 70% RAM | 主内存预算 |
| `MCP_MIN_CONNECTIONS` / `MCP_MAX_CONNECTIONS` | 层级 | 池大小 |
| `MCP_EMBED_DIMS` | `384` | 活动嵌入维度 |
| `MCP_INDEX_TYPE` | 层级（`flat`/`hnsw`） | 向量索引后端 |
| `MCP_INDEX_METRIC` | `cosine` | `cosine`或`euclidean`（索引构建指标） |
| `MCP_HNSW_M` / `_EF_CONSTRUCTION` / `_EF_SEARCH` | `16` / `200` / `64` | HNSW参数 |
| `MCP_QCACHE_ENTRIES` / `MCP_QCACHE_THRESHOLD` | 层级 / `0.97` | 语义查询缓存 |
| `MCP_MAX_REQUEST_MB` | 层级 | 单个stdio请求行上的上限（竞技场绑定） |
| `MCP_MAX_K` / `MCP_MAX_CANDIDATES` / `MCP_MMR_MAX_N` | 层级 | 检索上限：结果计数，每个臂的候选数，MMR截止 |
| `MCP_WRITE_BATCH_ROWS` | 层级 | 块上载事务窗口（绑定参数批量插入） |
| `MCP_RW_SPLIT` | `false` | 读取者/写入者连接分割：只读读取者池+单个写入者（WAL） |
| `MCP_IVF_NLIST` / `MCP_IVF_NPROBE` | 自动检测 / `8` | IVF-FLAT索引：单元格数量和每个查询的探测单元格 |
| `MCP_SQLITE_CACHE_MB` / `_MMAP_MB` / `_PAGE_SIZE` | 层级 | SQLite存储引擎 |
| `MCP_SQLITE_SYNC` / `_TEMP` / `_WAL_CKPT` / `_BUSY_MS` | 层级 | SQLite耐久性/IO |
| `MCP_DRY_RUN` | `false` | 打印解析的配置并退出 |
运行`MCP_DRY_RUN=1 zig-out/bin/mcp-rag`以查看任何层级/覆盖组合的完全解析的参数表。
## 精选RAG工具
| 工具 | 备注 |
|---|---|
| `rag_chunk_text` | `strategy`: `window`（默认）或`recursive` |
| `rag_parent_child_chunk` | 小子项+较大父项（`parentOrdinal`反向引用） |
| `rag_ingest_document` | 原子；内容哈希去重（`skipped:true`表示无操作） |
| `rag_search` | 混合+RRF+MMR；`documentId(s)`过滤；`trace:true`表示计时 |
| `rag_vector_search` | 纯语义；启用时HNSW加速（`index:"hnsw"`） |
嵌入由调用者提供（主机使用其选择的嵌入器计算）。
## MCP客户端配置
```json
{
"mcpServers": {
"mcp-rag": {
"command": "/path/to/zig-out/bin/mcp-rag",
"env": { "DATABASE_URL": "sqlite:///tmp/mcp.db" }
}
}
}
```
