Scholar RAG MCP

scholar-rag-mcp

状态：预览版（v0.4.0）。 接口和存储布局可能会在未来版本中更改。

scholar-rag-mcp 是一款可发布的学术论文知识库 MCP 工具。指定一个 PDF 文件夹后，它会通过真实的解析流水线（MinerU）摄取每篇论文，规范化元数据、标注章节结构、对文本分块并生成嵌入向量，然后将所有内容存储在 Qdrant 中。之后，Agent（或你）即可通过 stdio 上的 11 个 MCP 工具进行语义分块搜索、执行 PubMed 风格的文档查询、逐节阅读全文、添加或移除单篇论文，以及管理知识库。嵌入、标注和重排序由 OpenAI 兼容的模型服务（例如 vLLM）处理。

功能

• 真实的摄取流水线：MinerU PDF 解析（python/cli/api 后端）-> 元数据提取（本地启发式方法、CrossRef、可选的 GROBID）-> 清理 -> 章节标注 -> 确定性分块（可配置为 300/1500/100 个字符）-> 嵌入。
• 大规模快速检索：先进行嵌入检索，再通过交叉编码器重排序；可选元数据筛选（doc_id、section、year、journal 等）在 Qdrant 索引内部执行。10 万个分块时，p95 查询延迟 < 1 秒（见 docs/perf-report.md）。
• 异步任务：create_kb/add_document 在后台运行，可通过 get_job 查询进度；支持安全重启（中断的任务会在重新运行时恢复并跳过已完成部分）。
• 上下文安全阅读：分页式 get_document_text，并设有严格的大小上限；先查看大纲，需要时再按页读取。
• 通过 stdio 提供 11 个 MCP 工具：list_kbs、create_kb、delete_kb（两阶段）、add_document、 remove_document、get_document、get_document_text、list_documents、search_documents、 search_chunks、get_job。
• 自包含存储：知识库位于单个数据目录下（默认位置因平台而异，见“数据布局”）；Qdrant 可自动启动（单个二进制文件，版本固定），也可连接到外部实例。

安装

scholar-rag-mcp 可在 Linux x64、Windows x64 和 macOS（Intel 和 Apple Silicon）上运行。 该项目已发布到 PyPI；标准运行方式是使用 uv（会自动获取合适的 Python 3.12）：

uvx scholar-rag-mcp             # download and start the MCP server (stdio)

无需检出代码仓库。可通过 SCHOLAR_RAG_* 环境变量或 <data_dir>/config.json 配置模型端点和存储（见 .env.example）；自动启动所用的 Qdrant 二进制文件会在首次使用时按平台下载。

一键安装 / 卸载

uvx scholar-rag-mcp install --with-mineru # install via uv, provision managed MinerU, register MCP clients
uvx scholar-rag-mcp install              # MCP only; bring your own parse service (see PDF parsing)
scholar-rag-mcp uninstall                # unregister clients and remove the package

uvx scholar-rag-mcp install 会通过 uv tool install 安装软件包，并交互式引导你设置六项模型端点配置（chat/embed/rerank 的基础 URL 和模型名称）。除非提供 SCHOLAR_RAG_* 值或 --chat-base-url / --chat-model / --embed-base-url / --embed-model / --rerank-base-url / --rerank-model 标志，否则将使用“最低限度环境”中列出的默认值；使用 --yes 可接受所有默认值而不进行提示。随后，它会检测四种受支持的 MCP 客户端（Claude Desktop、Claude Code、opencode、Codex），并通过将 scholar-rag-mcp 条目合并到用户级配置中来注册工具；只会修改该条目。传入 --client <name> 可注册到单个客户端。无法解析的配置（例如含注释的 JSON）不会被修改，而会打印手动配置片段。

scholar-rag-mcp uninstall 会从检测到的客户端中移除 scholar-rag-mcp 条目，并运行 uv tool uninstall；知识库数据目录会予以保留。--purge 还会在明确确认后删除数据目录（使用 --yes 可跳过提示）。

