@pipeworx/mcp-nhtsa 0.2.1 → 0.2.3

package/README.md

@@ -1,12 +1,12 @@
 # NHTSA — National Highway Traffic Safety Administration
 
-The U.S. Department of Transportation's NHTSA. Vehicle recalls, complaints, investigations, crash test ratings (NCAP), safety standards, VIN decoder. The authoritative source for "is this car safe?" Free, no auth.
+The U.S. Department of Transportation's NHTSA. Vehicle recalls, complaints, investigations, crash test ratings (NCAP), safety standards, VIN decoder, fatal-crash statistics (FARS), and fuel-economy ratings. The authoritative source for "is this car safe?" and "how much gas does it use?" Free, no auth.
 
-Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 1679+ live data sources.
+Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 1877+ live data sources. This is an independent, unofficial integration — not affiliated with, endorsed by, or published by the upstream provider.
 
 ## Why this matters for AI agents
 
-For automotive research — buying a used car, evaluating recall exposure, analyzing fleet safety, doing IP / patent due diligence on vehicle technology — NHTSA is the canonical source. Pair with [USPTO patents](/docs/reference/patents) for vehicle-tech IP and [Federal Register](/docs/reference/federal-register) for proposed automotive rules.
+For automotive research — buying a used car, evaluating recall exposure, analyzing fleet safety, doing IP / patent due diligence on vehicle technology, or researching traffic-safety policy — NHTSA (plus DOE/EPA's fueleconomy.gov) is the canonical source. Pair with [USPTO patents](/docs/reference/patents) for vehicle-tech IP and [Federal Register](/docs/reference/federal-register) for proposed automotive rules.
 
 Common flows:
 
@@ -15,10 +15,12 @@ Common flows:
 - **Consumer complaints.** "Complaints about brake issues on Honda Civic?" → complaint search by make/model.
 - **VIN decoder.** "What does VIN 1HGBH41JXMN109186 tell me?" → year, make, model, engine, manufacturer details.
 - **Crash test ratings.** NCAP star ratings for vehicles.
+- **Fatal-crash statistics.** "How many traffic fatalities did Texas have in 2023?" → state-level FARS aggregates.
+- **Fuel economy.** "What's the combined MPG for a 2024 Toyota Camry?" → fueleconomy.gov lookup.
 
 ## Auth
 
-None. NHTSA's APIs are fully public, free.
+None. NHTSA's and fueleconomy.gov's APIs are fully public, free, keyless.
 
 ## Datasets
 
@@ -30,6 +32,20 @@ None. NHTSA's APIs are fully public, free.
 | **NCAP Crash Test** | Star ratings, frontal/side/rollover scores |
 | **VIN Decoder** | Decode VIN to make/model/year + manufacturer specs |
 | **TSBs** (Technical Service Bulletins) | Manufacturer service guidance |
+| **FARS** (Fatality Analysis Reporting System) | Fatal motor-vehicle crash counts, fatalities, persons/vehicles/pedestrians involved, by state/month; vehicle makes involved in fatal crashes, by year |
+| **Fuel Economy** (fueleconomy.gov, DOE/EPA) | City/highway/combined MPG, CO2 g/mile, fuel type, by model year + make + model |
+
+## FARS data (fleet #2972)
+
+NHTSA's live crash-query API returned an Akamai 403 to every probe tried on 2026-10-12, including with browser-like headers. NHTSA separately publishes FARS as annual bulk files, US federal government work and public domain, so `fars_state_fatalities`, `fars_vehicle_makes`, and `fars_coverage` are backed by those files loaded ahead of time rather than a live proxy, per CLAUDE.md "BUILD THE COPY".
+
+- **What's loaded:** `scripts/nhtsa-fars/load-data.mjs` aggregates each year's crash-level file into `fars_state_month` (state × year × month: crashes, fatalities, persons/vehicles/pedestrians involved) and the vehicle-level file into `fars_vehicle_make_year` (make × year, national: count of vehicles of that make involved in a fatal crash — an involvement count, not a causation claim). Raw crash/vehicle rows are never stored. Call `fars_coverage` for the exact years loaded.
+- **Refresh:** re-run `node scripts/nhtsa-fars/load-data.mjs --years 2022,2023,2024,2025` (add the newest published year; `--db`/`--config` override the defaults) once NHTSA publishes a new annual file — usually with roughly a one-year lag. Needs `wrangler` authenticated to the Pipeworx Cloudflare account (`CLOUDFLARE_ACCOUNT_ID` env var if the account has more than one in non-interactive mode).
+- **Known gap:** no county/city granularity and no driver/vehicle-level detail (BAC, injury severity, road conditions) — those live in FARS's other per-record files, not aggregated here. File a follow-up if a caller needs them.
+
+## fueleconomy.gov (live proxy)
+
+`fuel_economy_mpg` and `fuel_economy_models` call the DOE/EPA fueleconomy.gov vehicle data service live, per request — it's a keyless REST API with no bulk download, so there is nothing to copy. A model year + make can have several engine/transmission/drivetrain *variants* under one model string (e.g. several Camry trims); `fuel_economy_mpg` returns up to 5. Pass the model string exactly as fueleconomy.gov lists it — `fuel_economy_models` shows the valid strings for a year + make when unsure.
 
 ## Common pitfalls
 
@@ -39,6 +55,9 @@ None. NHTSA's APIs are fully public, free.
 - **Complaint counts ≠ defect rates.** Some defects produce many complaints; others produce few because they're catastrophic (drivers can't complain post-mortem). Cross-reference with crash data when relevant.
 - **VIN decoder limitations.** The free VIN decoder gives factory-spec data but doesn't reflect aftermarket modifications, accident history, or current ownership. For those, you need commercial sources (Carfax, AutoCheck).
 - **NCAP scoring evolved.** The 5-star scale changed in 2011 — earlier ratings aren't directly comparable to newer ones. Don't compare a 2008 5-star to a 2024 5-star.
