vin-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 keptlive
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# VIN MCP
+
+**Free VIN decoder for humans and AI. No API keys. No accounts. No limits.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js 18+](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org)
+[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io)
+[![Smithery](https://smithery.ai/badge/@keptlive/vin-mcp)](https://smithery.ai/server/@keptlive/vin-mcp)
+
+[mcp.vin](https://mcp.vin) -- Try it now
+
+---
+
+## What It Does
+
+Enter a 17-character VIN and get a comprehensive vehicle report by aggregating six free data sources into a single response:
+
+| Source | Data Provided |
+|--------|--------------|
+| **NHTSA vPIC** | Make, model, year, trim, body class, engine specs, transmission, drive type, weight, plant info, 140+ decoded fields |
+| **NHTSA Recalls** | Open recalls with campaign number, component, summary, consequence, and remedy |
+| **NHTSA Complaints** | Consumer complaints with crash, fire, injury, and death statistics |
+| **NHTSA Safety Ratings** | NCAP star ratings for overall, frontal, side, and rollover crash tests |
+| **EPA Fuel Economy** | City/highway/combined MPG, annual fuel cost, CO2 emissions, EV range and charge time |
+| **IMAGIN.studio** | Stock vehicle photos from multiple angles |
+
+Additionally, VIN validation (checksum, WMI country/manufacturer decode, model year) is computed locally with zero API calls.
+
+---
+
+## Quick Start -- Connect via MCP
+
+### Smithery (one command)
+
+```bash
+npx -y @smithery/cli install @keptlive/vin-mcp --client claude
+```
+
+### Claude Code (stdio)
+
+Add to your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "vin": {
+      "command": "npx",
+      "args": ["-y", "vin-mcp"]
+    }
+  }
+}
+```
+
+Or if you have the repo cloned locally:
+
+```json
+{
+  "mcpServers": {
+    "vin": {
+      "command": "node",
+      "args": ["/path/to/vin-mcp/server.mjs"]
+    }
+  }
+}
+```
+
+### Claude Desktop / claude.ai (HTTP)
+
+Use the hosted MCP endpoint:
+
+```
+https://mcp.vin/mcp
+```
+
+Add to your Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "vin": {
+      "url": "https://mcp.vin/mcp"
+    }
+  }
+}
+```
+
+---
+
+## MCP Tools
+
+| Tool | Description | Input |
+|------|-------------|-------|
+| `decode_vin` | Full VIN decode with specs, recalls, complaints, safety ratings, fuel economy, and photos | `{ vin: string }` |
+| `validate_vin` | Quick local validation -- checksum, WMI country/manufacturer, model year. No external API calls | `{ vin: string }` |
+| `lookup_recalls` | Look up recalls by VIN or by make/model/year | `{ vin?: string, make?: string, model?: string, year?: number }` |
+| `batch_decode` | Decode up to 50 VINs in a single request via NHTSA batch API | `{ vins: string[] }` |
+
+---
+
+## REST API
+
+All endpoints are available at `https://mcp.vin` or on your self-hosted instance.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/vin/:vin` | Full decode -- all 6 sources aggregated |
+| `GET` | `/api/vin/:vin/validate` | Quick checksum and format validation |
+| `GET` | `/api/vin/:vin/recalls` | Recall data only |
+| `GET` | `/api/vin/:vin/complaints` | Consumer complaints only |
+| `GET` | `/api/vin/:vin/safety` | NCAP safety ratings only |
+| `GET` | `/api/vin/:vin/fuel` | EPA fuel economy only |
+| `GET` | `/api/vin/:vin/photo` | Redirects to vehicle photo URL |
+| `POST` | `/api/batch` | Batch decode (body: `{ "vins": ["VIN1", "VIN2", ...] }`, max 50) |
+
+Rate limits: 30 requests/minute per IP for most endpoints, 60/minute for validation and photos, 5/minute for batch.
+
+**Example:**
+
+```bash
+curl https://mcp.vin/api/vin/1HGCM82633A004352
+```
+
+Direct VIN URLs also work -- visit `https://mcp.vin/1HGCM82633A004352` to see the web report.
+
+---
+
+## Self-Hosting
+
+```bash
+git clone https://github.com/keptlive/vin-mcp.git
+cd vin-mcp
+npm install
+node server.mjs --http --port 3200
+```
+
+The server starts in HTTP mode with:
+- Web frontend at `http://localhost:3200`
+- REST API at `http://localhost:3200/api/vin/{vin}`
+- MCP endpoint at `http://localhost:3200/mcp`
+
+For stdio mode (Claude Code integration without a web server):
+
+```bash
+node server.mjs
+```
+
+---
+
+## How VINs Work
+
+A VIN (Vehicle Identification Number) is a 17-character code assigned to every vehicle manufactured since 1981. Each position encodes specific information:
+
+```
+1 H G C M 8 2 6 3 3 A 0 0 4 3 5 2
+|_____| |___| | | | |_| |_________|
+  WMI    VDS  | | | |yr  Sequential
+              | | | plant
+              | | check digit
+              | vehicle attributes
+              manufacturer ID
+```
+
+- **Positions 1-3 (WMI):** World Manufacturer Identifier -- country and manufacturer
+- **Positions 4-8 (VDS):** Vehicle Descriptor Section -- model, body, engine, transmission
+- **Position 9:** Check digit -- validates the VIN using a weighted algorithm
+- **Position 10:** Model year code (A-Y, 1-9 on a 30-year cycle)
+- **Position 11:** Assembly plant
+- **Positions 12-17:** Sequential production number
+
+The letters I, O, and Q are never used in VINs to avoid confusion with 1, 0, and 9.
+
+---
+
+## Tech Stack
+
+- **Runtime:** Node.js 18+
+- **Server:** Express 5
+- **MCP SDK:** `@modelcontextprotocol/sdk` with stdio and Streamable HTTP transports
+- **Frontend:** Vanilla HTML, CSS, and JavaScript
+- **Caching:** In-memory LRU with TTL (1h for decodes, 6h for recalls, 24h for ratings and fuel data)
+- **External dependencies:** Zero API keys required -- all data sources are free public APIs
+
+---
+
+## License
+
+MIT
+
+---
+
+Built for [mcp.vin](https://mcp.vin)

package/lib/auth.mjs

@@ -0,0 +1,48 @@
+import crypto from 'node:crypto';
+
+const SCRYPT_OPTS = { N: 16384, r: 8, p: 1 };
+
+export function hashPassword(password) {
+  const salt = crypto.randomBytes(16).toString('hex');
+  return new Promise((resolve, reject) => {
+    crypto.scrypt(password, salt, 64, SCRYPT_OPTS, (err, key) => {
+      if (err) reject(err);
+      else resolve({ hash: key.toString('hex'), salt });
+    });
+  });
+}
+
+export function verifyPassword(password, hash, salt) {
+  return new Promise((resolve, reject) => {
+    crypto.scrypt(password, salt, 64, SCRYPT_OPTS, (err, key) => {
+      if (err) reject(err);
+      else resolve(crypto.timingSafeEqual(Buffer.from(hash, 'hex'), key));
+    });
+  });
+}
+
+export function createToken(payload, secret, expiresInSec = 86400) {
+  const header = Buffer.from(JSON.stringify({ alg: 'HS256', typ: 'JWT' })).toString('base64url');
+  const now = Math.floor(Date.now() / 1000);
+  const body = Buffer.from(JSON.stringify({ ...payload, iat: now, exp: now + expiresInSec })).toString('base64url');
+  const sig = crypto.createHmac('sha256', secret).update(`${header}.${body}`).digest('base64url');
+  return `${header}.${body}.${sig}`;
+}
+
+export function verifyJwt(token, secret) {
+  try {
+    const parts = token.split('.');
+    if (parts.length !== 3) return null;
+    const [header, body, sig] = parts;
+    const expected = crypto.createHmac('sha256', secret).update(`${header}.${body}`).digest('base64url');
+    const sigBuf = Buffer.from(sig, 'base64url');
+    const expectedBuf = Buffer.from(expected, 'base64url');
+    if (sigBuf.length !== expectedBuf.length) return null;
+    if (!crypto.timingSafeEqual(sigBuf, expectedBuf)) return null;
+    const payload = JSON.parse(Buffer.from(body, 'base64url').toString());
+    if (payload.exp < Math.floor(Date.now() / 1000)) return null;
+    return payload;
+  } catch {
+    return null;
+  }
+}

package/lib/cache.mjs

@@ -0,0 +1,65 @@
+// LRU Cache with TTL for VIN decode results
+
+const DEFAULT_MAX = 1000;
+const DEFAULT_TTL = 60 * 60 * 1000; // 1 hour
+
+export class LRUCache {
+  constructor(max = DEFAULT_MAX, ttl = DEFAULT_TTL) {
+    this.max = max;
+    this.ttl = ttl;
+    this.map = new Map(); // key → { value, expires }
+  }
+
+  get(key) {
+    const entry = this.map.get(key);
+    if (!entry) return undefined;
+    if (Date.now() > entry.expires) {
+      this.map.delete(key);
+      return undefined;
+    }
+    // Move to end (most recent)
+    this.map.delete(key);
+    this.map.set(key, entry);
+    return entry.value;
+  }
+
+  set(key, value) {
+    this.map.delete(key); // remove old position
+    this.map.set(key, { value, expires: Date.now() + this.ttl });
+    // Evict oldest if over capacity
+    if (this.map.size > this.max) {
+      const oldest = this.map.keys().next().value;
+      this.map.delete(oldest);
+    }
+  }
+
+  has(key) {
+    return this.get(key) !== undefined;
+  }
+
+  delete(key) {
+    return this.map.delete(key);
+  }
+
+  clear() {
+    this.map.clear();
+  }
+
+  get size() {
+    return this.map.size;
+  }
+
+  // Prune all expired entries
+  prune() {
+    const now = Date.now();
+    for (const [key, entry] of this.map) {
+      if (now > entry.expires) this.map.delete(key);
+    }
+  }
+}
+
+// Shared cache instances
+export const vinCache = new LRUCache(1000, 60 * 60 * 1000);     // 1hr for full decodes
+export const recallCache = new LRUCache(500, 6 * 60 * 60 * 1000); // 6hr for recalls (change less often)
+export const ratingCache = new LRUCache(500, 24 * 60 * 60 * 1000); // 24hr for safety ratings (static)
+export const fuelCache = new LRUCache(500, 24 * 60 * 60 * 1000);  // 24hr for fuel economy (static)

package/lib/db.mjs

@@ -0,0 +1,100 @@
+import Database from 'better-sqlite3';
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const dataDir = path.join(__dirname, '..', 'data');
+if (!fs.existsSync(dataDir)) fs.mkdirSync(dataDir, { recursive: true });
+
+const db = new Database(path.join(dataDir, 'vin.db'));
+db.pragma('journal_mode = WAL');
+db.pragma('foreign_keys = ON');
+
+db.exec(`
+  CREATE TABLE IF NOT EXISTS users (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    email TEXT UNIQUE NOT NULL COLLATE NOCASE,
+    password_hash TEXT NOT NULL,
+    salt TEXT NOT NULL,
+    display_name TEXT,
+    created_at TEXT DEFAULT (datetime('now')),
+    updated_at TEXT DEFAULT (datetime('now'))
+  );
+
+  CREATE TABLE IF NOT EXISTS saved_vins (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    vin TEXT NOT NULL,
+    label TEXT,
+    year INTEGER,
+    make TEXT,
+    model TEXT,
+    created_at TEXT DEFAULT (datetime('now')),
+    UNIQUE(user_id, vin)
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_saved_vins_user ON saved_vins(user_id);
+
+  CREATE TABLE IF NOT EXISTS output_preferences (
+    user_id INTEGER PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE,
+    show_overview INTEGER DEFAULT 1,
+    show_engine INTEGER DEFAULT 1,
+    show_safety_ratings INTEGER DEFAULT 1,
+    show_fuel_economy INTEGER DEFAULT 1,
+    show_recalls INTEGER DEFAULT 1,
+    show_complaints INTEGER DEFAULT 1,
+    show_safety_equipment INTEGER DEFAULT 1,
+    show_photos INTEGER DEFAULT 1,
+    show_raw_nhtsa INTEGER DEFAULT 0,
+    updated_at TEXT DEFAULT (datetime('now'))
+  );
+
+  -- Observability: request log
+  CREATE TABLE IF NOT EXISTS request_log (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    ts TEXT DEFAULT (datetime('now')),
+    ip TEXT,
+    method TEXT,
+    path TEXT,
+    status INTEGER,
+    duration_ms INTEGER,
+    user_agent TEXT,
+    user_id INTEGER,
+    bytes INTEGER DEFAULT 0
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_reqlog_ts ON request_log(ts);
+  CREATE INDEX IF NOT EXISTS idx_reqlog_ip ON request_log(ip);
+  CREATE INDEX IF NOT EXISTS idx_reqlog_path ON request_log(path);
+
+  -- Observability: security events
+  CREATE TABLE IF NOT EXISTS security_events (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    ts TEXT DEFAULT (datetime('now')),
+    event_type TEXT NOT NULL,
+    ip TEXT,
+    detail TEXT,
+    severity TEXT DEFAULT 'info'
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_secevents_ts ON security_events(ts);
+  CREATE INDEX IF NOT EXISTS idx_secevents_type ON security_events(event_type);
+  CREATE INDEX IF NOT EXISTS idx_secevents_ip ON security_events(ip);
+`);
+
+// Prepared statements for hot-path logging (avoid re-parsing SQL)
+export const logRequest = db.prepare(
+  'INSERT INTO request_log (ip, method, path, status, duration_ms, user_agent, user_id, bytes) VALUES (?, ?, ?, ?, ?, ?, ?, ?)'
+);
+export const logSecurityEvent = db.prepare(
+  'INSERT INTO security_events (event_type, ip, detail, severity) VALUES (?, ?, ?, ?)'
+);
+
+// Prune old logs (keep 30 days)
+export function pruneOldLogs() {
+  db.prepare("DELETE FROM request_log WHERE ts < datetime('now', '-30 days')").run();
+  db.prepare("DELETE FROM security_events WHERE ts < datetime('now', '-90 days')").run();
+}
+
+export default db;

package/lib/epa.mjs

@@ -0,0 +1,157 @@
+/**
+ * EPA Fuel Economy API integration.
+ * Free, no API key required.
+ * Docs: https://www.fueleconomy.gov/feg/ws/
+ */
+
+const BASE = 'https://fueleconomy.gov/ws/rest/vehicle';
+const FETCH_TIMEOUT = 10_000;
+
+/**
+ * Create an AbortSignal that times out after the specified ms.
+ */
+function timeoutSignal(ms = FETCH_TIMEOUT) {
+  return AbortSignal.timeout(ms);
+}
+
+/**
+ * Parse a numeric string, returning null if not valid.
+ */
+function num(value) {
+  if (value === undefined || value === null || value === '') return null;
+  const n = Number(value);
+  return Number.isNaN(n) ? null : n;
+}
+
+/**
+ * Clean a string value, returning null for empty/missing.
+ */
+function clean(value) {
+  if (value === undefined || value === null) return null;
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    return trimmed === '' ? null : trimmed;
+  }
+  return value;
+}
+
+/**
+ * Build the empty/unavailable response object.
+ */
+function unavailable() {
+  return {
+    available: false,
+    city_mpg: null,
+    highway_mpg: null,
+    combined_mpg: null,
+    annual_fuel_cost: null,
+    co2_grams_per_mile: null,
+    fuel_type: null,
+    fuel_type2: null,
+    is_ev: false,
+    ev_range: null,
+    ev_charge_time_240v: null,
+    phev_combined: null,
+    cylinders: null,
+    displacement: null,
+    drive: null,
+    transmission: null,
+    vehicle_class: null,
+  };
+}
+
+/**
+ * Get fuel economy data for a vehicle.
+ * Two-step: first get menu options for the year/make/model, then fetch full data.
+ *
+ * @param {number|string} year - Model year
+ * @param {string} make - Make (e.g., "Toyota")
+ * @param {string} model - Model (e.g., "Camry")
+ * @returns {object} Fuel economy data
+ */
+export async function getFuelEconomy(year, make, model) {
+  try {
+    // Step 1: Get available options (trims/variants) for this vehicle
+    const menuParams = new URLSearchParams({
+      year: String(year),
+      make: String(make),
+      model: String(model),
+    });
+    const menuUrl = `${BASE}/menu/options?${menuParams}`;
+
+    const menuRes = await fetch(menuUrl, {
+      headers: { Accept: 'application/json' },
+      signal: timeoutSignal(),
+    });
+
+    if (!menuRes.ok) {
+      console.error(`[epa] getFuelEconomy menu HTTP ${menuRes.status}`);
+      return unavailable();
+    }
+
+    const menuData = await menuRes.json();
+
+    // The API returns { menuItem: { value, text } } for single result
+    // or { menuItem: [{ value, text }, ...] } for multiple results
+    let items = menuData?.menuItem;
+    if (!items) {
+      return unavailable();
+    }
+
+    // Normalize to array
+    if (!Array.isArray(items)) {
+      items = [items];
+    }
+
+    if (items.length === 0) {
+      return unavailable();
+    }
+
+    // Step 2: Get full data for the first option
+    const vehicleId = items[0].value;
+    if (!vehicleId) {
+      return unavailable();
+    }
+
+    const detailUrl = `${BASE}/${vehicleId}`;
+    const detailRes = await fetch(detailUrl, {
+      headers: { Accept: 'application/json' },
+      signal: timeoutSignal(),
+    });
+
+    if (!detailRes.ok) {
+      console.error(`[epa] getFuelEconomy detail HTTP ${detailRes.status}`);
+      return unavailable();
+    }
+
+    const v = await detailRes.json();
+
+    // Determine if this is an EV
+    const fuelType1 = clean(v.fuelType) || clean(v.fuelType1);
+    const fuelType2 = clean(v.fuelType2);
+    const isEv = fuelType1 === 'Electricity' && !fuelType2;
+
+    return {
+      available: true,
+      city_mpg: num(v.city08) || num(v.cityA08),
+      highway_mpg: num(v.highway08) || num(v.highwayA08),
+      combined_mpg: num(v.comb08) || num(v.combA08),
+      annual_fuel_cost: num(v.fuelCost08) || num(v.fuelCostA08),
+      co2_grams_per_mile: num(v.co2TailpipeGpm) || num(v.co2TailpipeAGpm),
+      fuel_type: fuelType1,
+      fuel_type2: fuelType2,
+      is_ev: isEv,
+      ev_range: num(v.range) || num(v.rangeCity),
+      ev_charge_time_240v: num(v.charge240),
+      phev_combined: num(v.combE),
+      cylinders: num(v.cylinders),
+      displacement: num(v.displ),
+      drive: clean(v.drive),
+      transmission: clean(v.trany),
+      vehicle_class: clean(v.VClass),
+    };
+  } catch (err) {
+    console.error(`[epa] getFuelEconomy error:`, err.message);
+    return unavailable();
+  }
+}