Qdrant RAG Build

通过对话构建完整 RAG 管道的 Qdrant MCP 服务器。

非官方、社区构建 —— 与 Qdrant 无关联，也不代表 Qdrant 官方立场。

官方 Qdrant MCP 服务器只暴露 2 个工具（qdrant-store、qdrant-find）。Qdrant RAG Build 则在 6 个命名空间中暴露了 33 个工具 —— 完全通过 MCP 对话管理一个生产级 RAG 系统 —— 外加一个 对话式设置向导，让用户在一次次对话中即可从零开始，得到一个可用且配置良好的 RAG 集合，无需编写任何代码。

电梯推销语："将你的 AI 接入 Qdrant，让生产级 RAG 在一段对话中运行起来。" 而不是又一个 Qdrant 包装 —— RAG-in-a-box via MCP。

包名：qdrant-rag-build-mcp · 许可证：Apache-2.0 · 状态：规划已完成，开发尚未开始。

目录

1. 愿景与市场空白

2. 已锁定的决策

3. 架构

4. 工具目录

5. 对话式向导

6. 摄取管道

7. 精英检索

8. 质量与评估

9. GitHub 权威

10. 开发阶段

11. 继承的经验教训与风险

12. 名称、许可证与第一步

Related MCP server: RAG Knowledge Base MCP Server

1. 愿景与市场空白

论点： 如今，通过 MCP 把 LLM 连接到 Qdrant，你得到的只是一个玩具级的语义记忆。没有集合管理，没有文件摄取，没有混合搜索，没有重排，没有引用，没有引导式配置。所有这些能力本身已存在于量身定制的企业级 RAG 系统中 —— 但还没有人把它打包成一个只需一句命令即可安装的 MCP 服务器。

2. 已锁定的决策

范围。 完整的检索能力 + Qdrant 管理 + 高质量获取常见格式的文件内容（PDF、DOCX、Excel、PPTX、MD、HTML、CSV、网址）。干净、对 RAG 更友好的内容，是项目的签名特色。

目标客户端。 v1 是整个 Claude 全家桶：Claude Lark、Claude CODE、Claude Web Desktop（网页）。其中 Code 和 Desktop 走 stdio，本地运行，基本是一键安装（见 §3）。claude.ai 按照协议要求必须走远程 HTTP（浏览器无法拉起本地进程）—— 不过这只是量级较小的增加，并不是一种新的工作类别：官方 SDK 已经支持 streamable HTTP，而 v1 只需要一个 bearer token，不需要完整版 OAuth 2.1（见 §3），外加一份通公开 HTTPS 地址的部署指南。ChatGPT 不入 v1。 和 claude.ai 不同，ChatGPT 需要开启 Developer Mode（要接受一个明确披露风险的应用清单），并且只提供付费版，完全没有免费层级的门槛 —— 这和各种"把 Claude 放首位"的立场不一致，所以推迟到 v2 再说。

项目目标。 一个出色的开源工具：既是作品集的门面，也是 GitHub 权威引擎。文档质量、CI 质量、开发体验质量都不是可选项，就是产品本身。

**不做的事情（v1）。**不处理电子邮件、不. ,不做重 OCR、不做命名实体识别/实体提取、不在服务端生成 LLM 内容（客户端本身就是 LLM）,也不做定制的 UI。

3. 架构

一个 Python 二进制文件，三个清晰的层次。MCP 服务器只有一个轻薄的壳；所有逻辑都放在一个与 MCP 无关的、可测试的内核当中（这也会为将来提供 CLI 或任意 SDK 而不必动任何东西）。

flowchart LR
    subgraph Clients
      CC[Claude Code / Desktop<br/>stdio]
      WEB[claude.ai<br/>HTTPS + bearer token]
    end
    subgraph QRB["Qdrant RAG Build"]
      T[Transport<br/>stdio · streamable HTTP]
      F[MCP facade<br/>33 tools · validation]
      CORE[RAG core<br/>ingestion · retrieval · wizard]
      EMB[Embeddings<br/>local fastembed · external APIs]
    end
    Q[(Qdrant<br/>local · cloud)]
    CC --> T
    WEB --> T
    T --> F --> CORE
    CORE --> EMB
    CORE --> Q

技术选型

| 领域 | 决策 | 原因 |

GXPID（为什么向导是状态机，而不是 MCP elicitation）。 MCP 客户端对"引导式需求获取（elicitation）"的支持参差不齐，哪怕在 Claude 家族内部、不同 SDK 版本之间也是如此。一个纯粹由普通工具驱动的状态机，可以在所有环境上行为一致，不要求特定客户端配合，也不会在前一个客户端上换个 v2 的新客户端需要通过不同的 elicit 才能兼容 —— 和传输协议无关，所以 v1 就锁死这个方案。

