paper-download-mcp

通用论文获取器 MCP：按 DOI/UT 标识探测 provider、下载到短生命周期暂存区、核验 PDF、清理。不连接 PostgreSQL，不接收 project/output_dir/year/publisher/filename，不管理最终存储——这些是调用项目（如 HC 集成侧）的职责。

架构（2026-07-22 收敛）

MCP (通用获取器)                    调用项目集成侧
  health                              任务规划与项目筛选
  list_providers                      最终存储与资产登记
  probe(identifier, hint?)            批量编排与限速
  fetch(identifier, hint?) → artifact 下载审计
  verify_artifact(id)                 项目级状态管理
  discard_artifact(id)

工具（6 个）

工具	说明
paper_download_health	版本/暂存目录/provider 可用性（不回显 key）
paper_download_list_providers	列出 provider 及状态
paper_download_probe	探测 provider 能否获取某标识
paper_download_fetch	下载到暂存区，返回 artifact_id（不收 project/output_dir 等）
paper_download_verify_artifact	核验暂存 PDF（存在/页数/哈希/大小）
paper_download_discard_artifact	清理暂存 artifact

fetch 返回：artifact_id / temp_path / 来源 / 字节数 / SHA-256 / 页数 / 状态 / 失败分类。

Providers

Provider	状态	说明
fake	✅	测试用，合成 PDF，无网络
elsevier	✅ 受控启用	Article Retrieval API；需要授权、校园网 IP 和 0600 key 文件
mdpi	✅	cloakbrowser 提取 PDF 链接并捕获浏览器下载
springer	✅	cloakbrowser 获取 cookie，requests 下载；订阅范围有限
frontiers	✅	重定向后的文章 URL 从 /full 转 /pdf
plos	✅	DOI 期刊前缀映射到 PLOS PDF 地址
copernicus	✅	文章页与 DOI 后缀构造 PDF 地址
bmc	✅	Springer 同类页面结构与 cookie 下载

Elsevier key 只经 PAPER_DOWNLOAD_ELSEVIER_API_KEY_FILE 指向的 mode 0600 文件进入，不进工具参数/日志/消息。

这些 provider 的页面规则来自已有英文文献下载工作的实战记录，具体限制和证据见 docs/provider-acceptance.md。代码中的“已实现”不等于当前网络环境下每篇论文都可下载；订阅、页面变化、限流和文章下线仍会导致可解释的失败。

本项目不集成 scansci-pdf。它是独立的第三方 MCP，不属于本项目的 provider 链路。

安装与运行

cd paper-download-mcp
python -m pip install -e ".[dev,browser]"

# 测试（无网络无 DB 无 secret）
python -m pytest tests -v

# 启动 MCP (stdio)
paper-download-mcp   # 或 python -m paper_download_mcp

浏览器 provider 需要 cloakbrowser；Elsevier 的页数核验需要系统提供 pdfinfo（通常由 poppler-utils 提供）。

调用项目集成侧

项目侧负责候选 SQL、canonical 落盘策略、编排循环、资产表和下载审计。这个 MCP 只交付暂存 artifact 及其核验元数据。