scansci-pdf

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

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

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

概述

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

工具名可能带宿主的 MCP 命名空间前缀（mcp__<server>__<tool>）；以当前工具列表中实际注册的名称为准。

MCP 工具参考（20 个）

下载

工具	功能	关键参数
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；中文并入 NCPSSD；配置 Key 后并入 Sciverse）	query/author/author_id、limit、year_from、year_to、sort
scansci_pdf_sciverse	Sciverse 全能力分发：search（agentic 片段）/ content（读全文）/ meta_search（元数据）/ relations（引文图谱）/ catalog（字段目录）/ resource（图表附件）	query、doc_id、unique_id、relation、top_k、page/page_size、offset/limit、file_name、filters_json、sort_json、fields、enrich_dois、年份/语言/期刊/主题/作者/DOI/引用数字段
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 而不是逐条失败。

Sciverse 能力：配置 sciverse_api_key（https://sciverse.space/tokens）后，`scansci_pdf_search` 会自动并入 agentic-search 证据片段和 meta-search 元数据（记录带 doc_id/unique_id/evidence/页码）；需要原始 chunk、精确元数据、引文图谱或图表时用 scansci_pdf_sciverse。分场景：统一 search 默认补 DOI（多 1 次 doc_id 定向 meta-search）；单独 action="search" 默认不补，需要下载时传 enrich_dois=true。action="relations" 的 REFERENCES 可能只返回 OpenAlex ID、标题为空；实测这些 ID 在 OpenAlex 不可解析，保留 ID 由调用方处理。meta-search 的 total_count 到 10000 是上限，返回 total_count_capped=true。agentic 的 filters_json 是对象（字段间 AND、同字段列表内 OR，doc_ids 硬范围 ≤1000）；meta-search 的 filters_json 是 {field, operator, value} 数组，算子用 FILTER_OP_*。sciverse_meta_search_enabled=false 可省掉每次 search 的第二路 Sciverse 配额（同时关闭统一 search 的 DOI 补全）。

配置、通道与诊断

工具	功能	关键参数
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（キーを検証）
scansci_pdf_springer_setup	Springer TDM 全文 API Key の設定と利用権限の確認	test（キー／機関購読を検証）
scansci_pdf_sciverse_setup	Sciverse API Token 設定ウィザード（コンソールを開き、保存して検証。意味的エビデンス／メタデータ／引用グラフ／図表を有効化）	token、test

ワークフローのオーケストレーション

フロー 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 的等价组合）

フロー 2.5：機関認証方式とブラウザーを先に決める（フロー 3／4／5 の事前判断）

機関認証で失敗する原因の多くは「ダウンロードできない」ことではなく、次の 2 点が決まっていないことです。

① ブラウザー：scansci_pdf_login が開くのは、ツールに付属する可視のアンチディテクションブラウザーです。Cookie はそのコンテキストから取得され、ディスクに保存されます。ユーザーが付属の Safari／Edge／普段使っている Chrome でログインしたり、ヘッドレスモードを使ったりしても、ログイン状態は取得できません。要件：browser_headless=false（機関ログイン／CAPTCHA／Cloudflare には可視ウィンドウが必要です）。バックエンドには camoufox または cloakbrowser を使用してください（patchright 1.56~1.61 には Turnstile で空白ページになるバグがあります）。ユーザーが自分のブラウザーの使用を希望する場合、無理に止める必要はありません。代替策は 2 つあります。config-cmd browser_executable "<他的 Chrome 路径>" で使用するブラウザーを指定するか、scansci_pdf_login(kind="cookie_import", cookie_file="cookies.txt") で Netscape cookie をインポートします（CARSI は別途、ローカルマシンの Chrome の cookie ライブラリを自動で読み込みます）。

② 出口 IP：出版社（特に Elsevier）は、リクエスト元 IP に基づいて利用権限を判定します。マシンでシステム／グローバルプロキシを有効にすると、ツールとブラウザーの出口がプロキシの出口に変わり、機関認証がただちに無効になります。典型的な症状は、pdf.sciencedirectassets.com が「要求されたコンテンツの提供に問題がありました」（CPE コード付き。ページには検出された IP が表示されます）を返すことです。まずその IP が機関のネットワーク範囲に属するかを確認してから、「学校が購読していない」と判断してください。 ツールが認識するのは network_proxy／SCANSCI_PDF_PROXY のみで、HTTP_PROXY／HTTPS_PROXY は無視します。

状況	方法	設定方法
学内（IP 認証）	直接接続	is_campus_network=true
学外 ＋ 出版社がフェデレーション認証に対応	WebVPN より CARSI を優先	config-cmd carsi_idp_name <学校>
学外 ＋ 学校に WebVPN ゲートウェイがある	WebVPN	フロー 3
学校が EasyConnect/aTrust のみ提供	SOCKS5 コネクター	network_proxy=socks5://…。自己署名証明書には institutional_allow_self_signed が必要です
学校が図書館プロキシを提供	EZProxy	ezproxy_login_url（プレフィックス形式／ドメイン書き換え形式）
Elsevier／Springer のキーがある	API 経路。1～2 秒／件で、ブラウザー不要	フロー 5／Springer TDM

学校名をユーザーに代わって推測しないでください。scansci_pdf_schools(action="search") で検索し、ユーザーに確認してもらいます。プロジェクトの方針では「学校をデフォルトで設定しない」と明確に定めています。

フロー 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 の事前設定は不要です
• Cookie は保持されるため、同じ出版社へのログインは一度で済みます
• ブラウザーエンジンは CloakBrowser（Playwright 互換のアンチディテクションブラウザー）で、Cloudflare Turnstile を通過できます。出版社は TLS フィンガープリントを検知するため、Cookie を付けても Python HTTP クライアントでは 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：Sciverse の意味検索とメタデータ（任意、推奨）

