模型上下文协议（MCP）服务器

一个生产级别的模型上下文协议（MCP）服务器，它将最先进的MCP客户端（Claude桌面/代码/Codex CLI）纳入检索和摄取循环中。代理使用原子MCP工具进行规划——决定提取器、分块器、重排序器路径、HyDE重试、图跳转和元数据预算调用——而服务器保证确定性、来源和薄索引安全性。一切都在本地开源组件上运行，因此嵌入和重排序在您的Claude订阅之外是零成本的。

🌟 功能

• 零成本嵌入与重排序：由Ollama驱动的嵌入和本地TEI交叉编码器使每个文档和查询都免除了按令牌收费。
• 结构感知摄取：Docling通过单次调用处理整个PDF，性能提高约60-65%，提取表格、图形、标题及其边界框、部分面包屑和元素ID。全文档处理消除了每页开销，同时保留了所有语义结构。
• 代理导向混合检索：自动模式选择密集、混合、稀疏和重排序路径；当得分低时，返回拒绝，以便MCP客户端可以决定是否运行HyDE或尝试其他查询。每个基本操作都暴露出来以供手动覆盖。
• 多集合支持（手动）：通过向NOMIC_KB_SCOPES添加条目来组织文档到不同的知识库中；默认配置附带一个集合（daf_kb）。
• 增量及确定性摄取：智能更新检测仅重新处理更改的文档。确定性的分块ID允许基于upsert的自动更新，无需手动清理。
• 图与实体（轻量级）：摄取提取设备/化学/参数实体，并将其链接回分块，以便代理可以通过kb.entities/kb.linkouts进行切换。（完整的语义关系提取仍在路线图中）。
• 操作工具：scripts/manage_cache.py和scripts/manage_collections.sh帮助清除缓存或管理Qdrant集合；GPU调节器（DOCLING_DEVICE，DOCLING_BATCH_SIZE）保持重型PDF流动。
• 金丝雀质量保证框架：ingest.assess_quality可以运行用户提供的金丝雀查询（config/canaries/），并在文档到达生产之前报告警告。
• 丰富的来源跟踪：每个分块携带plan_hash，model_version，prompt_sha和client_decisions以实现全面审计。搜索结果包括page_numbers，section_path，element_ids，table_headers，table_units和bboxes以实现精确引用和源验证。所有元数据在Qdrant矢量负载和全文搜索数据库中均得到保存。
• MCP控制的upsert：ingest.upsert，ingest.upsert_batch和ingest.corpus_upsert让代理可以直接将分块工件推送到Qdrant + FTS，而不离开MCP工作流。
• 客户端编排摘要与HyDE：LLM客户端通过ingest.generate_summary贡献章节摘要，并在重新查询kb.dense之前本地生成上下文感知的HyDE假设，每次决策都会记录在计划来源中。
• 可观测性和护栏：搜索日志包括散列主题ID、阶段级计时和顶级命中；eval.py运行黄金集，具有召回率/nDCG/延迟阈值，用于CI门控。
• MCP集成：无缝与Claude桌面、Claude代码、Codex CLI以及任何符合MCP规范的客户端集成。
• 代理剧本：准备运行的“检索→评估→精炼”工作流程已记录在CLAUDE.md和.codex/AGENTS.md中。

实验/可选功能如SPLADE稀疏扩展、ColBERT晚期交互、自动摘要/大纲、HyDE查询扩展和强制金丝雀质量保证需要额外的服务或配置。详情见下表的状态。

特性状态一览

功能	状态	备注
核心密集/混合/稀疏检索	✅ 工作中	kb.search，kb.dense，kb.hybrid，kb.sparse，kb.batch
实体提取+图链接	✅ 工作中	kb.entities，kb.linkouts，kb.graph（实体→分块关系）
表格检索	✅ 工作中（数据依赖）	需要在摄取期间提取表格
金丝雀质量保证	⚠️ 需要用户配置	默认config/canaries/*.json是占位符；添加查询以强制门控
文档摘要/大纲	⚠️ 客户端提供	ingest.generate_summary存储带有来源的语义摘要；大纲仍需构建标题索引
HyDE重试	⚠️ 客户端生成	没有服务器工具；在您的MCP客户端中起草假设，然后使用它重新查询kb.dense/kb.search
MCP upsert管道	✅ 工作中	ingest.upsert，ingest.upsert_batch，ingest.corpus_upsert
SPLADE稀疏扩展	💤 计划中	存在--sparse-expander挂钩，但默认不捆绑SPLADE模型
ColBERT晚期交互	💤 计划中	需要外部ColBERT服务；当COLBERT_URL未设置时禁用

✅今天可用 · ⚠️需要额外配置或构建步骤 · 💤计划中/尚未实现

🤖 MCP优先架构

传统的RAG系统隐藏检索在单一API后面。此服务器将MCP客户端作为规划者：

• 摄取作为工具链 – ingest.extract_with_strategy使用Docling一次性处理整个PDF（无每页路由）；ingest.chunk_with_guidance在枚举的分块器之间切换（heading_based，procedure_block，table_row）；ingest.generate_metadata强制字节预算和提示哈希。每一步都返回工件和计划哈希，以实现可重放的摄取。
• 检索作为可组合的基本操作 – kb.sparse，kb.dense，kb.hybrid，kb.rerank，kb.hint，kb.table_lookup，kb.entities，kb.linkouts，kb.batch，kb.quality和kb.promote/demote。使用这些与客户端编写的HyDE重试和规划器启发式方法，在对话中途分支、重试或融合策略。
• 自我批判与洞察 – 结果展示完整的评分向量（bm25，dense，rrf，rerank，prior，decay）和why注释（匹配别名、标题、表格线索），让代理在呈现答案前推理信心。

由于Claude（或其他任何MCP客户端）处于驾驶席，您会获得代理检索和确定性摄取，而不会放弃来源或安全性。

🏗️ 架构

┌──────────────────────────────┐
│  MCP客户端                  │
│  Claude桌面/代码/CLI        │
└────────────┬─────────────────┘
             │ MCP协议（标准输入输出）
         ↓
┌────────────────────────────────────────┐
│         server.py (FastMCP)            │
│  ┌──────────────────────────────────┐  │
│  │  搜索模式：                       │  │
│  │  • 语义（仅向量）               │  │
│  │  • 重排序（向量+重排序器）       │  │
│  │  • 混合（RRF+重排序）            │  │
│  └──────────────────────────────────┘  │
└─────┬──────────────┬────────────┬──────┘
      │              │            │
      ↓              ↓            ↓
┌──────────┐  ┌──────────┐  ┌────────────┐
│  Qdrant  │  │ SQLite   │  │  Ollama    │
│  向量    │  │  FTS5    │  │ 嵌入        │
│   数据库 │  │  （BM25） │  └────────────┘
└──────────┘  └──────────┘
      │
      ↓
┌──────────────┐
│ TEI重排序器  │
│ (Hugging     │
│  Face)       │
└──────────────┘

处理流水线：

文档 → 提取（Docling全文档） → 分块 → 图与摘要 → 嵌入 → [Qdrant + SQLite FTS] → 规划器 → 检索 → 重排序 → 自我批判 → 结果

📋 使用案例

• 工程文档：搜索技术手册、规格和手册（例如，水处理工程、化工工程）
• 法律研究：查询判例法、合同和监管文件
• 医学文献：搜索研究论文、临床指南和医学教科书
• 学术研究：建立可搜索的论文和书籍库
• 企业知识库：使内部文档和报告可搜索
• 个人研究：整理并查询您的个人文档集合

🚀 快速开始

先决条件

• Docker Desktop（用于Qdrant + TEI重排序器）
• Ollama（用于嵌入）
• Python 3.9+
• 可选但推荐：设置HF_HOME为可写文件夹（例如，export HF_HOME="$PWD/.cache/hf"）以便Docling可以在分诊路由页面到结构化提取时缓存布局模型。

安装

1. 克隆仓库：

git clone https://github.com/yourusername/knowledge-base-mcp.git
cd knowledge-base-mcp

2. 安装Ollama（如果尚未安装）：

   • 访问ollama.com并下载适用于您平台的版本
   • 拉取嵌入模型：

   ollama pull snowflake-arctic-embed:xs
   

3. 启动Docker服务（Qdrant + TEI重排序器）：

docker-compose up -d

4. 设置Python环境：

python -m venv .venv
source .venv/bin/activate  # 在Windows上：.venv\Scripts\activate
pip install -r requirements.txt

5. 配置您的MCP客户端：

选择适合您的MCP客户端的配置：

对于Claude代码：

cp .mcp.json.example .mcp.json
# 编辑.mcp.json并更新Python虚拟环境路径

对于Claude桌面：

• 将claude_desktop_config.json.example的内容复制到：
  • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows：%APPDATA%\Claude\claude_desktop_config.json
• 更新路径以匹配您的系统（在Windows上使用wsl命令）

对于Codex CLI：

• 使用.codex/config.toml.example作为模板

6. 摄取您的第一个文档：

.venv/bin/python3 ingest.py \
  --root /path/to/your/documents \
  --qdrant-collection my_docs \
  --max-chars 700 \
  --batch-size 128 \
  --parallel 1 \
  --ollama-threads 4 \
  --fts-db data/my_docs_fts.db \
  --fts-rebuild

7. 测试搜索：

python validate_search.py \
  --query "您的搜索查询" \
  --collection my_docs \
  --mode hybrid

8. 可选地运行评估框架（如果错过阈值则CI失败）：

python eval.py \
  --gold eval/gold_sets/my_docs.jsonl \
  --mode auto \
  --fts-db data/my_docs_fts.db \
  --min-ndcg 0.85 --min-recall 0.80 --max-latency 3000

9. 可选：将金丝雀质量保证查询添加到config/canaries/，以便ingest.assess_quality可以强制通过/失败门控，而不仅仅是报告警告。

详见INSTALLATION.md中的详细设置说明。

🔍 搜索模式

语义搜索（mode="semantic"）

使用密集嵌入的纯向量相似度搜索。

最佳用途：概念查询，即使没有确切关键词匹配也能找到相关内容

示例："生物系统如何去除氮？"即使使用诸如"硝化"或"反硝化"这样的术语也能找到相关内容

重排序搜索（mode="rerank"，默认）

向量检索后跟随交叉编码器重排序。

最佳用途：大多数用例——速度和准确性之间的良好平衡

示例：标准搜索，希望比纯向量搜索有更好的精度

混合搜索（mode="hybrid"）

结合向量搜索+BM25词法搜索使用RRF，然后重排序。

最佳用途：复杂查询，既有概念又有具体关键词需求

示例："不锈钢316L在氯化物环境中的腐蚀"既受益于语义理解又需要精确术语匹配

稀疏搜索（mode="sparse"）

仅运行意识别名的BM25，适用于短关键词查询或作为语义路径未能匹配精确术语时的备用选项。

自动规划器（mode="auto"）

默认。启发式选择语义、混合、重排序和稀疏路径。当最高得分低于ANSWERABILITY_THRESHOLD时，服务器拒绝并返回遥测数据，以便MCP客户端（Claude等）可以决定是否生成HyDE假设并使用kb.dense或kb.sparse重试。

额外的MCP工具

• kb.collections – 列出配置的集合别名及其支持的索引。
• kb.open(collection="slug", chunk_id=...) – 通过chunk_id或element_id获取分块，可选地通过字符偏移量切片。
• kb.neighbors(collection="slug", chunk_id=...) – 拉取分块周围的FTS邻居以获得更多上下文。
• kb.summary(collection="slug", topic=...) – 检索摄取过程中构建的轻量级章节摘要（类似RAPTOR风格）。
• kb.graph(node_id=...) – 检查从结构化元数据生成的轻量级图（文档→部分→分块→实体）。

📊 搜索参数

参数	默认值	描述
query	—	搜索查询文本
mode	rerank	semantic，rerank，hybrid，sparse或auto
top_k	8	最终返回的结果数（1–100）
retrieve_k	24	初始候选池（1–256）
return_k	8	重排序后返回的结果数（≤ retrieve_k）
n（针对kb.neighbors）	10（建议）	上下文扩展的邻域半径 - 综合答案的必要参数

参数调整指南

场景	retrieve_k	return_k	top_k	mode
快速搜索	12	8	5	rerank
综合	48	16	10	hybrid
高精度	24	12	5	hybrid
探索性	32	12	8	semantic

配置旋钮

通过环境变量（或可用的CLI标志）设置：

环境变量	目的
MIX_W_BM25，MIX_W_DENSE，MIX_W_RERANK	调整词法、密集和重排序信号之间的混合比例。
DOCLING_TIMEOUT	等待Docling完成文档处理的时间（默认300秒）。
HF_HOME	Docling模型使用的Hugging Face缓存目录（默认.cache/hf）。
GRAPH_DB_PATH，SUMMARY_DB_PATH	覆盖轻量级图和摘要存储位置。
ANSWERABILITY_THRESHOLD	自动模式响应所需的最低分数；较低分数返回拒绝，由客户端处理（例如，运行HyDE或重新表述）。
上下文检索	关键：搜索后始终使用kb.neighbors(n=10) - 单个分块在分块大小为700时是不够的。

📚 使用

详见USAGE.md中的全面文档，包括：

• 摄取参数和示例
• 多集合设置
• 高级搜索功能（邻域扩展、时间衰减）
• 增量摄取模式
• 性能调整

有关即将改进的信息，请查看ROADMAP.md。

📘 进一步阅读

• CLAUDE.md – 适用于Claude桌面/代码的MCP代理提示，包括摄取和检索工作流程。
• .codex/AGENTS.md – 适用于Codex CLI的MCP代理提示。
• ARCHITECTURE.md – 对RRF、重排序和分块设计选择的深入探讨。
• ROADMAP.md –