Skip to main content
Glama
literature-bot-mcp

literature-bot-mcp

by Remus-cloud

Local MCP Literature Assistant

文献搜索与问答助手,支持语义排序、原文溯源与科学证据核对。

在本地搜索 arXiv、读取 PDF,并用可追溯的正文证据回答文献问题。 提供 Streamlit 聊天界面和独立的本地 stdio MCP Server。

从查找论文到核对回答依据,在一个界面中完成。科学证据核对会提供 片段支持度、数值与实验条件等诊断提示,帮助定位需要回到原文确认的内容; 它不认证结论真假,也不会自动修改回答。

本仓库面向希望在自己电脑上运行文献助手的用户。无需使用 Notebook、 MCP Inspector 或开发评测脚本,安装后直接通过浏览器使用。

功能

  • 查找论文:搜索 arXiv,用 SPECTER2 对标题与摘要候选进行语义排序。

  • 基于原文问答:读取 PDF,通过 BM25 查找相关正文片段,生成带引用的回答。

  • 追溯回答依据:将结论与证据片段关联,通过页码引用查看 PDF 原文。

  • 核对科学证据:结合本地 MiniCheck、简单计算、比例与单位规则,以及实验条件差异,提供只读诊断提示。

  • 便于人工确认:逐条查看诊断,并按需下载回答诊断或人工核对材料。

  • 多种使用入口:浏览器内提供搜索、分析、总结快捷任务,也可通过 MCP Tools、Resources 和 Prompts 接入其他客户端。

SPECTER2 只重排最多 10 篇 arXiv 候选,不是全库语义检索。 MiniCheck 只评估所给片段的支持信号,低分不等于论文反驳。

Related MCP server: arxiv-mcp

安装

以下命令用于 Windows 的 Anaconda Prompt;需要 Git、Conda 和网络连接。

git clone https://github.com/Remus-cloud/local-mcp-literature-assistant.git
cd local-mcp-literature-assistant
conda create -n literature-bot python=3.12 -y
conda activate literature-bot
python -m pip install -e ".[scientific,verification]"
python scripts/prepare_verification.py

环境已存在时跳过创建命令。MiniCheck 准备步骤会下载约 3.2 GB 固定版本权重; SPECTER2 在首次搜索时下载并缓存权重。已有缓存不必重新下载。 无 Git 时可下载仓库 ZIP,解压后在项目根目录执行后续命令。

已验证的 Windows / Python 3.12 依赖版本记录在 版本快照。若需要尽量复现本次验证环境, 可将安装命令换为:

python -m pip install -c docs/tested-windows-py312.txt -e ".[scientific,verification]"

这是测试时的版本约束,不是跨平台锁文件;其他系统不保证使用完全相同的版本。

配置接口

首次使用:

if not exist .env copy .env.example .env
notepad .env

不要覆盖已有 .env。填写:

DASHSCOPE_API_KEY=你的API密钥
DASHSCOPE_BASE_URL=https://你的服务地址/v1
DASHSCOPE_MODEL=服务商提供的模型ID
LITERATURE_BOT_EXTRA_BODY={}

沿用的 DASHSCOPE_* 变量名不限定服务商。接口需支持 OpenAI 格式的 Chat Completions、工具调用及工具结果消息,结构化绑定默认还使用 response_format={"type":"json_object"}。仅支持普通聊天不够。

默认不发送私有扩展参数。若当前 Qwen 服务需要关闭思考模式,可显式设置:

LITERATURE_BOT_EXTRA_BODY={"enable_thinking":false}

问答及辅助模型调用使用同一配置,无需修改源码。 扩展配置不允许覆盖 model/messages/tools 等核心字段。 接口兼容性仍需由服务商确认,不承诺所有模型都接受相同的 token 或 JSON 模式参数。 SDK 扩展机制见 OpenAI Python 官方文档。

不支持 JSON 模式的服务可将 LITERATURE_BOT_BINDING_FORMAT=prompt_only; 此模式仍严格校验返回内容,但格式失败风险更高。 不要把真实 .env、密钥或研究会话记录提交到仓库。

启动与使用

在项目根目录运行:

