mcp-pergaminos

学术论文检索与 OA 对账 MCP 服务器。只报告元数据与获取路径，不下载全文。

名字取自加西亚·马尔克斯《百年孤独》里的墨尔基阿德斯（Melquíades）—— 那个把布恩迪亚家族百年史写在羊皮卷上、并且 「没有按人类惯常的时间顺序来排列这些事件」的人。本项目与同为该出处的 [mcp-melquiades]（会话档案）共享这一母题：身份稳定，顺序易变。

它做什么

两个工具，只有两个：

Related MCP server: paper-search-mcp

它不做什么

不下载全文。没有、也不会有下载工具。 四条理由：

1. 版权 —— arXiv 使用条款「不得做的事」明文禁止：*"Store and serve arXiv e-prints (PDFs, source files, or other content) from your servers, unless you have the permission of the copyright holder"*，并且明确 "arXiv is not the copyright holder"。 我们既不是版权持有人，也没有获得许可。

2. 限速 —— arXiv 官方要求「每 3 秒不超过 1 次请求，且限于单连接」， 而且这个限制适用于「你控制的所有机器合计」。一次全文抓取就吃掉 3 秒额度， 对账 20 篇就是 60 秒纯等待。

3. 静默降级 —— 出版商站点常有反爬/登录墙；失败常表现为 HTTP 200 但内容是一个 PDF.js 空壳。模型会以为拿到了论文， 然后基于一页 JavaScript 编出结论。这比报错更危险，所以从接口层消除。

4. 成本 —— 若启用 OpenAlex，官方定价把全文下载定为检索的 10 倍（$10 vs $1 / 1000 次）。

拿到 DOI 与获取路径之后，由人决定怎么取。

数据源与覆盖边界

各源覆盖不同，所以默认按源分组返回，不做推断式合并。 这是有意的： 合并会掩盖「这条来自哪儿」，而不同源的可靠性并不相同。

已知的边界（不知道这些会误判）

• Unpaywall 不能检索。 它的 /v2/search 已于 2026-09-18 废止（返回 410 Gone）。 现在只能按 DOI 查。

• Crossref 搜不到 arXiv 预印本。 arXiv 的 DOI 由 DataCite 注册，不在 Crossref。

• Crossref 的摘要有很大空缺（实测常见 abstract 为空）；arXiv 则稳定提供摘要。

• 同一篇论文可能有两个 DOI（预印本 + 正式版）。所以合并只做 DOI 精确匹配， 绝不按标题猜测——merge=true 也只做精确匹配。

• OA 分类法的值集两源不同：Unpaywall 是 5 值 （gold/hybrid/bronze/green/closed），OpenAlex 多一个 diamond。 本工具以 Unpaywall 为准，若启用 OpenAlex 会在 conflicts 里显式记差异。

配置

优先级：真实环境变量 > .env > 代码内兜底。 代码内的兜底常量只放可公开的安全默认值——本项目要发布， 任何"为了跑得通向里塞一下"的值都会随发布泄露。

cp .env.example .env
$EDITOR .env

必填一项：

PERGAMINOS_UNPAYWALL_EMAIL=you@example.com

常用项见 .env.example。代理支持 http:// 与 socks5:// （后者需要 socksio，即 pip install 'httpx[socks]'），并可按源豁免：

PERGAMINOS_PROXY=http://127.0.0.1:8994
PERGAMINOS_PROXY_BYPASS=arxiv

启动时会把每个源的生效配置打印到 stderr——代理、池、超时、节流值。 这是故意的：配置配错了却看不出来（「静默指错」）比崩溃难查得多。

运行

依赖：mcp>=2.2、httpx（含 socksio 可选）。

python -m pergaminos.server          # stdio

MCP 客户端（如 DSH）配置示例：

- name: pergaminos
  command: bash
  args: ["-l", "/path/to/mcp-stdio.sh", "pergaminos"]

设计要点（给要改代码的人）

• 所有 HTTP 出网必须走 pergaminos/net.py 的 request()。 上一代有 29 个各自为政的出网点，策略必然漂移。这里只有一个权威。

• 重试策略的数值有出处（net.py 文件头有完整交代）：total=5、backoff=0.5 （退避序列 0/1/2/4/8，累计 15s）。特别注意 429 被显式排除在可重试状态之外——匿名共享池的限流是持续状态，退避救不回来。

• 跨进程节流（xlock.py）：arXiv 的限速是"全机器合计"， 而本机可能同时跑多个实例，所以互斥必须落到内核对象上。 POSIX 用 flock，Windows 用 CreateMutexW（真·有名互斥体，ctypes，无需 pywin32）。 双平台均有自检脚本：tools/verify_throttle_crossproc.py。

• 每源有总预算（PER_SOURCE_TIMEOUT_MS）：上一代用 asyncio.gather 无预算， 结果是「等最慢协程 ⇒ 每次搜索白等 15 秒」。现在是并行 + 每源硬预算， 总耗时 ≈ max(各源) 而非求和。

• 上游结构变化必须显式报错（UPSTREAM_CHANGED），绝不静默返回空。 这条不是洁癖：Unpaywall 的 /v2/search 在 2026-09-18 刚变成 410 Gone。

• 控制台输出一律 ASCII。 Windows 控制台默认 GBK(CP936)， 中文与 emoji 会乱码甚至 UnicodeEncodeError 崩溃——实测单一个 ✅ 就足以让脚本挂掉。 协议输出走 json.dumps(..., ensure_ascii=True)，任何编码都安全。

自检

python tools/verify_throttle_crossproc.py 4 3000   # 跨进程节流（双平台）
python tools/smoke_e2e.py                          # 端到端（需联网）

许可

代码：AGPL-3.0（见 LICENSE）。

数据：不适用本仓库的许可。本工具只是转发，数据的权利归各来源：

• arXiv 的描述性元数据以 CC0 1.0 释出（官方明文）；e-print 正文的版权归作者或出版方。

• Crossref、Unpaywall、OpenAlex 的数据适用其各自的服务条款。

本工具不存储、不代持、不镜像任何论文全文。