tariff-resolver

tariff-resolver

一款 MCP 服务，可将 AI 助手变成美国进口关税查询工具——基于美国国际贸易委员会（USITC）官方《协调关税表》（US Government 公共领域数据，包含 35,000 多条关税细目）。

• 🔍 根据普通产品描述查找 HTS 编码候选项，并提供 CBP CROSS 裁定链接
• 🧮 到岸成本构成：最惠国（MFN）／自由贸易协定（FTA）基础税率 + 第 99 章附加关税（IEEPA／Section 301／232）+ MPF／HMF 费用
• 📡 关税变更追踪：将 HTS 编码加入监视列表，对比不同 HTS 修订版本的税率
• 🤖 针对 AI 优化，降低幻觉风险：返回实际的第 99 章规则文本及解析出的税率，让大模型基于真实的例外规则链进行推理，而不是编造 2024 年时期的数字

为何现在推出：最低限额豁免于 2025 年 8 月 29 日终止后，所有运往美国的货物都需要 HTS 编码并缴纳关税——而 2025—26 年的税率仍在随行政命令变化。

与任何政府机构均无关联。输出仅为报关代理预审候选项／估算值，不构成海关、法律或税务建议。估算不包括反倾销／反补贴（AD/CVD）关税。

安装

需要 Node.js ≥ 18。

claude mcp add tariff-resolver -- npx -y tariff-resolver

也可以在任何 MCP 客户端配置中使用：

{ "mcpServers": { "tariff-resolver": { "command": "npx", "args": ["-y", "tariff-resolver"] } } }

**Claude Desktop（一键安装）：**从 Releases 下载 tariff-resolver-<version>.mcpb，然后双击即可——无需使用终端。

💡 试试这些提示词

• 基本搜索： “查找一件 100% 纯棉男士 T 恤的 HTS 编码。”
• 完整场景： “计算 HTS 6109.10.00、原产地为中国、海关价值为 $5,000、采用海运的关税场景。”
• 采购决策： “我正在进口价值 $10k 的不锈钢真空保温瓶。比较从中国和越南采购的到岸成本。”
• 跟进最新变化： “跟踪我的产品目录中的关税变化：6109.10.00、8507.60.00、9617.00.10。”

工具

工具	功能
search_hs_candidates	产品描述 → 排名前列的 HTS 候选项，附带税率和 CBP CROSS 裁定链接
calculate_tariff_scenario	HTS 编码 + 原产地 + 价值（+ 重量）→ 结构化 JSON：基础 MFN／FTA 税率、候选第 99 章关税层（含每层的匹配情况／置信度）、有来源依据的 possibly_expired 分类、MPF／HMF
watch_tariff_changes	将 HTS 编码添加到本地监视列表
check_tariff_updates	对比当前与之前的 HTS 修订版本——准确查看税率变化
dataset_info	数据修订日期、行数、来源、许可证

设计

服务负责检索，大模型负责推理。第 99 章规则会原样返回（适用时附带解析后的 adder_pct），让模型读取实际的例外链，而不是盲目信任黑箱计算。10 位统计后缀的税率沿用其上级税率行。对于税则表标记为失效的标题——已终止、暂停或过期——会予以过滤并计数；美国国际贸易委员会（USITC）自己的 compiler_note 也会随附在带有该备注的规则中。

状态覆盖项。 data/status_overrides.json 是一份简短且注明来源的清单，列出了第 99 章中虽仍印在税则表上、但已停止征收、已过期或已暂停征收的标题。与某条目匹配的层会返回在 possibly_expired 中，并附上条目的 status、reason、source URL 和 as_of 日期，而不是放在 layers 中。每个条目都附有 CBP、《联邦公报》或 USITC 的来源；添加条目的拉取请求必须包含来源。

数据无法告诉你的内容。 在任何给定时刻，已发布的税则表在两个方向上都可能有误，因此每个结果都会附带 stacking_warning 和快照日期。已停止征收的条款仍可能继续印在税则表上，且没有结束日期——IEEPA 和第 122 条标题就是常见情况；新宣布的措施也可能在生效数日后才出现在税则表中。将税则表列出的所有层相加，得出的税率并非实际向任何人征收的税率。请将这些层视为候选项，并在依赖税率层叠结果前，先通过 CBP CSMS 消息核实征收状态。

一个核心，两种入口。 所有关税逻辑都位于 tariff-resolver/core（纯 TypeScript，不使用文件系统或网络）：resolveDuty(dataset, { hts, origin, value_usd?, ocean? })——origin 接受 ISO-3166 alpha-2 代码或英文国家名称——返回基础税目、单独列出的 MPF/HMF、所有带有 match 和 confidence 的候选第 99 章层、注明来源的 possibly_expired 分类，以及快照日期。MCP 工具会调用它；任何 Node 或边缘运行时也都可以调用它。无法识别的国家名称会返回 ORIGIN_UNKNOWN 错误，而非部分匹配，因此拼错的原产地绝不会悄无声息地解析为层数较少的结果。

数据

随附完整的 HTS 快照，取自 USITC 官方 JSON API（美国政府公有领域数据）。可随时刷新：

python3 scripts/fetch_hts.py   # ~2 min, fails hard rather than write a partial dataset

dataset_info 会报告查询所依据的修订日期。

隐私政策

tariff-resolver 完全在你的机器上运行，不会收集任何信息：

• 数据收集：无。不收集或传输任何查询、遥测、分析或使用数据。
• 使用与存储：你的监控列表存储在机器上的本地 JSON 文件中；所有查询均基于随附的本地数据集运行。
• 与第三方共享：无。服务在运行时不会发出网络请求。（可选的 scripts/fetch_hts.py 刷新脚本仅会连接官方 USITC API。）
• 数据保留：无需保留任何数据——你可以随时删除本地监控列表文件。
• 联系方式：[email protected]

完整政策：https://opsloft.dev/privacy

许可证

MIT。关税数据属于美国政府作品（公有领域）。