从源码开发

需要 pixi。在仓库根目录运行：

pixi install                      # installs the default environment

pixi 环境已针对所有四个受支持的目标锁定。项目定义了两个 pixi 环境，各有不同用途：

环境	用途
default	核心运行时 + 开发工具（pytest/ruff/mypy）。在此环境中运行 MCP 服务和所有脚本。
mineru	添加 MinerU（==3.4.5）及其完整运行时依赖栈（固定版本的 transformers<5、torch、onnxruntime、shapely 等）。用于 PDF 解析和端到端冒烟测试。

使用内置诊断工具验证环境：

pixi run python scripts/doctor.py

模型部署

环境（chat、embed 和 rerank 客户端）需要兼容 OpenAI 的 HTTP 端点。 scripts/serve_models.sh 会为参考模型集启动三个 vLLM 实例：

服务	模型	端口
chat	Qwen3.5-0.8B	8101
embed	jina-embeddings-v5-text-small	8102
rerank	jina-reranker-v3.5	8103

# point *_MODEL at your local model directories, then:
bash scripts/serve_models.sh

SCHOLAR_RAG_CHAT_MODEL、SCHOLAR_RAG_EMBED_MODEL 和 SCHOLAR_RAG_RERANK_MODEL 均为必填项——如果其中任何一项未设置，脚本会退出并列出缺失项。每个值都必须是本地 HuggingFace 模型目录的绝对路径；vLLM 会使用目录的 basename 作为模型的简短名称，因此客户端设置必须使用该简短名称（服务提供的名称不再等于完整路径）。请相应替换 .env.example 中的 /path/to/... 占位符。端口（CHAT_PORT/EMBED_PORT/RERANK_PORT）和 GPU ID 均为可选项，并提供了可用的默认值。

该脚本会传入经默认模型集验证的 vLLM 标志，尤其是 --trust-remote-code；三个模型在固定版本的 vLLM（0.27.1）上都需要此标志。模型加载需要几分钟；脚本会轮询健康状态，直到三个模型均能响应。

scripts/serve_models.sh 仅支持 Linux（bash + CUDA + vLLM；vLLM 不支持 Windows）。在 Windows/macOS 上，请将 *_BASE_URL 设置为任意兼容 OpenAI 的服务端点，例如 Ollama（http://127.0.0.1:11434/v1）、LM Studio 的本地服务，或 llama.cpp 服务端，并将各个 *_MODEL 设置为该服务端报告的模型名称。重排端点必须提供 /v1/rerank（否则可使用仅嵌入回退方案）。

最简环境

以 .env.example 为基础，至少设置模型端点（使用服务脚本提供的简短名称，该名称与各模型目录的 basename 相同）：

# data dir is optional - defaults to the platform data directory (see Data layout)
# SCHOLAR_RAG_DATA_DIR=
# SCHOLAR_RAG_QDRANT_STORAGE_DIR=

SCHOLAR_RAG_CHAT_BASE_URL=http://127.0.0.1:8101/v1
SCHOLAR_RAG_CHAT_MODEL=Qwen3.5-0.8B

SCHOLAR_RAG_EMBED_BASE_URL=http://127.0.0.1:8102/v1
SCHOLAR_RAG_EMBED_MODEL=jina-embeddings-v5-text-small

SCHOLAR_RAG_RERANK_BASE_URL=http://127.0.0.1:8103/v1
SCHOLAR_RAG_RERANK_MODEL=jina-reranker-v3.5

嵌入模型的维度会在创建知识库时记录到 kb_meta.json，因此之后更换嵌入模型需要新建知识库。

PDF 解析（MinerU）

从 v0.4.0 起，默认解析后端为 api。推荐使用托管式 sidecar 设置：它会将 MinerU 安装到隔离的 Python 3.12 venv 中（MinerU 需要 Python >=3.10,<3.14），并在首次解析时自动启动 mineru-api：