1. scansci_pdf_sciverse_setup → 打开 https://sciverse.space/tokens，创建 API Token
2. scansci_pdf_sciverse_setup(token="...", test=true) → 保存并验证
3. scansci_pdf_search(...) → 自动并入语义证据片段 + meta-search 元数据
4. 需要原始片段/元数据/引文图谱/图表：scansci_pdf_sciverse(action="search|meta_search|relations|resource", ...)

ポイント：設定しなくても、既存の検索やダウンロードには影響しません。未設定の場合、検索結果には config_hint が含まれ、設定方法が示されます。各検索ではデフォルトで agentic と meta の 2 経路を実行します。クォータが厳しい場合は、scansci_pdf_config(key="sciverse_meta_search_enabled", value="false") を設定してください。

フロー 7：内蔵 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")

フロー 7：ある研究者の被引用数 TOP-N 論文

1. 解析作者 ID（不要用 author=姓名 直接搜，见「已知坑位」）
   GET https://api.openalex.org/authors?search=<姓名>
   → 取被引最高、同被引再看 works_count 最大的那条，核对 last_known_institutions 是否含目标单位
2. 取代表作（务必加 type:article，否则数据集/paratext 会混进榜）
   GET https://api.openalex.org/works?filter=author.id:<ID>,type:article
       &sort=cited_by_count:desc&per_page=25
3. scansci_pdf_batch_download(identifiers=[DOI...], output_dir=<宿主已授权的目录>)
4. 校验 + 去重（下载器会为每篇留下多份源标记副本，见「已知坑位」）

対応範囲

リクエスト	対応方法
論文の内容を読む／理解する	非対応です。PDF のダウンロードのみです（markdown=true で AI が読み取れるテキストレイヤーを利用できます）
論文を翻訳する	別のツールが必要です
文献レビュー／要約を作成する	LLM に PDF を読み取らせて生成する必要があります
学術論文以外の PDF をダウンロードする	非対応です
ユーザーが DOI なしでタイトルを指定した	先に search で DOI を取得してからダウンロードします
100 件以上を一括処理する	batch_download を使います。並列数は batch_workers 設定で制御されます
機関のアクセス権が必要な論文	login でログインしてから、ダウンロードを再試行します
ダウンロードに失敗した	結果に error_type が含まれます。paywall → ログインフロー、rate_limited → 少し待って再試行、cloudflare_blocked → CloakBrowser を起動／プロキシを設定

已知坑位（2026-10-22 实测，agent 必读）

• search 的 author= 曾经会命中同名假档案（2026-10-22 已修）。传 author="Shilong Piao" 时旧版只返回 1 条 figshare 数据集，命中 A5072538516（1 篇 / 0 被引）：权威档案 A5000033522（999 篇 / 125 224 被引）因为带中间名缩写 L. 不算"精确匹配"而被排除，max() 于是在假档案里选。现已改为名字 token 兼容（容忍中间名缩写、紧凑缩写 L.Piao、姓在前；Jr/Sr/III/IV 不同会被拒绝）后取最大，并在 _author_match 里返回 exact、fallback 与 alternatives。旧版仍会选错，此时先解析 author_id 再用 author_id= 调；看到 exact=false、fallback=true 或 alternatives 非空时，核对一下选中的是不是目标学者。
• batch_download 的 failed 计数曾经会骗人（2026-10-22 已修）。车道模式下重试成功的 DOI 会留两行（先 failed 后 success），旧版按行计数，于是 total 大于去重条数（实测 24 > 20）、failed: 4 与 succeeded: 20 同时出现。现已由 server._merge_lane_results 按论文合并（成功覆盖失败，新增 retried 计数）。旧版或其它宿主的返回仍可能这样，此时以 failed_dois 和每条的 success 为准。
• 每篇会落 2–4 个源标记副本。除自动改名的 Piao2009_Carbon.pdf 外，还可能留 10.xxxx_Sci-Hub.pdf、_CrossrefPage.pdf、_NatureDirect.pdf、_PublisherDirect.pdf、_OpenAIRE.pdf；其中一份与最终改名文件逐字节相同（实测 20 篇留下 34 个多余副本）。交付前必须去重，否则文件夹里全是同一篇的多份副本。
• output_dir 不要指向宿主运行时新建的子目录。在 DSH 这类沙箱宿主里，由非沙箱进程（MCP server 自己）创建的子目录拿不到沙箱写权限：write 工具能写，但 pwsh 之后在同一目录里新建或删除任何文件都报 Access denied，把"删几个副本"拖成一轮权限排查。先让宿主在自己的目录里建好目标文件夹，再下到那里。
• 校验用轻量手段：大小 ≥ min_pdf_size_bytes（默认 10 000）+ 头 5 字节 %PDF- 即可判定；要页数就用 pymupdf 一次跑完。实测 _check.py 第一版把 doc.close() 写在 doc.page_count 之前，20 篇全报 "document closed"，白跑一轮。
• 非正式版本要点出来：机构库存档稿（"Accepted Article"、"archived peer-reviewed author-version"）与 early-online-release 都是合法 PDF，但页数和排版与正式版差别很大（实测 71 页 vs 正式版约 20 页），交付时要说明版本性质。
• 合作者不等于通讯作者：OpenAlex 按署名计入，大团队论文（Crowther / Luyssaert / Janssens 领衔）会出现在"某人的高被引"列表里；报告时要区分本人主导与合作署名。

常见边界情况

• 科学符号（版权 ©、重音姓名）在 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")