scansci-pdf — 学术论文下载 MCP 服务

⚠️ 修改反爬/嗅探/镜像相关代码前必读

先读 docs/PLAYBOOK.md：镜像健康唯一存储（domain_db wall_state 表）、 结构性失败签名表、节奏参数、已知死镜像清单、以及六条铁律（含"造轮子前先 grep 家底"—— 镜像健康存储曾被重复造过三代）。

概述

scansci-pdf 是一个 MCP 服务器，提供 17 个高层工具，覆盖学术论文的搜索、下载（开放获取 / 灰色源 / 机构渠道）、发现与队列准备、引文导出和诊断排障。下载引擎支持 13+ 数据源并行竞速、100+ 中国高校 WebVPN。

MCP 工具参考（17 个）

下载

工具	功能	关键参数
scansci_pdf_download	单篇下载（OA/灰色源/机构级联）	identifier（必需）、strategy（可覆盖全局策略）、markdown/bibtex/download_si（可选）
scansci_pdf_batch_download	批量下载	identifiers（必需）、scihub_enabled、batch_id（断点续传）、resume（默认 true）
scansci_pdf_cache_clear	清理下载缓存	identifier（可选，省略清全部）

identifier 格式：DOI（10.1038/nature12373）、DOI URL、arXiv ID（2301.00001）。

下载策略（download_strategy，全局配置或单次 strategy= 覆盖）：

策略	含义
fastest（默认）	全部源并行竞速（含灰色源，若 scihub_enabled=true）
oa_first	OA 源优先，失败后回退灰色源
scihub_first	灰色源优先，失败后回退合法源
scihub_only	仅 Sci-Hub
legal_only	仅合法源（Unpaywall/出版商/OpenAIRE 等），不碰 Sci-Hub/LibGen

来源授权不可被调度扩张：用户显式设置 scihub_enabled=false 或 legal_only 时，任何批量/车道调度都不会重新启用灰色源；只有显式 --scihub/scihub_enabled=true 或全局策略允许时才启用。

发现与队列准备

工具	功能	关键参数
scansci_pdf_find	ScanSci Find 引擎：action=plan|estimate|smoke|calibrate 系统综述搜索协议	action、query、domain、depth、sample_size
scansci_pdf_expand_citations	引文追踪（Semantic Scholar/OpenCitations）	query、rounds（≤5）、citation_source
scansci_pdf_prepare_queue	准备下载队列：action=verify|resolve_oa|build|full	candidates_json、query、limit
scansci_pdf_search	关键词/作者搜索（OpenAlex）	query/author/author_id、limit、year_from、year_to、sort
scansci_pdf_parse_list	解析论文列表文件（APA/BibTeX/DOI 列表/表格）	file_path（必需）
scansci_pdf_citation	导出引文	identifier（必需）、format（bibtex/ris/endnote/metadata）
scansci_pdf_zotero_push	推送已下载论文到 Zotero	identifier（必需，需先下载）

重要：verify/resolve_oa 是轻量操作，预算 45 秒内返回；超时会返回结构化错误（stage/timeout_seconds/retryable），不会无反馈地等 180 秒。resolve_oa 依赖 Unpaywall 邮箱配置（scansci_pdf_config(key='email', ...)），缺失时直接返回 blocked_configuration 而不是逐条失败。

配置、通道与诊断

工具	功能	关键参数
scansci_pdf_config	读取/设置配置（值会脱敏）	key（可选）、value（可选）
scansci_pdf_channel_status	机构渠道状态：kind=webvpn|carsi|ezproxy|browser|webvpn_test	kind、doi（仅测试）
scansci_pdf_schools	搜索/设置 WebVPN 高校	action=search|set、query、school
scansci_pdf_diagnostics	健康/网络/来源/设置诊断	check=health|network|sources|setup
scansci_pdf_tor	内嵌 Tor：action=install|start|stop	action、use_bridges

登录（机构渠道）

工具	功能	关键参数
scansci_pdf_login	统一登录：kind=publisher|webvpn|carsi|ezproxy|custom|cookie_import	kind（默认 publisher）、identifier、publisher、custom_url、cookie_file
scansci_pdf_elsevier_setup	Elsevier API Key 配置向导（免费，无需机构邮箱）	test（验证 key）

工作流编排

流程 1：模糊研究查询 → 下载

1. scansci_pdf_find(action="plan"|"estimate", query="植物功能性状 气候变化")
   或 scansci_pdf_search(query="plant functional traits climate change", limit=20, sort="cited_by_count")
