Usgs Mineral Commodities

@pipeworx/usgs-mineral-commodities

USGS Mineral Commodity Summaries（MCS）— 85 種の非燃料鉱物資源（リチウム、銅、コバルト、レアアース、金、アルミニウム、ニッケル、白金族金属、数十種類の工業用鉱物を含む）について、米国の生産、輸入、輸出、消費、価格、雇用、純輸入依存度を提供します。また、そのうち 75 種について、国別の世界の鉱山・工場生産量と埋蔵量も提供します。

Pipeworx の一部です。AI エージェントを 1784 以上のライブデータソースに接続する MCP ゲートウェイです。これは独立した非公式の連携機能であり、上流プロバイダーとは提携、承認、公開のいずれの関係もありません。

ツール

• mcs_list_commodities(query?, limit?) — このリリースが対象とする 85 種の鉱物資源を一覧します。各項目には、その鉱物資源固有の統計列（MCS の章ごとに独自の表が定義されています）と、世界比較表（mcs_country_comparison）が利用可能かどうかが記載されています。
• mcs_commodity_data(commodity) — 1 種の鉱物資源に関する米国の主要統計情報です。直近 5 年間の生産、輸入、輸出、消費、価格、雇用、純輸入依存度（米国の消費量のうち輸入によって賄われる割合）を返します。一般名（「lithium」、「rare earths」、「platinum group metals」など）または MCS コードを指定できます。
• mcs_country_comparison(commodity, countries?, limit?) — 1 種の鉱物資源について、国別の世界の鉱山・工場生産量（前年の実績値と当年の推定値）および埋蔵量を返します。「リチウムの埋蔵量を保有する国はどこか」「中国とオーストラリアのレアアース生産量の比較」などに使えます。85 種のうち 75 種が対象です（残り 10 種については、下記の「既知の不足項目」を参照）。

認証

キー不要です。

データソース

USGS の National Minerals Information Center は、MCS を年 1 回、ファイルのみの ScienceBase データリリースとして公開しています。2026-10-07 にライブで確認済みです。 ScienceBase のアイテム 677eaf95d34e760b392c4970 （「U.S. Geological Survey Mineral Commodity Summaries 2025 Data Release, ver. 2.0, April 2025」）には、CSV テーブルを格納した ZIP ファイルが 2 つと、改訂履歴の .txt ファイルが含まれています。JSON/REST エンドポイントは一切ありません。

• Salient_Commodity_Data_Release_Grouped_MCS_2025.zip — 鉱物資源ごとに mcs2025-<code>_salient.csv が 1 つ含まれます（85 種）。直近 5 年間の米国の主要統計情報です。列名は鉱物資源ごとに異なります。
• World_Data_Release_MCS_2025.zip — MCS2025_World_Data.csv が 1 つ含まれます。このリリースでは、国別の世界の鉱山・工場生産量（2023 年の実績値と 2024 年の推定値）および 2024 年の埋蔵量を、約 79 の鉱物資源グループ別に掲載しています（85 種の主要統計コードよりも大まかな分類です）。

scripts/bake-index.mjs は両方をダウンロードし、すべての CSV を解析して、名称を基に主要統計の鉱物資源を世界データ表の行に対応付けます（2 つの刊行物間の名称の違いに対応するため、手作業で確認した短い別名リストを使用します。USGS の誤記「Germanium」と世界データ表の「Gemanium」の違いも含め、詳細はスクリプト内のコメントを参照してください）。その後、src/mcs-index-data.ts に書き込みます。

ライブエンドポイントを呼び出すのではなく、テーブルをここに埋め込む理由

MCS データリリースはファイルのみで提供されるため、プロキシできる API がありません。ルートの CLAUDE.md にある恒常的な指針は、バルクファイルのみを公開するソースにまさに該当します。また、米国連邦政府のデータ（USGS）はパブリックドメインであるため、このパックにリリースで公開された数値を埋め込む際、再利用許諾は不要です。更新手順：USGS は毎年 1 月に新しい MCS リリースを公開します（2025 年の「ver. 2.0」のように、春に再改訂される場合もあります）。新しいリリースが公開されたら、その ScienceBase アイテム ID を使って node scripts/bake-index.mjs > src/mcs-index-data.ts を再実行してください。

焼き込み済みテーブルが静的インポートではない理由

このテーブルは、重要な行が約430件、世界全体の行が1,250件（JSONで約509KB）あります。静的に importすると、その分離環境がこのパックを提供するかどうかにかかわらず、すべてのゲートウェイ分離環境のヒープに全データが読み込まれます。これは、2026-10-07に6つの州コードパックで発生した障害とまったく同じです（フリート #2754：保持ヒープ約48MB、ゲートウェイ呼び出しのおよそ4回に1回がCloudflare 1102で終了）。代わりに、デプロイ時にテーブルをKVへアップロードし（workers/gateway/src/pack-baked-indexes.jsonで登録し、scripts/sync-gateway-static-json.mjsでアップロードします）、このパックへの最初の呼び出し時にゲートウェイが解析済みオブジェクトをargs._bakedIndexとして注入します。各分離環境での採用は一度だけです。注入がない、または形式が不正な場合は、商品や国が単に見つからなかったかのように応答するのではなく、エラーを明示的にスローします（src/index.test.tsを参照）。