v1 鉴权方案。 完整的 MCP 版 OAuth 2.1（授权服务器、PKCE、Dynamic Client Registration / Client ID Metadata Documents、issuer 校验、refresh token）是标准级别、需要好几周的工作量，v1 时间不充足 —— 而且 claude.ai 自己的连接器面板还把 OAuth 视为高级可选字段，不是必填。**v1 对 HTTP 路径采用"每个 profile 一个静态 bearer token"**的方案：token 由向导生成、存进 profile 的 YAML 文件，请求方式为 Authorization: Bearer <token>。至于 stdio（Code、Desktop）完全不需要鉴权 —— 它们只是本地进进程，不对网络开放网络。完整的 OAuth 2.1 作为 v2 的功能列入文档，等 ChatGPT 进入范围时再重新考虑（它的生态对 OAuth 的依赖更大）。

部署模型：一个人，一个服务器

MCP 并不是抽象地将服务器“连接到 AI”——它连接的是承载模型的客户端应用（Claude Desktop、Claude Code、claude.ai）。客户端才是维持连接存活、把可用工具列表交给模型、拦截模型的工具调用决策并针对服务器执行这些调用的一方。对最终用户来说，这看起来就是“我在和 Claude 对话，而它在管理我的 Qdrant”——这是一个合理的简化——但真正与服务器相连的是客户端，而不是模型。

v1 范围内没有共享/多租户服务器。每个用户运行自己的服务器，同一个本地进程同时服务全部三个 v1 客户端：

• Claude Code / Claude Desktop： 服务器在用户自己的机器上以本地 stdio 子进程形式运行，由客户端根据其配置启动。真实文件系统访问，且限定在允许列表目录内——这是标准 MCP stdio 行为，不需要这个项目额外做任何事情。

• claude.ai： 同一个本地进程，通过隧道（cloudflared）以 HTTPS 方式暴露到外部，或部署在一个运行相同 Docker 镜像的小型常驻主机上（$5 VPS、Fly.io、Railway）——不是独立的云部署，也不是共享服务器。当运行在用户自己的隧道机器上时，文件系统访问与本地场景完全相同，只是到达它的传输方式不同。claude.ai 所有套餐均可用，包括 Free（一个 connector）。

• **结果：**只要用户自己的服务器（如果是 claude.ai，还需要隧道）在运行，ingest_directory / ingest_file 在三个客户端上的行为就完全一致。任何地方都不需要文件上传机制——服务器在结构设计上始终拥有直接磁盘访问权限。

• 一次性安装：

  • **Claude Desktop：**把一个 .mcpb 文件拖入 Settings → Extensions。完全不需要终端。

  • Claude Code：claude mcp add qdrant-rag-build -- uvx qdrant-rag-build-mcp。一行即可。

  • **claude.ai：**Settings → Connectors → Add，粘贴服务器的 HTTPS URL 和 bearer token。需要让服务器（如果使用笔记本电脑方案，还需要隧道）先运行起来——这和任何远程 MCP connector 一样，是协议上的必须要求，不是这个项目自己的选择。

  • 之后，向导会让配置 RAG 变成纯对话式流程——创建 collection、选择 embedding、摄入文档、执行搜索——在三个平台中任何一个上都无需更多技术步骤。

v2：ChatGPT（暂未有意支持）

ChatGPT 需要与 claude.ai 相同类型的远程 HTTP 形态，技术上新东西不多。它被排除在 v1 之外，是 ChatGPT 自身特有的摩擦：Developer Mode 必须显式启用（并提示关于运行第三方代码的警告），而自定义 connectors 均要求 付费套餐（Plus/Pro/Business/Enterprise/Edu）——完全没有 ChatGPT 免费通道，这与 claude.ai 免费层也附带 connectors 不同。这些都不符合“优先支持 Claude”的目标。v2 会加入 ChatGPT 专属 connector 指南，并且如果实际变得重要，会重新评估完整 OAuth 2.1（ChatGPT 的生态比 claude.ai 更倾向使用 OAuth 2.1）。

4. 工具目录

整个项目的核心。六个命名空间、可预测的名称、面向 LLM 写的描述（何时用某个工具，而不只是它能做什么）。每个破坏性工具都要求显式确认，同时还有一个全局 read-only 模式。

Collections

Ingestion

Search

RAG context

Wizard

Admin

5. 对话式向导