2. scansci_pdf_prepare_queue(action="full", candidates_json=<candidates>)
   → 验证 DOI + 解析 OA 位置（45s 预算，超时给出结构化错误）
3. scansci_pdf_batch_download(identifiers=[...])

关键点：搜索后必须让用户确认，不要自动下载所有结果。

流程 2：论文列表全文下载

1. scansci_pdf_parse_list(file_path="papers.md") → 查看解析结果
2. scansci_pdf_batch_download(identifiers=entries)（或 resolve_and_download 的等价组合）

流程 3：WebVPN 机构代理

1. scansci_pdf_schools(action="search", query="清华") → 找到学校
2. scansci_pdf_schools(action="set", school="清华大学")
3. scansci_pdf_login(kind="webvpn") → 浏览器 CAS 认证
4. scansci_pdf_channel_status(kind="webvpn_test", doi="10.1038/nature12373") → 确认连通
5. scansci_pdf_download(identifier="...") → 自动走 WebVPN 渠道

流程 4：付费论文登录下载（出版社 SSO）

当下载返回 error_type="paywall" 和 action="login_required" 时：

1. scansci_pdf_download(identifier="10.1126/science.aec6396")
   → 返回 {"error_type": "paywall", "action": "login_required", ...}
2. scansci_pdf_login(identifier="10.1126/science.aec6396")  # kind=publisher 默认
   → 打开浏览器到论文页 → 用户点 "Access through your institution" → 选择机构 → SSO → 关闭浏览器
3. scansci_pdf_download(identifier="10.1126/science.aec6396") → 用已保存 cookies 成功下载

要点：

• 任何有机构账号的用户都能用，无需预配置 WebVPN/CARSI
• Cookies 持久化，同一出版商登录一次即可
• 浏览器引擎为 CloakBrowser（Playwright 兼容反检测浏览器），能通过 Cloudflare Turnstile；出版社检测 TLS 指纹，Python HTTP 客户端即使带 cookies 也可能 403

流程 5：Elsevier API 快速通道（1-2 秒下载）

1. scansci_pdf_elsevier_setup → 浏览器注册指引 → 复制 API Key
2. scansci_pdf_config(key="elsevier_api_key", value="...")
3. scansci_pdf_elsevier_setup(test=true) → 验证
4. 后续 10.1016/ 开头 DOI 自动走 API 直接下载（无需 insttoken：校园网出口 + API key 即可）

NOT_ENTITLED 含义：未连校园网或学校未订阅该刊，不是缺 insttoken。

流程 6：内嵌 Tor（灰色源被墙时）

1. scansci_pdf_tor(action="install")   # 首次下载 Tor Expert Bundle
2. scansci_pdf_tor(action="start")     # 受限网络可 use_bridges=true
3. scansci_pdf_download(identifier="...", strategy="scihub_only")

能力边界

请求	处理方式
阅读/理解论文内容	不支持——只下载 PDF（可用 markdown=true 得 AI 可读文本层）
翻译论文	需要其他工具
生成文献综述/摘要	需要 LLM 读取 PDF 后生成
下载非学术 PDF	不支持
用户给了标题没有 DOI	先 search 获取 DOI 再下载
批量 100+ 篇	batch_download，并发数由 batch_workers 配置控制
需要机构权限的论文	login 登录后重试下载
下载失败	结果含 error_type；paywall→登录流程，rate_limited→稍后重试，cloudflare_blocked→启动 CloakBrowser/配置代理

常见边界情况

• 科学符号（版权 ©、重音姓名）在 Markdown 导出中可能有质量告警（markdown_warnings）——文本可读，罕见字符需人工核对。
• 批量任务无论成功、失败或超时都会在预算内退出并写 batch_results.json（原子写入）；挂住的源会被放弃而不是拖住整批。
• scan_find 未安装时，find/search/expand_citations 会给出安装指引；verify/resolve_oa 超时返回结构化错误。

环境安装引导

1. scansci_pdf_diagnostics(check="setup") → 环境状态
2. 按 readiness 处理：ready / partial / limited
3. 缺少组件时按建议安装（pymupdf4llm 用于 markdown、cloakbrowser 用于反爬登录）

快速安装

pip install -U scansci-pdf
pip install -U cloakbrowser    # 反爬浏览器（Chromium 内核）
scansci-pdf doctor             # 或 MCP: scansci_pdf_diagnostics(check="health")