cpsc-recalls-mcp-server

---

概要

CPSC の saferproducts.gov データベースにある消費者製品リコールを扱います。対象は、おもちゃ、電子機器、家具、家電、子ども向け製品、工具、衣類です。製品、ブランド、小売業者、危険性でリコールを検索したり、特定のリコール番号の詳細を取得したり、指定した期間の最近のリコール一覧を取得したりできます。

ツール

ツール	説明
cpsc_search_recalls	タイトル、製品名、ブランド、小売業者、輸入業者、販売業者、危険性、救済措置、説明のキーワードで消費者製品リコールを検索します。日付による絞り込みとオフセットを使ったページ送りも指定できます
cpsc_get_recall	リコール番号を指定して、単一のリコールの詳細（危険性、救済措置、製品、負傷、画像、CPSC の公式ページ）を取得します
cpsc_get_recent	設定可能な期間内の最新のリコールを、新しい順に取得します

CPSC の管轄は消費者製品のみです。食品・医薬品（FDA）、自動車・タイヤ（NHTSA）、ボート（USCG）、農薬（EPA）、銃器（ATF）はこのデータベースの対象外です。すべての応答には管轄に関する注記が含まれます。

機能リファレンス

cpsc_search_recalls _ツール

• ANDで組み合わせる条件を1つ以上指定します。各最大500文字の9つのテキストフィルター（最も有力な情報となることが多いtitle_searchに加え、product_name、manufacturer、retailer、importer、distributor、description_search、remedy、hazard_search）と、2つの日付軸（発行日を指定するdate_start／date_end、CPSCの最終公開日を指定するupdated_start／updated_end）を使用できます。limit（1～200、デフォルトは20）とoffsetでtotal_foundをページ分割します
• 危険性、救済措置の選択肢と手順、製品、UPC、役割別の企業名、画像、cpsc_url、リコールごとのdata_quality_notesを返します。一致するものがない場合は、条件を反映したeffectiveQueryを返す空の成功レスポンスとなり、緩和すべき条件を示す通知が含まれます。失敗：missing_criteria、invalid_date_range、upstream_rejected（再試行不可）、upstream_error（再試行可能）
• has_moreはページ分割の指標です。レスポンスが64,000バイトの上限で途中までになる場合は、続きから取得するためのオフセットを示す通知が含まれます

---

cpsc_get_recall _ツール

• recall_numberを1つ指定します。2002年以降の記録では5桁（"25043"）、1998～2001年の記録では5桁と英字a～d（"99003a"）を指定します
• 完全な記録を返します。description（通常、モデル番号が含まれます。値がない場合はnull）、危険性、救済措置の選択肢と手順、すべての製品バリエーション、UPC、負傷に関する説明、役割別の企業名、製造国、画像、連携機関によるリコールのURL、data_quality_notesが含まれます
• 失敗：not_found（cpsc_search_recallsまたはcpsc_get_recentで番号を特定してください）、upstream_rejected（再試行不可）、upstream_error（再試行可能）

---

cpsc_get_recent _ツール

• 今日を基準とする遡及期間days（1～365、デフォルトは30）を指定します。limit（1～100、デフォルトは20）とoffsetでtotal_foundをページ分割します。daysを狭めると古いリコールがページ分割されるのではなく除外されるためです。より古いリコールは、日付範囲を指定したcpsc_search_recallsで取得できます
• リコールごとに、cpsc_get_recallで詳細を取得できる簡易レコード（番号、日付、タイトル、危険性、救済措置の種類、製品名、cpsc_url、data_quality_notes）を返します。has_moreはページ分割の指標です。対象期間内に記録がない場合、末尾を超えるオフセットが指定された場合、またはレスポンスが上限で途中までになる場合は、通知が含まれます。失敗：upstream_rejected（再試行不可）、upstream_error（再試行可能）

特徴

@cyanheads/mcp-ts-core を基盤としています。stdio および Streamable HTTP トランスポート、プラグイン可能な認証（none / jwt / oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレーシングを備えた構造化ログに対応しています。

CPSC 固有の機能：

• CPSC の saferproducts.gov 公開リコール API 用の完全なクライアント。検索、個別リコールの詳細、最近のリコールフィードに対応しています
• 9 つすべてのテキストフィルターで、単語ごとの一致をサポートします。各単語は順不同、大文字・小文字を区別せず、結果に表示されるプレーンテキストを対象に照合されます。ページング前に結果全体へ適用されるため、total_found と has_more は正確な値を保ちます。hazard_search（別名 hazard）は、危険情報のテキスト、製品名、改善指示を対象とします
• 最新の 5 桁のリコール番号と、文字の接尾辞が付いた 1998〜2001 年の過去の記録の両方を処理します
• すべての応答に管轄の境界を記載します。エージェントが誤った管轄の情報として扱う前に、対象外の食品、自動車、医薬品のリコールにフラグを立てます

エージェント向けの出力：