我们的差异化所在。服务器上有一个状态机：每次工具调用都会返回下一个问题、可选项以及一条有依据的推荐说明；客户端的 LLM 再把问题以自然语言转达给用户，并将其回答传回服务端。不需要提示语，也不依赖任何特定客户端——对话本身就是交互界面。

stateDiagram-v2
    direction LR
    [*] --> Discover
    Discover --> Validate : setup_answer
    Validate --> Discover : next question
    Validate --> Summary : all answered
    Summary --> Apply : user confirms
    Apply --> SmokeTest
    SmokeTest --> [*] : report + saved profile

问题脚本（固定顺序，每一步都给出推荐）

向导成功的标准。 一个从未接触过 Qdrant 的用户，在不到 10 分钟的对话之后得到以下结果：一个 schema 整洁的 collection，可用的 embeddings，一个已保存的 profile，一条示例文档已完成摄入，以及一次能返回带引用结果的测试搜索。冒烟测试生成的最终报告就是证明——假如把那段对话录下来，就是 README 的封面。

6. 摄入管道

质量的特征是：干净、对 RAG 最优的内容，无论哪种格式，且每次摄入都附带质量报告。绝不只是把解析器吐出的内容“原样倒进去”。

横切规则

• 结构优先，token 其次。 先按文档结构（章节、工作表、幻灯片）切分，只有当一个单元超出 token 预算时，才按 token 进一步细分（并有 overlap）。每个块都携带面包屑（"手册 > 第3章 > 安装"）。

• 基于规范化内容哈希去重，在块级别执行，并结合每个文档的幂等性：重新摄取文件只会更新它，而不会产生重复。

• 最小化的、带版本控制的引用契约。 引用载荷（document、page/section、date、source、date）是一个封闭字段集。内部流水线元数据绝不会进入 LLM 的上下文——这个项目曾两次因为这个问题付出代价：元数据膨胀导致真正的源被截断（§11）。

• 始终报告摄取结果。 已创建的块数、因质量问题被丢弃且写明原因的页面、检测到的重复项。透明本身就是质量的一部分。

• 文本净化（代理字符、控制字符、错误编码）发生在嵌入之前——这是从真实 PST 文件中得到的惨痛教训。

7. Elite retrieval（高级检索）

• 默认混合检索： 稠密向量（multilingual embeddings）+ 稀疏向量（BM25/miniCOIL），通过 Qdrant Query API（prefetch + fusion）原生实现 RRF 融合——不需要额外基础设施。

• 可选重排 使用 cross-encoder 从 top-50 → top-N。可通过 fastembed 纯本机运行，也可以通过 API 运行（Cohere 或 llama.cpp 的 /v1/rerank）。

• MMR 调优多样性， 直接复用 Qdrant 已返回的向量（with_vectors=true）。检索过程中绝不再嵌入（embedding），—此前同样的错误曾在前代项目中引发真实的生产 OOM。

• 一门 DataFrame?

• **支持文本过滤字段：**date —— 完整的日期范围，lte 中包含 end-of-day —— 再加上 source、type、author，都基于 wizard 创建的索引之上。

• get_context 为旗舰工具： 编排 hybrid → rerank → MMR → token 预算 → 带编号的格式化引用块，如 [1][2]。硬保证是：只有真正被包含进 context 的内容才会被引用 —— 绝不出现虚构来源。

• 生成永远在客户端。 服务端从不调用 LLM：它只把最好的 context 提供给用户，用户自己的模型（Claude、GPT）写作回答。这使服务端保持低成本、低消耗，也避免了强制依赖第三方 API key。

8. 质量与评估

• 仓库中的 golden corpus： 15–20 个不同类型的文档（含表格的 PDF、真实电子表格、一个有噪声的网页）以及 ~50 个带注释相关 chunk 的问题。

• CI 中的检索性指标： recall@k、MRR、nDCG（基于 golden corpus），并设置阈值，若有回归会直接使构建失败。Dense 与 Hybrid 与 Hybrid+rerank 的比较会提到文档中——数字本身就是项目的卖点。

• 分层测试： 核心层的单元测试（无 Qdrant 依赖）、基于 testcontainers 在容器中针对 Qdrant 的集成测试，以及使用 SDK 测试客户端对 MCP 协议进行完整 e2e 测试。每个格式还有专门的 torture 文件（扫描 PDF、合并单元格 Excel、垃圾 HTML）。

• 发布时验证兼容性矩阵： Claude Code、Claude Desktop 以及 claude.ai，并在文档中用截图说明。ChatGPT 将在 v2 中加入该矩阵。

