Usgs Critical Deposits

@pipeworx/usgs-critical-deposits

美国地质调查局（USGS）的《美国关键矿产矿床》（第 3.0 版，2026 年 9 月）——涵盖 41 个州和波多黎各的 1,271 个已记录矿床，每个矿床均按矿产系统和矿床类型分类，并包含生产历史、资源量／储量数据及参考资料。数据汇编自 MRDS、ARDF 和 USMIN，以及行业报告和文献。它不同于 usgs-mrdata（原始 MRDS 矿点，不含经过整理的关键矿产资源／参考资料汇编）和 usgs-mineral-commodities（全国生产／贸易摘要，不含单个矿床记录）。

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

工具

• usgs_cmd_deposits_search(commodity?, state?, bbox?, limit?) — 按关键矿产／商品（例如“锂”“钴”“稀土”）、美国州或领地缩写和／或边界框搜索。返回每个矿床的 ID、名称、州、坐标、矿产、矿床类型和资源量数据。如果商品无法识别，则返回 found: false，并附上此数据集中实际包含矿床的完整商品列表（见下文“商品词汇表”）。
• usgs_cmd_deposit_detail(id) — 返回单个矿床的完整记录：矿产、矿床类型、矿产系统、生产历史、资源量／储量数据、参考资料、指向底层 MRDS／ARDF／USMIN 记录的链接，以及发布版本／DOI。

认证

无需密钥。

数据来源

• https://energy.usgs.gov/arcgis/rest/services/Hosted/Critical_mineral_deposits_of_the_United_States/FeatureServer/0/query — 此工具包按请求代理的实时 ArcGIS FeatureServer。
• https://doi.org/10.5066/P9K1HBNT — 数据发布页面（ScienceBase 条目 6464de5bd34ec179a83d9e6c），《美国关键矿产矿床》（第 3.0 版，2026 年 9 月）。FGDC 元数据修订日期为 2026-09-09；USGS 发布的更新公告日期为 2026-09-29。

为什么代理实时数据，而不是预置表格

该数据发布还提供仅供下载的 Excel／shapefile 文件包，但 USGS 也将相同的表格作为无需密钥的 ArcGIS FeatureServer 提供（已于 2026-10-08 验证可实时访问）。因此，与真正只能通过文件获取的 usgs-mineral-commodities 不同，这里是每次请求都实时调用的代理，而不是镜像；根据根目录 CLAUDE.md 中“代理不等于再分发”的规定，无需申请重用许可。无需 KV 预置，也没有模块作用域数据表。

上游服务的故障有明确测量记录

2026-10-08 的实时测量结果：完全相同且未经修改的查询（where=1=1&outFields=fid&resultRecordCount=3）在约 45 秒内连续六次返回 HTTP 502，随后一次则返回 HTTP 200，而我们这边没有做任何改动——这是上游 ArcGIS 托管基础设施发生故障，并非请求格式错误。此工具包中的每次调用在遇到非 2xx 状态、非 JSON 响应正文或 ArcGIS 格式的 {"error": {...}} 响应时，都会明确抛出错误并指出上游状态；绝不会退化为 found: false 或空的矿床列表，因为这会与真实的零结果查询无法区分。固定的契约见 src/index.test.ts。

商品词汇

底层数据集中的 CritMin 字段是以逗号分隔的开放文本，混合了单个元素、USGS 自己的分组简写（“ree”“pge”），以及少数原始多词条目（“palladium rhenium”“tantalum tin”）——它不是一个干净的、每种商品对应一个词条的字段，也不等同于 USGS 新闻稿中提到的“59 种关键矿物”清单（2025 年关键矿物清单共 60 种商品，减去本汇编未涉及的冶金煤）。这两个数字不同，是因为这次发布中有几种列出的商品没有已记录的矿床，也因为分组词条（ree、pge）代表了官方清单中多个单独列出的元素。

因此，本工具包会根据从数据集中实时生成的词汇表验证 commodity——即 1,271 个矿床中实际出现的所有不同逗号分隔、小写词条（测量日期：2026-10-08，共 47 个词条）——而不是重新录入一份新闻稿中的清单。这样可以确保 deposits_search 不会对某种商品报告“未找到”，而后续查询也无法匹配该商品。每个 isolate 只获取一次词汇表并进行记忆化；若获取失败，则清除记忆化结果，以便下次调用重试，而不是让该 isolate 在整个生命周期内都保留空词汇表。

已知字段问题

• state 是美国州／地区的 2 个字母缩写；波多黎各为 PR。没有国家筛选条件——此数据集仅涵盖美国（包括 PR）。
• resources1–resources4、prduction1–prduction3 和 comments1–comments3 是 USGS 自带的文本溢出续接列（单个自由文本单元格超过 254 个字符时，会溢出到下一个编号字段）——本工具包会将非空列合并到 resources／production_history／comments 数组中，而不暴露原始编号字段。
• 原始字段名末尾带有下划线的 references_（在某些 ArcGIS 客户端库中，references 是类似保留字的字段）在本工具包的输出中显示为 references。
• 源数据中的空单元格会以单个空格 " " 或字面字符串 "--" 返回，而不是空字符串或 null——在构建 resources／production_history／comments 数组前，两者都会被过滤掉。

快速开始

添加到 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "usgs-critical-deposits": {
      "url": "https://gateway.pipeworx.io/usgs-critical-deposits/mcp"
    }
  }
}

此端点实际提供的内容

https://gateway.pipeworx.io/usgs-critical-deposits/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 都会访问同一个网关和相同的 1764+ 个数据源。唯一的区别是直接列出哪个工具包的工具；无论使用哪一个，ask_pipeworx 都可以访问所有工具。

没有 MCP 客户端？通过 HTTP 调用

curl -X POST https://gateway.pipeworx.io/v1/tools/usgs_cmd_deposits_search \
  -H 'Content-Type: application/json' \
  -d '{"commodity":"lithium","state":"AR"}'

首次调用无需账号。检查任意工具：GET https://gateway.pipeworx.io/v1/tools/usgs_cmd_deposits_search。查找工具：使用 {"query":"..."} 向 https://gateway.pipeworx.io/v1/tools/search_packs 发送 POST 请求。

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

此软件包也可作为本地 stdio MCP 服务运行，无需 Pipeworx 账户，也无需经过网关往返：

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

也可以直接运行，确认它能正常启动：

npx -y @pipeworx/mcp-usgs-critical-deposits

它通过 stdin/stdout 使用 MCP 通信，并针对仅限此软件包的工具响应 initialize/tools/list/tools/call——不包含上方网关连接所添加的任何共享元工具。相同的源代码，相同的工具，无需 ask_pipeworx 路由。

使用 ask_pipeworx

你也可以用通俗的英语提问，而不是直接调用工具——这既适用于上方的软件包端点，也适用于完整网关：

ask_pipeworx({ question: "your question about Usgs Critical Deposits data" })

网关会选择合适的工具并自动填写参数。

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT