Msha Mines

@pipeworx/msha-mines

事業者名または鉱山名で米国の鉱山を検索するか、既知の MSHA Mine ID を指定して、そのステータス、最近の検査、違反（査定された罰金を含む）、四半期ごとの雇用者数・生産量を MSHA（Mine Safety and Health Administration）の記録から調べられます。

Pipeworx の一部です。AI エージェントを 1819 以上の稼働中のデータソースに接続する MCP ゲートウェイです。これは独立した非公式の統合であり、上流プロバイダーとは提携・承認・公開の関係にありません。

ツール

• msha_mine_search(query, state?, status?, limit?) — 事業者、支配会社、または鉱山名で検索します。一致する鉱山について、MSHA Mine ID、ステータス（Active、Abandoned、Intermittent など）、鉱山の種類（Surface／Underground／Facility）、石炭か金属／非金属かの分類、鉱産物、州、現在の事業者／支配会社を返します。msha_mine_detail を呼び出す前に、会社の Mine ID を調べるために使用します。
• msha_mine_detail(mine_id, violations_limit?, inspections_limit?) — 既知の MSHA Mine ID について、現在のステータス、種類、鉱産物、事業者、支配会社に加えて、最近の検査、最近の違反（査定された罰金、S&S フラグ、是正／終了日を含む）、最近の四半期ごとの雇用者数と、サブユニット全体で合算した石炭生産量を返します。一致する Mine ID がない場合は、エラーではなく data_as_of と found: false を返します。
• msha_violation_counts(mine_id?, mine_name?, year?, year_from?, year_to?) — 1 回の呼び出しで、暦年または期間内の鉱山の違反件数を集計します。合計に加え、発行先（Operator、Contractor、Agent、Miner）および重大かつ実質的（S&S）な違反かどうかによる内訳を返します。msha_mine_detail の violations リストは violations_limit（最大 100 件）で上限が設定され、実際の総数は含まれません。「鉱山 X は年 Y に違反を何件受けましたか」という質問には、このツールを使用します。違反ごとの発行日（VIOLATION_ISSUE_DT、MSHA 独自の CAL_YR フィールド経由）の暦年に基づいて集計します。Mine ID を直接指定するか、鉱山／事業者／支配会社の名前を指定できます。名前から鉱山を一意に特定できない場合や一致するものがない場合は、候補を列挙した名前付きエラーが返されます。読み込み済みの 5 年間の範囲外の年は、無言でゼロ件として回答されることなく、coverage で未読み込みと示されます。

認証

キーは不要です。

データソース

• https://arlweb.msha.gov/OpenGovernmentData/OGIMSHA.asp — MSHA 独自の Open Government Data ポータルです。おおむね週 1 回更新される、パイプ区切り形式のダウンロード可能なファイルが掲載されています。4 つのファイルを読み込んでいます。Mines.zip（Mine ID が割り当てられたすべての鉱山のマスターリスト。ステータス、種類、鉱産物、現在の事業者／支配会社）、Violations.zip（査察通知／命令と査定された罰金）、Inspections.zip（検査イベント）、MinesProdQuarterly.zip（サブユニットごとの四半期別雇用者数と石炭生産量）。米国連邦政府のデータであり、パブリックドメインです。同じ URL で ControllerOperatorHistory.zip も提供されていますが、このパックの最初の機能の範囲外です。Mines.zip には各鉱山の現在の事業者／支配会社がすでに含まれており、検索と詳細表示に対応できます。

これがライブプロキシではなくローカルコピーのパックである理由

MSHA の Mine Data Retrieval System（msha.gov/mdrs）は、iframe タグに埋め込まれた MicroStrategy BI アプリケーションです（2026-10-08 に確認：ページの src は microstrategy.msha.gov/MicroStrategy/asp/Main.aspx です）。Worker がリクエストごとに呼び出せる JSON エンドポイントではありません。クエリ可能な経路は、パイプ区切り形式の一括ファイルだけです。このパックは、scripts/ingest-msha-mines.mjs（.github/workflows/msha-mines-refresh.yml）によって毎週読み込まれる Supabase ミラー（msha_mines、msha_violations、msha_inspections、msha_employment_production。スキーマは supabase/migrations/237_msha_mines.sql）を読み込みます。成功したレスポンスにはすべて、元となるテーブル自身の loaded_at に基づく data_as_of が含まれます。