• すべての応答に出典情報を付与します。source_note、cpsc_url、および引用ブロックの (CPSC source text) ラベルによって、伝達された CPSC の説明とサーバー独自のガイダンスを区別します
• どちらの表示形式でもプレーンテキストを使用します。CPSC が一部の記録に保存している HTML マークアップと文字コード（&、<br>、不要なテーブルタグ）は、一致判定と出力の前にプレーンテキストへ変換されます。また、content[] では Markdown をエスケープするため、1HFVE05**K4000003 などのモデル番号やシリアル番号の文字がすべて保持されます。リコールページと関連リコールはリンクとして表示され、製品画像はキャプション付きでインライン表示されます。HTTP(S) アドレスはどちらの表示形式でも CPSC の URL 値を保持し、それ以外のスキームはテキストとして表示されます
• ページネーション用の判別情報として、すべての検索／最近のリコール応答に total_found、offset、has_more、truncated を含めるため、エージェントは結果が切り詰められているかを確認し、offset を指定して次のページを取得できます。ページの各表示形式は 64,000 バイト以内に収まり、バイト数の上限によってページが途中で終わった場合は、次のオフセットを通知します
• すべての応答に data_quality_notes を含めます。上流の記録で確認された不足（危険情報のテキストがない、製品エントリーがないなど）を、判断を加えず、CPSC が空欄にしたフィールドに基づいて示します
• すべての応答に管轄に関する注記（cpsc_jurisdiction）を含めます。製品が対象外の場合、エージェントが問い合わせを適切な機関（FDA、NHTSA、USCG、EPA、ATF）へ案内できます

はじめに

公開ホストインスタンス

https://cpsc-recalls.caseyjhand.com/mcp で公開インスタンスを利用できます。インストールは不要です。Streamable HTTP を提供しており、クライアントごとに設定形式が異なります。

Claude Code の場合：

claude mcp add --transport http cpsc-recalls-mcp-server https://cpsc-recalls.caseyjhand.com/mcp

Cline の場合（cline_mcp_settings.json）：

{
  "mcpServers": {
    "cpsc-recalls-mcp-server": {
      "type": "streamableHttp",
      "url": "https://cpsc-recalls.caseyjhand.com/mcp"
    }
  }
}

Cursor の場合（mcp.json）：

{
  "mcpServers": {
    "cpsc-recalls-mcp-server": {
      "url": "https://cpsc-recalls.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop では、Settings → Connectors からリモートサーバーを追加できます。

セルフホスト／ローカル

以下を MCP クライアントの設定ファイルに追加します。

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

または、npx を使用します（Bun は不要です）。

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

または、Docker を使用します。

{
  "mcpServers": {
    "cpsc-recalls-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/cpsc-recalls-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 以降）。
• API キーは不要です。CPSC の公開リコール API は無料で利用できます。

インストール

1. リポジトリをクローンします：

git clone https://github.com/cyanheads/cpsc-recalls-mcp-server.git

2. ディレクトリに移動します：

cd cpsc-recalls-mcp-server

3. 依存関係をインストールします：

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env if needed — no required API keys

設定

すべての設定は、起動時に Zod スキーマを使って検証されます。主な環境変数は次のとおりです。

変数	説明	デフォルト
MCP_TRANSPORT_TYPE	トランスポート：stdio または http	stdio
MCP_HTTP_PORT	HTTP サーバーのポート	3010
MCP_HTTP_HOST	HTTP サーバーのホスト	127.0.0.1
MCP_HTTP_ENDPOINT_PATH	HTTP エンドポイントのパス	/mcp
MCP_PUBLIC_URL	TLS 終端リバースプロキシを使用するデプロイ向けの公開オリジン	—
MCP_SESSION_MODE	セッション処理：auto、stateful、または stateless。サーバーは src/index.ts で stateless を宣言します。設定すると、この宣言が上書きされます。	stateless
MCP_AUTH_MODE	認証：none、jwt、または oauth	none
MCP_LOG_LEVEL	ログレベル（debug、info、warning、error）	info
LOGS_DIR	ログファイルのディレクトリ（Node.js のみ）	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	失敗したツール呼び出しごとに、引数と結果をログに記録します。キー名に基づいて機密情報をマスキングし、LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（デフォルトは 16384）で上限を設けます。自由形式の値に含まれるシークレットはマスキングされません。	false
STORAGE_PROVIDER_TYPE	ストレージバックエンド：in-memory、filesystem、supabase、cloudflare-kv/r2/d1	in-memory
OTEL_ENABLED	OpenTelemetry を有効にするかどうか	false

サーバー固有の API キーは不要です。オプションの設定項目の全一覧については、.env.example を参照してください。

サーバーの実行

ローカル開発

• 本番用バージョンをビルドして実行する：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• チェックとテストを実行する：

  bun run devcheck  # Lint, format, typecheck, security
  bun run test      # Vitest test suite
  

Docker

docker build -t cpsc-recalls-mcp-server .
docker run --rm -p 3010:3010 cpsc-recalls-mcp-server

Dockerfile では、デフォルトで HTTP トランスポート、ステートレスセッションモードが設定され、ログは /var/log/cpsc-recalls-mcp-server に出力されます。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	目的
src/index.ts	createApp() エントリーポイント。ツールを登録し、CPSC サービスを初期化します
src/mcp-server/tools	ツール定義（definitions/*.tool.ts）：search、get-recall、get-recent。これに加えて、2 つのリストツールで共有するページサイズの上限を定める response-budget.ts と、content[] 内の CPSC テキストに適用されるエスケープ処理を行う markdown-escape.ts があります
src/services/cpsc-recall	CPSC リコールサービス。API クライアント、型、および CPSC の HTML マークアップと文字コードをプレーンテキストに変換する normalize-text.ts で構成されます

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md ／ AGENTS.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークがキャッチします。ツールのロジックで try/catch は使用しないでください。
• リクエストスコープのロギングには ctx.log を、テナントスコープのストレージには ctx.state を使用してください。
• 新しいツールは、src/index.ts の createApp() 配列に登録してください。
• 外部 API 呼び出しはラップしてください。生データを検証し、ドメイン型に正規化してから、出力スキーマに従って返します。不足しているフィールドを捏造してはいけません。

貢献

問題の報告を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0。詳細は LICENSE を参照してください。