@pipeworx/msha-mines

Connect: https://pipeworx.io/mcp — every tool in the catalog, including @pipeworx/msha-mines’s. Install: one-click buttons

No MCP client? Skip the connection: POST https://gateway.pipeworx.io/v1/tools/search_packs {"query":"..."} to find a tool below, GET /v1/tools/<name> for its schema, POST the same URL with arguments for the data — see For AI agents.

Tools: 2

Search US mines by operator or mine name, or look up a known MSHA Mine ID for its status, recent inspections, violations (with assessed penalties), and quarterly employment/production — from MSHA (Mine Safety and Health Administration) records.

Tools

• msha_mine_search(query, state?, status?, limit?) — search by operator, controller, or mine name. Returns matching mines with their MSHA Mine ID, status (Active, Abandoned, Intermittent, etc.), mine type (Surface/Underground/Facility), coal vs. metal/non-metal classification, commodity, state, and current operator/controller. Use this to find a company’s Mine ID(s) before calling msha_mine_detail.
• msha_mine_detail(mine_id, violations_limit?, inspections_limit?) — a known MSHA Mine ID’s current status, type, commodity, operator and controller, plus recent inspections, recent violations (with assessed penalties, S&S flag, and abatement/termination dates), and recent quarterly employment and coal production summed across subunits. A Mine ID with no match returns found: false with data_as_of — not an error.

Auth

Keyless.

Data sources

• https://arlweb.msha.gov/OpenGovernmentData/OGIMSHA.asp — MSHA’s own Open Government Data portal, listing downloadable pipe-delimited files refreshed roughly weekly. Four are loaded: Mines.zip (the master list of every mine ever assigned a Mine ID — status, type, commodity, current operator/controller), Violations.zip (citations/orders with assessed penalties), Inspections.zip (inspection events), and MinesProdQuarterly.zip (quarterly employment and coal production by subunit). US federal data, public domain. ControllerOperatorHistory.zip ships at the same URL but is out of scope for this pack’s first capability — Mines.zip already carries each mine’s current operator/controller, which covers search and detail.

Why this is a local-copy pack, not a live proxy

MSHA’s Mine Data Retrieval System (msha.gov/mdrs) is a MicroStrategy BI application embedded in an iframe tag (confirmed 2026-10-08: the page’s src is microstrategy.msha.gov/MicroStrategy/asp/Main.aspx) — not a JSON endpoint a Worker can call per request. The only queryable path is the bulk pipe-delimited files. This pack reads a Supabase mirror (msha_mines, msha_violations, msha_inspections, msha_employment_production; schema in supabase/migrations/237_msha_mines.sql) loaded weekly by scripts/ingest-msha-mines.mjs (.github/workflows/msha-mines-refresh.yml). Every successful response carries data_as_of from the backing table’s own loaded_at.

Fetched directly from MSHA, not routed through the gateway. Unlike registry.faa.gov (Akamai-fronted, blocks on header shape — see mcps/faa-aircraft-registry’s README), arlweb.msha.gov answered a plain fetch() from a throwaway wrangler dev --remote Worker on the prod Cloudflare account the same clean HTTP 200 it gives a laptop curl — verified 2026-10-08 against Mines_Definition_File.txt (byte-identical, 10,285 bytes) and the full 120,770,798-byte Violations.zip. No blocking to work around, so the ingest script calls MSHA directly from wherever it runs.

Bounded on purpose

Violations.zip unzips to 1.44 GB (~3.1M rows back to 2000); Inspections.zip to 348 MB (~1.16M rows); MinesProdQuarterly.zip to 262 MB (~2.76M rows). Loading the full history of any of them is not worth it for a lookup tool whose job is “is this mine okay lately” — the ingest script keeps only the most recent 5 calendar years of each (recomputed from the current date every run, so the window slides forward on its own). msha_mines (the ~92k-row master list) is loaded in full — it is the smallest file and the one every other table joins against. Every response that touches the bounded tables carries a bound field saying so, so a short violations/inspections list never reads as “this mine has no older history” — it has history, it just isn’t loaded.

The DB load is TRUNCATE + psql \copy per table, all four in one transaction, using the pooled connection string the ingest script reads from its environment — a full weekly snapshot, not an incremental upsert. A parse failure on any of the four files rolls the whole transaction back, so last week’s data stays live rather than a table going half-replaced.

Natural keys are not unique

VIOLATION_NO has 51 duplicate values and EVENT_NO has at least 1, across MSHA’s full un-bounded files (verified 2026-10-08 with sort | uniq -d over the extracted .txt files) — so msha_violations and msha_inspections use a surrogate bigserial id, not the natural key, as primary key. msha_mines.mine_id is a real primary key — MSHA’s own definition file calls it the unique join key across every other table.

Empty-registry guard

If the weekly refresh has never completed a successful run, the backing tables are empty but a query against them still succeeds — so a naive read would answer a confident found: false for every mine, indistinguishable from a genuine miss against good data. Both tools check for at least one loaded row before answering and throw a loud dataset_unavailable-class error naming that condition instead (same pattern as mcps/faa-aircraft-registry, fleet #2790).

Tools

• msha_mine_search — Search MSHA (Mine Safety and Health Administration) mine records by operator name, controller name, or mine name. Returns matching mines with their MSHA Mine ID, status (Active, Abandoned, Intermitten
• msha_mine_detail — Look up a known MSHA Mine ID: current status, type, commodity, operator and controller, plus recent inspections, recent violations (with assessed penalties, S&S flag, and abatement/termination dates),