io.github.cyanheads/usitc-tariffs-mcp-server

@cyanheads/usitc-tariffs-mcp-server

Search USITC tariff schedules, inspect heading trees, and look up published duty rates via MCP. STDIO or Streamable HTTP.

6 Tools • 0 Resources • 0 Prompts

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

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

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

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.