nhtsa-vehicle-safety-mcp-server

---

概要

NHTSA の車両安全データを提供します。リコール、消費者からの苦情、NCAP 衝突試験評価、欠陥調査、VIN のデコードに対応しています。メーカー、モデル、年式ごとの安全性を一度の呼び出しでまとめて確認したり、VIN をデコードしたりできます。

ツール

ツール	説明
nhtsa_get_vehicle_safety	衝突試験評価、リコール、苦情の概要をまとめた包括的な安全性プロファイルを取得します。各セクションの利用可能状況も示します。
nhtsa_search_recalls	日付による絞り込みにも対応し、車両またはキャンペーン番号でリコールキャンペーンを検索します。
nhtsa_search_complaints	消費者からの安全性に関する苦情を、部品別の内訳と深刻度の統計とともに取得します。
nhtsa_get_safety_ratings	NCAP 衝突試験評価と ADAS 機能の利用可能状況を取得します。
nhtsa_decode_vin	メーカー、モデル、年式、エンジン、安全装備などの VIN 情報をデコードします（単件、または最大 50 件の一括処理）。
nhtsa_search_investigations	キャッシュされたインデックスを使用して、NHTSA の欠陥調査（PE、EA、DP、RQ、AQ など）を検索します。
nhtsa_lookup_vehicles	VPIC から有効なメーカー、モデル、車種、メーカーの詳細を検索します。

機能リファレンス

nhtsa_get_vehicle_safety _tool

• NCAP の衝突試験評価、リコール履歴、苦情の概要を1つのレスポンスにまとめます
• 車両バリアントごとの前面衝突、側面衝突、横転の評価
• リコールの結果に関する説明に加え、運転禁止、屋外駐車、OTA アップデートに関する注意事項
• コンポーネント別の苦情の内訳と、衝突、火災、負傷、死亡の件数
• 各セクションの sectionStatus（available／partial／unavailable）と warnings を返すため、NHTSA の一部停止を問題のない記録と誤認することがありません

---

nhtsa_search_recalls _tool

• メーカー／モデル／年、または特定の NHTSA キャンペーン番号で検索できます。これら2つの方法は併用できません
• キャンペーン番号で検索すると、対象となるすべてのメーカー／モデルと、その前段階の ODI 調査が返されます
• 省略可能な包括的 dateRange の境界値（after／before、暦上有効な YYYY-MM-DD）はどちらの方法にも適用されます。空欄の境界値は未設定として扱われます
• 運転禁止に関する注意事項、屋外駐車の警告、OTA アップデートの提供状況を含みます

---

nhtsa_search_complaints _tool

• コンポーネント別の内訳は、ページネーションにかかわらず一致するすべての苦情を対象とします。苦情の説明は1ページあたり最大50件（デフォルトは20件）で、オフセット方式のページネーションを使用し、届出日の降順に並べ替えます
• 省略可能な component フィルターは、カンマ区切りのコンポーネントリスト内を照合します（例：「ENGINE」、「AIR BAGS」）
• コンポーネントごとの各行には、ゼロ件の場合も含め、衝突、火災、負傷、死亡の合計が記載されます。個々の苦情には、NHTSA が実際に報告したフィールドが保持されます
• 苦情の届出日またはモデルイヤーから見て不可能な事故日が NHTSA によって報告された場合、その日付は事故日として提示せず、unreliableIncidentDate として開示されます

---

nhtsa_get_safety_ratings _tool

• メーカー＋モデル＋モデルイヤー、または以前の結果から取得した後続検索用の vehicleId のいずれかを指定できます。両方の方法を組み合わせると拒否されます
• 前面衝突、側面衝突（バリア＋ポール）、横転の評価に加え、ESC／前方衝突／車線逸脱に関する ADAS の提供状況
• レコードごとの苦情、リコール、調査の件数はバリアント単位であり、車両全体の合計ではありません
• NCAP の対象は1990年以降で、モデルイヤーが2011年以降の車両が最も網羅されています

---

nhtsa_decode_vin _tool

• VIN を1件、または最大50件のバッチで指定できます。不明な位置には * を使った部分 VIN も受け付けます。空欄の項目が1つでもあると、デコード前にバッチ全体が拒否されます
• 省略可能な modelYear を指定すると、1980年より前の VIN や部分 VIN の判別に役立ちます
• 欠落データをプレースホルダーで補わず、疎な VPIC フィールドをそのまま保持します
• 各結果には、正常な「0」の場合も含め、VPIC 独自のデコード品質シグナルである errorCode／errorText が含まれます

---

nhtsa_search_investigations _tool

• 調査の種類：予備評価（PE）、技術解析（EA）、欠陥請願（DP）、リコール照会（RQ）、監査照会（AQ）、および追加の ODI コード（SQ、EQ、RP など）
• 調査 ID、件名、概要を対象とするフリーテキスト検索に加え、メーカー、モデル、コンポーネントによる構造化フィルターを指定できます。すべて AND 条件で適用されます
• 包括的な openDateRange と closeDateRange の境界値（after／before、暦上有効な YYYY-MM-DD）は、件数の集計とページネーションより前に適用されます。有効な境界値がある場合、該当する日付が利用できないレコードは除外されます
• nhtsaId を指定すると、他のフィルターとは併用せず、完全一致する ID の調査を1件取得します。リコールリンクとは逆方向の検索で、キャンペーンから調査までの往復検索が完結します
• NHTSA の ODI 一括ファイル（FLAT_INV.zip）をデータソースとして使用します。コールドクエリが同時に実行される場合、2分の期限が設定された1つのストリーミング読み込みを共有します。1つのクエリをキャンセルしても、他の呼び出しは継続します。読み込みに成功すると、完了時点から24時間キャッシュされます
• 1ページあたり最大25件の調査を返します（デフォルトは20件）。オフセット方式のページネーションを使用します

