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 で、1 ページあたり最大 100 項目です。ページを続けるには、同じ引数で page.nextCursor を使用してください。
• context: "flat_search_matches" と ratesResolved: false の行を返します。系統の確認には見出し検索を、解決済みの基本関税率の取得には関税率検索を使用してください。一致項目がない場合も正常な空の結果です。

---

usitc_get_heading _ツール

• 必須の code：4、6、または8桁。区切りなし、または一般的なドット区切りの形式で指定します。返された nodeId は任意で、正確なノードを選択します。limit の既定値は25で、1ページあたり最大100件です。
• parentId、実行可能な parentFollowUp、および published、inherited、not_published のいずれかの状態を持つ resolvedRates を含む、ソース順のフラットな nodes を返します。番号のない上位行も階層の一部です。分類が見つからない場合は found: false を返します。

---

usitc_browse_chapter _ツール

• 必須の chapter：01～99。1桁または2桁を指定できます。limit の既定値は25で、1ページあたり最大100件です。
• 公開されている各サブツリーの完全な rateLineCount と statisticalLineCount を返します。第98章と第99章では実際の番号付き項目を保持します。検証済みの対応表がない場合、サブチャプターによるグループ化は行われません。また、予約章では空のコレクションが返される場合があります。

---

usitc_lookup_duty_rate _ツール

• 必須の code：正確な8桁または10桁のコード。ISO 3166-1 alpha-2 の countryCode は任意です。識別子では先頭のゼロが保持され、一般的なドット区切りの形式も使用できます。
• 料率の出典情報を含む General、Special、Column 2 の各セル、または found: false を返します。空白の統計セルは、対応する8桁の法的祖先からのみ継承されます。空白はゼロや Free を意味しません。
• specialPrograms は一致しないテキストと parseCoverage を保持します。countryAssessment では、加盟状況を unknown、適格性と列の選択を not_determined のまま保持します。国の入力によって料率が選択されたり、特恵適用資格が確立されたりすることはありません。

---

usitc_check_additional_duties _ツール

• 必須の code：第99章を除く、基本貨物の正確な8桁または10桁のコード。countryCode は任意です。view は candidates（既定値）、evidence（返された candidateCode が必要）、または unmapped を指定します。limit の既定値は25で、1ページあたり最大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で、1ページあたり最大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 のガイダンスに照らして確認してください。

エージェントに適した出力：

• 出所情報 — すべての結果に 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/	6 つの定義、共有出力スキーマ、ロスレスなレスポンス形式
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 の下でライセンスされています。詳細については、LICENSE ファイルを参照してください。