biorxiv-mcp-server

---

概述

bioRxiv 和 medRxiv 预印本、元数据及全文。按关键词和作者搜索，浏览日期区间（可选按主题筛选），按 DOI 获取任意预印本，并查看哪些预印本后来发表在期刊上。

工具

工具	描述
biorxiv_get_preprint	按 DOI 获取一个或多个预印本的完整元数据、摘要、修订历史及期刊对应信息
biorxiv_list_recent	列出在指定日期区间内发布或更新的预印本，可选按服务、类别和资助方筛选
biorxiv_search_preprints	通过 EuropePMC 按关键词和/或作者搜索预印本，以获得相关性排序，并补充 bioRxiv/medRxiv 元数据
biorxiv_get_published_version	将预印本 DOI 对应到其期刊发表记录（期刊 DOI、名称、发表日期），或将期刊文章 DOI 对应到作为其发布版本的预印本
biorxiv_list_published_versions	列出在指定期刊发表日期区间内作为期刊文章发表的预印本，不论其发布日期，可选按一家出版商筛选
biorxiv_get_fulltext	尽可能将预印本渲染后的 HTML 文章页面提取为 Markdown，以获取其全文
biorxiv_list_categories	列出 bioRxiv 和 medRxiv 的有效主题类别字符串

能力参考

biorxiv_get_preprint _工具

• 接受裸 DOI 或粘贴的 DOI（https://doi.org/…、doi:…、biorxiv.org/medrxiv.org 文章 URL、vN 或 .full 后缀），可限定为 biorxiv、medrxiv 或 both（默认值为 both）
• 最多接受 200 条，并查询前 10 个不同的 DOI；其余条目会返回在 unprocessed[] 中，供后续调用传入。重复的 DOI 只查询一次，所有列表均保持输入顺序
• 每篇预印本都会在 revisions[] 中返回完整的修订历史，包括标题、作者、类别、许可证、awards、jatsxmlUrl、接受发表后才有的 publishedJournalDoi，以及发现该预印本的 server（biorxiv 或 medrxiv，可直接作为 server 传回）。由于上游 API 会错误归属资助方，因此不返回资助方名称
• 摘要仅显示在最新修订版中：上游 API 每篇预印本只保留一份摘要。较早修订版自己的摘要可在其文章页面中查看，也可通过带 version 的 biorxiv_get_fulltext 获取
• 查询失败的 DOI 会列在 failed[] 中，并附带 reason（not_found、invalid_doi_format、upstream_unavailable、rate_limited）和 retryable 标志；只有在所有尝试的服务均已响应时，才会标记为 not_found

---

biorxiv_list_recent _工具

• 接受 start_date/end_date 时间区间、server（默认值为 both），以及可选的 category（取值来自 biorxiv_list_categories）和仅适用于 bioRxiv 的 funder（ROR ID）筛选条件；无法应用的筛选条件会触发 invalid_category 或 invalid_funder
• 每页 30 条，使用整数 cursor 翻页，并按服务分别跟踪（{ biorxiv: { cursor, total }, medrxiv: { cursor, total } }）；超过最后一页的游标会标记为 exhausted: true，未响应的服务会列在 failed[] 中
• 默认不返回摘要；设置 include_abstract: true 可将摘要加入结果。每条摘要均为该预印本最新修订版的摘要，即使对应条目是较早的修订版

---

biorxiv_search_preprints _工具

• 接受 query 和/或 author，以及可选的 date_from/date_to 和 server（默认值为 both）；每页最多返回 100 条结果（默认值为 25；limit 大于 100 时仍返回 100 条，并附带提示），使用 cursor_mark 翻页
• EuropePMC 为匹配结果排序（会在预印本发布后 1–2 天内将其编入索引），bioRxiv/medRxiv API 则会使用与 biorxiv_get_preprint 相同的字段补充信息；仅包含 EuropePMC 元数据的记录会带有 enriched: false 和 enrichment_error（service_error、rate_limited、not_found），并设置 partial_results
• 默认包含摘要；设置 include_abstract: false 可省略摘要，使响应大小缩减至约三分之一

---

biorxiv_get_published_version _工具