---

nhtsa_lookup_vehicles _ツール

• 4 つの操作：makes、models、vehicle_types、manufacturer — メーカー名には部分一致が使用できます
• models は年で絞り込めます。models と vehicle_types にはどちらも make が必要です
• 各操作では、対象外のフィルターは拒否されます。makes はフィルターを受け付けず、models は make／modelYear、vehicle_types は make、manufacturer は manufacturer を受け付けます。空白の文字列は未設定として扱われます。操作で必須のメーカー名は空白以外で指定する必要があります
• 1 ページあたり最大 200 件（デフォルトは 100 件）を取得でき、オフセット方式のページネーションに対応しています
• manufacturer の検索は 500 件を上限とし、それを超える可能性がある場合は truncated で通知します — VPIC は一致件数の合計を公開していません

機能

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

NHTSA 固有の機能：

• 4 つの NHTSA JSON API をラップする型安全なクライアント。リトライ処理と疎なフィールドの正規化に加え、ODI 調査の一括ファイル用ストリーミングパーサーを備えています
• 繰り返しのクエリを高速化する調査インデックスのキャッシュ（TTL は 24 時間）
• API キーは不要です — すべての NHTSA API は公開されています

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

• 出典情報：各ツールはエンリッチメントブロック内で effectiveQuery を返すため、呼び出し元は検索対象を正確に確認できます
• 部分的な失敗への対応：nhtsa_get_vehicle_safety はセクションごとの sectionStatus と warnings を返すため、NHTSA の一部で障害が発生しても、安全記録に問題がないと誤認されません
• 識別可能な出力：unreliableIncidentDate（苦情）、VIN デコードの errorCode／errorText、メーカー検索の truncated により、値を黙って省略したり捏造したりせず、データ品質の制約を通知します

はじめに

公開ホストインスタンス

公開インスタンス https://nhtsa.caseyjhand.com/mcp を利用できます — インストールは不要です。Streamable HTTP 経由で、任意の MCP クライアントから接続します：

{
  "mcpServers": {
    "nhtsa-vehicle-safety-mcp-server": {
      "type": "streamable-http",
      "url": "https://nhtsa.caseyjhand.com/mcp"
    }
  }
}

セルフホスト／ローカル

MCP クライアントの設定ファイルに次の内容を追加します：

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

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

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

または Docker を使用します：

{
  "mcpServers": {
    "nhtsa-vehicle-safety-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/nhtsa-vehicle-safety-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 >= 24.0.0）

インストール

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

git clone https://github.com/cyanheads/nhtsa-vehicle-safety-mcp-server.git

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

cd nhtsa-vehicle-safety-mcp-server

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

bun install

4. 環境を設定します（任意）：

cp .env.example .env
# edit .env to override transport, auth, or storage defaults — no API key required

設定

API キーは不要です — すべての NHTSA API は公開されています。

変数	説明	デフォルト
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_HOST	HTTP サーバーのホスト。	127.0.0.1
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_HTTP_ENDPOINT_PATH	HTTP エンドポイントのパス。	/mcp
MCP_AUTH_MODE	認証モード：none、jwt、または oauth。	none
MCP_SESSION_MODE	HTTP セッションの動作モード：auto、stateful、または stateless。サーバーはコード内で stateless を宣言しています — セッションごとの状態を保持しません — この変数でその設定を上書きできます。	stateless
MCP_LOG_LEVEL	ログレベル（RFC 5424）。	info
LOG_TOOL_FAILURE_PAYLOADS	失敗した各ツール呼び出しの引数と結果をログに記録します。キー名に基づいて機密情報をマスキングし、LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（デフォルトは 16384）で指定したサイズを上限とします。自由形式の値に含まれるシークレットはマスキングされません。	false
OTEL_ENABLED	OpenTelemetry instrumentation（スパン、メトリクス、完了ログ）を有効にします。	false

オプションで上書きできる設定の全一覧については、.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
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t nhtsa-vehicle-safety-mcp-server .
docker run --rm -p 3010:3010 nhtsa-vehicle-safety-mcp-server

Dockerfile はデフォルトで HTTP トランスポートを使用し、/var/log/nhtsa-vehicle-safety-mcp-server にログを記録します。また、サーバーがすでに宣言しているステートレスセッションモードを再度指定しています。OpenTelemetry のピア依存関係はデフォルトでインストールされます。省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	目的
src/index.ts	createApp() のエントリーポイントです。ツールを登録し、NHTSA サービスを初期化します。
src/mcp-server/tools/definitions/	ツール定義（*.tool.ts）です。
src/services/nhtsa/	NHTSA API クライアント、ODI 一括ファイルパーサー、およびフィールドの正規化を扱います。
tests/	src/ に対応する単体テストと統合テストです。

開発ガイド

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

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックに try/catch を記述しないでください
• リクエストごとのログ記録には ctx.log を使用してください
• 1 ファイルにつき 1 つのツールを定義し、すべてのツール名に nhtsa_ プレフィックスを付け、createApp() に登録してください
• NHTSA の生のレスポンスを検証し、ドメイン型に正規化してから出力スキーマを返してください。NHTSA が提供していないフィールドを作り出さないでください

データソース

すべてのデータは、NHTSA の公開 API と一括ファイルから取得しています。

• リコール API — api.nhtsa.gov/recalls
• 苦情 API — api.nhtsa.gov/complaints
• 安全性評価 API — api.nhtsa.gov/SafetyRatings
• 調査一括ファイル — static.nhtsa.gov/odi/ffdd/inv/FLAT_INV.zip
• VPIC API — vpic.nhtsa.dot.gov/api/vehicles

コントリビューション

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

bun run devcheck
bun run test

ライセンス

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