Usgs Mineral Commodities

@pipeworx/usgs-mineral-commodities

USGS Mineral Commodity Summaries（MCS）——85 种非燃料矿产商品的美国生产、进口、出口、消费、价格、就业和净进口依赖度（包括锂、铜、钴、稀土、黄金、铝、镍、铂族金属以及数十种工业矿物），以及其中 75 种商品按国家划分的全球矿山／工厂产量和储量。

属于 Pipeworx——一个将 AI Agent 连接到 1784+ 个实时数据源的 MCP 网关。这是一项独立的非官方集成，与上游提供方无关联、未经其认可，也非由其发布。

工具

• mcs_list_commodities(query?, limit?) — 浏览此版本涵盖的 85 种商品；每个条目都会列出该商品自己的统计数据列（每种商品的 MCS 章节都定义了自己的表格），以及是否提供世界对比表（mcs_country_comparison）。
• mcs_commodity_data(commodity) — 查询一种商品的美国主要统计数据：最近 5 年的生产、进口、出口、消费、价格、就业和净进口依赖度——即美国消费中来自进口的比例。可接受常见名称（“lithium”“rare earths”“platinum group metals”）或 MCS 代码。
• mcs_country_comparison(commodity, countries?, limit?) — 按国家查询一种商品的全球矿山／工厂产量（上一年实际值＋当年估值）和储量——例如“哪些国家拥有锂储量”“中国与澳大利亚的稀土产量对比”。涵盖 85 种商品中的 75 种（其余 10 种请参见下文“已知缺口”）。

身份验证

无需密钥。

数据来源

USGS 国家矿产信息中心每年发布一次 MCS，形式为仅含文件的 ScienceBase 数据发布版本——已于 2026-10-07 实时验证： ScienceBase 条目 677eaf95d34e760b392c4970 （“U.S. Geological Survey Mineral Commodity Summaries 2025 Data Release, ver. 2.0, April 2025”）包含两个 CSV 表格 ZIP 文件和一个修订说明 .txt 文件——没有任何 JSON/REST 端点：

• Salient_Commodity_Data_Release_Grouped_MCS_2025.zip — 每种商品对应一个 mcs2025-<code>_salient.csv 文件（共 85 种商品），包含最近 5 年的美国主要统计数据。列名因商品而异。
• World_Data_Release_MCS_2025.zip — 包含一个 MCS2025_World_Data.csv 文件，按国家列出全球矿山／工厂产量（此版本为 2023 年实际值＋2024 年估值）和 2024 年储量，涵盖约 79 种商品分组（分类比 85 种主要统计代码更粗略）。

scripts/bake-index.mjs 会下载这两个文件，解析所有 CSV，按名称将主要统计商品与世界表格的行匹配（针对两份出版物中命名差异，使用一份经人工核对的简短别名列表——详见脚本自身的注释，其中包括一处 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 六个州代码数据包导致的问题（集群 #2754：约 48MB 的保留堆 内存，且约四分之一的网关调用因 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 仅在国内跟踪的废料／矿渣／碎石类别，以及少数没有已发布全球储量估算的稀有元素（钪、铊、 钍）：Iron and Steel Scrap、Iron and Steel Slag、Quartz Crystal (Industrial)、Sand and Gravel (Construction)、Scandium、Stone (Crushed)、Stone (Dimension)、Thallium、Thorium、Yttrium。 mcs_country_comparison 对这些商品返回 found: false, reason: "no_world_data"，而不是空行列表。
• 原始 USGS 脚注代码（W = 为避免披露公司的专有数据而隐去，E = 估算值，NA = 不可用， ">50" 表示净进口依赖度，以及 "Less than 1/2 unit." 等自由文本注释）均按原样传递，绝不会强制转换为数字或置空——每个工具的响应都包含 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 服务。目前无法挂载不包含这些元工具的数据包端点；如果额外的 schema 消耗的上下文 超过了路由带来的价值，请连接一次完整网关，而不要连接多个数据包端点。

也可以连接完整的 Pipeworx 网关，直接列出每个数据包的工具， 而不只是当前数据包的工具：

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

两个 URL 都连接到同一个网关和相同的 1784+ 个数据源。唯一的区别是直接列出 哪个数据包的工具；从任一端点调用 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":"..."} 向 https://gateway.pipeworx.io/v1/tools/search_packs 发送 POST 请求。

独立运行（无需网关账户）

此软件包也可作为本地 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