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	1 人の著者または任意の文献クエリについて、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 から取得できます。

エージェントスキル

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 の場合は統合後のレコードが返され、指定した recid は mergedFrom で示されます
• 寄稿者をページ分割するには、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）を指定し、最初の 10,000 件の一致結果の範囲内で page によるページ分割を行います。それを超えると beyond_result_window エラーになります
• 各項目は INSPIRE からそのまま返され、texkey が含まれます。さらに結果がある場合は truncated と nextPage で示され、appliedFilters に選択内容が反映されます

---

cern_inspire_search_authors _ツール

• 名前または識別子を 1 つ指定します（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 _tool

• 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-index、引用数の合計と平均、0、1–9、10–49、50–99、100–249、250–499、500+ の各区分の論文数を返します。それぞれ、引用可能な論文全体と出版済み論文について集計されます
• year_from、year_to、exclude_self_citations のいずれかが設定されている場合、INSPIRE が値を返さない場合、またはクエリに約150,000件を超えるレコードが一致する場合、citationsByYear は通知とともに省略されます

---

cern_inspire_search_experiments _tool

• 実験、コラボレーション、加速器、施設の名前、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 _tool

• 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 _tool

• topic：search_syntax、identifiers、document_types、subjects、citation_buckets、または hepdata
• 静的な term／meaning／example の項目です。上流への呼び出しはありません

---

inspire://literature/{recid} _resource

• application/json 形式の cern_inspire_get_paper 詳細情報です。最初の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 秒あたり 12 件に調整し、INSPIRE の上限である 15 件を下回るようにします。429 の発生後にはクールダウンを設けます。時間内に開始できない呼び出しは、retryAfter を伴う pacer_shed として失敗します
• 各ツール呼び出しの予算は 55 秒です。キューでの待機時間と最大 2 回の再試行を含みます
• リクエストでは、ツールが返すフィールドのみを選択します。著者のメールアドレスはリクエストしません
• 柔軟な入力に対応しています。論文識別子には arXiv:／doi: プレフィックス、バージョンサフィックス、arxiv.org、doi.org、inspirehep.net の URL を指定できます。著者識別子には orcid.org の URL を指定できます

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

• 上限を超える正の整数の結果件数を指定しても、要求値と有効値を示す通知とともに成功します。文献は 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 を拒否するため、サーバーは hepdata.net を呼び出しません。cern_inspire_get_paper と cern_inspire_search_hepdata は、レコード DOI と、値を確認できる hepdata.net のページを返します。
• 不正な INSPIRE 構文の多くはエラーになりません。 文献検索、引用の要約、引用エクスポートでは、認識可能なフィールド句が空の場合（a:、a: not、a:""、空白文字だけを含む引用値を含む）に invalid_query を返します。各フィールドに値を指定してください（a Witten）。それ以外の場合、解析されない演算子によって一致範囲が広がったり、結果が空になったりします。結果が 0 件、または totalCount が非常に大きい場合は、通常、構文の誤りを示しています（cern_inspire_list_reference のトピック search_syntax）。
• 選択結果の検証には追加のリクエストが必要です。 文献検索では、フィルター適用後の選択結果と後続ページを検証します。エクスポートでは、フィルター適用後の最初のページと、すべての後続ページを検証します。これにより、INSPIRE の参照フォールバックがフィルターを迂回したり、取得済みの結果を繰り返したりするのを防ぎます。必須の検証に失敗すると呼び出し全体が失敗します。フィルターなしの最初のページでは、リクエストは 1 回のままです
• 結果ウィンドウは 10,000 件です。 クエリの最初の 10,000 件のみ取得できます。残りの結果を取得するには、クエリを絞り込んでください。
• リクエストキューを共有します。 1 つのサーバープロセスへのすべての呼び出し元は、アドレスごとの INSPIRE の上限である 5 秒あたり 15 件に従う単一のキューを共有します。そのため、リクエストが集中すると、再試行可能なレート制限エラーが発生し、ほかの呼び出しが遅延したり、破棄されたりすることがあります。

はじめに

インストール不要で、ホストされているインスタンスに接続できます。

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

ホストされているインスタンスを呼び出すすべてのクライアントで、5 秒あたり 12 回のリクエスト開始という INSPIRE のリクエスト予算を共有します。継続的に使用する場合は、独自のインスタンスを実行してください。

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 . でローカルにビルドできます。OpenTelemetry のピア依存関係を省略するには、--build-arg OTEL_ENABLED=false を追加してください。

プロジェクト構成

ディレクトリ	目的
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/	サーバーを呼び出すエージェント向けに公開されている 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 呼び出しはラップします：生データを検証 → ドメイン型に正規化 → 出力スキーマに沿って返却。欠落しているフィールドを捏造してはいけません

コントリビューション

Issue を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

このプロジェクトは Apache 2.0 License の下でライセンスされています。詳細は LICENSE ファイルを参照してください。