cern-inspire-mcp-server

---

概述

来自 INSPIRE-HEP 的高能物理文献及其背后的 HEPData 表格。搜索论文、作者和实验，计算引文摘要和 h 指数，导出 BibTeX 或 LaTeX，并查找保存论文数值数据的记录。

工具

工具	描述
cern_inspire_search_literature	使用 INSPIRE 查询语法或自由文本搜索论文，并按文档类型、主题和年份筛选
cern_inspire_get_paper	通过 recid、arXiv ID 或 DOI 获取单篇论文的完整记录及其 HEPData 可用性
cern_inspire_export_citations	导出查询所选论文的 INSPIRE BibTeX 或 LaTeX \bibitem 条目
cern_inspire_search_authors	通过姓名、BAI、ORCID、INSPIRE ID 或作者 recid 查找物理学家档案
cern_inspire_get_citation_summary	获取单位作者或任意文献查询的 h 指数、引文总数、引文分组和逐年引文数
cern_inspire_search_experiments	查找实验、合作组和设施，并通过查询选取其论文
cern_inspire_search_hepdata	按过程、可观测量、能量或合作组查找 HEPData 测量记录
cern_inspire_list_reference	解码查询语法、标识符格式、筛选值、引文分组和 HEPData DOI

资源

资源	描述
inspire://literature/{recid}	一条文献记录，以 JSON 格式呈现为 cern_inspire_get_paper 档案

对于无法显示资源的客户端，同一条记录也可通过 cern_inspire_get_paper 获取。

Agent 技能

cern-inspire-guide 涵盖标识符路由、查询语法和研究工作流。插件安装包、npm、Docker 和 Claude Desktop 套件均包含此技能。MCP 客户端可通过 skills/list 发现此技能，也可以从 resources/list 读取 skill://cern-inspire-guide/SKILL.md。

功能参考

cern_inspire_search_literature _工具

• 支持 INSPIRE 查询语法或自由文本，并可使用 sort（relevance、mostrecent、mostcited）、document_types 和 subjects（各最多 4 个值，且必须全部匹配），以及 year_from / year_to；size 为正整数（默认值为 10，最大为 100），通过 page 分页
• 查询只能访问前 10,000 条结果：page × effective size 超出此范围时会失败并返回 beyond_result_window；年份范围逆序时会失败并返回 invalid_year_range
• 匹配结果包含 recid、标题、第一作者、日期、引用次数、arXiv ID、DOI、出版物和 300 个字符的摘要片段；页面还会返回 totalCount、nextPage 和 appliedFilters，若查询匹配超过 100,000 条记录，则会在 notice 中标记

---

cern_inspire_get_paper _工具

• paper 可接收 recid、arXiv ID、DOI、inspirehep.net 文献 URL，或 HEPData ins<recid> / hepdata.net record/ins<recid> URL；resolvedAs 指明匹配的形式，未找到时会失败并返回 paper_not_found。合并后的 recid 会返回保留的记录，并通过 mergedFrom 指明请求的 recid
• max_authors（默认值为 25，上限为 500）和 author_offset（默认值为 0）用于对贡献者分页；传入 nextAuthorOffset 可继续获取。条目会保留记录中的 roles（如编辑或导师）；缺失的角色仍视为未知。authorCount 保留 INSPIRE 的计数；若没有，则使用可用贡献者列表的长度
• documents 列出公开的附件 URL，以及记录的文件名、描述、材料和全文状态；隐藏的条目和没有 URL 的条目会被省略。不会下载文件。外部 urls 会单独列出；citingQuery 和 referencesQuery 可用于 cern_inspire_search_literature
• hepdata.status 的值为 available、none 或 lookup_failed；若有数据，则还会返回 recordDoi、latestVersion、tableCount 和 hepdataUrl；其他 HEPData 记录会列在 hepdata.otherRecords 中

---

cern_inspire_export_citations _工具

• 支持任意文献查询（指定论文可用 recid:451647 or arxiv:1207.7214），并支持与搜索相同的 document_types、subjects、year_from、year_to 和 sort；年份逆序时会失败并返回 invalid_year_range
• format 的值为 bibtex（默认值）、latex-eu 或 latex-us；size 为正整数（默认值为 10，最大为 50），通过 page 分页，范围限于前 10,000 条匹配结果（超出时返回 beyond_result_window）
• 条目直接采用 INSPIRE 的原文，每条均带有 texkey；truncated 和 nextPage 用于指示是否还有更多结果，appliedFilters 会回显所选筛选条件

---

cern_inspire_search_authors _工具

• 支持姓名或一个标识符（BAI、ORCID、INSPIRE ID、作者 recid）；limit 为正整数（默认值为 5，最大为 25）
• matchedAs 的值为 orcid、inspire_id、bai 或 recid（精确匹配），也可以是 name（自由文本搜索，返回按相关度排序的候选项供选择）
• 作者档案包含 recid、bai、ORCID、职位（其中 institutionRecid 可通过 affid:N 用于查找该机构的论文）、导师、arXiv 类别、奖项，以及用于筛选此人论文的 literatureQuery

