hazmat-cfr-mcp

hazmat-cfr-mcp

完整的 49 CFR 172.101 危险品表，作为供 AI Agent 使用的 MCP 工具提供——每个字段均注明所依据的固定版本 eCFR。

为 Claude、Cursor、Codex 和其他 MCP 客户端提供 DOT 危险品查询、分类和验证工具，数据基于完整的危险品表，而非示例数据。

向 Agent 提问：

我可以通过仅限货机运输 60 L 丙酮吗？需要什么标签、包装和特殊规定？

它会以结构化 JSON 返回正确的运输名称、危险类别、包装等级、标签代码、包装参考、航空器限量、船舶积载信息、解读后的特殊规定以及 CFR 引用。

有两种使用方式：

• hazmat-cfr-mcp — 供 Agent 使用的 MCP stdio 服务
• hazmat-cfr — 供用户、测试和脚本使用的本地 CLI

无需 API 密钥。无客户数据。无承运人合同。无 NMFC。仅使用公开的 CFR 数据。

包含内容

• 约 2,700 条危险品表记录（49 CFR 172.101）——所有 UN/NA 条目及禁运材料，直接从官方 eCFR 导入。
• 特殊规定解读——将所有约 420 个第 7 栏代码（49 CFR 172.102：数字、A、B、IB、IP、N、R、T、TP、W）展开为对应的法规文本。
• 图例解读——解析第 1 栏符号（+ A D G I W）、第 10A 栏船舶积载类别，以及指向第 173 部分条款的第 8A–8C 栏包装参考。
• 固定到带日期的 eCFR 快照，确保每个答案均可复现，并可引用到确切修订版本。
• 精心整理的同义词/CAS 层，可识别“IPA”“盐酸”或“漂白剂”等名称，并与法规数据明确区分。

10 秒快速体验

npx -y hazmat-cfr-mcp --help
npx -y hazmat-cfr lookup UN1088          # not in any "sample" — the whole table is here
npx -y hazmat-cfr decode-sp IB2 T8 A3

为什么要做这个项目

基础模型不擅长处理受监管的运输细节。它们可能知道丙酮是什么，但不应猜测运输描述是否完整、IB2 的含义，或哪个 CFR 字段支持某项标签要求。

此服务为 Agent 提供明确、有引用且完整的危险品工具集，让它们依据法规作答，而不是凭空编造。

准确性与验证

这是一个与合规相关的工具，因此正确性由构建流程强制保障，而非寄希望于运气：

• 数据集由 eCFR 版本 API 生成并提交到仓库（参见 docs/data-pipeline.md）。绝不手动编辑。
• 如果表格引用的任何特殊规定代码无法在 172.102 中找到，导入流程就会失败（已记录的来源勘误，例如 IP16，会明确标注为“已引用但未定义”，绝不捏造）。
• 每次运行时，test/data-integrity.test.ts 都会重新检查条目数量、结构有效性、引用完整性，以及约 22 项经过人工核验的抽查结果。
• 解析器通过 test/fixtures/ 中的测试样例进行单元测试。

⚠️ 免责声明。 这是用于展示公开 CFR 文本的信息辅助工具。它不构成法律建议，不代表合规认证，也不能替代受过培训的危险品员工。请务必根据当前的 eCFR 核实任何运输决定。

安装与运行

npx hazmat-cfr-mcp            # MCP stdio server
npx hazmat-cfr lookup UN1090  # CLI

从克隆的仓库开始：

git clone https://github.com/andretaki/hazmat-cfr-mcp.git
cd hazmat-cfr-mcp
npm install
npm run build
npm run demo

CLI：

npx hazmat-cfr lookup UN1090
npx hazmat-cfr requirements UN1830          # everything to ship it, in one call
npx hazmat-cfr placard 2.3
npx hazmat-cfr validate "UN1090, Acetone, 3, PG II"
npx hazmat-cfr segregation 3 5.1 8
npx hazmat-cfr lq 3 II 1000 12 true
npx hazmat-cfr decode-sp IB2 T8 A3
npx hazmat-cfr decode-pkg nonBulk 202

MCP 客户端配置

{
  "mcpServers": {
    "hazmat-cfr": {
      "command": "npx",
      "args": ["hazmat-cfr-mcp"]
    }
  }
}

对于本地检出版本，将 command 指向 node，并将 args 指向 dist/server.js。

工具

工具	用途
lookup_hazmat_entry	按 UN/NA 编号或正式运输名称查找；返回匹配条目，以及已解码的符号和特殊规定。
get_shipping_requirements	**一次调用 → 获取运输某种材料所需的一切信息：**身份信息、标签、已解码的包装要求、特殊规定、船舶积载信息、标牌和引用来源。
classify_shipping_description	将自由文本解析为结构化字段，然后进行验证。
validate_basic_hazmat_description	根据完整的 172.101 表验证结构化字段。
get_label_requirements	返回危险标签代码和注意事项。
get_placard	返回 49 CFR 172.504 中某危险类别的标牌名称及数量阈值。
check_basic_segregation	提供保守的成对隔离判定（49 CFR 177.848 子集）。
check_limited_quantity_eligibility	保守筛查第 3 类／第 8 类限量候选项。
decode_special_provision	将第 7 栏代码（如 IB2、T8、A3）展开为 49 CFR 172.102 中的文本。
decode_packaging_reference	将第 8A/8B/8C 栏的值解析为对应的第 173 部分条款。
explain_cfr_source	说明哪个公开的 CFR 来源支持某个字段或规则。

调用示例：

{ "query": "UN1090" }

库的使用

import { defaultCatalog, decodeSpecialProvisions, ECFR_SNAPSHOT_DATE } from "hazmat-cfr-mcp";

const acetone = defaultCatalog.lookup("UN1090");
const provisions = decodeSpecialProvisions(acetone.entries[0].specialProvisions);
console.log(`Backed by eCFR snapshot ${ECFR_SNAPSHOT_DATE}`);

刷新数据

# bump ECFR_SNAPSHOT_DATE in src/data/snapshot.ts, then:
npm run ingest -- --fresh
npm test

完整流程请参阅 docs/data-pipeline.md。

非目标

不构成法律建议；不能替代受过培训的危险品员工；不是完整的合规认证引擎；不进行 NMFC 分类；不分析承运人合同／运价表。此仓库不得包含私人客户数据、合同费率或内部业务记录。

安全

npm test
npm run typecheck
npm run scan:secrets

维护者

Andre Taki — Alliance Chemical — [email protected]

许可证

MIT — 底层的 49 CFR 文本属于美国政府的公有领域作品。