MCP Knowledge Service

可复用的 MCP 知识检索服务

这是一个独立的 MCP Server，通过 stdio / JSON-RPC 向 Agent 或业务应用提供知识检索 tools。服务将向量检索（Dense Retrieval）与 BM25 关键词检索结合，再使用倒数排名融合（Reciprocal Rank Fusion, RRF）统一排序，并返回可追溯的来源引用（Citations）。

当前仓库以 salon 作为示例集成，但核心服务通过 collection 选择知识集合，不写死为理发店场景。当前 CLI 直接摄取 PDF；示例中的 Markdown 用作可维护知识源，生成 PDF 后进入 ingestion pipeline。

Related MCP server: mcp-rag-assistant

项目简介

MCP Knowledge Service 将文档导入、索引构建和在线查询封装成独立进程。Consumer Application 通过官方 MCP Client 执行 initialize、tools/list 和 tool call，无需在业务仓库中维护第二套检索实现。

服务负责返回检索上下文和 Citations，不负责上层业务的价格、库存、排班、交易或预约裁决，也不将检索结果包装成完整的业务 LLM 决策。

设计目标

• 使用模型上下文协议（MCP）解耦 Agent 与知识检索服务。

• 使用命名 collection 隔离不同领域的索引与查询范围。

• 组合 Dense Retrieval 与 BM25，兼顾语义召回和关键词匹配。

• 使用 RRF 融合异构排名，不依赖原始分数尺度一致。

• 通过 Citations 保留 source、文档和 chunk 等来源信息。

• 将协议输出与运行日志分离：stdout 仅承载 MCP 消息，日志写入 stderr。

核心能力

系统架构

• Ingestion：Markdown 可作为维护源；当前实际输入为 PDF，导入后生成 collection 对应的 ChromaDB vectors 与 BM25 documents。

• MCP Serving：Consumer Application 使用 MCP Client 通过 stdio 调用 MCP Server 暴露的 tools。

• Query：query_knowledge_hub 执行 Dense Retrieval、BM25 和 RRF，返回检索结果与 Citations。

数据导入流程

PDF
  -> SHA256 完整性检查
  -> PdfLoader（解析与标准化）
  -> DocumentChunker（Chunking）
  -> Dense Encoding + Sparse Encoding
  -> ChromaDB Vector Store + BM25 Index
  -> Named Collection

examples/salon/knowledge_sources/ 中保留 Markdown 维护源，examples/salon/generated_pdfs/ 是当前真实 ingestion 输入。CLI 目前不会直接发现 .md 文件。

查询与混合检索流程

MCP Client
  -> stdio JSON-RPC
  -> query_knowledge_hub
  -> Query Processing
  -> Dense Retrieval + BM25
  -> RRF
  -> Retrieved Context + Citations

检索服务返回排序后的上下文和来源信息。是否进一步调用 LLM、如何组织最终回答、是否允许检索结果影响业务流程，由 Consumer Application 自己决定。

MCP Tools

query_knowledge_hub 调用示例：

{
  "query": "What is this collection about?",
  "top_k": 4,
  "collection": "knowledge_hub"
}

Collection 设计

collection 是命名知识集合，也是检索和运行时索引的选择边界，例如：

• knowledge_hub：默认通用 collection；

• salon_knowledge：examples/salon/ 显式使用的示例 collection；

• Consumer Application 可以传入自己的 collection 名称。

这里的 collection isolation 是索引和查询范围隔离，不代表已经实现认证、授权、租户安全或 production multi-tenancy。

技术栈

• Python 3.11

• Official MCP Python SDK

• ChromaDB

• BM25、jieba、RRF

• OpenAI-compatible Embedding Provider（示例配置支持 Qwen）

• MarkItDown PDF loader

• pytest

项目结构

mcp-knowledge-service/
├── src/
│   ├── core/               # Query、RRF、response 与 trace
│   ├── ingestion/          # Chunking、encoding 与索引写入
│   ├── libs/               # Loader、Embedding、Vector Store 抽象
│   ├── mcp_server/         # stdio MCP Server 与三个 tools
│   └── observability/      # stderr logger
├── scripts/                # ingest、query、evaluate
├── tests/                  # unit、integration、e2e
├── examples/salon/         # salon 示例知识源与 PDF
├── config/settings.example.yaml
├── docs/
├── architecture.svg
└── pyproject.toml

快速开始

python3.11 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
cp .env.example .env
cp config/settings.example.yaml config/settings.yaml

真实执行 Embedding 或 Provider 驱动的 ingestion 前，在本地 .env 或 shell 环境中配置私有 Key；不要提交 .env 或 config/settings.yaml。

MCP Server 入口：

python -m src.mcp_server.server

