Modular RAG MCP Server

面向 DIY 留学服务团队内部顾问的留学申请知识检索与可观测 RAG 基础设施

Modular RAG MCP Server 是一个本地优先、可插拔、可观测的检索增强生成（RAG）服务。系统通过 Model Context Protocol（MCP）向 AI 客户端提供知识检索能力，并通过 Streamlit Dashboard 管理文档、摄取任务、查询链路与评估结果。

本项目源于大学期间的实际协作场景：学院内的 DIY 留学服务团队为同学提供海外高校申请协助，本系统用于解决顾问在院校要求、申请材料、流程规范和历史经验之间反复查找、难以追溯来源的问题。目前系统已完成团队内部部署；公开仓库仅提供匿名合成样例，不包含真实学生资料、内部文档或运行数据。

仓库中的示例资料均应使用匿名合成数据；系统输出是供顾问核验的检索依据，不替代顾问判断，也不构成院校、签证或法律建议。

目录

• 业务背景

• 系统边界

• 核心能力

• 系统架构

• 数据与存储一致性

• MCP Tools

• Dashboard

• 快速开始

• 质量保障

• 安全与运营约束

• 当前状态与演进计划

Related MCP server: mcp-rag-assistant

业务背景

DIY 留学顾问在处理申请时，需要同时查阅学校官网说明、项目手册、材料模板、内部操作清单和历史案例。原始资料通常以 PDF 形式分散保存，且存在以下问题：

• 同一要求可能以不同措辞出现在多份资料中，纯关键词搜索容易漏召回。

• 院校、专业、学位和入学季等专有名词需要精确匹配，单纯向量检索容易误召回。

• PDF 中的表格、流程图和截图包含重要信息，纯文本解析会丢失上下文。

• 顾问需要知道答案来自哪一份资料、哪一个片段，并判断资料是否仍然有效。

• 文档更新后，向量库、BM25 索引、图片索引和摄取记录必须保持一致。

• 检索效果需要通过稳定测试集回归，而不是依赖主观体验。

系统服务对象是团队内部顾问。典型工作流包括：

1. 将院校项目资料、内部清单和匿名案例摄取到指定 Collection。

2. 通过 MCP Client 或命令行提交自然语言问题。

3. 系统执行 Dense + BM25 双路召回、RRF 融合和可选 Rerank。

4. 返回带来源引用的文本片段，并在命中图片时返回多模态内容块。

5. 通过 Dashboard 检查摄取过程、召回结果、耗时和评估指标。

系统边界

本项目负责知识摄取、检索、引用、评估与链路观察，不负责：

• 代替顾问作出选校、录取概率或签证结论。

• 自动提交申请、发送邮件或修改学生材料。

• 提供学生端账户、CRM、支付或申请进度管理。

• 自动抓取并宣称掌握最新院校政策。

• 在缺少来源支撑时生成确定性业务结论。

核心能力

系统架构

flowchart LR
    A["PDF 业务资料"] --> B["Ingestion Pipeline"]
    B --> C["Chroma 向量库"]
    B --> D["BM25 索引"]
    B --> E["SQLite 摄取历史"]
    B --> F["图片文件与索引"]
    G["顾问 / MCP Client"] --> H["MCP Server"]
    H --> I["Query Processor"]
    I --> J["Dense Retrieval"]
    I --> K["Sparse Retrieval"]
    J --> L["RRF Fusion"]
    K --> L
    L --> M["Optional Rerank"]
    M --> N["Response + Citations + Images"]
    B --> O["Ingestion Trace"]
    I --> P["Query Trace"]
    O --> Q["Streamlit Dashboard"]
    P --> Q

核心目录：

src/
├── core/            # 数据契约、查询编排、响应构建、Trace、配置
├── ingestion/       # Chunk、Transform、Embedding、Storage 与 Pipeline
├── libs/            # LLM/Embedding/Loader/Reranker/Splitter/VectorStore 抽象
├── mcp_server/      # MCP 协议处理、Server 与 Tools
└── observability/   # Dashboard、评估与结构化日志

