rag-mcp：用LanceDB+Tantivy实现本地混合搜索MCP服务

编程代理不应该在逐个打开文件和把整个仓库丢进上下文之间做取舍。

构建自主式 AI 编程助手（如 Claude Code、Codex 或 Cursor）时，上下文窗口管理是一切的核心。如今，代理面临一个痛苦的三角困境：

贪婪式文件探测：在数十个目录上运行 cat、grep 或 find_by_name 会浪费宝贵的 token，产生多轮工具延迟，而且常常遗漏跨文件的抽象。

暴力上下文填充：将整个目录丢进提示词会触发二次方注意力开销，使推理速度慢如龟爬，并增加推理幻觉。

朴素向量搜索：纯稠密 embedding 搜索在精确符号名、编译器错误码以及 AUTH_JWT_SECRET_KEY 或 handle_epoch_timeout 这类唯一变量标识符上惨烈失效。

为此，我构建了 rag-mcp：一个 100% 本地化、高吞吐量的混合搜索引擎，专为编程代理设计的 Model Context Protocol（MCP）服务器。

🚀 在浏览器中在线体验（零下载 / 零后端）：https://rag.masihmoafi.com（镜像：https://rag.masihmoafi.tech）

架构：为什么纯向量搜索在代码上会失效

将稀疏词法搜索（BM25）和稠密语义向量合并听起来简单，但实践中，线性分数组合（$S = \alpha S_{\text{vector}} + (1-\alpha) S_{\text{bm25}}$）会导致严重的校准偏差，因为 BM25 分数是无界浮点数，而余弦相似度被限制在 $[-1, 1]$ 区间内。

rag-mcp 通过两阶段检索管道解决这一问题：

1. Tantivy Rust BM25（词法精度）

Tantivy 提供原生 Rust 速度的全文索引，直接在你的代码库上建立索引。如果你的提示词询问类 TransactionHandler 或精确的错误字符串，Tantivy 能以零语义幻觉的方式返回精确的行范围。

2. LanceDB Apache Arrow 向量（语义上下文）

与将记录序列化为 SQLite blob 或需要重型后台 Docker 容器的传统向量数据库不同，LanceDB 将 embeddings 存储在 Apache Arrow 列式内存格式中。它允许对你的文件系统直接进行零拷贝向量查询。

3. 互惠排名融合（RRF，$k=60$）

rag-mcp 不去标准化未校准的相似度分数，而是使用互惠排名融合来合并排名列表：

$$RRF(d) = \sum_{m \in M} \frac{1}{k + r_m(d)}$$

其中 $k=60$ 作为平滑常数，防止任何单一异常值主导最终排名。

4. Cross-Encoder 重排器

融合后的前 $N$ 个候选通过一个快速的本地 Cross-Encoder（ms-marco-MiniLM-L-6-v2）进行处理，该编码器对（查询 passage）对进行联合注意力计算，以在向代理返回 token 之前剪枝假阳性。

实证基准测试结果

我们在 open-rag-eval 分类法上针对多个异构语料库评估了 rag-mcp（$top_k=5$，本地 Ollama embeddings）：

在真实世界的软件代码库上，将面包屑 AST 分块与 RRF 相结合，实现了 100% 的至少部分证据捕获和 0% 的完全检索失败。

尝试浏览器内 WASM 演示（零配置）

在配置本地 CLI 之前，你可以在气隔离的 WebAssembly 环境中测试完整管道：

🔗 在线演示：https://rag.masihmoafi.com

🔒 100% 隐私保护：通过 Transformers.js 在专用 Web Worker 中运行量化 ONNX 模型（all-MiniLM-L6-v2）。

💾 本地 IndexedDB 持久化：所有文档、分块和向量表都持久化存储在浏览器中，零后端服务器请求。

快速开始与安装

git clone https://github.com/MasihMoafi/rag-mcp
cd rag-mcp
uv sync

运行自动化测试套件：

.venv/bin/python -m pytest tests/ -v

2. 连接到你的编程代理

{
  "mcpServers": {
    "rag": {
      "command": "/absolute/path/to/rag-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/rag-mcp/server.py"]
    }
  }
}

[mcp_servers.rag]
command = "/absolute/path/to/rag-mcp/.venv/bin/python"
args = ["/absolute/path/to/rag-mcp/server.py"]

Command: /absolute/path/to/rag-mcp/.venv/bin/python /absolute/path/to/rag-mcp/server.py

⭐️ GitHub 仓库：github.com/MasihMoafi/rag-mcp

🌐 在线 WASM 演示：rag.masihmoafi.com | rag.masihmoafi.tech

📖 深度技术报告：masihmoafi.com/projects/rag-mcp

👤 作者：Masih Moafi

欢迎给仓库加星、用你自己的文件测试 WASM 演示，或贡献优化！