preprint-fulltext

preprint-fulltext

English | 简体中文 | 繁體中文 | 한국어 | Deutsch | Español | Français | Italiano | 日本語

通过命令行、Python 库或 MCP 服务，获取 bioRxiv / medRxiv / arXiv 预印本的全文，并生成整洁、结构化、适合生成嵌入的数据。

preprint-fulltext 可将 DOI（或搜索结果）转换为结构化章节（摘要 / 引言 / 方法 / 结果 / 讨论）、单个 JSON/Markdown 文档，或适用于生成嵌入和 RAG 的分块 JSONL/Parquet 语料库。openRxiv 的文本与数据挖掘（TDM）合规性通过结构设计强制落实，而非交由用户自行处理。

“适合生成嵌入”意味着输出内容整洁、按章节组织，并且分块长度不超过令牌上限，可直接输入你自己的嵌入模型。计算嵌入是由你负责的可选最后一步；此工具不捆绑嵌入模型。

目录

• 为什么选择它 · 适用人群 · 面向 AI 驱动科学的全文
• 功能 · 安装 · 快速入门（命令行） · 典型工作流
• Python 库 · MCP 服务（编码 Agent） · 数据源与路由
• 配置 · 合规性 · 开发 · 联系 · 许可证

为什么选择它

预印本全文散落在彼此不兼容的渠道中：Europe PMC 为开放获取的部分论文提供 JATS XML，openRxiv 的 S3 存储桶保存权威的 .meca 语料库（由请求方付费），OpenAlex 是一个目录，只提供基于 n-gram 的全文搜索，而 bioRxiv/medRxiv 网站则以 HTML 呈现内容。preprint-fulltext 将这些来源统一到一个规范数据模型和一个通用的 JATS 解析器之后，无论文档来自何处，你都能获得相同的结构化输出。

适用人群

• 构建机器学习 / NLP 嵌入语料库或预印本文献 RAG 系统的研究人员。
• 需要将论文方法 / 结果作为整洁文本，用于分析、提取或大模型处理流程的生物信息学家和实验室。
• 需要在任务进行中获取预印本全文或搜索文献的编码 Agent（通过 MCP 服务 / SKILL.md）。
• 任何想要通过 DOI 获取单篇预印本的各个章节，而无需手动解析 JATS 或抓取 HTML的人。

面向 AI 科学研究的全文

语言模型和 Agent 对论文方法和结果的推理远比仅依据摘要可靠——大多数科学主张、实验方案、数量和注意事项都在正文中。preprint-fulltext 将正文以整洁、带章节标签并标注来源和许可的文本形式提供给 Claude、Codex 和其他 Agent，为有依据的科学推理和深度研究提供基础：

• 文献深度研究 — 阅读多篇论文的全文，而不仅是摘要。
• 方法／实验方案提取 — 提取准确的流程、参数和数据集。
• 主张核验 — 对照实际的 Results 章节，核查所述结果。
• 可重复性与荟萃分析 — 比较不同研究的方法和数据。
• 基于自有语料库的 RAG — 使用具备章节感知能力、受 token 数量限制且带引文的分块。

每个 Section／Chunk 都带有其 kind（methods / results / …）、source 和 license，因此 Agent 可以准确引用（指出论文及其版本中的具体章节），并在推理时遵守许可。全文用于检索，而非记忆：模型以原始来源为依据进行推理，而不是回忆可能已过时的摘要。

功能

• get <id> — 获取一篇预印本的全文，输出为结构化 JSON 或 Markdown。bioRxiv/ medRxiv 通过 Europe PMC → S3 获取（可选择启用 HTML 回退）；arXiv id 则通过 arXiv 的 LaTeXML 全文获取（原生 HTML → ar5iv）。默认使用最新版本；--version 可指定版本。
• search / discover — 在 Europe PMC、OpenAlex 和 arXiv 中按关键词、标题、摘要或作者搜索；也可按主题／类别／日期发现论文。
• ingest — 从 openRxiv S3 存储桶可恢复、增量式地批量摄取内容，生成分块语料库（JSONL 或 Parquet）及配套清单。
• MCP 服务 — 为编码 Agent 提供相同功能的工具。
• 内置合规机制 — 导出门禁会将不可再分发的作品降级为仅含链接的条目；未知许可按不可再分发处理（故障安全）。
• Europe PMC 和 S3 路径共用一个 JATS 解析器；分块会感知 token 数量和章节，并使用确定性、幂等的分块 id。

安装

pip install preprint-fulltext                       # CLI + Python library + MCP server
pip install "preprint-fulltext[parquet,openalex]"   # + Parquet output, pyalex