scripts/             # ingest、query、evaluate、Dashboard 启动入口
config/              # Provider、检索、重排、评估与摄取配置
tests/               # Unit、Integration、E2E 测试与固定样例

详细的接口、数据流和模块约束见 DEV_SPEC.md。

数据与存储一致性

一次摄取会协调多个存储后端：

文件完整性检查使用 SHA256 跳过已成功处理且未变化的文件。Chunk ID 由来源、位置与内容稳定生成，重复摄取采用幂等 Upsert。DocumentManager 负责跨 Chroma、BM25、摄取历史和图片索引进行协调删除，并返回部分失败信息。

MCP Tools

当前 Server 暴露四个 Tools。前三个通用 Tool 原样保留，第四个是留学业务适配层：

MCP 使用 Stdio Transport。stdout 专用于 JSON-RPC，运行日志写入 stderr，避免破坏协议帧。

search_admissions_knowledge 默认查询 admissions_knowledge，且始终限定 business_domain=study_abroad_admissions。它支持按国家、院校、项目、学位层级、入学季、申请轮次和来源类型精确筛选；默认排除 valid_until 早于查询业务日期的资料。缺少或无法解析有效期的资料会标记为 needs_review，不会被静默视作现行规则。业务 Tool 只是参数与响应适配层，底层仍执行 Dense + BM25、RRF、Cross-Encoder/LLM Rerank、引用和多模态返回。

Dashboard

Dashboard 保持六页面结构：

1. Overview：组件配置、数据资产、运行状态，以及留学资料的现行、待复核和过期统计。

2. Data Browser：文档、Chunk、Metadata 和关联图片；支持国家、院校、项目、学位、入学季、申请轮次、来源类型和时效状态组合筛选。

3. Ingestion Manager：触发摄取、查看进度并协调删除文档。

4. Ingestion Traces：摄取阶段、处理方法、耗时和异常。

5. Query Traces：Dense/Sparse 召回、融合、重排与最终结果。

6. Evaluation Panel：执行评估并查看指标与历史结果。

快速开始

1. 环境准备

要求 Python 3.10–3.12。

git clone https://github.com/xiaoxinbuxingyeyuan/MODULAR-RAG-MCP-SERVER.git
cd MODULAR-RAG-MCP-SERVER
python -m venv .venv

Windows PowerShell：

.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

macOS / Linux：

source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

pyproject.toml 已固定本项目当前验证使用的直接依赖版本。升级 MCP、Ragas、LangChain 或存储组件时，应单独升级并重新执行离线与在线回归。

2. 配置 Provider

编辑 config/settings.yaml，配置 LLM、Embedding、Vision LLM、VectorStore、Reranker 与评估后端。API Key 应通过安全配置注入，不应提交到仓库。

本地无模型服务时，可关闭非必要的 LLM 增强与 Rerank，用于验证不依赖外部服务的基础链路。

3. 摄取文档

python scripts/ingest.py \
  --path tests/fixtures/sample_documents/simple.pdf \
  --collection admissions_knowledge

目录摄取：

python scripts/ingest.py \
  --path tests/fixtures/sample_documents/ \
  --collection admissions_knowledge

使用留学业务 Manifest 摄取：

python scripts/ingest.py \
  --path examples/documents/synthetic/ \
  --collection admissions_knowledge \
  --manifest examples/admissions_manifest.example.jsonl

Manifest 使用 UTF-8 JSONL，每行对应一份 PDF。相对 document_path 以 Manifest 所在目录为基准解析；必填字段为 document_path、title、country 和 source_type。可选字段包括 institution、program、degree_level、intake、application_round、published_at、valid_until、language、tags 与 access_scope。完整示例见 examples/admissions_manifest.example.jsonl。

传入 Manifest 后，每份待摄取 PDF 都必须有唯一匹配项。未知字段、重复路径、非法枚举和日期倒置会在写入存储前失败。Manifest 元数据会由 Document 传播到 Chunk 与 Chroma 记录；Chunk 级 LLM 标题和标签不会覆盖 document_title 与 business_tags。

