Msha Mines

@pipeworx/msha-mines

按运营方或矿山名称搜索美国矿山，或查询已知的 MSHA Mine ID，获取其状态、近期检查、违规记录（含评估罚款），以及季度就业和产量数据——这些信息来自 MSHA（矿山安全与健康管理局）的记录。

这是 Pipeworx 的一部分——一个将 AI Agent 接入 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?) — 在一次调用中，统计某矿山在某个日历年或年份范围内的违规记录总数，并按接收对象（运营方、承包商、代理人、矿工）以及重大且实质性（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 自有的开放政府数据门户，列出以管道符分隔、约每周更新一次的可下载文件。本工具包加载了其中 4 个文件：Mines.zip（所有曾分配过 Mine ID 的矿山主列表——状态、类型、矿产品、当前运营方／控制方）、Violations.zip（含评估罚款的引证／命令）、Inspections.zip（检查事件），以及 MinesProdQuarterly.zip（按子单元统计的季度就业和煤炭产量）。美国联邦数据，属于公共领域。ControllerOperatorHistory.zip 位于同一 URL，但不在本工具包首项功能的范围内——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 端点。唯一可查询的路径是以管道符分隔的批量文件。此包读取 Supabase 镜像（msha_mines、msha_violations、msha_inspections、msha_employment_production；架构定义见 supabase/migrations/237_msha_mines.sql），数据由 scripts/ingest-msha-mines.mjs 每周加载（.github/workflows/msha-mines-refresh.yml）。每个成功响应都会携带来自底层表自身 loaded_at 的 data_as_of。

直接从 MSHA 获取数据，不经过网关。 与 registry.faa.gov（由 Akamai 代理，因请求头格式不符而被拦截——参见 mcps/faa-aircraft-registry 的 README）不同，arlweb.msha.gov 对来自生产 Cloudflare 账户上临时 wrangler dev --remote Worker 的普通 fetch() 请求，返回的 HTTP 200 与笔记本电脑上的 curl 请求完全相同——已于 2026-10-08 通过 Mines_Definition_File.txt（字节完全相同，10,285 字节）和完整的 120,770,798 字节 Violations.zip 验证。无需绕过任何拦截，因此摄取脚本会从运行所在的位置直接调用 MSHA。

有意限制数据范围

Violations.zip 解压后为 1.44 GB（约 310 万行，追溯至 2000 年）；Inspections.zip 为 348 MB（约 116 万行）；MinesProdQuarterly.zip 为 262 MB（约 276 万行）。对于一个用途是“这座矿最近状况如何”的查询工具，加载这些文件的完整历史数据并不划算——摄取脚本只保留每个文件最近 5 个日历年的数据（每次运行时根据当前日期重新计算，因此时间窗口会自动向前滚动）。msha_mines（约 9.2 万行的主列表）会完整加载——它是最小的文件，也是其他每张表都会关联的表。凡是涉及受限表的响应都会带有 bound 字段说明此限制，因此，简短的违规或检查列表不会让人误以为“这座矿没有更早的历史记录”——它有历史记录，只是未加载。

数据库加载过程是对每张表执行 TRUNCATE 和 psql \copy，四张表全部在一个事务中完成，并使用摄取脚本从环境中读取的连接池连接字符串——这是每周一次的完整快照，而非增量 upsert。只要四个文件中的任意一个解析失败，整个事务就会回滚，因此上周的数据仍然可用，不会出现某张表只替换了一半的情况。

自然键并非唯一

在 MSHA 的完整未限定范围文件中，VIOLATION_NO 有 51 个重复值，EVENT_NO 至少有 1 个重复值（已于 2026-10-08 对提取出的 .txt 文件执行 sort | uniq -d 验证），因此 msha_violations 和 msha_inspections 使用代理 bigserial id 作为主键，而非自然键。msha_mines.mine_id 确实 是真正的主键——MSHA 自己的定义文件称它是所有其他表的唯一关联键。

空注册表保护

如果每周刷新从未成功完成过，底层表就会为空，但针对这些表的查询仍会成功——因此，简单的读取会对每座矿都返回一个确定的 found: false，无法与在有效数据中确实未找到记录的情况区分开来。两个工具都会先检查是否至少有一行已加载数据，再返回结果；否则会抛出明确的 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 服务。目前无法挂载不带这些元工具的工具包端点；如果额外的架构定义消耗的上下文超过路由带来的价值，不妨只连接一次完整网关，而不是连接多个工具包端点。

也可以连接完整的 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