scholar-rag-mcp install --with-mineru

自主管理方案：在任意 Python 3.12 环境中安装 MinerU，运行 mineru-api --host 127.0.0.1 --port 8010，并保留默认设置（SCHOLAR_RAG_MINERU_BACKEND=api、SCHOLAR_RAG_MINERU_API_URL=http://127.0.0.1:8010）。

仍可通过 SCHOLAR_RAG_MINERU_BACKEND 使用 python 后端（进程内导入）和 cli 后端（每个文件启动一个子进程）。

MCP 客户端设置

将 MCP 客户端指向 uvx 入口点，并在 env 块中配置模型端点（任何兼容 OpenAI 的服务端均可；参见“模型部署”）。要检查服务是否能启动，请在终端中运行 uvx scholar-rag-mcp——它会等待通过 stdio 连接的 MCP 客户端（按 Ctrl+C 退出）。

Claude（Claude Desktop / claude CLI）

{
  "mcpServers": {
    "scholar-rag-mcp": {
      "command": "uvx",
      "args": ["scholar-rag-mcp"],
      "env": {
        "SCHOLAR_RAG_CHAT_BASE_URL": "http://127.0.0.1:8101/v1",
        "SCHOLAR_RAG_CHAT_MODEL": "Qwen3.5-0.8B",
        "SCHOLAR_RAG_EMBED_BASE_URL": "http://127.0.0.1:8102/v1",
        "SCHOLAR_RAG_EMBED_MODEL": "jina-embeddings-v5-text-small",
        "SCHOLAR_RAG_RERANK_BASE_URL": "http://127.0.0.1:8103/v1",
        "SCHOLAR_RAG_RERANK_MODEL": "jina-reranker-v3.5"
      }
    }
  }
}

opencode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "scholar-rag-mcp": {
      "type": "local",
      "command": ["uvx", "scholar-rag-mcp"],
      "environment": {
        "SCHOLAR_RAG_CHAT_BASE_URL": "http://127.0.0.1:8101/v1",
        "SCHOLAR_RAG_CHAT_MODEL": "Qwen3.5-0.8B",
        "SCHOLAR_RAG_EMBED_BASE_URL": "http://127.0.0.1:8102/v1",
        "SCHOLAR_RAG_EMBED_MODEL": "jina-embeddings-v5-text-small",
        "SCHOLAR_RAG_RERANK_BASE_URL": "http://127.0.0.1:8103/v1",
        "SCHOLAR_RAG_RERANK_MODEL": "jina-reranker-v3.5"
      }
    }
  }
}

若从源码检出目录运行：将命令设置为 pixi run scholar-rag-mcp（在仓库根目录运行），并在 shell 中设置相同的变量。

工具

工具	用途
list_kbs	列出知识库及其文档数、分块数和状态。
create_kb	异步将文件夹中的所有 PDF 导入新的知识库（返回 job_id）。
delete_kb	分两阶段删除知识库（见下文）。
add_document	异步将单个 PDF 导入现有知识库（返回 job_id）。
remove_document	同步删除一份文档（Qdrant 点、目录和文件）。
get_document	文档概览：元数据、摘要、章节大纲和总大小。
get_document_text	分页读取一份文档的全文或单个章节。
list_documents	分页浏览知识库中的文档。
search_documents	PubMed 风格的文档级搜索（全文搜索 + 标题／作者／期刊／年份）。
search_chunks	带元数据筛选和嵌入及重排分数的语义分块搜索。
get_job	查询后台作业的状态／进度／结果／耗时。

数据布局