增量判断同时比较 PDF SHA256 与规范化业务元数据 SHA256：两者都未变化才跳过；只修改 Manifest 会自动重新摄取并覆盖稳定 Chunk ID 对应的元数据。PDF 内容变化时，系统先写入新版本，再按旧 doc_hash 清理 Chroma Chunk、图片和旧摄取记录；BM25 按稳定来源路径前缀替换 postings。旧版 SQLite 摄取历史会自动增加 metadata_hash 字段，无需手工迁移。--force 仍可用于显式重建，但不再是应用 Manifest 更新的必要条件。

仓库提供三份完全虚构、无个人信息的业务样例，分别覆盖现行资料、有效期缺失和已过期资料，其中课程指南包含一张用于多模态链路验证的流程图。需要重新生成样例 PDF 时运行：

python examples/generate_synthetic_admissions_pdfs.py

4. 命令行查询

python scripts/query.py \
  --query "申请材料需要包含哪些证明？" \
  --collection admissions_knowledge \
  --verbose

5. 启动 Dashboard

python scripts/start_dashboard.py

默认地址为 http://localhost:8501。

6. 启动 MCP Server

python -m src.mcp_server.server

不同 MCP Client 的配置格式略有差异，核心进程配置如下：

{
  "command": "<project>/.venv/Scripts/python.exe",
  "args": ["-m", "src.mcp_server.server"],
  "cwd": "<project>"
}

macOS / Linux 将 Python 路径替换为 <project>/.venv/bin/python。

7. 执行评估

python scripts/evaluate.py \
  --test-set examples/admissions_golden_test_set.json \
  --collection admissions_knowledge

无外部检索环境时可运行：

python scripts/evaluate.py --no-search

质量保障

项目采用三层测试结构：

• Unit：数据契约、算法、Factory、Tool Handler 与存储适配器。

• Integration：摄取、混合检索、MCP、Provider 和 Trace 组合行为。

• E2E：CLI 摄取、MCP Client、Dashboard smoke 与 Recall 回归。

python -m pytest tests/unit
python -m pytest tests/integration
python -m pytest tests/e2e
python -m pytest

以上命令默认跳过所有标记为 online 的用例，不会主动调用真实 Provider。需要真实 Azure、OpenAI 或 Ollama 服务时，在对应凭据和服务可用的环境中显式运行：

python -m pytest --run-online -m online

OpenAI 兼容网关可通过 OPENAI_API_KEY、OPENAI_BASE_URL 和 OPENAI_MODEL 注入，不需要修改仓库配置或提交凭据。未配置的 Provider 用例应保持跳过状态。

只检查在线用例是否正确归类、但不发起调用时，可运行 python -m pytest --collect-only -m online。离线与在线结果应分开记录；--run-online 只解除跳过限制，不会替代 Provider 配置。

评估层继续支持 Custom Evaluator 与 Ragas。业务 Golden Test Set 额外记录组合筛选、业务日期、过期策略、期望来源和参考答案；离线业务验收同时检查这些字段与 MCP 业务适配器的时效行为。通用评估接口和原有 Golden Test Set 均未修改。

安全与运营约束

• 默认采用本地 Stdio 和本地存储，不开放网络端口。

• 不在日志、Trace、测试固定数据或 Git 历史中保存 API Key 与学生个人信息。

• 业务资料进入知识库前应完成授权确认和隐私脱敏。

• 检索结果必须保留来源引用，无法找到可靠依据时应返回空结果或提示人工核验。

• 院校要求具有时效性；业务 Tool 默认排除已过 valid_until 的资料，并显式提示有效期缺失项，但顾问仍必须核对官方来源。

• 当前架构是单用户本地服务，不提供身份认证、权限隔离或多租户保证。

当前状态与演进计划

现有 main 已具备完整的通用 RAG、MCP、Dashboard、Trace 和评估骨架。留学领域改造按增量方式推进，不能删除或简化现有技术能力。

任何阶段的实现都必须保留 PDF 全链路摄取、Dense + BM25、RRF、Rerank、多模态、多存储协同、增量与删除、原有三个 MCP Tools、六页面 Dashboard、双链路 Trace、Custom + Ragas、三层测试及全部可插拔接口。