PaperRAG MCP Server — 个人科研论文知识库（Personal Research Paper Knowledge Base）

基于可插拔 Modular RAG 架构打造的私人论文数据库：摄取 PDF 论文 → 混合检索（Hybrid Search + Rerank）→ MCP 协议暴露给 AI 助手，附带 Dashboard 可视化管理和自动化评估体系。

📖 目录

• 项目概述

• 快速开始

• 测试体系与评估基线

• 常见问题

Related MCP server: Personal Research Assistant MCP

🏗️ 项目概述

这个项目是什么

一个服务于个人论文阅读与管理的 RAG 系统：把下载的学术论文（PDF）摄入知识库，通过 BM25 稀疏检索 + 稠密向量检索（RRF 融合）+ Cross-Encoder 精排 找到最相关的段落，并作为 MCP Server 供 Claude Code / Cursor / Copilot 等 AI 助手直接调用——"问 AI 论文里的问题"。

当前知识库已摄入 17 篇目标检测/图神经网络方向论文（约 1670 个 chunk），并配套 64 题黄金测试集（tests/fixtures/paper_test_set.json）进行质量回归。

核心能力一览

技术亮点

🔌 全链路可插拔架构：LLM / Embedding / Reranker / Splitter / VectorStore / Evaluator 每一个核心环节均定义了抽象接口，支持"乐高积木式"替换，通过配置文件一键切换后端，零代码修改。

🔍 混合检索 + 重排：BM25 稀疏检索解决专有名词精确匹配 + Dense Embedding 解决同义词语义匹配，RRF 融合后可选 Cross-Encoder / LLM Rerank 精排，平衡查全率与查准率。

🖼️ 多模态图像处理：采用 Image-to-Text 策略，利用 Vision LLM 自动生成图片描述并缝合进 Chunk，复用纯文本 RAG 链路即可实现"搜文字出图"。

📡 MCP 生态集成：遵循 Model Context Protocol 标准，可直接对接 Claude Code、Cursor、GitHub Copilot 等 MCP Client，零前端开发，一次开发处处可用。

📊 可视化管理 + 自动化评估：Streamlit Dashboard 提供完整的数据管理与链路追踪能力，集成 Ragas 等评估框架，建立基于数据的迭代反馈回路。

🧪 三层测试体系：Unit / Integration / E2E 分层测试共 1363 个用例，覆盖独立模块逻辑、模块间交互、完整链路（MCP Client / Dashboard）。

🚀 快速开始

1. 环境准备

# 安装依赖（建议使用 .venv）
pip install -e .

# 或使用 Setup Skill 一键配置（Provider 选择 → API Key → 依赖 → 配置）
setup

编辑 config/settings.yaml 填入 LLM / Embedding 的 API Key（默认 OpenAI）。

2. 统一入口（main.py）

# 启动 MCP Server（供 AI 助手连接，stdio 传输）
python main.py

# 启动 Dashboard 前端（默认 http://localhost:8501）
python main.py dashboard --port 8501

3. 摄入论文

# 通过 Dashboard「论文导入」页上传，或 CLI：
python scripts/ingest.py --path <论文目录或文件> --collection default

4. 集成到 AI 助手

在 Claude Code / Cursor 等的 MCP 配置中注册本项目：

{
  "mcpServers": {
    "rag-kb": {
      "command": "python",
      "args": ["main.py"],
      "cwd": "<项目路径>"
    }
  }
}

配置完成后即可让 AI 直接调用 query_knowledge_hub 等工具查询论文内容。

📊 测试体系与评估基线

测试规模

pytest tests/unit -q          # 单元测试
pytest tests/integration -q   # 集成测试（部分需真实 LLM 凭据）
pytest tests/e2e -q           # 端到端测试

论文测试集评估基线（2026-09-11 实测）

64 题黄金测试集（17 篇论文）三指标：

# 检索指标（零 LLM 成本）
python scripts/evaluate.py --test-set tests/fixtures/paper_test_set.json --top-k 10 --json

# 三指标（需 ragas；--generate-answers 自动生成答案）
python scripts/evaluate.py --test-set tests/fixtures/paper_test_set.json --top-k 10 --generate-answers --json

⚠️ 测试集 chunk id 与当前入库数据绑定，重新入库后需重新验证：python scripts/verify_paper_testset.py 逐题验证检索，再用 python scripts/build_paper_testset.py 重建测试集。

❓ 常见问题

1. 如何切换 Provider（OpenAI / DeepSeek / Ollama / Azure）？

项目使用工厂模式（Factory Pattern），Provider 切换只需：① 新增/选用 Provider 类；② 在工厂注册；③ 更新 settings.yaml。直接让 AI 帮你完成，或运行 Setup Skill 引导配置。

2. 想摄取 PDF 以外的文档格式（Word / Markdown / HTML 等）？

Loader 层采用可插拔抽象设计（BaseLoader），默认实现 PDF Loader。新增格式只需让 AI 参考现有 PDF Loader 实现一个对应 Loader。

3. 如何集成到 AI 工具中（Claude Code / Cursor / Copilot 等）？

本项目是标准 MCP Server，任何支持 MCP 协议的 AI 工具都能集成——按工具要求填写 MCP 配置（见快速开始第 4 步），或直接问 AI 生成配置。

4. 项目报错 / Bug 怎么办？

三层测试体系覆盖主链路，遇到问题：① 把错误信息直接丢给 AI 修复；② 运行 qa-tester Skill 执行全量 QA 计划（QA_TEST_PLAN.md，A~P 共 16 章）；③ 检查 logs/traces.jsonl 追踪链路定位瓶颈。

5. 善用内置 Skill