+- **FARS counts FATAL crashes only.** It is not a general crash database — non-fatal crashes (the overwhelming majority) aren't in here. For general crash/injury data, FARS isn't the right source.
+- **`fars_vehicle_makes` is an involvement count, not a risk rate.** More Ford/Chevrolet/Toyota vehicles show up because those makes have far more vehicles on the road, not because they're less safe. Normalize by registrations/miles-driven before drawing a safety conclusion.
+- **`fuel_economy_mpg`'s model string must match fueleconomy.gov's own listing.** "F-150" alone won't match; it's "F150 Pickup 2WD" / "F150 Pickup 4WD" etc. Call `fuel_economy_models` first if unsure.
 
 ## Quick Start
 
@@ -84,7 +103,7 @@ directly, instead of just this one's:
 }
 ```
 
-Both URLs reach the same gateway and the same 1679+ data sources. The
+Both URLs reach the same gateway and the same 1877+ data sources. The
 only difference is which pack's tools are listed **directly**; `ask_pipeworx`
 reaches all of them from either one.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pipeworx/mcp-nhtsa",
-  "version": "0.2.1",
-  "description": "NHTSA MCP — wraps the NHTSA vPIC (Vehicle Product Information Catalog) API (free, no auth)",
+  "version": "0.2.3",
+  "description": "NHTSA MCP — wraps the NHTSA vPIC (Vehicle Product Information Catalog) API (free, no auth), NHTSA's Fatality Analysis Reporting System (FARS) fatal-crash data, and fueleconomy.gov vehicle MPG (fleet #2972).",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -26,7 +26,7 @@
     "@cloudflare/workers-types": "^4.20260405.1"
   },
   "pipeworx": {
-    "sourceHash": "v1-65db2bf0a4af4e88671b584c574e4caf9260a322071dcc9c18f7341a2a5035c5",
-    "sourceCommit": "adb69d997f82a62e8e22b594488c7d04a227db35"
+    "sourceHash": "v1-14bb9ef82ee44667f1660eb48a3483a7bd1242f9ff8d01450171f012220af4f8",
+    "sourceCommit": "774de7f685a75e02d0b828d24a7b94794102152c"
   }
 }

package/server.json

@@ -2,8 +2,8 @@
   "$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.1",
+  "description": "NHTSA MCP — wraps the NHTSA vPIC (Vehicle Product Information Catalog) API (free, no auth)…",
+  "version": "0.2.3",
   "websiteUrl": "https://pipeworx.io/packs/nhtsa",
   "repository": {
     "url": "https://github.com/pipeworx-io/mcp-nhtsa",

package/src/fars-store.ts

@@ -0,0 +1,170 @@
+/**
+ * D1 reads for the FARS fatal-crash tables added to the nhtsa pack (fleet #2972).
+ *
+ * Data: NHTSA Fatality Analysis Reporting System (FARS), annual National CSV
+ * bulk files (static.nhtsa.gov/nhtsa/downloads/FARS/<YYYY>/National/). US
+ * federal government work -- public domain (17 U.S.C. §105). FARS's live
+ * CrashAPI (crashviewer.nhtsa.dot.gov) returned an Akamai 403 to every probe
+ * on 2026-10-12, so this pack loads the annual bulk files ahead of time (CLAUDE.md "BUILD THE COPY")
+ * into D1 by scripts/nhtsa-fars/load-data.mjs -- never by a deploy. See
+ * mcps/nhtsa/README.md "FARS data".
+ */
+
+export interface D1Like {
+  prepare(sql: string): D1StmtLike;
+}
+export interface D1StmtLike {
+  bind(...values: unknown[]): D1StmtLike;
+  all<T = Record<string, unknown>>(): Promise<{ results: T[] }>;
+  first<T = Record<string, unknown>>(): Promise<T | null>;
+}
+
+export class FarsStoreUnavailableError extends Error {
+  constructor() {
+    super(
+      'nhtsa: the FARS fatal-crash store is not bound in this runtime (no _d1). This tool only answers through the Pipeworx gateway; a standalone install has no data to read.',
+    );
+    this.name = 'FarsStoreUnavailableError';
+  }
+}
+export function requireFarsDb(d1: unknown): D1Like {
+  if (!d1 || typeof (d1 as D1Like).prepare !== 'function') throw new FarsStoreUnavailableError();
+  return d1 as D1Like;
+}
+
+export const FARS_SOURCE = {
+  source: 'NHTSA Fatality Analysis Reporting System (FARS), annual National CSV files',
+  source_url: 'https://www.nhtsa.gov/research-data/fatality-analysis-reporting-system-fars',
+  license: 'US federal government work -- public domain (17 U.S.C. §105)',
+};
+
+// 2-letter postal code -> full state name used by this pack's loaded data
+// (FARS's own STATENAME values, e.g. "Texas", "District of Columbia").
+const STATE_ABBR: Record<string, string> = {
+  AL: 'Alabama', AK: 'Alaska', AZ: 'Arizona', AR: 'Arkansas', CA: 'California',
+  CO: 'Colorado', CT: 'Connecticut', DE: 'Delaware', DC: 'District of Columbia',
+  FL: 'Florida', GA: 'Georgia', HI: 'Hawaii', ID: 'Idaho', IL: 'Illinois',
+  IN: 'Indiana', IA: 'Iowa', KS: 'Kansas', KY: 'Kentucky', LA: 'Louisiana',
+  ME: 'Maine', MD: 'Maryland', MA: 'Massachusetts', MI: 'Michigan', MN: 'Minnesota',
+  MS: 'Mississippi', MO: 'Missouri', MT: 'Montana', NE: 'Nebraska', NV: 'Nevada',
+  NH: 'New Hampshire', NJ: 'New Jersey', NM: 'New Mexico', NY: 'New York',
+  NC: 'North Carolina', ND: 'North Dakota', OH: 'Ohio', OK: 'Oklahoma', OR: 'Oregon',
+  PA: 'Pennsylvania', RI: 'Rhode Island', SC: 'South Carolina', SD: 'South Dakota',
+  TN: 'Tennessee', TX: 'Texas', UT: 'Utah', VT: 'Vermont', VA: 'Virginia',
+  WA: 'Washington', WV: 'West Virginia', WI: 'Wisconsin', WY: 'Wyoming',
+  PR: 'Puerto Rico',
+};
+
+/** Resolve caller input (full name, 2-letter abbreviation, or FIPS code) to a
+ *  candidate state name/FIPS pair. Does NOT guarantee the state is actually
+ *  loaded -- call validState() for that. Returns null only on unparseable input. */
+export function resolveState(input: unknown): { byName: string | null; byFips: number | null } | null {
+  if (input == null) return null;
+  const raw = String(input).trim();
+  if (!raw) return null;
+  if (/^\d{1,2}$/.test(raw)) return { byName: null, byFips: Number(raw) };
+  const upper = raw.toUpperCase();
+  if (STATE_ABBR[upper]) return { byName: STATE_ABBR[upper], byFips: null };
+  return { byName: raw, byFips: null };
+}
+
+export async function lookupState(db: D1Like, resolved: { byName: string | null; byFips: number | null }): Promise<{ state_fips: number; state_name: string } | null> {
+  if (resolved.byFips != null) {
+    const r = await db.prepare('SELECT state_fips, state_name FROM fars_state_month WHERE state_fips = ? LIMIT 1').bind(resolved.byFips).first<{ state_fips: number; state_name: string }>();
+    return r ?? null;
+  }
+  if (resolved.byName) {
+    const r = await db
+      .prepare('SELECT state_fips, state_name FROM fars_state_month WHERE state_name = ? COLLATE NOCASE LIMIT 1')
+      .bind(resolved.byName)
+      .first<{ state_fips: number; state_name: string }>();
+    return r ?? null;
+  }
+  return null;
+}
+
+export interface FarsMeta {
+  loaded_at: string;
+  earliest_year: number;
+  latest_year: number;
+  years_loaded: number[];
+}
+let cachedMeta: FarsMeta | null = null;
+export async function getFarsMeta(db: D1Like): Promise<FarsMeta> {
+  if (cachedMeta) return cachedMeta;
+  const r = await db.prepare('SELECT key, value FROM fars_meta').all<{ key: string; value: string }>();
+  const m = Object.fromEntries(r.results.map((row) => [row.key, row.value]));
+  cachedMeta = {
+    loaded_at: m.loaded_at ?? '',
+    earliest_year: Number(m.earliest_year ?? 0),
+    latest_year: Number(m.latest_year ?? 0),
+    years_loaded: (m.years_loaded ?? '').split(',').filter(Boolean).map(Number),
+  };
+  return cachedMeta;
+}
+
+export interface StateMonthRow {
+  year: number;
+  month: number;
+  state_fips: number;
+  state_name: string;
+  crashes: number;
+  fatalities: number;
+  persons_involved: number;
+  vehicles_involved: number;
+  pedestrians_involved: number;
+}
+
+/** Monthly rows for one state and (optionally) one year. Omitting year
+ *  returns every loaded year/month for that state, most recent first. */
+export async function stateMonths(db: D1Like, stateFips: number, year: number | null): Promise<StateMonthRow[]> {
+  const where = ['state_fips = ?'];
+  const params: unknown[] = [stateFips];
+  if (year != null) {
+    where.push('year = ?');
+    params.push(year);
+  }
+  const sql = `SELECT year, month, state_fips, state_name, crashes, fatalities, persons_involved, vehicles_involved, pedestrians_involved
+    FROM fars_state_month WHERE ${where.join(' AND ')}
+    ORDER BY year DESC, month DESC`;
+  const r = await db.prepare(sql).bind(...params).all<StateMonthRow>();
+  return r.results;
+}
+
+/** All states for one year, summed across months -- for cross-state comparison. */
+export async function allStatesForYear(db: D1Like, year: number, limit: number): Promise<Array<Omit<StateMonthRow, 'month'>>> {
+  const sql = `SELECT year, state_fips, state_name,
+      SUM(crashes) AS crashes, SUM(fatalities) AS fatalities,
+      SUM(persons_involved) AS persons_involved, SUM(vehicles_involved) AS vehicles_involved,
+      SUM(pedestrians_involved) AS pedestrians_involved
+    FROM fars_state_month WHERE year = ?
+    GROUP BY state_fips, state_name
+    ORDER BY fatalities DESC
+    LIMIT ?`;
+  const r = await db.prepare(sql).bind(year, limit).all<Omit<StateMonthRow, 'month'>>();
+  return r.results;
+}
+
+export interface MakeYearRow {
+  year: number;
+  make_name: string;
+  vehicles_involved: number;
+}
+
+export async function vehicleMakesForYear(db: D1Like, year: number, limit: number): Promise<MakeYearRow[]> {
+  const sql = `SELECT year, make_name, vehicles_involved FROM fars_vehicle_make_year WHERE year = ? ORDER BY vehicles_involved DESC LIMIT ?`;
+  const r = await db.prepare(sql).bind(year, limit).all<MakeYearRow>();
+  return r.results;
+}
+
+export async function vehicleMakeYears(db: D1Like, makeName: string): Promise<MakeYearRow[]> {
+  const sql = `SELECT year, make_name, vehicles_involved FROM fars_vehicle_make_year WHERE make_name = ? COLLATE NOCASE ORDER BY year DESC`;
+  const r = await db.prepare(sql).bind(makeName).all<MakeYearRow>();
+  return r.results;
+}
+
+/** Distinct make names actually loaded (for a "did you mean" / discovery hint). */
+export async function listMakes(db: D1Like, limit = 80): Promise<string[]> {
+  const r = await db.prepare('SELECT DISTINCT make_name FROM fars_vehicle_make_year ORDER BY make_name LIMIT ?').bind(limit).all<{ make_name: string }>();
+  return r.results.map((row) => row.make_name);
+}