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 _工具

• 在单个响应中汇总 NCAP 碰撞测试评级、召回历史和投诉摘要
• 按车型变体提供正面碰撞、侧面碰撞和翻滚评级
• 提供召回后果说明，以及禁止驾驶、停放在室外和无线更新建议
• 按组件细分投诉，并统计碰撞、起火、受伤和死亡数量
• 返回 sectionStatus（按部分标记为 available/partial/unavailable）和 warnings，避免将 NHTSA 部分服务中断误认为记录完整无异常

---

nhtsa_search_recalls _工具

• 可按品牌／车型／年份或特定 NHTSA 召回活动编号查询，两种方式不能同时使用
• 召回活动编号查询会返回该活动涉及的所有品牌／车型，以及此前的 ODI 调查
• 两种查询方式均可选用包含边界的 dateRange（after／before，有效日历日期 YYYY-MM-DD）；空白边界视为未设置
• 包含禁止驾驶建议、停放在室外警告和 OTA 更新可用性

---

nhtsa_search_complaints _工具

• 组件细分涵盖所有匹配的投诉，不受分页影响；每页最多 50 条投诉叙述（默认 20 条），使用偏移分页，并按提交日期降序排列
• 可选的 component 筛选器会在逗号分隔的组件列表中进行匹配（例如，“ENGINE”“AIR BAGS”）
• 每个组件条目都包含碰撞、起火、受伤和死亡总数，包括零值；单条投诉保留 NHTSA 实际报告的字段
• 如果 NHTSA 报告的事故日期与投诉自身的提交日期或车型年份规则相矛盾，则会将其披露为 unreliableIncidentDate，而不会作为事故日期提供

---

nhtsa_get_safety_ratings _工具

• 接受品牌 + 车型 + 车型年份，或接受先前结果中的后续查询参数 vehicleId；不允许混用两种方式
• 提供正面碰撞、侧面碰撞（壁障 + 立柱）和翻滚评级，以及 ESC／前方碰撞／车道偏离 ADAS 的可用性
• 每条记录的投诉、召回和调查计数均按车型变体统计，而非车辆总计
• NCAP 覆盖范围始于 1990 年，2011 年及之后的车型年份数据最完整

---

nhtsa_decode_vin _工具

• 支持单个 VIN 或最多 50 个 VIN 的批量解码；部分 VIN 可用 * 表示未知位置；任何空白条目都会导致整个批次在解码前被拒绝
• 可选的 modelYear 有助于消除 1980 年以前或部分 VIN 的歧义
• 保留稀疏的 VPIC 字段，不用占位符填充缺失数据
• 每个结果都包含 VPIC 自带的 errorCode／errorText 解码质量信号，包括无错误的“0”情况

---

nhtsa_search_investigations _工具

• 调查类型：初步评估（PE）、工程分析（EA）、缺陷请愿（DP）、召回查询（RQ）、审计查询（AQ）及其他 ODI 代码（SQ、EQ、RP 等）
• 可通过自由文本搜索调查 ID、主题和摘要，并使用结构化的品牌、车型和组件筛选器；所有条件均以 AND 方式组合
• 包含边界的 openDateRange 和 closeDateRange（after／before，有效日历日期 YYYY-MM-DD）会在计数和分页前进行筛选；启用边界时，不包含缺少相应有效日期的记录
• nhtsaId 可按确切 ID 获取一项调查，且不能与其他筛选条件同时使用；这与召回链接的方向相反，从而完成从召回活动到调查的往返查询
• 数据来源为 NHTSA 的 ODI 批量文件（FLAT_INV.zip）；并发的冷查询会共用一次流式加载，截止时间为两分钟。取消一项查询不会中止其他调用者；成功加载的数据从完成时起缓存 24 小时
• 每页最多 25 项调查（默认 20 项），使用偏移分页

---

nhtsa_lookup_vehicles _工具

• 支持四种操作：makes、models、vehicle_types、manufacturer——支持对品牌或制造商名称进行部分匹配
• models 可按年份筛选；models 和 vehicle_types 都需要提供 make
• 每种操作都会拒绝不适用的筛选条件：makes 不接受任何筛选条件；models 接受 make/modelYear；vehicle_types 接受 make；manufacturer 接受 manufacturer。空白字符串视为未设置；操作必需的品牌或制造商名称不能为空
• 每页最多返回 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 专属功能：

• 类型安全的客户端，封装四种 NHTSA JSON API，并带有重试逻辑和稀疏字段规范化功能；还为 ODI 调查批量文件提供流式解析器
• 调查索引缓存（TTL 为 24h），加快重复查询速度
• 无需 API 密钥——所有 NHTSA API 均为公开接口

便于 Agent 使用的输出：

• 溯源：每个工具都会在其扩展信息块中回显 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 插桩（跨度、指标、完成日志）。	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 记录请求范围内的日志
• 每个文件定义一个工具，每个工具名称都使用 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

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。