该命令启动 stdio JSON-RPC Server，不是交互式 CLI。正常集成时由 MCP Client 作为独立子进程拉起；单独验证需要 MCP Client 或验证脚本发送 initialize、tools/list 和 tool call。stdout 只用于 MCP 协议消息，日志写入 stderr。

配置说明

主要本地配置位于 .env 与 config/settings.yaml：

Ingestion 示例

导入指定 PDF 或目录：

python scripts/ingest.py \
  --path <PDF_OR_DIRECTORY> \
  --collection knowledge_hub \
  --force

只检查待处理文件，不写入 runtime data：

python scripts/ingest.py \
  --path <PDF_OR_DIRECTORY> \
  --collection knowledge_hub \
  --dry-run

Salon 示例显式使用 salon_knowledge：

python scripts/ingest.py \
  --path examples/salon/generated_pdfs \
  --collection salon_knowledge \
  --force

MCP Client 接入示例

import os

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

params = StdioServerParameters(
    command="<PATH_TO_SERVICE>/.venv/bin/python",
    args=["-m", "src.mcp_server.server"],
    cwd="<PATH_TO_SERVICE>",
    env=dict(os.environ),
)

async with stdio_client(params) as (read_stream, write_stream):
    async with ClientSession(read_stream, write_stream) as session:
        await session.initialize()
        tools = await session.list_tools()
        result = await session.call_tool(
            "query_knowledge_hub",
            {
                "query": "What does the policy say?",
                "top_k": 4,
                "collection": "knowledge_hub",
            },
        )

调用方应检查 CallToolResult.isError，解析文本与 References，并保留 Citations。

测试与历史评估结果

静态依赖与本地测试命令：

.venv/bin/python -m pip check
.venv/bin/python -m pytest

真实 MCP 集成验证需要本地 Provider、已导入的 runtime data 和 MCP Client，流程为：

initialize -> tools/list -> query_knowledge_hub

已保存的历史 ingestion 说明记录了 salon 示例的 7 个 PDF、24 个 chunks、24 个 vectors 和 24 个 BM25 documents；本次 README 修改未重新执行 ingestion。该结果只说明示例数据链路和索引规模，不是通用检索质量 benchmark。

本仓库现有 8 条带来源 Ground Truth 的 salon 独立检索集。2026-07-24 的真实 Provider 验证结果为 Source Hit@1 7/8、Hit@3 8/8、MRR 0.9375、Citation expected-source match 8/8。这是小型受控语料的回归结果，不是生产准确率或通用 Benchmark。数据集、去敏验证快照、分母语义和复现方式见 检索评估。

tests/fixtures/golden_test_set.json 仅是无 Ground Truth 的 sample/template；其样本状态为 not_evaluated，不会被记为零分或进入 Hit@K / MRR 分母。

故障边界

• MCP 进程未启动、stdio 中断或 tool call 失败：Consumer Application 应将知识检索视为不可用，不应伪造检索结果。

• collection 不存在或尚未 ingestion：query_knowledge_hub 返回空结果或带 isError 的错误内容，调用方必须显式处理。

• Embedding Provider 配置缺失：需要向量编码的 ingestion 或 Dense Retrieval 无法正常初始化；不会自动获得真实 embedding。

• ChromaDB 或 BM25 runtime index 不可用：检索结果可能为空或 tool 返回错误，runtime data 需要在本地重建。

• 普通日志写入 stdout 会污染 MCP JSON-RPC；服务入口将日志导向 stderr。

• 本服务不负责预约、价格、排班、库存或交易成功等业务裁决。

项目边界与已知限制

• 当前 CLI 直接支持 PDF ingestion；Markdown 是示例中的可维护源文件，不声明直接 .md ingestion。

• runtime ChromaDB、BM25、SQLite、日志和 trace 不提交 Git，使用者需要本地导入。

• 当前公开范围不声明 Rerank、Ragas、Graph RAG、Memory、multimodal、Vision、认证授权、production multi-tenancy、自动扩缩容或生产部署。

• collection 提供命名隔离，不等同于安全租户隔离。

• 历史 ingestion 数量来自仓库已有记录，不能解释为本次现场验证或生产性能指标。

示例集成

• AI Hair Salon Agent：参考 Consumer Application，通过 MCP Client 调用 salon_knowledge。

• examples/salon/：示例知识源、生成 PDF 和 ingestion 说明；不是根服务默认领域。

相关文档

• 系统架构（Architecture）

• 文档导入（Ingestion）

• MCP Client 接入（Integration）

• 检索评估（Evaluation）

• 项目证据索引（Project Evidence）

• 规划路线（Roadmap）

安全说明

不要提交 .env、API Key、config/settings.yaml、ChromaDB、BM25 index、SQLite runtime data、日志、trace 或本地报告。当前公开项目不声明认证、授权、租户安全或生产级安全控制。