<data_dir>/                     # SCHOLAR_RAG_DATA_DIR, default: platform data dir (below)
├── kbs/<kb_name>/
│   ├── kb_meta.json            # dimension, chunk config, schema version
│   ├── catalog.sqlite3         # documents / authors / keywords / chunks + FTS5
│   └── documents/<doc_id>/     # source.pdf, full_text.md, sections.json
├── cache/parse/                # MinerU markdown cache, keyed by content hash
├── cache/resolver/             # annotation resolver cache, keyed by content hash
├── jobs.sqlite3                # async job history
├── bin/                        # auto-downloaded Qdrant binary (v1.12.5)
└── qdrant-storage/             # default QDRANT_STORAGE_DIR location

各平台的默认 data_dir（可通过 SCHOLAR_RAG_DATA_DIR 覆盖）：

平台	默认值
Linux	$XDG_DATA_HOME/scholar-rag（若无则使用 ~/.local/share/scholar-rag）
macOS	~/Library/Application Support/scholar-rag
Windows	%LOCALAPPDATA%\scholar-rag

Qdrant 存储默认为 <data_dir>/qdrant-storage（可通过 SCHOLAR_RAG_QDRANT_STORAGE_DIR 覆盖）——必须位于本地文件系统上，不能位于 9p／网络 挂载上。

从 Linux 上的 v0.1.0 升级：首次启动时会自动迁移旧默认目录（~/.scholar-rag 和 ~/.local/share/scholar-rag/qdrant）；如果新位置已有数据，则会发出警告并跳过迁移，旧文件 保持不变。

分两阶段删除知识库

如果参数有误，delete_kb 首次调用时不会意外删除内容：

1. 调用 delete_kb(kb="...")——返回知识库统计信息和有效期为 10 分钟的 confirm_token。
2. 调用 delete_kb(kb="...", confirm_token="<token>")，以实际删除 Qdrant 集合、知识库目录及其作业历史记录。

开发

pixi run lint          # ruff check src tests
pixi run typecheck     # mypy src
pixi run test          # pytest (unit + integration, no e2e/perf)
pixi run -e mineru pytest tests/e2e/smoke.py -v -m e2e   # real end-to-end smoke
python tests/perf/bench_query.py                          # query latency benchmark (writes docs/perf-report.md)

发行说明

有关已知限制和升级指南，请参阅 docs/handoffs/release-notes-v0.4.0.md、 docs/handoffs/release-notes-v0.3.0.md 和 docs/handoffs/release-notes-v0.2.1.md。

值得再次说明的已知限制：

• Qdrant 固定为 v1.12.5——这是可在 glibc 2.35 上运行的最高版本； 首次使用时会自动启动并下载该版本。在 glibc >= 2.38 上可以运行更新版本，但本次发行版中的旧知识库 数据格式不向前兼容。
• MinerU 在独立的 pixi 环境中运行，因为其 transformers 版本与 vLLM 的版本互斥。因此，PDF 解析 优先使用 pixi run -e mineru。
• MinerU 权重（约 3.2 GB）会在首次解析时下载到 ~/.cache/modelscope/。
• 元数据标题启发式规则：只有当 MinerU Markdown 以 #／## 标题开头时，才会在本地提取标题，因此开头的 ## Abstract（等）可能会被误判为标题。这只影响本地启发式元数据层；CrossRef 层（发现 DOI 时使用） 通常会纠正此问题。
• 工具分发：工具收到的未知额外参数会被静默忽略，而非拒绝。
• 9p 存储限制：Qdrant 存储必须位于本地文件系统上。
• 平台支持：Linux x64／Windows x64／macOS Intel+Apple Silicon。vLLM 部署脚本仅支持 Linux；Windows/macOS 可使用任意兼容 OpenAI 的服务。
• Windows 长路径：较深的数据目录可能会触及 260 字符的限制；请将 SCHOLAR_RAG_DATA_DIR 设为较浅的目录，或启用 Windows 长路径支持。
• macOS x64 CI：仅在代码层面覆盖；GitHub x64 macOS 运行器需要 使用更高规格运行器计费，因此 CI 矩阵使用 macOS arm64（macos-latest）。