@pipeworx/mcp-nhtsa 0.1.0 → 0.2.0

package/README.md

@@ -1,31 +1,57 @@
-# @pipeworx/mcp-nhtsa
+# mcp-nhtsa
 
-MCP server for vehicle data via the [NHTSA vPIC API](https://vpic.nhtsa.dot.gov/api/). Free, no authentication required.
+NHTSA MCP — wraps the NHTSA vPIC (Vehicle Product Information Catalog) API (free, no auth)
+
+Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 884+ live data sources.
 
 ## Tools
 
 | Tool | Description |
 |------|-------------|
-| `decode_vin` | Decode a 17-character VIN to get make, model, year, body style, engine, and more |
-| `get_makes` | Retrieve all vehicle makes (brands) registered with NHTSA |
-| `get_models` | Get all vehicle models for a specific make and model year |
-
-## Quickstart via Pipeworx Gateway
-
-```bash
-curl -X POST https://gateway.pipeworx.io/mcp \
-  -H "Content-Type: application/json" \
-  -d '{
-    "jsonrpc": "2.0",
-    "method": "tools/call",
-    "params": {
-      "name": "nhtsa__decode_vin",
-      "arguments": { "vin": "1HGBH41JXMN109186" }
-    },
-    "id": 1
-  }'
+| `get_makes` | Get all vehicle brands for a model year. Returns make names and IDs. E.g., year \'2023\'. |
+| `get_models` | Get all vehicle models for a make and year. Returns model names and IDs. E.g., make \'Toyota\', year \'2023\'. |
+
+## Quick Start
+
+Add to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):
+
+```json
+{
+  "mcpServers": {
+    "nhtsa": {
+      "url": "https://gateway.pipeworx.io/nhtsa/mcp"
+    }
+  }
+}
 ```
 
+Or connect to the full Pipeworx gateway for access to all 884+ data sources:
+
+```json
+{
+  "mcpServers": {
+    "pipeworx": {
+      "url": "https://gateway.pipeworx.io/mcp"
+    }
+  }
+}
+```
+
+## Using with ask_pipeworx
+
+Instead of calling tools directly, you can ask questions in plain English:
+
+```
+ask_pipeworx({ question: "your question about Nhtsa data" })
+```
+
+The gateway picks the right tool and fills the arguments automatically.
+
+## More
+
+- [All tools and guides](https://github.com/pipeworx-io/examples)
+- [pipeworx.io](https://pipeworx.io)
+
 ## License
 
 MIT

package/package.json

@@ -1,18 +1,20 @@
 {
   "name": "@pipeworx/mcp-nhtsa",
-  "version": "0.1.0",
-  "description": "MCP server for vehicle data (VIN decoding, makes, models) via NHTSA vPIC API",
+  "version": "0.2.0",
+  "description": "NHTSA MCP — wraps the NHTSA vPIC (Vehicle Product Information Catalog) API (free, no auth)",
+  "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
-  "files": ["src"],
+  "keywords": ["mcp", "mcp-server", "model-context-protocol", "pipeworx", "nhtsa"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pipeworx-io/mcp-nhtsa"
+  },
   "scripts": {
-    "build": "tsc",
-    "check": "tsc --noEmit"
+    "typecheck": "tsc --noEmit"
   },
-  "keywords": ["mcp", "mcp-server", "model-context-protocol", "pipeworx", "nhtsa", "vehicles", "vin", "automotive"],
-  "author": "Pipeworx",
-  "license": "MIT",
   "devDependencies": {
-    "typescript": "^5.0.0"
+    "typescript": "^5.7.0"
   }
 }

package/server.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.pipeworx-io/nhtsa",
+  "title": "Nhtsa",
+  "description": "NHTSA MCP — wraps the NHTSA vPIC (Vehicle Product Information Catalog) API (free, no auth)",
+  "version": "0.2.0",
+  "websiteUrl": "https://pipeworx.io/packs/nhtsa",
+  "repository": {
+    "url": "https://github.com/pipeworx-io/mcp-nhtsa",
+    "source": "github"
+  },
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://gateway.pipeworx.io/nhtsa/mcp"
+    }
+  ]
+}

package/src/index.ts

@@ -1,12 +1,3 @@
-/**
- * NHTSA MCP — wraps the NHTSA vPIC (Vehicle Product Information Catalog) API (free, no auth)
- *
- * Tools:
- * - decode_vin: decode a Vehicle Identification Number into make, model, year, and attributes
- * - get_makes: retrieve all vehicle makes registered with NHTSA
- * - get_models: retrieve all models for a given make and model year
- */
-
 interface McpToolDefinition {
   name: string;
   description: string;
@@ -20,15 +11,29 @@ interface McpToolDefinition {
 interface McpToolExport {
   tools: McpToolDefinition[];
   callTool: (name: string, args: Record<string, unknown>) => Promise<unknown>;
+  meter?: { credits: number };
+  cost?: Record<string, unknown>;
+  provider?: string;
 }
 
+/**
+ * NHTSA MCP — wraps the NHTSA vPIC (Vehicle Product Information Catalog) API (free, no auth)
+ *
+ * Tools:
+ * - decode_vin: decode a Vehicle Identification Number into make, model, year, and attributes
+ * - get_makes: retrieve all vehicle makes registered with NHTSA
+ * - get_models: retrieve all models for a given make and model year
+ */
+
+
 const BASE_URL = 'https://vpic.nhtsa.dot.gov/api';
+const SAFETY_BASE = 'https://api.nhtsa.gov';
 
 const tools: McpToolExport['tools'] = [
   {
     name: 'decode_vin',
     description:
-      'Decode a 17-character Vehicle Identification Number (VIN) to get make, model, year, body style, engine, and other attributes.',
+      'Decode a VIN to get vehicle details. Returns make, model, year, body style, engine type, drivetrain, and plant. E.g., \'1HGBH41JXMN109186\'. (For recalls/ratings use get_recalls / get_safety_ratings.)',
     inputSchema: {
       type: 'object' as const,
       properties: {
@@ -42,7 +47,7 @@ const tools: McpToolExport['tools'] = [
   },
   {
     name: 'get_makes',
-    description: 'Retrieve all vehicle makes (brands) registered with NHTSA.',
+    description: 'Get all vehicle brands for a model year. Returns make names and IDs. E.g., year \'2023\'.',
     inputSchema: {
       type: 'object' as const,
       properties: {},
@@ -50,7 +55,7 @@ const tools: McpToolExport['tools'] = [
   },
   {
     name: 'get_models',
-    description: 'Get all vehicle models available for a specific make and model year.',
+    description: 'Get all vehicle models for a make and year. Returns model names and IDs. E.g., make \'Toyota\', year \'2023\'.',
     inputSchema: {
       type: 'object' as const,
       properties: {
@@ -60,6 +65,48 @@ const tools: McpToolExport['tools'] = [
       required: ['make', 'year'],
     },
   },
+  {
+    name: 'get_recalls',
+    description:
+      'Get official NHTSA safety RECALLS for a vehicle. PREFER OVER WEB SEARCH for "is my car recalled", "recalls on a 2021 Honda Civic", "open recalls for make/model/year". Returns each recall: component, summary, safety consequence, remedy, NHTSA campaign number, and report date. Pass make + model + model_year.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        make: { type: 'string', description: 'Vehicle make (e.g., "Honda")' },
+        model: { type: 'string', description: 'Vehicle model (e.g., "Civic")' },
+        model_year: { type: 'number', description: 'Model year (e.g., 2021)' },
+      },
+      required: ['make', 'model', 'model_year'],
+    },
+  },
+  {
+    name: 'get_complaints',
+    description:
+      'Get owner-filed NHTSA complaints for a vehicle — real-world problems drivers reported (vs official recalls). Use for "common problems with a 2020 Ford Explorer", "what are owners complaining about". Returns components, summary, crash/fire flags, injuries/deaths, and filing date. Pass make + model + model_year.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        make: { type: 'string', description: 'Vehicle make (e.g., "Ford")' },
+        model: { type: 'string', description: 'Vehicle model (e.g., "Explorer")' },
+        model_year: { type: 'number', description: 'Model year (e.g., 2020)' },
+      },
+      required: ['make', 'model', 'model_year'],
+    },
+  },
+  {
+    name: 'get_safety_ratings',
+    description:
+      'Get NHTSA 5-Star Safety Ratings (NCAP crash-test results) for a vehicle — overall, frontal, side, and rollover star ratings. Use for "crash test rating for a 2021 Honda Civic", "how safe is X". Pass make + model + model_year.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        make: { type: 'string', description: 'Vehicle make (e.g., "Honda")' },
+        model: { type: 'string', description: 'Vehicle model (e.g., "Civic")' },
+        model_year: { type: 'number', description: 'Model year (e.g., 2021)' },
+      },
+      required: ['make', 'model', 'model_year'],
+    },
+  },
 ];
 
 async function callTool(name: string, args: Record<string, unknown>): Promise<unknown> {
@@ -70,11 +117,95 @@ async function callTool(name: string, args: Record<string, unknown>): Promise<un
       return getMakes();
     case 'get_models':
       return getModels(args.make as string, args.year as number);
+    case 'get_recalls':
+      return getRecalls(args.make as string, args.model as string, args.model_year as number);
+    case 'get_complaints':
+      return getComplaints(args.make as string, args.model as string, args.model_year as number);
+    case 'get_safety_ratings':
+      return getSafetyRatings(args.make as string, args.model as string, args.model_year as number);
     default:
       throw new Error(`Unknown tool: ${name}`);
   }
 }
 
+function reqVehicle(make: string, model: string, year: number) {
+  if (!make || !model || !year) {
+    throw new Error('make, model, and model_year are all required (e.g., make:"Honda", model:"Civic", model_year:2021).');
+  }
+}
+
+async function getRecalls(make: string, model: string, modelYear: number) {
+  reqVehicle(make, model, modelYear);
+  const url = `${SAFETY_BASE}/recalls/recallsByVehicle?make=${encodeURIComponent(make)}&model=${encodeURIComponent(model)}&modelYear=${modelYear}`;
+  const res = await fetch(url, { headers: { Accept: 'application/json' } });
+  if (!res.ok) throw new Error(`NHTSA recalls error: ${res.status}`);
+  const data = (await res.json()) as { Count?: number; results?: Array<Record<string, unknown>> };
+  return {
+    make, model, model_year: modelYear,
+    count: data.Count ?? (data.results?.length ?? 0),
+    recalls: (data.results ?? []).map((r) => ({
+      campaign_number: r.NHTSACampaignNumber ?? null,
+      component: r.Component ?? null,
+      summary: r.Summary ?? null,
+      consequence: r.Consequence ?? null,
+      remedy: r.Remedy ?? null,
+      report_received_date: r.ReportReceivedDate ?? null,
+      manufacturer: r.Manufacturer ?? null,
+    })),
+  };
+}
+
+async function getComplaints(make: string, model: string, modelYear: number) {
+  reqVehicle(make, model, modelYear);
+  const url = `${SAFETY_BASE}/complaints/complaintsByVehicle?make=${encodeURIComponent(make)}&model=${encodeURIComponent(model)}&modelYear=${modelYear}`;
+  const res = await fetch(url, { headers: { Accept: 'application/json' } });
+  if (!res.ok) throw new Error(`NHTSA complaints error: ${res.status}`);
+  const data = (await res.json()) as { count?: number; results?: Array<Record<string, unknown>> };
+  const results = data.results ?? [];
+  return {
+    make, model, model_year: modelYear,
+    count: data.count ?? results.length,
+    complaints: results.slice(0, 25).map((c) => ({
+      odi_number: c.odiNumber ?? null,
+      components: c.components ?? null,
+      summary: c.summary ?? null,
+      date_filed: c.dateComplaintFiled ?? null,
+      crash: c.crash ?? null,
+      fire: c.fire ?? null,
+      injuries: c.numberOfInjuries ?? null,
+      deaths: c.numberOfDeaths ?? null,
+    })),
+  };
+}
+
+async function getSafetyRatings(make: string, model: string, modelYear: number) {
+  reqVehicle(make, model, modelYear);
+  const lookupUrl = `${SAFETY_BASE}/SafetyRatings/modelyear/${modelYear}/make/${encodeURIComponent(make)}/model/${encodeURIComponent(model)}`;
+  const lookupRes = await fetch(lookupUrl, { headers: { Accept: 'application/json' } });
+  if (!lookupRes.ok) throw new Error(`NHTSA safety ratings error: ${lookupRes.status}`);
+  const lookup = (await lookupRes.json()) as { Count?: number; Results?: Array<{ VehicleId?: number; VehicleDescription?: string }> };
+  const variants = (lookup.Results ?? []).filter((v) => v.VehicleId);
+  if (variants.length === 0) {
+    return { make, model, model_year: modelYear, count: 0, note: 'No NCAP crash-test ratings published for this make/model/year (not all vehicles are tested).', ratings: [] };
+  }
+
+  // Each VehicleId is a tested variant (body style/drivetrain). Resolve up to 5.
+  const ratings = await Promise.all(
+    variants.slice(0, 5).map(async (v) => {
+      const r = await fetch(`${SAFETY_BASE}/SafetyRatings/VehicleId/${v.VehicleId}`, { headers: { Accept: 'application/json' } });
+      const rd = ((await r.json()) as { Results?: Array<Record<string, unknown>> }).Results?.[0] ?? {};
+      return {
+        variant: v.VehicleDescription ?? null,
+        overall: rd.OverallRating ?? null,
+        frontal_crash: rd.OverallFrontCrashRating ?? null,
+        side_crash: rd.OverallSideCrashRating ?? null,
+        rollover: rd.RolloverRating ?? null,
+      };
+    }),
+  );
+  return { make, model, model_year: modelYear, count: ratings.length, ratings };
+}
+
 interface NhtsaResult {
   Variable?: string;
   Value?: string | null;
@@ -161,4 +292,4 @@ async function getModels(make: string, year: number) {
   };
 }
 
-export default { tools, callTool } satisfies McpToolExport;
+export default { tools, callTool, meter: { credits: 5 } } satisfies McpToolExport;

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true
+  },
+  "include": ["src"]
+}