9. GitHub 阵地

就作品集而言，仓库就是产品，这和代码本身一样重要。发布清单：

• 一份能转化用户的 README。 用 vhs/asciinema 录一个真实对话中 wizard 完成 RAG 构建的过程，3 行 uvx quickstart、徽章（CI、coverage、PyPI、license）、与官方 MCP 对比表，以及公开的 benchmark 结果。

• 一个着陆页。 一个独立的、打磨过的静态页面，与 README 和文档站区分开来，包含 hero 区、对比官方 mapping MCP 的对比表、wizard 演示录像，以及三大 v1 客户端的安装 CTA，还有 F5 的 benchmark 数据。这就是 launch 帖子和社交分享链接所要指向的位置。

• 文档。 使用 mkdocs-material：每类客户端一份指南（Claude Code、Claude Desktop、claude.ai——并包含 bearer-token connector 的完整流程）、cookbook（"RAG over your own docs"、"team memory"）完全列出全部 33 个工具的参考、公开的 ADR。

• 可持续推动工程。 CI 中包含 ruff + mypy strict + pytest + coverage，自动 semver 版本发布（release-please）、CHANGELOG、issue/PR templates、CONTRIBUTING、Code of Conduct，并启用 GitHub Discussions。

• 分发与启动。 PyPI 包的 .mcpb bundle（用于 Claude Desktop）+ Docker 镜像 + compose stack（含 Qdrant）。已列入官方 MCP registry、Smithery、Glama、PulseMCP 以及 awesome-mcp-servers。启动时发布：一篇技术文章 + Show HN + r/LocalLLaMA + X，并用该 wizard 演示作为引子。

10. 开发阶段

平时项目节奏（晚间/周末）。每个阶段都以可展示的成果结束——绝不会同时有两个阶段并列。

合计：~14.5 周（约 3.5 个月） 在一个合理的业余项目速度上，而且每两周都有可演示的里程碑，保持势头。

11. 已沉淀的经验教训与风险

这个一家独没有说出的优势：它从真实的、处理过 TB 级数据的 enterprise RAG 系统中继承了很多已经"付过学费"的教训。每一条都已经从第一天起写进设计，而不是后来再打补丁。

11. Similarities with inherited 痛苦 (No separate section title)

正在评估的风险

12. 命名、许可与第一步

名称： 名称：Qdrant RAG Build（包名 qdrant-rag-build-mcp）—— 选择这个名字是为了贴近这个仓库自身的工作名称，而不是虚构一个品牌。命名并非两轮更早的过程：Quiver 是因为与那个无关的“Quiver Quantitative” MCP 命名空间冲突而落选（bolshchikov/quiver-mcp、pipeworx-io/mcp-quiver、jsconiers/quiver-quant-mcp）；Vectorsmith 经过验证是干净可用的，但它被一个明确的偏好所取代：那就是要让名字在仓库上具备辨识度。这意味着要接受当初计划已经指出的权衡——一个带“qdrant”前缀的名字可能会被误认为 Qdrant 官方项目——而缓解方法就是在 README 的标语和文档站点中直白地写清楚“非官方、社区构建”。字面量 qdrant-rag-mcp 已经是一个活跃的、不相关的项目（ancoleman/qdrant-rag-mcp），因此有意回避了它；qdrant-rag-build / qdrant-mcp-rag-build 已经在 PyPI 和 GitHub 上确认无冲突（2026 年 8 月）。

许可协议： Apache-2.0 — 与 Qdrant 相同，带有专利授权，并且是那些会看你个人简介的企业会期望看到的许可证。

第一个具体步骤： F0 会在服务器代码第一行之前，就先为全部 33 个工具编写 JSON schemas。§4 中的目录就是规格；先冻结它可以避免中途重新设计，并从第一周就开始产生一份可发布的文档。

参考资料： qdrant/mcp-server-qdrant（官方服务器，2 个工具） · fastembed PR #602（bge-m3 支持，开放中） · MCP Bundles (.mcpb) toolkit · 使用远程 MCP 的自定义连接器（claude.ai） · v2 阅读： ChatGPT Developer Mode， MCP 与 OpenAI 中的连接器

计划 v1.3 · 锁定于 2026-08-24 · v1 覆盖完整的 Claude 家族（Code、Desktop、claude.ai — stdio + bearer-token HTTP)；ChatGPT 则因人阻碍，明确延后至 v2 的发布会受到自身 Developer-Mode/付费计划的阻碍，而不是与 claude.ai 共享的技术制约。撰写时参考了 IA_EmailsContext 企业 RAG 项目所得到的经验教训。