既知の不足点

• 今回のリリースでは、85品目のうち10品目にMCS世界生産量・埋蔵量テーブルの行がありません。主に、USGSが国内データのみを追跡しているスクラップ、スラグ、砕石のカテゴリと、世界の埋蔵量推定値が公表されていない希少元素（スカンジウム、タリウム、トリウム）です。該当する品目は、鉄・鋼スクラップ、鉄・鋼スラグ、水晶（工業用）、砂および砂利（建設用）、スカンジウム、石材（砕石）、石材（建築用）、タリウム、トリウム、イットリウムです。これらについてmcs_country_comparisonは、空の行リストではなくfound: false, reason: "no_world_data"を返します。
• USGSの生の脚注コード（W＝企業の機密情報の開示を避けるため非公開、E＝推定値、NA＝入手不可、純輸入依存度の">50"、"Less than 1/2 unit."のような自由記述の注記）は、数値に変換したりnullにしたりせず、そのまま渡されます。すべてのツールの応答にはfootnote_legendフィールドが含まれます。
• これは特定時点の年間リリースであり、ライブフィードではありません。各応答にはdata_as_of（データの焼き込み時の取得タイムスタンプ）とrelease_yearが含まれます。

クイックスタート

MCP クライアント（Claude Desktop、Cursor、Windsurfなど）に追加します。

{
  "mcpServers": {
    "usgs-mineral-commodities": {
      "url": "https://gateway.pipeworx.io/usgs-mineral-commodities/mcp"
    }
  }
}

このエンドポイントが実際に提供するもの

https://gateway.pipeworx.io/usgs-mineral-commodities/mcpのtools/listは、上記のテーブルに記載されたツールに加えて、共有のPipeworxメタツール（ask_pipeworx、discover_tools、search_within、remember／recallなど、ゲートウェイ全体で使えるツール一式）を返します。そのため、表示されるツール数はこのテーブルの数より多くなります。現在、単一パックのエンドポイントには、パック独自のツールとともに約30個の共有ツールが表示されます。接続のinitialize応答には正確なスコープが示され、その日の状況を確認する際の確定情報になります。

これは意図的な設計であり、偶然の多重化ではありません。メタツールを使うと、このパックで扱わない質問にもask_pipeworx経由でカタログ全体に振り分けて回答できるため、MCP サーバーを追加する必要がありません。現時点では、メタツールなしでパックのエンドポイントをマウントする方法はありません。追加のスキーマによるコンテキスト消費がルーティングの利点を上回る場合は、複数のパックエンドポイントではなく、フルゲートウェイに一度だけ接続してください。

また、こちらのフルPipeworxゲートウェイに接続すると、このパックだけでなく、すべてのパックのツールが直接一覧表示されます。

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

どちらのURLも、同じゲートウェイと同じ1,784以上のデータソースに接続します。異なるのは、どのパックのツールが直接一覧表示されるかだけです。どちらからでもask_pipeworxを使ってすべてのツールにアクセスできます。

MCP クライアントがない場合：HTTPで呼び出す

curl -X POST https://gateway.pipeworx.io/v1/tools/mcs_list_commodities \
  -H 'Content-Type: application/json' \
  -d '{"query":"lithium"}'

最初の呼び出しにアカウントは不要です。ツールの内容を確認するには、GET https://gateway.pipeworx.io/v1/tools/mcs_list_commoditiesを実行します。ツールを探すには、{"query":"..."}を指定してPOST https://gateway.pipeworx.io/v1/tools/search_packsを実行します。

スタンドアロン（ゲートウェイアカウント不要）

このパッケージはローカルの stdio MCP サーバーとしても実行できます。Pipeworx アカウントも、ゲートウェイとの往復通信も不要です。

{
  "mcpServers": {
    "usgs-mineral-commodities": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-usgs-mineral-commodities"]
    }
  }
}

または、直接実行して起動を確認できます。

npx -y @pipeworx/mcp-usgs-mineral-commodities

stdin/stdout 経由で MCP を使用し、initialize／tools/list／tools/call に応答します。対象はこのパックのツールのみで、上記のゲートウェイ接続で追加される共有メタツールは含まれません。同じソース、同じツールで、ask_pipeworx によるルーティングはありません。

ask_pipeworx を使用する

ツールを直接呼び出す代わりに、平易な英語で質問できます。これは上記のパックエンドポイントだけでなく、フルゲートウェイでも機能します。

ask_pipeworx({ question: "your question about Usgs Mineral Commodities data" })

ゲートウェイが適切なツールを選び、引数を自動的に入力します。

詳細

• ドキュメントとガイド
• pipeworx.io

ライセンス

MIT