• 接受一个 DOI 和 server（默认值为 both）：可以是预印本 DOI（10.1101/、10.64898/），也可以是期刊文章的 DOI，后者会解析到该文章以预印本形式发布时的 DOI（10.1016/j.cell.2020.01.001 → 10.1101/614172）；10.64898/ DOI 会通过预印本自身的期刊 DOI 解析
• 返回预印本 DOI、期刊 DOI、期刊名称、发表日期、通讯作者所属机构，以及响应的 server；如果没有任何服务响应，则会触发可重试的 upstream_unavailable 或 rate_limited，绝不会触发 doi_not_found
• Cold Spring Harbor Laboratory Press 的期刊 DOI（10.1101/gr.…、gad.…、lm.…）与预印本共用 DOI 前缀，无法通过 DOI 解析

---

biorxiv_list_published_versions _工具

• 接受期刊发表日期的 start_date/end_date 区间，以及 server（默认值为 both）；每一行都对应 biorxiv_get_published_version 返回的记录，也可能是数年前发布的预印本
• 每个服务返回 limit 行（默认值为 25，最多为 API 单页的 100 行），从整数 cursor 开始，并通过每个服务的 nextCursor 继续查询；游标超出最后一行时会标记为 exhausted: true，未响应的服务会列在 failed[] 中
• 可选参数 publisher 为期刊 DOI 前缀（eLife 的前缀为 10.7554），可仅列出在该期刊前缀下发表的 bioRxiv 预印本；server: "both" 只查询 bioRxiv，而 server: "medrxiv" 或 API 无法识别的前缀会引发 invalid_publisher。这些行不包含期刊名称、作者或摘要
• 默认不包含摘要；设置 include_abstract: true 可将摘要加入结果

---

biorxiv_get_fulltext _工具

• 接受 DOI、server（默认值为 both）和可选的 version（或 vN 后缀；两者必须一致，若预印本没有该版本则会引发 version_not_found）；返回从渲染后的 HTML 文章页面提取的 Markdown，并标明响应的 server
• 页面上不包含表格单元格：每个表格都会保留其标题，omittedTables 会列出表格标题及提供单元格内容的 URL
• 通过 offset/limit 按字符分页（默认值为 20,000），并报告 totalChars、remainingChars、hasMore 和 wordCount；仅提供 PDF 的预印本和被拦截的页面会引发 fulltext_unavailable，并指向 biorxiv_get_preprint

---

biorxiv_list_categories _工具

• 不调用 API——这是一个静态列表，包含 25 个 bioRxiv 类别和 51 个 medRxiv 类别，仅限列表 API 支持筛选的类别
• 使用它为 biorxiv_list_recent 选择 category

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可替换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志记录。

bioRxiv 专属功能：

• BiorxivApiService 封装 api.biorxiv.org（详情、出版物和交叉映射端点），EuropePmcService 封装 EuropePMC 搜索；二者都支持重试和指数退避
• BiorxivFullTextService 从 www.biorxiv.org / www.medrxiv.org 上的文章页面提取 Markdown
• 每个上游重试流程都在工具调用单次 50 s 预算的剩余时间内运行，因此无响应的源站会在客户端的 60 s 请求超时前结束——要么返回分类后的可重试错误，要么在卡住的步骤为可选步骤时返回说明缺失内容的结果
• 当 server="both" 时并行查询 biorxiv 和 medrxiv，每个结果都标明响应的服务；按 DOI 查询时，一旦存有该 DOI 的服务响应，就停止等待
• 根据 Cold Spring Harbor Lab API 指南，使用包含 mailto 地址的规范 User-Agent 标头（BIORXIV_MAILTO 环境变量）
• 可与 pubmed-mcp-server（发表后数据）、openalex-mcp-server（引用分析）和 crossref-mcp-server（DOI 元数据）配合使用

适合 Agent 的输出：

• 优雅处理部分失败——每个 DOI 和每个服务的失败都会以带类型的 reason 和 retryable 标记记录在 failed[] 中，而不会中止调用
• 透明显示速率限制——429 响应会以 reason: "rate_limited" 返回，并附带解析出的 retryAfter 等待时间；该原因与 upstream_unavailable 区分开来
• 带类型的增强状态——biorxiv_search_preprints 结果包含 enriched 和带类型的 enrichment_error（service_error / rate_limited / not_found）
• 清理标题和摘要——将导出标记和符号占位符（{beta}、[≥]）转换为纯文本

