# 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`](docs/provider-acceptance.md)。代码中的“已实现”不等于当前网络环境下每篇论文都可下载；订阅、页面变化、限流和文章下线仍会导致可解释的失败。

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

## 安装与运行

```bash
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 及其核验元数据。