usitc-tariffs-mcp-server

---

Overview

The U.S. Harmonized Tariff Schedule from the USITC. Search commodity descriptions, inspect classification ancestry, read published base duty columns, and investigate partial Chapter 99 evidence. Runs as a stdio process or a local Streamable HTTP server; no upstream account or API key is required.

Tools

Tool	Description
usitc_search_hts	Search descriptions and code prefixes as flat published matches
usitc_get_heading	Inspect classification ancestry, descendants, and inherited-rate sources
usitc_browse_chapter	Browse chapter headings with rate-line and statistical-line counts
usitc_lookup_duty_rate	Retrieve every published base duty column for an exact rate or statistical line
usitc_check_additional_duties	Research Chapter 99 candidates, evidence, and complete supporting passages
usitc_list_reference	Decode identifiers, program symbols, chapters, units, and edition metadata

Capability reference

usitc_search_hts _tool

• Required query: commodity text or a code prefix. limit defaults to 25, with at most 100 items per page; follow page.nextCursor with the same arguments.
• Returns context: "flat_search_matches" and rows with ratesResolved: false. Use heading lookup for ancestry and duty lookup for resolved base columns; no matches is a successful empty result.

---

usitc_get_heading _tool

• Required code: four, six, or eight digits, bare or conventionally dotted. Optional returned nodeId selects an exact node; limit defaults to 25, at most 100 per page.
• Returns flat source-order nodes with parentId, executable parentFollowUp, and resolvedRates states of published, inherited, or not_published. Unnumbered superior rows remain part of the hierarchy; a missing classification returns found: false.

---

usitc_browse_chapter _tool

• Required chapter: 01–99, accepting one or two digits. limit defaults to 25, at most 100 entries per page.
• Returns complete rateLineCount and statisticalLineCount per published subtree. Chapters 98 and 99 retain their actual numbered entries; subchapter grouping is absent without a verified crosswalk, and reserved chapters can return an empty collection.

---

usitc_lookup_duty_rate _tool

• Required exact eight- or ten-digit code; optional ISO alpha-2 countryCode. Identifiers retain leading zeros and accept conventional dots.
• Returns General, Special, and Column 2 cells with rate-source provenance, or found: false. Blank statistical cells inherit only from the matching eight-digit legal ancestor; blank never means zero or Free.
• specialPrograms preserves unmatched text and parseCoverage; countryAssessment keeps membership unknown, eligibility and column selection not_determined. Country input does not select a rate or establish preference qualification.

---

usitc_check_additional_duties _tool

• Required exact eight- or ten-digit base commodity code, excluding Chapter 99; optional countryCode. view is candidates (default), evidence (requires returned candidateCode), or unmapped. limit defaults to 25, at most 100 per page.
• coverage.status is always partial; inspect supportedGrammar, limitations, and unresolved evidence. Candidate legalStatus is not_determined. Unknown and different-country evidence remains visible; an empty candidate list never establishes clearance.
• Follow returned nextCall and evidence followUp objects. For passages, supply noteId and optional noteCursor with the original code/country selectors, omitting view, candidateCode, and collection cursor; concatenate all notesPage.fragments across pages and inspect governing context.

---

usitc_list_reference _tool

• Required topic: identifiers, spi, chapters, units, or releases. limit defaults to 25, at most 100 entries per page.
• Program and unit decoders carry their verification edition and citations. SPI country membership remains unknown; release records describe published editions without enabling historical tariff lookup.

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

USITC-specific:

• Keyless access to the HTS application's undocumented interfaces, with paced requests and bounded retries.
• Published descriptions, rate strings, units, sparse fields, and footnotes preserved alongside legal ancestry.
• Edition-pinned Special Program Indicator decoding and partial Chapter 99 evidence research.
• No conclusive classification, preference qualification, duty stacking, combined-duty calculation, or current-enforceability determination. Confirm legal applicability against legal notes and current CBP/Federal Register guidance.

Agent-friendly output:

• Provenance — every result carries release, source, and notices; edition checks prevent detected cross-edition mixing, but do not prove atomic publication or current law.
• Complete continuation — pages expose total, returned, effectiveLimit, and nextCursor; a 24,000-byte complete-reply budget can reduce page size with budgetLimited: true. Cursors bind the original arguments and source snapshot, expire within 15 minutes, and can expire earlier after eviction or restart.
• Explicit uncertainty — found, rate states, partial coverage, and typed error reasons support branching without guessing. Restart the original call without cursors after cursor_expired; fix selectors after invalid_cursor or invalid_selector.
• Matching response surfaces — content[] and structuredContent carry the same selected data; published source text is framed as data rather than instructions.

Getting started

Add the following to your MCP client configuration file.

{
  "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" }
    }
  }
}

Or with npx (no Bun required):

{
  "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" }
    }
  }
}

Or with 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"]
    }
  }
}

For Streamable HTTP, set the transport and start the built server:

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

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+ for the published package).
• Network access to hts.usitc.gov.

Installation

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

Configuration

Variable	Description	Default
MCP_TRANSPORT_TYPE	Transport: stdio or http.	stdio
MCP_HTTP_HOST	HTTP bind address.	127.0.0.1
MCP_HTTP_PORT	HTTP server port.	3010
MCP_HTTP_ENDPOINT_PATH	MCP endpoint path.	/mcp
MCP_SESSION_MODE	HTTP session mode: stateless, stateful, or auto.	stateless
MCP_AUTH_MODE	Authentication: none, jwt, or oauth.	none
MCP_LOG_LEVEL	Log level (debug, info, warning, error, etc.).	info
LOGS_DIR	Directory for log files (Node.js only).	<app-root>/logs
STORAGE_PROVIDER_TYPE	Framework storage backend. Domain snapshots remain in process.	in-memory
OTEL_ENABLED	Enable OpenTelemetry.	false

No server-specific environment variables are required. See .env.example for common framework overrides.

Running the server

Local development

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

Run checks and tests:

bun run devcheck
bun run test

Docker

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

The image serves HTTP on port 3010; configure authentication before exposing it publicly.

Project structure

Directory	Purpose
src/mcp-server/tools/	Six definitions, shared output schemas, and lossless response formatting
src/services/usitc/	Fixed-origin HTTP client, edition checks, pacing, and derived snapshots
src/services/tariffs/	Hierarchy, base-rate resolution, and argument-bound pagination
src/services/reference/	Identifier validation and edition-pinned reference decoders
src/services/chapter99/	Partial evidence indexing, selectors, and passage fragments
tests/	Tests and public-source fixtures mirroring src/
docs/	Design contracts and directory tree

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic.
• Use ctx.log for logging and propagate ctx.signal to upstream work.
• Register tools in the createApp() array in src/index.ts.
• Validate raw responses, preserve missing values, and keep both output surfaces identical.
• Preserve partial-coverage and country-qualification limits when extending the evidence grammar.

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.