---

cern_inspire_get_citation_summary _工具

• author（BAI、ORCID、INSPIRE ID 或作者 recid）和 query（任意文献查询，例如用于查询某机构论文的 affid:902725）必须且只能提供其中一项；否则会返回 missing_target，而将姓名作为 author 传入则会失败并返回 author_not_identifier
• 可通过 document_types、subjects、year_from、year_to 和 exclude_self_citations 缩小范围
• 返回 h 指数、引用总数和平均数，以及按 0、1–9、10–49、50–99、100–249、250–499、500+ 分档的论文数量；每档分别统计所有可引用论文和已发表论文
• 当设置了 year_from、year_to 或 exclude_self_citations，INSPIRE 未返回 citationsByYear，或查询匹配的记录超过约 150,000 条时，将省略 citationsByYear 并附上说明

---

cern_inspire_search_experiments _工具

• 实验、合作组、加速器或设施名称，INSPIRE 旧名称（CERN-LHC-CMS），或实验 recid（仅限数字）；limit 必须为正整数（默认值为 5，上限为 25）
• 记录包含加速器、主办机构、合作组、生命周期日期、ongoing（INSPIRE 记录未说明任一状态时会省略）、INSPIRE 的论文数量，以及可用于 cern_inspire_search_literature 或 cern_inspire_get_citation_summary 的 literatureQuery

---

cern_inspire_search_hepdata _工具

• 对 HEPData 提交内容进行自由文本或 INSPIRE 语法搜索（collaborations.value:LHCb、literature.control_number:<recid>）；sort 可设为 relevance 或 mostrecent；size 必须为正整数（默认值为 10，上限为 50），结果范围限制在同一个 10,000 条结果窗口内
• 记录包含 paperRecids、合作组、关键词（反应、可观测量、质心能量）、recordDoi、latestVersion、tableCount 和 hepdataUrl（每条记录对应的 hepdata.net 页面）；不返回表格数值

---

cern_inspire_list_reference _工具

• topic：search_syntax、identifiers、document_types、subjects、citation_buckets 或 hepdata
• 静态的 term / meaning / example 条目；不会调用上游服务

---

inspire://literature/{recid} _资源

• cern_inspire_get_paper 档案，格式为 application/json，包含前 25 位贡献者、记录的角色以及公开的附件链接
• 仅接受 recid；对于 arXiv ID、DOI 或更多贡献者页面，请使用工具。合并后的 recid 指向保留的记录，并带有 mergedFrom

功能

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

INSPIRE 专属功能：

• 将请求速率限制为每 5 s 12 次，低于 INSPIRE 的 15 次限制；收到 429 后会进入冷却期。无法及时启动的调用会以 pacer_shed 失败，并附带 retryAfter
• 每次工具调用的预算为 55 s，包括排队等待和最多 2 次重试
• 请求只选择工具会返回的字段；绝不请求作者的电子邮件地址
• 灵活的输入：论文标识符接受 arXiv: / doi: 前缀、版本后缀，以及 arxiv.org、doi.org 或 inspirehep.net URL；作者标识符接受 orcid.org URL

便于 Agent 使用的输出：

• 超过上限的正整数结果预算仍会成功，并提示请求值和实际生效值：文献为 100，HEPData 和引文导出为 50，作者和实验搜索为 25。默认值保持不变；零、负数和小数预算会失败。分页和 10,000 条结果窗口使用实际生效的大小
• 可链式使用的标识符：命中结果包含 recid，作者档案和实验包含可直接使用的 literatureQuery，而 cern_inspire_get_paper 会返回 citingQuery 和 referencesQuery
• 查询回显和分页状态：totalCount、truncated / shown / cap、nextPage、appliedFilters 和 effectiveQuery；结果为空、达到上限或范围异常宽泛时，还会附带包含后续步骤文本的 notice
• 可辨别的字段：hepdata.status、resolvedAs、matchedAs 和 target.kind 让调用方能够根据数据进行分支处理；带类型的失败原因（paper_not_found、author_not_found、beyond_result_window、inspire_rate_limited）均附带恢复提示
• 不会捏造内容：INSPIRE 未提供的字段会保持缺失，并显示为“不可用”或“未记录”
• 标题和摘要以文本形式呈现：出版商 HTML、JATS 和 MathML 会转换为纯文本（σ_γ、^{23}Na(n,γ)）；LaTeX 保持出版时的形式，引文导出条目则逐字保留

数据与许可

• INSPIRE-HEP 元数据大多采用 CC0 许可，具体见 INSPIRE 的使用条款；重用时请注明 INSPIRE。
• HEPData 记录采用 CC0 许可；重用数据时请引用 HEPData 记录 DOI（recordDoi）。
• 这是一个独立项目，与 INSPIRE-HEP、HEPData 或 CERN 无关联，也未获其认可。

已知限制