MCP 服务已内置——无需额外安装，也不依赖第三方 MCP 框架。它是一个小型、自包含的 JSON-RPC 2.0 stdio 服务端，只需核心依赖即可直接运行 preprint-fulltext-mcp。

请为 Europe PMC / OpenAlex 的礼貌请求池设置联系邮箱（建议），如果使用 OpenAlex，还需设置 OpenAlex API 密钥（自 2026-02-13 起为 OpenAlex 的要求）：

export CONTACT_EMAIL="[email protected]"
export OPENALEX_API_KEY="..."            # only needed for OpenAlex discover/search

快速入门（CLI）

# Structured full text for one preprint (Europe PMC → S3 router)
preprint-fulltext get 10.1101/2024.01.15.575000 --markdown

# Accepts a DOI, a doi.org URL, or a bioRxiv/medRxiv content URL
preprint-fulltext get https://www.biorxiv.org/content/10.64898/2026.06.13.731750v1.full --html --markdown

# Versions: the DOI resolves to the latest version by default; --version selects one
preprint-fulltext get 10.64898/2026.01.29.702557 --version 1 --source html --markdown

# arXiv: id, arxiv.org URL, or 10.48550/arXiv.* DOI — routed to arXiv LaTeXML full text
preprint-fulltext get arXiv:1706.03762 --markdown
preprint-fulltext get https://arxiv.org/abs/2401.10515 --markdown

# Search: keyword, title, or author (add --source arxiv to search arXiv)
preprint-fulltext search "cortical interneurons" -n 20
preprint-fulltext search "Fezf2" --field title
preprint-fulltext search "Min Dai" --field author
preprint-fulltext search "diffusion model" --field title --source arxiv

# Discover by topic + date window (OpenAlex)
preprint-fulltext discover --query "spatial transcriptomics" --since 2025-01 -n 100

# Bulk corpus from S3 (requester-pays; needs AWS credentials)
preprint-fulltext ingest corpus.jsonl --source s3 --server biorxiv --since 2025-06

# A free, no-AWS corpus of the open-access (CC) subset via Europe PMC
preprint-fulltext ingest corpus.jsonl --source europepmc --query "long covid"

get 输出 FullText 文档（JSON）或 Markdown（--markdown）。search / discover 每行输出一个 SearchHit（JSONL）。ingest 每行写入一个 Chunk，并附带 <out>_manifest.jsonl 审计／恢复配套文件。

典型工作流

1. 以文本形式阅读一篇论文的方法和结果。

preprint-fulltext get 10.64898/2026.01.29.702557 --markdown > paper.md
# -> # Title / ## Abstract / ## Introduction / ## Methods / ## Results / ## Discussion

2. 构建特定主题的嵌入就绪语料库（免费，无需 AWS）。

# CC/open-access subset via Europe PMC — one Chunk per JSONL line
preprint-fulltext ingest cortex.jsonl --source europepmc --query "cortical interneurons" -n 500
# cortex.jsonl          -> {doi, version, chunk_id, section_kind, text, token_count, license, ...}
# cortex_manifest.jsonl -> one row per preprint (doi, version, license, n_chunks, status)

3. 从 S3 构建某个月的完整语料库（请求方付费）。

export AWS_PROFILE=...           # needs AWS credentials; ~$0.09/GB
preprint-fulltext ingest 2025-06.jsonl --source s3 --server both --since 2025-06 --format parquet
# resumable: rerun after an interruption and it skips finished preprints (no duplicates)

4. 按作者或标题查找论文，然后获取全文。

preprint-fulltext search "Min Dai" --field author -n 20 > hits.jsonl
preprint-fulltext get "$(head -1 hits.jsonl | python -c 'import sys,json;print(json.load(sys.stdin)["doi"])')" --markdown

5. 为编码 Agent 提供文献访问权限 — 运行 preprint-fulltext-mcp 并将 Agent 指向它（请参阅 skills/preprint-fulltext/SKILL.md）。

Python

from preprint_fulltext.pipeline.router import Router

result = Router().get_fulltext("10.1101/2024.01.15.575000")
if result.fulltext:
    for section in result.fulltext.sections:
        print(section.kind, section.title)

from preprint_fulltext.core.chunk import chunk_fulltext
chunks = chunk_fulltext(result.fulltext)   # embedding-ready Chunk records

MCP 服务

为编码 Agent 提供实时预印本访问权限。该服务通过 stdio 提供四个工具 — search_preprints、get_fulltext、get_metadata、resolve。（批量 ingest 有意不作为工具提供：它运行时间较长，且会产生请求方付费的费用。）

mcp-name: io.github.genecell/preprint-fulltext

这是一个本地 stdio 服务，可在 Claude Code / Cursor / VS Code / Windsurf / Zed / Codex / Cline 中运行，但不能用于 claude.ai 网页应用（请在那里改用 技能）。

