cern-opendata-mcp-server

---

概览

CERN Open Data Portal 提供的粒子物理数据：来自 ALICE、ATLAS、CMS、LHCb 等实验的碰撞与模拟数据集、分析软件和文档。支持通过实时筛选项计数进行搜索、打开记录查看许可证和引用信息、列出数据文件、组装记录的分析环境，以及查询 CMS 优质运行列表和触发器路径。可作为 stdio 进程、本地 Streamable HTTP 服务运行，也可使用上方的公共托管端点。

工具

工具	说明
cern_opendata_search_records	搜索数据集、软件、环境、文档和补充记录，支持精确词汇筛选和实时分面计数
cern_opendata_get_records	每次调用最多按 recid、DOI、CMS 数据集路径或文档 slug 获取 20 条记录的完整元数据，包含许可证和引用信息
cern_opendata_list_files	分页查看记录的文件索引和文件：XRootD URI、HTTPS URL、大小、校验和、磁带可用性
cern_opendata_get_analysis_env	汇总记录的分析环境：容器映像、CMSSW 版本、全局标签、关联的环境和软件记录、指南章节
cern_opendata_get_validated_runs	获取数据集、列表或运行周期对应的 CMS 验证运行（good-run）列表，包含积分亮度区段范围
cern_opendata_search_trigger_paths	按名称或前缀查找 CMS 高级触发器路径，并解析为运行范围、版本和 L1 种子
cern_opendata_list_reference	解码其他工具接受的词汇：实验、记录类型、能量、格式、物理类别、LHCb stripping、标识符、查询语法、许可、运行周期

资源

资源	说明
cern-opendata://record/{recid}	一条记录的元数据、许可证和引用信息，采用 cern_opendata_get_records 的记录结构

仅支持工具的客户端可通过 cern_opendata_get_records 获取相同数据。

功能参考

cern_opendata_search_records _工具

• 可选的 query（OpenSearch query_string，最多 500 个字符），以及 OR 列表筛选项 type、experiment、category（物理类别，例如 Higgs Physics::Standard Model）、keywords、collision_energy、collision_type、file_type、availability、collection，以及 LHCb 的 magnet_polarity、stripping_stream 和 stripping_version；每项均为值数组；year_from/year_to 和 min_events/max_events 用于限定数据采集年份和事件数
• sort（bestmatch、按最新 date_published 排序的 mostrecent、title、title_desc），limit 为 1–50（默认 10；较大的值最多为 10,000，但实际按 50 返回并附带提示），以及从 1 开始的 page，按应用的 limit 计算页数；page × limit 超过 10,000 时会以 page_window_exceeded 失败
• 精简的 hits（含 recid），以及 13 个实时 facets，每个分面都会忽略自身筛选项（type 和 category 各最多包含 10 个次级值；门户截断列表时会返回 subtypes_other_count 或 subcategories_other_count）；applied_filters 回显实际执行的筛选项，不在已验证词汇范围内的值会出现在 unrecognized_values 中

---

cern_opendata_get_records _工具

• ids：最多 100 个 recid、DOI、CMS 数据集路径（/Primary/Era/TIER）或文档 slug，可混合放入一个数组；查询前 20 个不同标识符，其余标识符会返回在 deferred 中
• 每条记录都包含 license，其中有 basis（record、cern_terms_default、not_stated）；如果记录有 DOI，还会提供可直接使用的 citation
• 文档和新闻正文以每片最多 30,000 个字符的形式返回：对该 id 指定 body_offset，即可从上次返回的片段中的 body_next_offset 继续读取
• 每个响应不超过 64,000 字节，但首条记录始终完整返回；超出预算的记录会被省略并列在 deferred 中，排在前 20 个之后的 id 之前，以便传回 ids
• 记录还会返回其所述的 variables 字典（名称、类型、单位、说明）、物理 category、pile-up（pileup_html，pile-up 数据集位于 links 中）、keywords，以及 LHCb 的 magnet_polarity 和 stripping 流与版本
• 无法解析的标识符会列在 missing 中，并附带 interpreted_as 和指导信息，而不会导致调用失败；文件列表由 cern_opendata_list_files 提供

---

cern_opendata_list_files _工具

• 必需参数 recid；不带 index 时，返回记录的文件索引和普通文件；带索引键时，仅返回该索引中的文件，无需读取记录的其余内容
• limit 为 1–500（默认 50；若值更大、最高为 10,000，则按 500 提供并附带提示），使用 next_cursor 继续；每个文件包含 xrootd_uri、size_in_bytes、checksum 和 availability；如果能根据文件键或 EOS 路径构建 https_url，也会一并提供；此外还会按门户中的原样提供 key 或 filename。每个索引还包含一个 uri_list_url，列出其中的所有 XRootD URI
• 标记为 on demand 的文件存放在磁带上，必须先在记录的门户页面中申请；没有自有文件的总记录会在 children 下返回其子记录的 recid

---

