scholar-rag-mcp

状态：预览版（v0.1.0）。 接口和存储布局在未来的版本中可能会发生变化。

scholar-rag-mcp 是一个可发布的学术论文知识库 MCP 工具。将其指向一个 PDF 文件夹，它会通过真实的解析流水线（MinerU）摄取每篇论文，规范化元数据，标注章节结构，对文本进行分块和嵌入，并将所有内容存储在 Qdrant 中——之后，智能体（或您）可以通过 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。

• 自包含存储：知识库位于单一数据目录（~/.scholar-rag）下；Qdrant 要么自动启动（单二进制，固定版本），要么连接到外部实例。

Related MCP server: Athena

安装

需要 pixi。在仓库根目录下：

pixi install                      # installs the default environment

该项目定义了三个 pixi 环境，每个环境服务于不同的目的：

使用内置的 doctor 验证您的环境：

pixi run python scripts/doctor.py

模型部署

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

# 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 以与目录基名相同的短名称提供每个模型，因此客户端设置必须使用该短名称（提供的名称不再等于完整路径）。请相应替换 .env.example 中的 /path/to/... 占位符。端口（CHAT_PORT/EMBED_PORT/RERANK_PORT）和 GPU id 仍然是可选的，并带有可用的默认值。

该脚本固定了针对这些模型验证过的确切 vLLM 标志（Jina 嵌入模型需要 --trust-remote-code 来处理其自定义代码；重排序器以其默认任务运行，无需额外标志）。模型加载需要几分钟；脚本会轮询健康状态，直到三个模型全部响应。

最小环境

从 .env.example 开始，至少设置模型端点（使用 serve 脚本暴露的短名称，与每个模型目录的基名相同）：

SCHOLAR_RAG_DATA_DIR=~/.scholar-rag
SCHOLAR_RAG_QDRANT_STORAGE_DIR=~/.local/share/scholar-rag/qdrant

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 时记录在 kb_meta.json 中，因此之后更改嵌入模型需要新建 kb。

MCP 客户端设置

直接启动服务器入口点以确保其运行：

pixi run scholar-rag-mcp

Claude (Claude Desktop / claude CLI)

{
  "mcpServers": {
    "scholar-rag-mcp": {
      "command": "pixi",
      "args": ["run", "scholar-rag-mcp"]
    }
  }
}

opencode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "scholar-rag-mcp": {
      "type": "local",
      "command": ["pixi", "run", "scholar-rag-mcp"]
    }
  }
}

工具

数据布局

<data_dir>/                     # SCHOLAR_RAG_DATA_DIR, default ~/.scholar-rag
├── 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 存储位于 data_dir 之外的 QDRANT_STORAGE_DIR（默认 ~/.local/share/scholar-rag/qdrant）——它必须位于本地文件系统上，而不是 9p/网络挂载。

两阶段 kb 删除

delete_kb 绝不会因第一次调用时参数错误而意外删除：

1. 调用 delete_kb(kb="...") - 返回 kb 统计信息以及一个 10 分钟有效的 confirm_token。

2. 调用 delete_kb(kb="...", confirm_token="<token>") 来实际删除 Qdrant 集合、kb 目录及其任务历史。

开发

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.1.0.md。

值得重复的已知约束：

• Qdrant 固定为 v1.12.5 - 这是可在 glibc 2.35 上运行的最高版本；自动启动会在首次使用时下载它。在 glibc >= 2.38 上，您可以运行更新的版本，但在此版本中，数据格式与较旧的 kb 不向前兼容。

• MinerU 在自己的 pixi 环境中运行，因为其 transformers 版本与 vLLM 的版本互斥。因此，PDF 解析优先使用 pixi run -e mineru。

• MinerU 权重（约 3.2 GB）在首次解析时下载到 ~/.cache/modelscope/。

• 元数据标题启发式：仅当 MinerU markdown 以 #/## 标题开头时，才会在本地选取标题，因此开头的 ## Abstract（等）可能被误读为标题。这仅影响本地启发式元数据层；CrossRef 层（在找到 DOI 时使用）通常会纠正它。

• 工具分发：工具的未知额外参数会被静默忽略，而不是被拒绝。

• 9p 存储限制：Qdrant 存储必须位于本地文件系统上。