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 データセットパス、ドキュメントスラッグを指定して、1 回につき最大 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 High-Level Trigger パスを名前またはプレフィックスで検索し、ラン範囲、バージョン、L1 シードに解析して表示します
cern_opendata_list_reference	他のツールが受け付ける語彙を確認します。実験、レコードタイプ、エネルギー、形式、物理カテゴリ、LHCb stripping、識別子、クエリ構文、ライセンス、ラン期間が含まれます

リソース

リソース	説明
cern-opendata://record/{recid}	1 件のレコードのメタデータ、ライセンス、引用情報を、cern_opendata_get_records のレコード形式で提供します

ツールのみを利用するクライアントは、cern_opendata_get_records から同じデータを取得できます。

機能リファレンス

cern_opendata_search_records _ツール

• 任意の query（最大 500 文字の OpenSearch query_string）と、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 から始まり適用された limit 件単位で数える page を指定できます。page × limit が 10,000 を超えると、page_window_exceeded エラーになります
• recid を含む簡潔な hits と、それぞれが自身のフィルターを無視する 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）、またはドキュメントスラッグを、1 つの配列に混在させて指定できます。先頭から重複を除いた 20 件を検索し、残りは deferred に返します
• 各レコードには basis（record、cern_terms_default、not_stated）を含む license があり、DOI がある場合はすぐに利用できる citation も含まれます
• ドキュメントとニュースの本文は最大 30,000 文字ずつの範囲で返されます。特定の ID とともに body_offset を指定すると、最後に返された範囲の body_next_offset から続きを読み取れます
• 各応答は 64,000 バイト以内に収まります。ただし、最初のレコードは常に全体が返されます。サイズ上限を超えるレコードは省略され、最初の 20 件を超える ID より前に deferred に列挙されます。続きはそれらの ID を ids として渡して取得します
• レコードには、記載されている variables 辞書（名前、型、単位、説明）、物理 category、パイルアップ（pileup_html。パイルアップデータセットは links 内）、keywords、および LHCb の magnet_polarity と stripping のストリームとバージョンも含まれます
• 解決できない識別子は、呼び出しを失敗させる代わりに interpreted_as とガイダンスを含めて missing に格納されます。ファイル一覧は 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 はポータルに表示されているとおりに記載されます。各インデックスには、その中のすべての XRootD URI を一覧表示する uri_list_url が含まれます。
• on demand と記載されたファイルはテープ上にあるため、先にレコードのポータルページからリクエストする必要があります。自身のファイルを持たないアンブレラレコードでは、子レコードの recid が children に返されます。

---

cern_opendata_get_analysis_env _ツール

• recid は必須です。software には、レコード独自のコンテナイメージ、CMSSW リリース、グローバルタグ、環境 recid が含まれます。
• レコードのラン期間に対応する environment_records（条件、VM、検証）と、そのレコードで動作すると明記された example_software が合わせて最大 50 件含まれます。guides には、最初の 2 件のポータルガイド内のリンク先セクションからの引用が含まれます。各引用は最大 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）または末尾に * を 1 つ付けたプレフィックス（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、または atlas-160006 のようなプレフィックス付き recid。先頭のゼロは無視されます）で指定したレコードを、cern_opendata_get_records のレコード形式に沿った application/json として返します。メタデータ（可変の辞書、物理カテゴリ、パイルアップおよび 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 分間キャッシュするため、レコードまたはインデックスのファイルをページングする際の読み込みは 1 回で済みます。
• レコード cern_opendata_get_records と、解決されたレコードリソースは 15 分間（最大 8 MiB）キャッシュされます。そのため、予算の都合で後回しにしたレコードの取得や body_next_offset の追跡で、ポータルへの追加リクエストは発生しません。

エージェントに適した出力：

• すべての応答に出典情報を含みます。各検索結果とレコードに 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 Terms of Use に基づき CC0 です。ソフトウェア、コンテナイメージ、ドキュメント、ガイドのコードには、レコードごとに個別のライセンスが適用されます（ソフトウェアは GPL であることが一般的です）。cern_opendata_get_records は、各レコードのライセンスとその根拠を返します。レコードにライセンスの記載がある場合は record、記載のないデータセットに CERN の利用規約に基づく既定の CC0 が適用される場合は cern_terms_default、それ以外の場合は not_stated です。

CERN は、アプリケーションや出版物で各データセットの DOI を引用するよう再利用者に求めています。cern_opendata_get_records は、DOI があるすべてのレコードについて、そのまま使える引用情報を返します。

このサーバーは独立したプロジェクトであり、CERN とは提携しておらず、CERN の推奨も受けていません。

既知の制限事項

• クライアント IP あたり1分間に60リクエスト。 ポータルがこの上限を公開しており、サーバーは1分間に50リクエストとなるよう間隔を調整します。期限内に開始できない呼び出しは、retryAfter を伴う rate_limited として失敗します。ホスト型のデプロイでは、送信元 IP を共有するすべてのユーザーで1つの予算を共有します。cern_opendata_get_analysis_env と cern_opendata_get_validated_runs は、1回の呼び出しにつき2～4リクエストを消費します。
• 結果は最大10,000件まで。 検索とトリガーパスのページングで取得できるのは、最初の10,000件までです。さらに深い結果セットはフィルターで絞り込んでください。
• ファセットリストは一部のみです。 用語ファセットはアルファベット順で最初の10件（file_type は最大100件）を返し、残りは other_count に集計されます。また、各 type と category のバケットでは、2次値の最初の10件を返し、残りは subtypes_other_count または subcategories_other_count に集計されます（フィルターを適用しない検索では、この方法で Supplementaries::Trigger が表示されません）。これらは値の合計数であり、レコード数ではありません。cern_opendata_list_reference はすべての値を一覧表示し、Primary::Secondary フィルターの totalCount は該当するレコード数を示します。
• テープ上に保存されているファイル。 availability が on demand のファイルは、ダウンロード前にレコードのポータルページからリクエストする必要があります。ステージングは書き込み操作のため、対象外です。availability が ondemand のレコードは、API 経由でファイルを一切表示しません。そのため、cern_opendata_list_files が報告するのは、メタデータに記載された件数とサイズのみです。
• CMS 限定のランリストとトリガー。 トリガーレコードは2011～2016年を対象とし、トリガーの詳細は各レコードの概要に記載された内容に限られます。cern_opendata_search_trigger_paths はプリスケール係数を返しません。これらは各 HLT メニューレコードの設定ファイル（cern_opendata_list_files が menu_recid とともに一覧表示する PrescaleService ブロック）にあり、CMS のルミノシティレコード（コレクション 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"
    }
  }
}

ホスト型インスタンスを利用するすべての呼び出し元で、ポータルへのリクエスト予算（1分間に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 ファイルを参照してください。