入门

公共托管实例

公共实例位于 https://biorxiv.caseyjhand.com/mcp，无需安装。通过 Streamable HTTP 将任意 MCP 客户端指向此实例：

{
  "mcpServers": {
    "biorxiv-mcp-server": {
      "type": "streamable-http",
      "url": "https://biorxiv.caseyjhand.com/mcp"
    }
  }
}

自托管 / 本地

将以下内容添加到 MCP 客户端配置文件中。

{
  "mcpServers": {
    "biorxiv-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/biorxiv-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "BIORXIV_MAILTO": "[email protected]"
      }
    }
  }
}

或者使用 npx（无需 Bun）：

{
  "mcpServers": {
    "biorxiv-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/biorxiv-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "BIORXIV_MAILTO": "[email protected]"
      }
    }
  }
}

或者使用 Docker：

{
  "mcpServers": {
    "biorxiv-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "-e", "[email protected]", "ghcr.io/cyanheads/biorxiv-mcp-server:latest"]
    }
  }
}

对于 Streamable HTTP，设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 [email protected] bun run start:http
# Server listens at http://localhost:3010/mcp

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/biorxiv-mcp-server.git

2. 进入目录：

cd biorxiv-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# optionally set BIORXIV_MAILTO for polite API access

配置

启动时会通过 src/config/server-config.ts 中的 Zod schema 校验所有配置。

变量	描述	默认值
BIORXIV_MAILTO	User-Agent 标头使用的电子邮件地址；可选，但建议设置。	—
BIORXIV_API_BASE_URL	覆盖 bioRxiv API 基础 URL。	https://api.biorxiv.org
EUROPEPMC_API_BASE_URL	覆盖 EuropePMC 基础 URL。	https://www.ebi.ac.uk/europepmc/webservices/rest
BIORXIV_WEB_BASE_URL	覆盖 bioRxiv 网站基础 URL（biorxiv_get_fulltext 的全文 HTML 来源）。	https://www.biorxiv.org
MEDRXIV_WEB_BASE_URL	覆盖 medRxiv 网站基础 URL（biorxiv_get_fulltext 的全文 HTML 来源）。	https://www.medrxiv.org
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_HTTP_ENDPOINT_PATH	HTTP 端点路径。	/mcp
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）。	info
LOGS_DIR	日志文件目录（仅 Node.js）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	记录每次失败工具调用的参数和结果，并按键名脱敏；日志大小上限由 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES 决定（默认 16384）。自由格式值中的秘密信息不会被脱敏。	false
OTEL_ENABLED	启用 OpenTelemetry 插桩。	false

完整的可选覆盖项列表请参见 .env.example。

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t biorxiv-mcp-server .
docker run --rm -e [email protected] -p 3010:3010 biorxiv-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/biorxiv-mcp-server。默认会安装 OpenTelemetry 对等依赖；构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖。

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具并初始化服务。
src/config	解析并校验服务专用环境变量，使用 Zod。
src/mcp-server/tools	工具定义（*.tool.ts）。涵盖 bioRxiv 和 medRxiv 的七个工具。
src/services/biorxiv	BiorxivApiService——详情、出版物和 crosswalk 端点封装，并支持重试。
src/services/biorxiv-fulltext	BiorxivFullTextService——获取渲染后的 HTML 文章页面并提取 Markdown。
src/services/europe-pmc	EuropePmcService——预印本关键词 / 作者搜索端点封装。
tests/	单元测试和集成测试，结构与 src/ 对应。

开发指南

开发指南和架构规则请参见 CLAUDE.md。简要说明：

• 处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围内的日志，使用 ctx.state 存储租户范围内的数据
• 通过 src/mcp-server/tools/definitions/index.ts 中的 barrel 文件注册新工具
• 封装外部 API 调用：校验原始数据 → 规范化为领域类型 → 返回输出 schema；绝不伪造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参见 LICENSE。