python scripts/check_setup.py
python -m streamlit run src/literature_bot/streamlit_app.py --server.address 127.0.0.1 --server.port 8501 --browser.gatherUsageStats false

浏览器访问 http://localhost:8501。保持终端开启,停止时按 Ctrl+C。 以后重新进入项目目录并 conda activate literature-bot,执行同一启动命令即可。

页面中的三个选择

  • 论文排序:SPECTER2 按标题和摘要重排候选论文;正文证据仍由 BM25 检索。

  • 运行科学核验:为新回答增加 MiniCheck 及数值等检查,可能增加耗时与 API 费用。

  • 显示诊断:查看已经生成的提示;隐藏或显示不会重新调用模型。

页面选项只影响当前会话的使用;关闭核验运行只影响之后的新问题, 不会删除已有诊断,结构化引用仍保留。 首次使用建议先完成一次搜索,再针对指定论文提问并开启核验。

示例:

搜索 5 篇关于 multimodal object detection 的论文。

分析 arXiv <填入所选论文的完整 ID> 的实验设置、主要结果和局限,并给出原文依据。

每次提问独立,页面旧消息不构成模型长期记忆;请明确给出 arXiv ID。 “查看原文”的页码是 PDF 文件页序,不一定是印刷页码。

如何理解诊断

“支持信号”只表示所提供片段与结论具有一定一致性,不等于结论已被科学证明。 “低支持信号”也不等于论文反驳;可能是证据片段不足、翻译偏差或模型误判。 未评分、证据不足和条件不同均不能当作核验通过。请结合页码引用查看原文, 特别留意表格、实验条件与比较对象。

可选:MCP 与命令行

网页会自动启动 MCP 子进程,无需单独运行 Inspector 或 Server。

Streamlit → Chatbot → MCP Client → 本地 stdio MCP Server
                                     ├─ arXiv / SPECTER2
                                     └─ PDF / BM25
回答与证据 → MiniCheck / 数值规则 / 统一诊断 → 只读提示

可独立启动:

literature-bot-mcp
literature-bot-chat --question "搜索三篇视觉语言模型论文"

第一条用于 MCP 客户端通信,不会启动网页。支持四个文献 Tools、 论文元数据/页面 Resources,以及搜索/分析/总结 Prompts。

限制与数据处理

  • 面向本地单用户,不包含公网服务、登录或多用户隔离。

  • 检索只覆盖 arXiv 候选及选中的正文片段,不保证全文审阅。

  • 指定历史 arXiv 版本时,当前流程可能返回其他版本;涉及版本对比或精确复现时,请先核对返回的论文 ID 与 PDF 版本。

  • 复杂任务可能达到工具调用轮次上限而无法完成;可先搜索并确认论文,再将分析任务拆成较小的问题。

  • 不支持扫描 PDF OCR;复杂表格、公式和多栏排版可能损坏。

  • 数值与条件规则覆盖较窄,不验证因果、统计显著性或实验可重复性。

  • MiniCheck 最多检查 8 条已绑定结论;未评分不算通过,分数未经领域校准。

  • 语义核验软预算不是硬超时;首次加载和 CPU 推理可能较慢。

  • 问题、证据和核验翻译会发送到所配置的 API,可能产生费用。

  • 普通聊天仅保存在浏览器会话;论文缓存和主动导出的文件保存在本地。

常见问题

启动提示缺少模块或找不到命令

确认已激活 literature-bot 环境,并在含有 pyproject.toml 的项目根目录 执行安装命令。python scripts/check_setup.py 可检查配置项是否填写、安装版本 和部分模型缓存,不会调用付费 API;它不代表网络连接或实际推理已验证。

接口能聊天,但文献问答失败

检查工具调用与 JSON 模式支持,以及模型 ID、额度和扩展参数。 若服务不支持 JSON 模式,可尝试上文的 prompt_only 配置。 配置修改后应停止并重新启动应用。

模型下载失败或首次搜索很慢

科学组件需要访问 Hugging Face 下载权重,并占用数 GB 磁盘和额外内存。 先确认网络及磁盘空间,MiniCheck 下载失败后可重新运行 python scripts/prepare_verification.py。CPU 推理可能较慢; 暂时不使用科学组件时,可在页面选择不使用 SPECTER2 的排序方式并关闭科学核验。