推荐：通过 uvx 运行（无需安装）

uv 可按需运行已发布的软件包，无需通过 pip install 安装，也无需将其保留在 PATH 中。只需安装一次 uv：

curl -LsSf https://astral.sh/uv/install.sh | sh    # macOS / Linux
# or:  pipx install uv  |  pip install --user uv  |  brew install uv  |  winget install astral-sh.uv

启动命令为 uvx --from preprint-fulltext preprint-fulltext-mcp（由于运行命令与软件包名称不同，因此需要使用 --from）。首次启动时会下载软件包（约需 30 秒）；之后的启动会使用缓存。

claude mcp add preprint-fulltext --scope user -- uvx --from preprint-fulltext preprint-fulltext-mcp
# uvx not on PATH? use its absolute path:
claude mcp add preprint-fulltext --scope user -- "$(which uvx)" --from preprint-fulltext preprint-fulltext-mcp
claude mcp get preprint-fulltext        # verify → Status: ✔ Connected

{ "mcpServers": { "preprint-fulltext": {
  "command": "uvx",
  "args": ["--from", "preprint-fulltext", "preprint-fulltext-mcp"],
  "env": { "CONTACT_EMAIL": "[email protected]" }
} } }

{ "mcpServers": { "preprint-fulltext": {
  "command": "uvx",
  "args": ["--from", "preprint-fulltext", "preprint-fulltext-mcp"],
  "env": { "CONTACT_EMAIL": "[email protected]" }
} } }

{ "servers": { "preprint-fulltext": {
  "type": "stdio",
  "command": "uvx",
  "args": ["--from", "preprint-fulltext", "preprint-fulltext-mcp"]
} } }

{ "context_servers": { "preprint-fulltext": {
  "source": "custom",
  "command": "uvx",
  "args": ["--from", "preprint-fulltext", "preprint-fulltext-mcp"],
  "env": {}
} } }

[mcp_servers.preprint-fulltext]
command = "uvx"
args = ["--from", "preprint-fulltext", "preprint-fulltext-mcp"]
# env = { CONTACT_EMAIL = "[email protected]" }

其他方式：通过 pip 安装

如果你已经通过 pip install preprint-fulltext 安装，服务会以 preprint-fulltext-mcp 的名称位于 PATH 中——在上述任一配置中使用 "command": "preprint-fulltext-mcp"（无需 args）。

**环境变量：**通过配置中的 env 区块设置 CONTACT_EMAIL（用于 Europe PMC / OpenAlex 礼貌访问池）和 OPENALEX_API_KEY（仅用于 OpenAlex 搜索/发现），也可以在启动客户端前于 shell 中设置。完整的面向 Agent 的工具参考请参阅 SKILL.md。

数据源与路由

配置

可通过环境变量（添加前缀 PREPRINT_FULLTEXT_ 或使用下方的裸名称）、 .env 文件或 preprint-fulltext.toml 进行配置：

合规

语料库仅供运营者根据 openRxiv TDM 条款进行文本／数据挖掘。 preprint-fulltext 不会重新托管或再分发预印本全文。每个 FullText／Chunk 都带有其许可证；导出关卡有两种模式：

• analysis（默认）：允许通过，用于你自己的挖掘。
• redistribution（--redistribution）：许可证允许再分发的作品保持原样通过；其他作品均会降级为回链占位内容（元数据 + URL，不含正文）。未知或有歧义的许可证均视为不允许再分发。

开发

pip install -e ".[dev]"
pytest              # offline suite (HTTP mocked with respx, S3 with moto)
ruff check preprint_fulltext/

实时测试为可选项（会调用真实的公共 API——Europe PMC、arXiv 和 bioRxiv/medRxiv JSON API）：

PREPRINT_FULLTEXT_LIVE=1 [email protected] pytest -m live   # EPMC / arXiv / medRxiv / versions
PREPRINT_FULLTEXT_LIVE_S3=1 pytest -m live_s3    # requester-pays S3 (small; needs AWS creds)

同样的实时冒烟测试会按需（Actions → live-smoke）及每周在 CI 中运行，以捕捉上游 API 的变动；默认的 test 工作流始终完全离线。

Agent 文档（AGENTS.md、llms.txt、.cursor/rules/…、.github/copilot-instructions.md） 由 skills/preprint-fulltext/SKILL.md 生成：

python scripts/build_agent_docs.py

联系方式

Min Dai — [email protected]（Gord Fishell Lab， Harvard Medical School / Broad Institute）。欢迎在 https://github.com/genecell/preprint-fulltext 提交问题和拉取请求。

许可证

BSD-3-Clause（参见 LICENSE）。此许可证仅涵盖软件—— 检索到的预印本内容仍受其作者选择的许可证约束。