cern_opendata_get_analysis_env _工具

• 必需参数 recid；software 包含记录自身的容器镜像、CMSSW 版本、全局标签和环境 recid
• environment_records（条件、VM、验证）包含记录运行期的环境记录，example_software 则列出声明可用于该记录的软件，两者合计最多 50 条；guides 引用前两个门户指南中链接部分的内容，每段最多 12,000 个字符，并包含该引用在指南其他位置所链接的 [label]: url 参考定义；如果内容被截断，会提供可用于继续读取的 cern_opendata_get_records body_offset
• 始终为 separately_licensed: true；无法读取的关联记录或指南会产生 notice，而不会导致调用失败

---

cern_opendata_get_validated_runs _工具

• 必须且只能提供 recid（CMS 碰撞数据集或已验证运行列表）或 run_period（Run2012B；也匹配 2012B）中的一项；variant 为 full 或 muons_only；可选 run_min/run_max；limit 为 1–2000（默认 200；若值更大、最高为 10,000，则按 2000 提供并附带提示）
• 数据集 recid 会将运行范围限定在数据集列出的首个和最后一个运行，并在 run_bounds 中回显；如果匹配多个列表，matched_lists 会列出这些列表，且不会读取运行
• 每个运行包含 lumi_sections 和 lumi_ranges；list.https_url 用于下载完整列表文件。仅限 CMS：其他记录会以 no_validated_runs 错误失败

---

cern_opendata_search_trigger_paths _工具

• path：精确名称（HLT_IsoMu24、AlCa_EcalPi0），或末尾带一个 * 的前缀（HLT_IsoMu*）；不带 HLT_ 前缀的名称会按所给大小写与记录中的路径名称匹配，并且也会加上 HLT_ 后进行搜索；_v<n> 版本后缀会被去除；可选 year、limit 1–50（默认 10；若值更大、最高为 10,000，则按 50 提供并附带提示）和 page
• 每条按年份划分的记录都会解析为标题中列出的主要 datasets、first_seen、last_seen、每个版本的运行范围及其 l1_seed，以及 HLT 菜单记录链接；parsed: false 表示应从记录的 abstract_html 中读取
• 仅限 2011–2016 年的 CMS 开放数据

---

cern_opendata_list_reference _工具

• 可选参数 topic：experiments、record_types、collision_energies、collision_types、file_types、availability、categories、lhcb、identifiers、query_syntax、licensing 或 run_periods；省略时返回所有表格
• 静态且离线；categories、lhcb 和 run_periods 是带日期的快照，而搜索筛选项和 cern_opendata_get_validated_runs 会读取实时门户数据

---

cern-opendata://record/{recid} _资源

• 通过 recid 获取一条记录（6004，或带前缀的 recid，如 atlas-160006；忽略前导零），以 application/json 格式返回，结构与 cern_opendata_get_records 中的记录一致：包含元数据（含可变字典、物理类别、堆积和 LHCb 运行条件）、许可证和引用信息，不含文件列表
• recid 来自 cern_opendata_search_records；读取结果带有 15 分钟的公开缓存提示

功能

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

CERN Open Data 专属功能：

• 无需密钥且为只读；不会暂存磁带文件，也不会写入任何内容
• 使用一个共享限速器，将速率限制在每分钟 50 个请求，低于门户网站公布的每个客户端 IP 60 个请求；每次调用的总期限为 50 秒，涵盖队列等待和重试
• 将筛选值规范化为门户网站已验证的词汇（13 tev → 13TeV、lhcb → LHCb、Pb-Pb → PbPb、dataset/collision → Dataset::Collision）；未知值会按原样发送并标记
• 每次搜索和查询都包含存储在磁带上的（ondemand）记录；否则门户网站会悄然将它们排除
• 文件清单以及单独读取的文件索引会缓存 15 分钟，因此翻阅某条记录或某个索引中的文件只需读取一次
• cern_opendata_get_records 记录和解析出的记录资源会缓存 15 分钟（最多 8 MiB），因此获取因预算而延后的记录或继续读取 body_next_offset 不会产生额外的门户网站请求

便于 Agent 使用的输出：

• 每个响应均包含来源信息：每条命中和记录都带有 portal_url，还包含带有 basis 的 license、DOI citation，以及反映实际执行内容的 applied_filters 或 effectiveQuery
• 优雅地返回部分结果：无法解析的 ID 会归入 missing 并附上指引；cern_opendata_get_analysis_env 中无法读取的关联记录或指南会以 notice 提示，而不是导致失败
• 使用带判别字段的输出：kind、license.basis、interpreted_as、scope、variant、run_bounds.source 和 parsed 让调用方可以基于数据分支，而不必解析字符串
• 将门户网站文本保留为数据：标题、说明、指南章节和文件名会在 content[] 中加围栏或转义，并在 structuredContent 中按接收时的内容传递（_html 字段中的 HTML）

数据与许可

