@pipeworx/mcp-nhtsa 0.2.3 → 0.3.1

package/tools.json

@@ -0,0 +1,222 @@
+[
+  {
+    "name": "decode_vin",
+    "description": "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",
+      "properties": {
+        "vin": {
+          "type": "string",
+          "description": "17-character VIN (e.g., \"1HGBH41JXMN109186\")"
+        }
+      },
+      "required": [
+        "vin"
+      ]
+    }
+  },
+  {
+    "name": "get_makes",
+    "description": "Get all vehicle brands for a model year. Returns make names and IDs. E.g., year '2023'.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {}
+    }
+  },
+  {
+    "name": "get_models",
+    "description": "Get all vehicle models for a make and year. Returns model names and IDs. E.g., make 'Toyota', year '2023'.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "make": {
+          "type": "string",
+          "description": "Vehicle make name (e.g., \"Toyota\", \"Ford\", \"BMW\")"
+        },
+        "year": {
+          "type": "number",
+          "description": "Model year (e.g., 2022)"
+        }
+      },
+      "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",
+      "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",
+      "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",
+      "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": "fars_state_fatalities",
+    "description": "Fatal motor-vehicle crash counts and fatalities for a US state, from NHTSA's Fatality Analysis Reporting System (FARS). Pass a state (full name like \"Texas\", 2-letter postal code like \"TX\", or FIPS code) and a year. Returns monthly rows: crashes, fatalities, persons involved, vehicles involved, pedestrians involved. Omit year to get every loaded year/month for that state. Covers a recent multi-year window (see data_as_of and call fars_coverage for the exact range), not full FARS history. Unknown states are refused with a clear error, never an empty success.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "state": {
+          "type": "string",
+          "description": "State name (\"Texas\"), 2-letter postal code (\"TX\"), or FIPS code (\"48\")."
+        },
+        "year": {
+          "type": "number",
+          "description": "Optional: calendar year, e.g. 2023. Omit to return every loaded year for this state."
+        }
+      },
+      "required": [
+        "state"
+      ]
+    }
+  },
+  {
+    "name": "fars_vehicle_makes",
+    "description": "Vehicle makes involved in fatal crashes nationwide for a given year, from NHTSA FARS. Pass year alone to get the top makes ranked by vehicle-involvement count (e.g. \"which vehicle makes show up most in fatal crashes in 2023\"); pass make as well to get that one make's involvement count across every loaded year. This is an INVOLVEMENT count, not a claim that the make caused the crash. Unknown makes are refused with a clear error naming a few valid makes, never an empty success.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "year": {
+          "type": "number",
+          "description": "Calendar year, e.g. 2023. Required unless make is given (then optional, scoping to one year)."
+        },
+        "make": {
+          "type": "string",
+          "description": "Optional: vehicle make, e.g. \"Toyota\", \"Ford\", \"Harley-Davidson\"."
+        },
+        "limit": {
+          "type": "number",
+          "description": "Max makes to return when ranking by year. Default 20, max 50."
+        }
+      },
+      "required": []
+    }
+  },
+  {
+    "name": "fars_coverage",
+    "description": "What FARS fatal-crash data this pack actually has loaded right now: the earliest and latest year covered and when it was last loaded. Call this before fars_state_fatalities/fars_vehicle_makes if unsure a given year is covered.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {}
+    }
+  },
+  {
+    "name": "fuel_economy_mpg",
+    "description": "EPA fuel-economy ratings (city/highway/combined MPG, CO2 g/mile, fuel type) for a specific model year + make + model, from fueleconomy.gov (DOE/EPA), proxied live. Pass the model string exactly as fueleconomy.gov lists it (e.g. \"Camry\", \"F-150 2WD\", \"Model 3\") -- if unsure, call fuel_economy_models first to see valid model strings for that year+make. A model year/make/model can have several engine/transmission/drivetrain VARIANTS; this returns up to 5, each with its own MPG. Unknown make/model/year combos are refused with a clear error (never an empty success) and, when the make or model itself is not recognized for that year, list a few valid options.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "year": {
+          "type": "number",
+          "description": "Model year, e.g. 2024."
+        },
+        "make": {
+          "type": "string",
+          "description": "Vehicle make, e.g. \"Toyota\"."
+        },
+        "model": {
+          "type": "string",
+          "description": "Vehicle model exactly as fueleconomy.gov lists it, e.g. \"Camry\". Call fuel_economy_models to see valid strings."
+        }
+      },
+      "required": [
+        "year",
+        "make",
+        "model"
+      ]
+    }
+  },
+  {
+    "name": "fuel_economy_models",
+    "description": "List the exact model strings fueleconomy.gov recognizes for a given model year + make (e.g. year 2024, make \"Toyota\" -> \"Camry\", \"Camry Hybrid LE\", \"RAV4 AWD\", ...). Call this before fuel_economy_mpg when you are not sure of the exact model string, or when fuel_economy_mpg refuses a model as unrecognized.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "year": {
+          "type": "number",
+          "description": "Model year, e.g. 2024."
+        },
+        "make": {
+          "type": "string",
+          "description": "Vehicle make, e.g. \"Toyota\"."
+        }
+      },
+      "required": [
+        "year",
+        "make"
+      ]
+    }
+  }
+]

package/src/fars-store.ts

@@ -1,170 +0,0 @@
-/**
- * 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);
-}