SuperAPI AI 工具集
合作ENAI 行业资讯收藏
全部工具AI开发平台scholar-rag-mcp

scholar-rag-mcp

scholar-rag-mcp 是一个面向学术论文本地 PDF 的知识库 MCP（Model Context Protocol）服务器。将存放 PDF 的文件夹指向它，即可通过真实解析流水线（MinerU）逐篇摄取论文：提取并规范化元数据、标注章节结构、切块并向量化，最终全部存入 Qdrant。之后 AI 智能体或用户可通过 stdio 上的 11 个 MCP 工具进行语义检索、类似 PubMed 的文档查询、按章节分页阅读全文、增删单篇论文以及管理知识库。嵌入、标注与重排序均运行在 OpenAI 兼容的模型服务（如 vLLM）上。检索采用嵌入初筛加交叉编码器重排序，可选元数据过滤在 Qdrant 索引内执行，号称 10 万切块规模下 p95 查询延迟低于 1 秒。create_kb 与 add_document 以异步后台任务执行，可用 get_job 查询进度；阅读文档采用分页与硬性大小上限，先返回大纲再按需翻页，避免上下文过载。项目当前为预览版 v0.4.0，接口与存储布局可能变化。支持 Linux x64、Windows x64 与 macOS（Intel 和 Apple Silicon），已发布到 PyPI，推荐用 uv 运行，无需检出仓库。

访问官网

工具介绍

用途

scholar-rag-mcp 是一个可发布的学术论文知识库 MCP 工具。它面向本地 PDF 文件夹，把每篇论文经过真实解析流水线（MinerU）处理后，规范化元数据、标注章节结构、切块并嵌入向量，统一存入 Qdrant。之后 AI 智能体（或用户本人）可以通过 stdio 上的 11 个 MCP 工具进行语义检索切块、运行 PubMed 风格的文档查询、按章节阅读全文、添加/移除单篇论文以及管理知识库。嵌入、标注和重排序运行在 OpenAI 兼容的模型服务上（例如 vLLM）。

主要能力

  • 真实摄取流水线：MinerU PDF 解析（python/cli/api 后端）→ 元数据提取（本地启发式、CrossRef、可选 GROBID）→ 清洗 → 章节标注 → 确定性切块（可配置 300/1500/100 字符）→ 嵌入。
  • 大规模快速检索：嵌入初筛 + 交叉编码器重排序；可选元数据过滤（doc_id、section、year、journal 等）在 Qdrant 索引内部求值。据称 100k 切块规模下 p95 查询延迟 < 1s（见 docs/perf-report.md）。
  • 异步任务：create_kb / add_document 是后台任务，可通过 get_job 查询进度；重启安全（中断的任务会被恢复并在重跑时跳过）。
  • 上下文安全的阅读：分页式 get_document_text，带硬性大小上限；先给大纲，再按需取页。
  • 11 个 stdio 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 可自动启动（单二进制、版本固定）或连接外部实例。
  • 两阶段知识库删除：delete_kb 首次调用返回统计信息和 10 分钟有效的 confirm_token，第二次携带该 token 才真正删除 Qdrant 集合、知识库目录及其任务历史。

使用方式

平台支持 Linux x64、Windows x64 和 macOS（Intel 与 Apple Silicon）。已发布到 PyPI，标准运行方式是用 uv（会自动获取合适的 Python 3.12），无需检出仓库。

一键安装/卸载：

  • uvx scholar-rag-mcp install 会通过 uv tool install 安装，并交互式引导完成六项模型端点设置（chat / embed / rerank 的 base 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> 指定单个客户端。无法解析的配置会被保持原样并打印手动片段。
  • scholar-rag-mcp uninstall 从检测到的客户端中移除该条目并运行 uv tool uninstall；知识库数据目录保留。--purge 在明确确认后额外删除数据目录（可用 --yes 跳过提示）。

从源码开发运行需要 pixi。仓库根目录下，pixi 环境已为全部四个支持目标锁定；项目定义两个 pixi 环境，各司其职。可用内置 doctor 验证环境。

模型部署：环境变量（chat、embed、rerank 客户端）期望 OpenAI 兼容的 HTTP 端点。scripts/serve_models.sh 会为参考模型集启动三个 vLLM 实例。SCHOLAR_RAG_CHAT_MODEL、SCHOLAR_RAG_EMBED_MODEL 和 SCHOLAR_RAG_RERANK_MODEL 为必填——若未设置脚本会报错退出。每个值必须是本地 HuggingFace 模型目录的绝对路径；vLLM 以目录 basename 作为短名提供模型，因此客户端设置需使用该短名。端口（CHAT_PORT / EMBED_PORT / RERANK_PORT）和 GPU id 可选且有可用默认值。该脚本为 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 开始，至少设置模型端点（使用 serve 脚本暴露的短名，等于各模型目录的 basename）。嵌入模型维度在知识库创建时记录在 kb_meta.json，因此之后更换嵌入模型需要新建知识库。

PDF 解析（MinerU）：自 v0.4.0 起默认解析后端为 api。推荐使用托管 sidecar，会把 MinerU 安装到隔离的 Python 3.12 venv（MinerU 要求 Python >=3.10,<3.14），并在首次解析时自动启动 mineru-api。首次解析会触发 MinerU 模型下载；如需中国友好镜像可设置 MINERU_MODEL_SOURCE=modelscope。自管理替代方案：在任何 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）。python 后端（进程内导入）和 cli 后端（每文件子进程）仍可通过 SCHOLAR_RAG_MINERU_BACKEND 使用。

MCP 客户端设置：将 MCP 客户端指向 uvx 入口点，并在 env 块中配置模型端点（任何 OpenAI 兼容服务器均可）。要检查服务器是否启动，可在终端运行 uvx scholar-rag-mcp——它会等待 stdio 上的 MCP 客户端（Ctrl+C 退出）。以 Claude（Claude Desktop / claude CLI）为例；从源码检出运行时使用 pixi run scholar-rag-mcp 作为命令并设置相同变量。

数据布局默认 data_dir：因平台而异，可用 SCHOLAR_RAG_DATA_DIR 覆盖。Qdrant 存储默认 <data_dir>/qdrant-storage（可用 SCHOLAR_RAG_QDRANT_STORAGE_DIR 覆盖），必须位于本地文件系统，不能是 9p/网络挂载。从 v0.1.0 在 Linux 升级：旧默认值（~/.scholar-rag 和 ~/.local/share/scholar-rag/qdrant）在首次启动时自动迁移；若新位置已有数据，迁移会跳过并警告，旧文件保持不动。

适用场景

适合希望在本地构建学术论文知识库、并通过 AI 智能体进行语义检索与全文阅读的研究人员或开发者；适合需要 PubMed 风格文档查询、元数据过滤以及大规模切块低延迟检索的场景。

限制与已知约束

  • 状态为预览版 v0.4.0，接口与存储布局可能在未来版本变化。
  • 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 runner 需更高计费，故 CI 矩阵运行 macOS arm64（macos-latest）。

同类工具

查看分类