• 不提供 HEPData 表格数值。 hepdata.net 的机器人验证会拒绝该服务的 User-Agent，因此服务端不会调用它。cern_inspire_get_paper 和 cern_inspire_search_hepdata 会返回记录 DOI 和可查看数值的 hepdata.net 页面。
• 格式错误的 INSPIRE 语法大多不会导致失败。 文献搜索、引文摘要和引文导出会将已识别字段子句为空的情况（a:、a: not 或 a:""，包括仅含空格的带引号值）作为 invalid_query 拒绝；请为每个字段提供值（a Witten）。其他情况下，未解析的运算符会扩大或清空匹配范围；没有命中或 totalCount 非常大，通常意味着语法有误（cern_inspire_list_reference 的主题 search_syntax）。
• 选择验证会增加一次请求。 文献搜索会验证经过筛选的选择和后续页面；导出会验证经过筛选的第一页和所有后续页面。这样可以避免 INSPIRE 的参考文献回退绕过筛选条件或重复已耗尽的结果。必要的验证失败会导致调用失败；未筛选的第一页仍只需一次请求
• 10,000 条结果窗口。 每个查询只能访问前 10,000 条结果；请缩小查询范围以访问其余结果。
• 共享请求队列。 同一服务进程的所有调用方共用一个队列，该队列受 INSPIRE 对每个地址每 5 s 15 次请求的限制，因此突发请求可能会延迟其他调用，或使其因可重试的速率限制错误而被丢弃。

入门

连接到托管实例，无需安装：

claude mcp add --transport http cern-inspire-mcp-server https://cern-inspire.caseyjhand.com/mcp

托管实例的所有调用方共用一个 INSPIRE 请求预算，即每 5 秒最多启动 12 个请求。若需持续使用，请运行自己的实例：

claude mcp add cern-inspire-mcp-server -- npx -y @cyanheads/cern-inspire-mcp-server

对于其他客户端，请将以下内容添加到 MCP 配置文件中：

{
  "mcpServers": {
    "cern-inspire-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/cern-inspire-mcp-server"]
    }
  }
}

无需 API 密钥。有关 Docker 或从源代码构建的信息，请参阅运行服务。

配置

服务没有自己的设置：INSPIRE 无需密钥，请求间隔控制在代码中固定。这些框架变量适用于大多数部署。

变量	说明	默认值
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。.env.example 和 Docker 镜像设置为 stateless。	auto
MCP_AUTH_MODE	身份验证：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、notice、warning、error 等）。Docker 镜像设置为 info。	debug
LOGS_DIR	日志文件目录（仅限 Node.js）。	<app-root>/logs
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	启用 OpenTelemetry。	false

完整的框架配置项列表请参阅 .env.example。

运行服务

本地开发

需要 Bun v1.4.0 或更高版本（或 Node.js v24+）。INSPIRE-HEP 的 API 是公开的，无需密钥。

git clone https://github.com/cyanheads/cern-inspire-mcp-server.git
cd cern-inspire-mcp-server && bun install
cp .env.example .env
# Optional: change transport, logging, or session settings in .env

• 构建并运行生产版本：

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

• 运行检查和测试：

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

Docker

docker run --rm -p 3010:3010 ghcr.io/cyanheads/cern-inspire-mcp-server:latest

镜像默认使用 HTTP 传输、无状态会话，并将日志写入 /var/log/cern-inspire-mcp-server。对于使用 stdio 的 MCP 客户端，请使用 "command": "docker" 和 "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/cern-inspire-mcp-server:latest"]。使用 docker build -t cern-inspire-mcp-server . 在本地构建；添加 --build-arg OTEL_ENABLED=false 可省略 OpenTelemetry 对等依赖。

项目结构

目录	用途
src/index.ts	createApp() 入口：注册工具和资源，设置服务端说明，启动并释放 INSPIRE 服务。
src/mcp-server/tools	工具定义（*.tool.ts）和共享输入架构（inputs.ts）。
src/mcp-server/resources	文献记录资源。
src/services/inspire	INSPIRE 服务：请求间隔控制器、每次调用的预算、重试、标识符路由、规范化、受控词表。
src/services/http	有界抓取：每次尝试的超时和响应字节数上限。
src/utils	对工具输出和错误消息中的上游文本进行转义（render.ts）。
skills/	为调用此服务的 Agent 发布的 cern-inspire-guide。
tests/	使用 INSPIRE 响应样例的 Vitest 测试套件。
docs/design.md	工具接口、已验证的 INSPIRE 行为、设计决策，以及延期实现的 HEPData 直连工具。

开发指南

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

• 处理程序抛出异常，框架捕获异常——工具逻辑中不要使用 try/catch
• 每个 INSPIRE 请求都必须通过 InspireService 发出，并由 beginCall(ctx) 开始调用；处理程序不得直接调用 fetch
• 在 src/mcp-server/tools/definitions/index.ts 和 src/mcp-server/resources/definitions/index.ts 的汇总文件中注册新工具和资源
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不捏造缺失字段

贡献

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

bun run devcheck
bun run test

许可证

本项目采用 Apache 2.0 许可证。详情请参阅 LICENSE 文件。