usitc-tariffs-mcp-server

---

概述

美国协调关税税则，来自 USITC。搜索商品描述、查看分类层级、读取已公布的基本税率栏，并调查第 99 章的部分证据。可作为 stdio 进程或本地 Streamable HTTP 服务运行；无需上游账户或 API 密钥。

工具

工具	描述
usitc_search_hts	搜索描述和编码前缀，返回扁平的已公布匹配项
usitc_get_heading	查看分类层级、后代项和继承税率的来源
usitc_browse_chapter	浏览章标题，并查看税率行和统计行的数量
usitc_lookup_duty_rate	获取精确税率行或统计行的所有已公布基本税率栏
usitc_check_additional_duties	调查第 99 章候选项、证据和完整的佐证段落
usitc_list_reference	解码标识符、计划符号、章节、单位和版本元数据

功能参考

usitc_search_hts _工具

• 必填项 query：商品文本或编码前缀。limit 默认为 25，每页最多 100 项；使用相同参数传入 page.nextCursor 以获取后续页面。
• 返回 context: "flat_search_matches"，行中的 ratesResolved: false。使用税目查询查看层级，使用税率查询获取已解析的基本税率栏；没有匹配项属于成功的空结果。

usitc_get_heading _工具

• 必填 code：四位、六位或八位数字，可不带分隔符，也可使用常规点号格式。可选的返回值 nodeId 用于选择精确节点；limit 默认为 25，每页最多 100 项。
• 返回按源顺序排列的扁平 nodes，包含 parentId、可执行的 parentFollowUp，以及值为 published、inherited 或 not_published 的 resolvedRates 状态。未编号的上级行仍属于层级结构；找不到分类时返回 found: false。

---

usitc_browse_chapter _工具

• 必填 chapter：01–99，接受一位或两位数字。limit 默认为 25，每页最多 100 项。
• 对每个已发布子树返回完整的 rateLineCount 和 statisticalLineCount。第 98 章和第 99 章保留实际编号条目；未经验证的交叉表不会提供子章分组，保留章节可能返回空集合。

---

usitc_lookup_duty_rate _工具

• 必填精确的八位或十位 code；可选 ISO alpha-2 格式的 countryCode。标识符保留前导零，并接受常规点号格式。
• 返回 General、Special 和 Column 2 单元格及税率来源溯源信息，否则返回 found: false。空白统计单元格仅从匹配的八位法定上级继承；空白绝不表示零或 Free。
• specialPrograms 保留未匹配文本和 parseCoverage；countryAssessment 将成员资格保留为 unknown，将资格和税则栏选择保留为 not_determined。输入国家/地区不会选择税率，也不会确定优惠资格。

---

usitc_check_additional_duties _工具

• 必填精确的八位或十位基础商品 code，不包括第 99 章；可选 countryCode。view 为 candidates（默认值）、evidence（需要返回的 candidateCode）或 unmapped。limit 默认为 25，每页最多 100 项。
• coverage.status 始终为 partial；请检查 supportedGrammar、limitations 和未解决的证据。候选项的 legalStatus 为 not_determined。未知国家/地区及不同国家/地区的证据仍会显示；候选列表为空绝不能作为已获放行的依据。
• 按照返回的 nextCall 和证据 followUp 对象继续调用。对于段落，使用原始代码/国家/地区选择器提供 noteId 和可选的 noteCursor，省略 view、candidateCode 和集合 cursor；拼接所有页面中的 notesPage.fragments，并检查其管辖上下文。

---

usitc_list_reference _工具

• 必填 topic：identifiers、spi、chapters、units 或 releases。limit 默认为 25，每页最多 100 项。
• 项目和单位解码器附带其验证版本和引文。SPI 国家/地区成员资格仍为未知；版本记录描述已发布的版本，但不支持历史税率查询。

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔认证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、结构化日志记录，并可选启用 OpenTelemetry 跟踪。

USITC 专属功能：

• 无需密钥即可访问 HTS 应用未公开的接口，并采用限速请求和有界重试。
• 保留已发布的描述、税率字符串、单位、稀疏字段和脚注，并同时保留法律沿革。
• 按版本锁定的特别计划指标解码，以及第 99 章的部分证据研究。
• 不提供最终归类、优惠资格认定、税率叠加、综合税费计算或当前可执行性判定。请依据法律注释以及 CBP/Federal Register 的最新指引确认法律适用性。