ゲートウェイを経由せず、MSHA から直接取得します。 registry.faa.gov（Akamai の背後にあり、ヘッダーの形式によってブロックされます。mcps/faa-aircraft-registry の README を参照）とは異なり、arlweb.msha.gov は、本番 Cloudflare アカウント上で使い捨ての wrangler dev --remote Worker から実行したプレーンな fetch() に対し、ノート PC からの curl と同じ通常の HTTP 200 を返しました。これは Mines_Definition_File.txt（バイト単位で同一、10,285 バイト）と、全体で 120,770,798 バイトの Violations.zip を使って、2026-10-08 に確認済みです。回避すべきブロックはないため、取り込みスクリプトは実行場所を問わず MSHA を直接呼び出します。

意図的に範囲を限定

Violations.zip は解凍すると 1.44 GB（2000 年まで遡る約 310 万行）、Inspections.zip は 348 MB（約 116 万行）、MinesProdQuarterly.zip は 262 MB（約 276 万行）になります。「この鉱山は最近問題ないか」を調べるためのツールでは、これらすべての全履歴を読み込む価値はありません。取り込みスクリプトは、それぞれ直近の暦年 5 年分だけを保持します（実行のたびに現在の日付から再計算するため、対象期間は自動的に先へ進みます）。msha_mines（約 9.2 万行のマスターリスト）は最小のファイルであり、他のすべてのテーブルが結合に使うため、全件を読み込みます。対象範囲を限定したテーブルに触れるレスポンスにはすべて、その旨を示す bound フィールドが含まれます。そのため、違反や検査の一覧が短くても、「この鉱山にはそれより古い履歴がない」という意味にはなりません。履歴はありますが、読み込まれていないだけです。

DB の読み込みは、取り込みスクリプトが環境変数から取得するプール済み接続文字列を使い、各テーブルで TRUNCATE と psql \copy を行います。4 つすべてを 1 つのトランザクションで処理する、毎週の完全なスナップショットであり、差分の upsert ではありません。4 ファイルのいずれかで解析に失敗するとトランザクション全体がロールバックされるため、テーブルが中途半端に置き換えられることなく、先週のデータが引き続き利用できます。

自然キーは一意ではありません

MSHA の全期間ファイル（範囲制限なし）を対象に、抽出した .txt ファイルに対して sort | uniq -d を実行したところ（2026-10-08 に確認）、VIOLATION_NO には 51 個、EVENT_NO には少なくとも 1 個の重複値がありました。そのため、msha_violations と msha_inspections は、自然キーではなくサロゲートの bigserial id を主キーとして使います。msha_mines.mine_id は実際の主キーです。MSHA 自身の定義ファイルでも、他のすべてのテーブルを結合する一意のキーとされています。

空のレジストリに対するガード

週次更新が一度も正常に完了していない場合、元となるテーブルは空ですが、クエリ自体は成功します。そのため、単純に読み取ると、正常なデータに対する実際の不一致と区別できないまま、すべての鉱山について確信を持って found: false と回答してしまいます。両方のツールは、回答する前に読み込み済みの行が少なくとも 1 件あることを確認し、代わりにその状態を明示する dataset_unavailable クラスのエラーをスローします（mcps/faa-aircraft-registry、fleet #2790 と同じパターンです）。

クイックスタート

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

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

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

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

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

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

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

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

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

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

最初の呼び出しにアカウントは必要ありません。任意のツールを確認するには、GET https://gateway.pipeworx.io/v1/tools/msha_mine_search を使用します。ツールを検索するには、{"query":"..."} を指定して POST https://gateway.pipeworx.io/v1/tools/search_packs を使用します。

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

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

{
  "mcpServers": {
    "msha-mines": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-msha-mines"]
    }
  }
}

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

npx -y @pipeworx/mcp-msha-mines

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

ask_pipeworx の使用

ツールを直接呼び出す代わりに、自然な英語で質問できます。これは上記のパックエンドポイントとフルゲートウェイの両方で使用できます。

ask_pipeworx({ question: "your question about Msha Mines data" })

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

詳細情報

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

ライセンス

MIT