ragjson-zvec

基于 zvec 向量数据库的 RAG MCP Server。消费 .mushroom 变更文件，通过 MCP 协议提供语义检索服务。

架构

rag update -r              ragjson-zvec                    MCP Client
─────────────              ────────────                    ──────────
解析 → 切片 → 嵌入    →    定时采蘑菇 → zvec         →    query(text, topn)
写 .ragjson                启动时立即同步一轮               返回 content + source + score
写 .mushroom               之后每 N 秒扫描一次
                           消费后删除蘑菇

三个环节通过文件解耦，进程间无直接依赖。

快速开始

前置条件

• ~/.rag.config 配置文件（embedding API）
• 知识库已由 rag update 处理过（存在 .ragjson 和 .mushroom 文件）

配置

~/.rag.config：

{
  "embedding_model": {
    "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
    "api_key": "sk-...",
    "model_name": "text-embedding-v4",
    "dimension": 768
  }
}

安装

uv sync

使用

stdio 模式（推荐，client 自动启动 server 子进程）：

uv run ragjson-zvec-client \
  --kb-root ~/knowledge-base \
  --db-path ~/vector-db

HTTP 模式（需要先手动启动 server）：

# 终端 1：启动 server
uv run ragjson-zvec \
  --kb-root ~/knowledge-base \
  --db-path ~/vector-db \
  --transport sse --host 0.0.0.0 --port 8000

# 终端 2：client 连接
uv run ragjson-zvec-client \
  --transport sse \
  --url http://localhost:8000/sse

接入 Claude Desktop

{
  "mcpServers": {
    "ragjson-zvec": {
      "command": "uv",
      "args": [
        "run", "--directory", "/path/to/ragjson-zvec",
        "ragjson-zvec",
        "--kb-root", "/path/to/knowledge-base",
        "--db-path", "/path/to/vector-db"
      ]
    }
  }
}

CLI 参考

ragjson-zvec (server)

usage: ragjson-zvec [options]

必选参数:
  --kb-root PATH          知识库根目录
  --db-path PATH          向量数据库存储目录

可选参数:
  --index-type TYPE       索引类型: flat | hnsw（默认 flat，仅新建库时生效）
  --sync-interval INT     蘑菇同步间隔秒数（默认 60）
  --config PATH           配置文件路径（默认 ~/.rag.config）
  --transport MODE        传输模式: stdio | sse | streamable-http（默认 stdio）
  --host HOST             HTTP 监听地址（默认 127.0.0.1）
  --port INT              HTTP 监听端口（默认 8000）

ragjson-zvec-client (调试客户端)

usage: ragjson-zvec-client [options]

传输模式:
  --transport MODE        stdio | sse | streamable-http（默认 stdio）

stdio 模式参数（自动启动 server）:
  --kb-root PATH          知识库根目录
  --db-path PATH          向量数据库存储目录
  --index-type TYPE       索引类型: flat | hnsw（默认 flat）
  --sync-interval INT     同步间隔秒数（默认 60）
  --config PATH           配置文件路径

HTTP 模式参数（连接已运行的 server）:
  --url URL               Server URL（如 http://localhost:8000/sse）
  --host HOST             Server 地址（默认 127.0.0.1）
  --port INT              Server 端口（默认 8000）

交互式命令:
  /tools                  列出可用 tools
  /topn N                 设置返回条数（默认 5）
  /quit                   退出
  (任意文本)              搜索知识库

MCP Tool: query

query(text: str, topn: int = 5) -> str

参数	类型	默认值	说明
text	str	（必填）	查询文本
topn	int	5	返回最相似的前 N 条结果

返回 JSON 数组，每条包含：

[
  {
    "content": "chunk 原文内容",
    "source": "docs/readme.md",
    "score": 0.123456
  }
]

• score：余弦距离，越小越相似（0 = 完全匹配）
• source：源文件相对知识库根目录的路径

知识库目录结构

server 期望知识库包含 .rag/ 目录，其中有 .ragjson 和 .mushroom 文件（由 rag update 生成）：

~/knowledge-base/
├── docs/
│   ├── .rag/
│   │   ├── readme.md.ragjson              ← 切片 + 向量数据
│   │   └── 20260715T120000Z.mushroom      ← 变更通知（会被消费并删除）
│   └── readme.md                          ← 源文件
└── src/
    ├── .rag/
    │   └── app.js.ragjson
    └── app.js

工作原理

1. 启动时：立即执行一轮蘑菇同步，然后启动定时任务
2. 定时同步：每 N 秒扫描 **/.rag/*.mushroom，按时间戳顺序处理
   • upsert 事件：删除旧 chunks → 读 .ragjson → 解码 base64 向量 → 写入 zvec
   • delete 事件：删除该 source 的所有 chunks
   • 成功后删除蘑菇文件；失败则保留，下次重试（幂等操作）
3. 查询时：embedding 查询文本 → zvec 向量检索 → 返回 topn 结果

项目结构

src/ragjson_zvec/
├── __init__.py
├── __main__.py          # Server CLI 入口
├── config.py            # ~/.rag.config 加载
├── embedding.py         # QwenDenseEmbedding 封装
├── collection.py        # zvec collection 管理
├── indexer.py           # 蘑菇扫描 + zvec 同步
├── server.py            # MCP server + query tool
└── client.py            # MCP 调试客户端

依赖

• zvec — 阿里巴巴开源的进程内向量数据库
• mcp — Model Context Protocol SDK