便于 Agent 使用的输出：

• 来源信息——每个结果都包含 release、source 和 notices；版本检查可防止检测到的跨版本混用，但无法证明发布过程是原子性的，也无法证明其反映现行法律。
• 完整续传——页面会公开 total、returned、effectiveLimit 和 nextCursor；完整回复预算为 24,000 字节，可能会缩小页面大小，并设置 budgetLimited: true。游标会绑定原始参数和来源快照，有效期不超过 15 分钟；若发生驱逐或重启，也可能提前失效。
• 明确的不确定性——found、税率状态、部分覆盖情况和类型化错误原因可用于分支处理，无需猜测。遇到 cursor_expired 时，不带游标重新发起原始调用；遇到 invalid_cursor 或 invalid_selector 时，修正选择器。
• 响应形式一致——content[] 和 structuredContent 包含相同的所选数据；已发布的来源文本会作为数据呈现，而非指令。

开始使用

将以下内容添加到 MCP 客户端配置文件中。

{
  "mcpServers": {
    "usitc-tariffs-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/usitc-tariffs-mcp-server@latest"],
      "env": { "MCP_TRANSPORT_TYPE": "stdio", "MCP_LOG_LEVEL": "info" }
    }
  }
}

或使用 npx（无需 Bun）：

{
  "mcpServers": {
    "usitc-tariffs-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/usitc-tariffs-mcp-server@latest"],
      "env": { "MCP_TRANSPORT_TYPE": "stdio", "MCP_LOG_LEVEL": "info" }
    }
  }
}

或使用 Docker：

{
  "mcpServers": {
    "usitc-tariffs-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/usitc-tariffs-mcp-server:latest"]
    }
  }
}

对于 Streamable HTTP，请设置传输方式并启动构建好的服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前置条件

• Bun v1.4.0 或更高版本（已发布的程序包也支持 Node.js v24+）。
• 可访问网络并连接到 hts.usitc.gov。

安装

git clone https://github.com/cyanheads/usitc-tariffs-mcp-server.git
cd usitc-tariffs-mcp-server
bun install
cp .env.example .env
bun run rebuild

配置

变量	描述	默认值
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_HOST	HTTP 绑定地址。	127.0.0.1
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_HTTP_ENDPOINT_PATH	MCP 端点路径。	/mcp
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。	stateless
MCP_AUTH_MODE	认证方式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<app-root>/logs
STORAGE_PROVIDER_TYPE	框架存储后端。领域快照仍保留在进程内。	in-memory
OTEL_ENABLED	启用 OpenTelemetry。	false

无需设置服务专属环境变量。常见的框架覆盖项请参阅 .env.example。

运行服务

本地开发

bun run rebuild
bun run start:http
# or
bun run start:stdio

运行检查和测试：

bun run devcheck
bun run test

Docker

docker run --rm -p 3010:3010 ghcr.io/cyanheads/usitc-tariffs-mcp-server:latest

此镜像通过 3010 端口提供 HTTP 服务；公开访问前请先配置认证。

项目结构

目录	用途
src/mcp-server/tools/	六个定义、共享输出架构和无损响应格式化
src/services/usitc/	固定来源的 HTTP 客户端、版本检查、请求节流和派生快照
src/services/tariffs/	层级结构、基本税率解析和参数约束分页
src/services/reference/	标识符验证和固定版本的参考解码器
src/services/chapter99/	部分证据索引、选择器和段落片段
tests/	测试及与 src/ 目录结构对应的公开来源测试夹具
docs/	设计约定和目录树

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简而言之：

• 处理程序抛出异常，由框架捕获——工具逻辑中不要使用 try/catch。
• 使用 ctx.log 记录日志，并将 ctx.signal 传递给上游操作。
• 在 src/index.ts 的 createApp() 数组中注册工具。
• 验证原始响应、保留缺失值，并确保两种输出形式完全一致。
• 扩展证据语法时，保留部分覆盖范围和国家限定条件。

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

本项目采用 Apache 2.0 许可证。详情请参阅 LICENSE 文件。