Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ data/*.db-wal
data/*.db-shm

data/runtime-secrets.json
# NHTSA test-vehicle photos (scripts/build-nhtsa-photos.py): copied to the server, not kept in git
data/nhtsa-photos/

operations/free-data/
__pycache__/
42 changes: 39 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ Enter a 17-character VIN and get a comprehensive vehicle report by aggregating s
| **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 |
| **NHTSA Vehicle Crash Test Database** | Photos of a vehicle NHTSA tested (same make, model, body style and generation): before the test and after NHTSA's crash tests. Never the decoded vehicle and never stock photos; mcp.vin serves resized copies itself |

Additionally, VIN validation (checksum, WMI country/manufacturer decode, model year) is computed locally with zero API calls.

Expand Down Expand Up @@ -101,7 +101,7 @@ Account tools require the user's website login token. Public lookup tools requir

| Tool | Description | Input |
|------|-------------|-------|
| `decode_vin` | Full VIN decode with specs, recalls, complaints, safety ratings, fuel economy, and photos | `{ vin: string }` |
| `decode_vin` | Full VIN decode with specs, recalls, complaints, safety ratings, fuel economy, and NHTSA test-vehicle 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[] }` |
Expand All @@ -121,7 +121,7 @@ All endpoints are available at `https://mcp.vin` or on your self-hosted instance
| `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 |
| `GET` | `/api/vin/:vin/photo` | Redirects (302) to the first photo of NHTSA's test car, before the test; 404 when no tested vehicle matches |
| `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.
Expand All @@ -134,6 +134,42 @@ curl https://mcp.vin/api/vin/1HGCM82633A004352

Direct VIN URLs also work -- visit `https://mcp.vin/1HGCM82633A004352` to see the web report.

### Photos (`photos` in a report)

Photos come only from NHTSA's vehicle crash-test database: the test lab's own photos of a vehicle NHTSA bought and
tested. They are never the decoded vehicle and there are no stock photos. The vehicle is the closest NHTSA test vehicle
(same matching as `test_vehicle_specs`: exact model year first, then the nearest year of the same generation, or the
same year in another trim), and never one with a different body style, cab or door count. `photos` is `null` when
nothing matches. Otherwise:

```json
"photos": {
"scope": "nhtsa_test_vehicle", "vin_specific": false, "note": "Photos of a vehicle NHTSA bought and tested, ...",
"items": [
{ "url": "https://mcp.vin/nhtsa-photos/14086/v14086P014-960.webp", "width": 960, "height": 640,
"thumbnail_url": "https://mcp.vin/nhtsa-photos/14086/v14086P014-320.webp", "thumbnail_width": 320, "thumbnail_height": 213,
"phase": "pre_test", "view": "front_34_right", "label": "Before the test: right front three-quarter view",
"tested_as": "2022 Nissan Pathfinder four door SUV", "model_year": 2022, "test_no": 14086, "test_kind": "frontal",
"test_label": "NHTSA frontal crash test 14086", "test_description": "The car was driven into a rigid barrier at 56 km/h (35 mph).",
"test_type": "NEW CAR ASSESSMENT TEST",
"match": { "kind": "exact", "tested_model_year": 2022, "vin_model_year": 2022, "year_gap": 0, "differences": [], "generation_check": null },
"nhtsa_test_url": "https://nrd-static.nhtsa.dot.gov/reports/vehdb/v10000/v14000/v14086R001.pdf",
"nhtsa_photo_url": "https://nrd-static.nhtsa.dot.gov/photos/vehdb/v10000/v14000/v14086P014.JPG",
"original_file_name": "No. 014 Pre-Test Right Front 3-4 View.JPG" },
{ "url": "https://mcp.vin/nhtsa-photos/14086/v14086P015-960.webp", "phase": "post_test", "view": "front_34_right",
"label": "After NHTSA's frontal crash test: right front three-quarter view", "...": "same fields" }
],
"source": { "provider": "NHTSA vehicle crash-test database: test-lab photos of the tested vehicles (nrd-static.nhtsa.dot.gov), resized and served by mcp.vin",
"indexed_at": "...", "dataset_generated_at": "..." }
}
```

`items` lists up to three views of the test car before the test (`phase` `pre_test`), then up to three crash views,
one per NHTSA test of that model year (`post_test`: the car after that test), each with its own
test car (`tested_as`, `test_no`) and match. `nhtsa_test_url` is NHTSA's report for that test. Images are WebP, fit in
960 x 720 (thumbnails 320 x 240), with no metadata. Self-hosted servers show photos only when `data/nhtsa-photos/` and
the photo index are deployed (see `scripts/build-nhtsa-photos.py`); without them `photos` is `null`.

---

## Self-Hosting
Expand Down
1,840 changes: 1,840 additions & 0 deletions data-src/test-vehicle-photos.jsonl

Large diffs are not rendered by default.

10 changes: 10 additions & 0 deletions data-src/test-vehicle-photos.meta.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
{
"generated_at": "2026-11-18T20:14:48+00:00",
"source": "NHTSA vehicle crash-test database (nrd.api.nhtsa.dot.gov get-multimedia-files) photo listings; photos from nrd-static.nhtsa.dot.gov (photos/vehdb and vehdb/<test>/photos), chosen by file name (scripts/nhtsa_photo_select.py), resized to WebP (fit 960x720 and 320x240, no metadata) by scripts/build-nhtsa-photos.py. Keys from the vPIC decode of each test vehicle's VIN (data-src/test-vehicle-specs.jsonl, tire-placards.jsonl).",
"tests": 1840,
"photos": 7308,
"image_bytes": 511565022,
"left_out_by_build": 230,
"pre_test_tests": 1840,
"crash_view_tests": 1819
}
42 changes: 42 additions & 0 deletions docs/data-sources.md
Original file line number Diff line number Diff line change
Expand Up @@ -539,6 +539,48 @@ The National Safety Council's [Check To Protect FAQ](https://www.checktoprotect.
- **Not shown.** Crash results (injury measures, crush, post-test observations) are extracted into
a research dataset only; NCAP star ratings are not in these reports and are not derived.

## NHTSA test-vehicle photos (`photos`, added 18 November 2026)

Replaces the IMAGIN.studio renders (they were served under IMAGIN's demo customer id, which mcp.vin had no licence
for, and had started returning an "Access error" image).

- **Source.** NHTSA's vehicle crash-test database: `get-multimedia-files/<test>` lists every photo the test lab
took, with the lab's own file name (`originalFileName`); the files are on `nrd-static.nhtsa.dot.gov` (`photos/vehdb/...`,
newer tests `vehdb/<test>/photos/...`). Public, no key, a US government work. NHTSA's showroom images
(`static.nhtsa.gov/images/vehicles/...`) are not used: they are likely licensed stock photos.
- **Which photos.** Only the file name says what a photo shows, so `scripts/nhtsa_photo_select.py` reads it and
keeps a photo only when the name is clearly the whole car before the test ("Pre-Test Left Front 3-4 View",
"As-Delivered Left Rear 3-4 View", "Right Front 3-4 View, As Received") or after it ("Post-Test Left Side View").
Anything else is never used: labels, placards, dummies, seats, belts, interiors, underbody, engine bay,
barriers, impactors, close-ups, and camera file names (IMG_1234.jpg). Per test it keeps up to three views
before the test (front three-quarter, side, rear three-quarter) and the one view after the test that shows
the damage (frontal test: front three-quarter; side and pole: the struck side; rear: rear three-quarter).
The lab's "impact for web" stills are recognised but not kept (most are 222 x 127 thumbnails).
Rules were checked by eye on contact sheets of 57 tests from all five labs (Calspan, Karco, MGA, TRC,
Medical College of Wisconsin), model years 2007-2025; `tests/nhtsa_photos_test.py` holds real names as cases.
- **Images.** Downloaded once on a build server (never by visitors' browsers or the web server),
`scripts/build-nhtsa-photos.py`: one connection, one request a second, stops on HTTP 429/5xx or three 403s in a
row. Each photo is resized to WebP fitting 960 x 720 (q74) and 320 x 240 (q70), metadata stripped, and served by
mcp.vin from `data/nhtsa-photos/<test>/<stem>-960.webp` / `-320.webp`. Photos narrower than 640 px are left out.
- **Matching.** The `test_vehicle_specs` closest-match tiers, stricter: never a tested vehicle with another body
style, cab or door count; another model year only when Transport Canada lists the same wheelbase for both years
(`unknown` is not enough). A photo before the test is required for anything to show. Crash views come from the
same tested model year (NHTSA uses a separate car for each test), one per test kind (frontal, side, pole, rear),
at most three. `photos` is `null` when nothing qualifies, and the site shows no photo area.
- **Labelling.** Every photo names its test car (`tested_as`), its NHTSA test and phase, links NHTSA's report for
that test, and says "Not this vehicle; trim, colour and equipment may differ."
- **Shipped files.** `data-src/test-vehicle-photos.jsonl` (+ `.meta.json`) from `scripts/nhtsa-photo-manifest.py`;
`npm run import:test-vehicles` adds table `photos` to `data/tire-placards.db`, dropping any photo whose files are
missing from `data/nhtsa-photos/`. The image folder is not in git.
- **Coverage (18 November 2026).** Of the 2,202 crash tests the site can match, 1,840 have photos (1,819 also a
view after the test): 7,308 photos, 511.6 MB of WebP for both sizes. By tested model year: 2011-2024 88-99% of
tests; 2005-2010 0-38% (the labs named files by camera number then, so nothing is used); 2025 55% and 2026 0%,
because NHTSA's photo host answered HTTP 502 for the newest tests during the build (218 photos of 59 tests
left out; the build is resumable). Of 1,617 VINs of cars listed by US dealers (a traffic proxy, mostly 2026-2027
models), 9% get photos from the same tested model year; in a seeded sample of 100 of those VINs from model
years 2016-2025, with the site's real Transport Canada generation check, 57 got photos (6 exact, 8 same year
in another version, 43 a nearest year of the same generation).

## VIN decoding: NHTSA's decoder, run locally (added 18 November 2026)

VINs are decoded by mcp.vin's own copy of NHTSA's vPIC decoder instead of NHTSA's live API, so decoding does not
Expand Down
2 changes: 1 addition & 1 deletion lib/capabilities.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ export const capabilities = [
{
"feature": "Vehicle photos",
"status": "partial",
"detail": "Existing representative stock images retained; no exact-VIN listing photo coverage.",
"detail": "NHTSA's own test-lab photos of a vehicle it crash-tested (same make, model, body style and generation), before the test and after NHTSA's crash tests; served by mcp.vin. Not the decoded vehicle, no stock photos, no listing photos; none for models NHTSA did not test in reach.",
"endpoint": "/api/vin/{vin}/photo"
},
{
Expand Down
2 changes: 1 addition & 1 deletion lib/mcp/account-tools.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ export function accountTools(add, { db, JWT_SECRET }) {
show_overview: z.optional(z.boolean()), show_engine: z.optional(z.boolean()),
show_safety_ratings: z.optional(z.boolean()), show_fuel_economy: z.optional(z.boolean()),
show_recalls: z.optional(z.boolean()), show_complaints: z.optional(z.boolean()),
show_safety_equipment: z.optional(z.boolean()), show_photos: z.optional(z.boolean()),
show_safety_equipment: z.optional(z.boolean()), show_photos: z.optional(z.boolean()).describe('Show the photos of NHTSA\'s test vehicle on the website report'),
show_raw_nhtsa: z.optional(z.boolean()),
},
async ({ user_token, ...prefs }) => {
Expand Down
2 changes: 1 addition & 1 deletion lib/mcp/vehicle-tools.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ import { applyOwnerDetails } from '../transmission-choice.mjs';

export function vehicleTools(add) {
add('decode_vin',
'Decode a VIN and return a vehicle report: specs, recalls (with manufacturer build-date ranges), a complaint summary with the most recent complaints, safety ratings, fuel economy, EPA test-vehicle data, parts content and origin (MY2020+), historical production and theft (MY1998-2012), and photo URLs. decode_checks checks the official decode field by field (drive, engine, electrification, transmission, speeds, seats, GVWR) against the manufacturer\'s description of this VIN, NHTSA test vehicles with the same VIN pattern and EPA\'s configurations: confirmed, corrected, doubtful or filled, with vPIC\'s original value kept. recall_status is the manufacturer\'s VIN-specific recall status; a maker that has not answered within about 6 s (Ford\'s lookup takes 10 s or more) gives recall_status.pending true: unknown, not "no open recalls"; call vin_recall_status with the VIN for the complete answer, or pass recall_wait "full". NHTSA\'s complaint list for a common model can take 15 s or more: complaints.pending true is unknown, not zero; call decode_vin again in a minute (cached once it arrives).',
'Decode a VIN and return a vehicle report: specs, recalls (with manufacturer build-date ranges), a complaint summary with the most recent complaints, safety ratings, fuel economy, EPA test-vehicle data, parts content and origin (MY2020+), historical production and theft (MY1998-2012), and photos of NHTSA\'s own test vehicle (photos: null when none of the same make, model, body style and generation was tested; never the decoded vehicle, no stock photos; each item names its test car, NHTSA test and phase, before or after the crash test). decode_checks checks the official decode field by field (drive, engine, electrification, transmission, speeds, seats, GVWR) against the manufacturer\'s description of this VIN, NHTSA test vehicles with the same VIN pattern and EPA\'s configurations: confirmed, corrected, doubtful or filled, with vPIC\'s original value kept. recall_status is the manufacturer\'s VIN-specific recall status; a maker that has not answered within about 6 s (Ford\'s lookup takes 10 s or more) gives recall_status.pending true: unknown, not "no open recalls"; call vin_recall_status with the VIN for the complete answer, or pass recall_wait "full". NHTSA\'s complaint list for a common model can take 15 s or more: complaints.pending true is unknown, not zero; call decode_vin again in a minute (cached once it arrives).',
{ vin: z.string().describe('17-character Vehicle Identification Number'),
transmission: z.optional(z.enum(['automatic', 'manual'])).describe('Transmission, when the owner knows it and the VIN does not say. Applies to fuel economy only when EPA lists the model with both; without it an automatic is assumed and marked (fuel_economy.assumed, alternatives).'),
recall_wait: z.optional(z.enum(['full'])).describe('"full": wait for the manufacturer\'s VIN recall lookup (up to about 15 s) instead of returning recall_status.pending after about 6 s.') },
Expand Down
67 changes: 0 additions & 67 deletions lib/photo.mjs

This file was deleted.

Loading
Loading