门户网站元数据和数据集依据 CERN Open Data 使用条款 采用 CC0 许可。软件、容器镜像、文档和指南代码分别按记录适用的许可授权（软件通常采用 GPL）。cern_opendata_get_records 会报告每条记录的许可及其依据：记录中明确声明许可时为 record，未声明许可的数据集默认采用 CC0 时为 cern_terms_default，其他情况为 not_stated。

CERN 要求再利用者在应用和出版物中引用每个数据集的 DOI；对于每条带 DOI 的记录，cern_opendata_get_records 都会返回可直接使用的引用。

此 MCP 服务为独立项目，与 CERN 无关联，也未获 CERN 背书。

已知限制

• 每个客户端 IP 每分钟 60 个请求。 门户公布了这一限制；服务会将请求速率控制在每分钟 50 个，并且无法在截止时间内开始的调用会以 rate_limited 失败，并返回 retryAfter。托管部署中，所有共用同一出口 IP 的用户共享一个额度。cern_opendata_get_analysis_env 和 cern_opendata_get_validated_runs 每次各消耗 2–4 个请求。
• 结果窗口为 10,000 条。 搜索和触发路径分页最多只能获取前 10,000 条匹配结果；可通过筛选条件缩小更深层的结果集。
• Facet 列表不完整。 terms facet 会按字母顺序返回前 10 个值（file_type 最多 100 个），其余计入 other_count；每个 type 和 category 分桶也会返回前 10 个次级值，其余分别计入 subtypes_other_count 或 subcategories_other_count（未筛选的搜索会以这种方式隐藏 Supplementaries::Trigger）。这些是值的汇总计数，而不是记录数；cern_opendata_list_reference 会列出所有值，而 Primary::Secondary 筛选条件的 totalCount 统计的是对应记录数。
• 驻留于磁带的文件。 可用性为 on demand 的文件必须先在记录的门户页面上申请，才能下载；暂存文件属于写入操作，不在支持范围内。可用性为 ondemand 的记录不会通过 API 列出任何文件，因此 cern_opendata_list_files 只会报告其元数据中注明的数量和大小。
• 仅限 CMS 的运行列表和触发器。 触发器记录涵盖 2011–2016 年，触发器详情仅限于各记录摘要中所述的内容。cern_opendata_search_trigger_paths 不会返回预设比例因子：这些因子位于各 HLT 菜单记录的配置文件中（即其 PrescaleService 区块，该文件会通过带有 menu_recid 的 cern_opendata_list_files 列出）；CMS luminosity 记录（集合 CMS-Luminosity-Information）则记录了每个运行和亮度区间适用的预设比例列。Commissioning2010、Run2010B 或 2011 ReReco 列表均没有仅含 μ 子的运行列表。
• 不提供术语表条目。 门户的术语表链接会返回 404，因此搜索会将其排除。

开始使用

公共托管实例

可通过 https://cern-opendata.caseyjhand.com/mcp 使用公共实例，无需安装。使用 Streamable HTTP 将任意 MCP 客户端指向该实例：

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

托管实例的所有调用者共享每分钟 50 个请求的门户请求额度。如需持续使用，请运行自己的实例。

自托管／本地

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

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

也可使用 npx（无需 Bun）：

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

或使用 Docker：

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

如需使用 Streamable HTTP，请设置传输方式并启动服务：

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

先决条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 无需 API 密钥或账户：CERN Open Data Portal 是公开的。

安装

1. 克隆仓库：

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

2. 进入目录：

cd cern-opendata-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

cp .env.example .env
# optional: adjust transport, logging, or telemetry settings

配置

服务本身没有设置项；以下框架变量适用。

变量	说明	默认值
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_HTTP_HOST	HTTP 服务主机。	127.0.0.1
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。	stateless
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<app-root>/logs
OTEL_ENABLED	启用 OpenTelemetry。	false

常见的框架覆盖项请参阅 .env.example。

运行服务

本地开发

• 构建并运行生产版本：

  # 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
  

项目结构

目录	用途
src/index.ts	createApp() 入口：注册工具和资源，设置服务说明，并启动门户客户端。
src/mcp-server/tools	工具定义（*.tool.ts）、共享输入辅助函数和列表增强功能。
src/mcp-server/resources	cern-opendata://record/{recid} 资源定义。
src/mcp-server/record-schema.ts	cern_opendata_get_records 和资源共用的记录输出架构。
src/services/cern-opendata	门户客户端（请求节流、重试、截止时间、缓存）、规范化、词汇表、文本渲染和触发器解析。
tests/	单元测试和工具测试，结构与 src/ 对应，使用门户响应样例进行测试。
docs/design.md	工具接口、已验证的门户行为和设计决策。

开发指南

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

• 处理程序抛出异常，由框架捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录日志，使用 ctx.enrich 提供通知和分页上下文
• 在 src/mcp-server/*/definitions/index.ts 中注册新工具和资源
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；切勿捏造缺失字段

贡献

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

bun run devcheck
bun run test

许可证

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