arXiv 搜索或 PDF 下载失败

检查本机网络、代理和 arXiv 访问情况,稍后重试。当前仅支持可提取文字的 PDF, 扫描版论文无法通过本项目自动 OCR。

端口 8501 被占用

将启动命令中的 --server.port 8501 改为 --server.port 8502, 然后访问 http://localhost:8502。

组件如何配合

SPECTER2 帮助排序候选论文,BM25 查找正文证据,配置的聊天模型负责生成回答。 结构化绑定记录结论与证据的对应关系;MiniCheck 和规则检查在此基础上提供诊断。 这些组件各司其职,不是将主模型替换为另一个“科学大模型”。

主模型可使用满足上文接口要求的服务。论文缓存与模型权重按需在本地生成或下载, 不随仓库分发;安装与使用无需开发用 Notebook 或内部评测数据。

Available Tools

4 tools
literature_get_paper_detailsGet arXiv Paper DetailsA
Read-onlyIdempotent

Return detailed metadata for one arXiv paper.

Use this for title, authors, abstract, categories, dates, and URLs. If the paper has not been seen in this session, the server resolves the ID through arXiv. It does not download the PDF.

Inputs: arxiv_id (required). Returns: paper, prepared_in_memory

literature_prepare_paperPrepare Paper for RetrievalA
Idempotent

Download, extract, and chunk one paper for evidence retrieval.

The PDF is cached in the configured local papers directory and is not overwritten. Extracted pages and chunks stay only in server memory. Repeating the call is safe and reuses the cache.

Inputs: arxiv_id (required). Returns: title, arxiv_id, pdf_path, page_count, +3 more

literature_retrieve_paper_evidenceRetrieve Evidence from a PaperA
Idempotent

Retrieve page-cited evidence chunks from one paper.

Use this before answering a question about paper content. The query must be concise English keywords because retrieval uses local BM25 rather than a model. If necessary, the paper is prepared automatically. Return the page numbers with any answer built from these results.

Inputs: query (required), arxiv_id (required), top_k. Returns: query, title, arxiv_id, evidence, +2 more

literature_search_papersSearch arXiv PapersA
Read-onlyIdempotent

Search arXiv and return concise paper metadata.

Use this first when the user wants literature recommendations or has not supplied an arXiv ID. It does not download PDFs. The returned arXiv IDs can be passed to the other literature tools.

Inputs: query (required), max_results. Returns: count, query, papers

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 4 tools

    Disambiguation4/5

    Each tool targets a distinct stage: search, metadata details, preparation/download, and evidence retrieval. The only mild overlap is prepare_paper vs retrieve_paper_evidence, since retrieve auto-prepares when needed, but descriptions clarify the distinction well.

    Naming Consistency5/5

    All four tools follow a strict literature_verb_noun pattern (search_papers, get_paper_details, prepare_paper, retrieve_paper_evidence), making the namespace and conventions fully predictable.

    Tool Count4/5

    Four tools is slightly lean but well-matched to a focused paper search-and-retrieval server. Each tool earns its place with a distinct role in the pipeline.

    Completeness4/5

    The surface covers a coherent lifecycle: search, inspect metadata, prepare, and retrieve cited evidence. Minor gaps exist (no listing/clearing of the local cache), but core literature workflows are fully supported.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables searching, downloading, and managing academic papers from arXiv.org through natural language interactions. Provides tools for paper discovery, PDF downloads, and local paper collection management.
      4
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables searching arXiv, fetching metadata, reading papers as section-aware Markdown, listing recent papers, and downloading PDFs via five MCP tools.
      49 npm
      2
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A local, rule-based MCP server for searching and analyzing academic papers from arXiv. Enables paper search, ranking, smart summarization, keyword extraction, and citation generation without API keys or LLM calls.
      -
    • F
      license
      C
      quality
      B
      maintenance
      Enables users to build and query a project-local literature database by ingesting papers from Semantic Scholar, PubMed, arXiv, and OpenAlex, caching open-access PDFs, extracting full text, ranking results, and exposing MCP tools for search, seeds, feedback, and pipeline status over stdio.
      16
      -