nhtsa-vehicle-safety-mcp-server

공개 호스팅 서버: https://nhtsa.caseyjhand.com/mcp

도구

NHTSA 차량 안전 데이터를 조회하기 위한 일곱 가지 도구:

nhtsa_get_vehicle_safety

종합 안전 프로파일 — 차량 안전, 신뢰성, 구매 결정에 관한 질문 시 기본적으로 사용되는 도구입니다.

• NCAP 충돌 테스트 등급, 리콜 이력, 불만 사항 요약을 단일 응답으로 결합합니다.

• 차량 변형별 정면 충돌, 측면 충돌, 전복 등급을 제공합니다.

• 리콜 조치 설명과 함께 운전 금지, 야외 주차, 무선(OTA) 업데이트 권고를 포함합니다.

• 구성 부품별 불만 사항 분류와 함께 충돌, 화재, 부상, 사망 수를 제공합니다.

• sectionStatus 및 경고를 반환하므로 상위 API 장애가 완전한 차량 내역으로 오인되지 않습니다.

nhtsa_search_recalls

차량 또는 캠페인 번호로 리콜 캠페인을 검색합니다.

• 제조사/모델/연식 또는 특정 NHTSA 캠페인 번호로 조회합니다.

• 캠페인 조회 시 해당 캠페인이 포함하는 모든 제조사/모델과 그 이전 ODI 조사를 반환합니다.

• 선택적 날짜 범위 필터링 (ISO 8601)

• 운전 금지, 야외 주차 경고, OTA 업데이트 가능 여부 포함.

nhtsa_decode_vin

제조 및 안전 세부 정보를 위한 차량 식별 번호 디코딩.

• 단일 VIN 또는 최대 50대 VIN 일괄 디코딩.

• 부분 VIN 허용 — 알 수 없는 위치에는 * 사용.

• 누락된 데이터를 빈 값으로 채우는 대신 기본 필드를 유지합니다.

nhtsa_search_investigations

NHTSA 결함 조사 검색.

• 조사 유형: 예비조사(PE), 엔지니어링 분석(EA), 결함 제기(DP), 리홀 조회(RQ), 감사 조회(AQ), 추가 ODI 코드(SQ, EQ, RP 등).

• 조사 ID, 제목, 요약에 대한 자유 텍스트 검색과 구조화된 제조사, 모델, 부품 필터 제공.

• nhtsaId는 넓은 ID로 조사 하나를 정확히 가져오며 리홀 링크와 연결됩니다.

• NHTSA ODI 일괄 파일(FLAT_INV.zip)에서 데이터를 가져와 첫 요청 시 다운로드/파싱(약 10초)하고 이후에는 캐시된 인덱스를 사용합니다(캐시 TTL 24시간, 파일 매일 갱신).

• 페이지당 최대 25건을 반환하며 응답에는 offset/limit 및 다음 페이지의 오프셋이 포함됩니다.

nhtsa_search_complaints

NHTSA에 접수된 소비자 안전 불만 사항 검색.

• 구성 부품별 분류 및 충돌, 화재, 부상, 사망 건수.

• 선택적 제품 필터 (예: "ENGINE", "AIR BAGS")

• 접수일 기준 최대 50건 최신 불만 사항 반환.

• 신고 접수일 또는 연식과의 모순된 사건 날짜는 실제 사고일로 제공하지 않고 unreliableIncidentDate로 표시됩니다.

nhtsa_get_safety_ratings

NCAP 충돌 테스트 및 ADAS 장비 데이터.

• 정면 충돌, 측면 충돌(배리어 + 폴), 오버(overview) 등급.

• ADAS 기능: ESC, 전방 충돌 경고, 차선 이탈 경고.

• 제조사/모델/연도 또는 이전 NCAP 결과의 vehicleId 사용 가능.

• 보유 중인 불만 사항, 리콜, 조사 건수.

nhtsa_lookup_vehicles

NHTSA VPIC 데이터베이스에 대한 참조 조회.

• 네 가지 작업: makes, models, vehicle_types, manufacturer

• makes는 VPIC 전체 카탈로그에 대한 limit와 offset 페이징을 지원합니다.

• 모호한 차 이름 확인 또는 철자 검증에 유용합니다.

• 모델은 연도별로 필터링할 수 있으며, 제조업체는 부분 일치를 지원합니다.

• manufacturer는 최대 500개 레코드까지 페이징하며, 부분 일치 결과가 해당 상한에 도달하면 이를 안내합니다.

Related MCP server: vehicle-safety

주요 기능

@cyanheads/mcp-ts-core 기반 프레임워크:

• 선언적 도구 정의 — 도구 파일이 하나고, 프레임워크가 등록 및 검증 처리.

• 모든 도구에 걸져 일관된 오류 처리.

• 플러그형 인증 (none, jwt, oauth)

• 교체 가능한 저장 백엔드: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1

• 구조화 보로그와 선택형 OpenTelemetry 추적.

• 같은 코드베이스로 로컬(stdio/HTTP) 실행 가능.

NHTSA 관련:

• 4개 NHTSA JSON API를 래핑한, 타입 안전 클라이언트 및 재시도 로직과 소수 필드 정규화, ODI 조사 일괄 파일용 스트리밍 파서를 제공합니다.

• 조회 인덱스 캐싱( 24시간 TTL)로 반복 쿼리를 빠르게 처리합니다.

• API 키가 필요 없습니다 — NHTSA 모든 API는 공개입니다.

시작하기

공개 호스팅 인스턴스

공개 인스턴스는 <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를 사용하려면 전송 방식(transport)를 설정하고 서버를 시작하세요:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

사전 요구 사항

• Bun v1.3.2 이상 (또는 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

Configuration

API 키가 필요 없습니다 — NHTSA 모든 API는 공개입니다.

데이터 소스

모든 데이터는 NHTSA의 공개 API와 일괄(bulk) 파일에서 가져옵니다:

• 리콜 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  # Lints, formats, type-checks, and more
bun run test      # Runs the test suite

프로덕션

bun run build
bun run start:stdio   # Production stdio
bun run start:http    # Production HTTP

Docker

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

프로젝트 구조

개발 가이드

개발 지침 및 아키텍처 규칙은 CLAUDE.md 문서를 참고하세요. 요약:

• 핸들러가 오류를 던지면 프레임워크가 캐치합니다. 도구 로직에 try/catch를 사용하지 않습니다.

• 로깅은 ctx.log를 사용하세요.

• 파일마다 도구 하나씩, 모든 도구 이름은 nhtsa_ 접두사를 사용합니다.

기여

이슈 및 pull 요청은 언제나 환영합니다. 제출 전 검사를 실행하세요:

bun run devcheck
bun run test

라이선스

Apache-2.0 — 자세한 내용은 LICENSE 파일을 참고하세요.