Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
50cd027
Reports stop waiting on slow manufacturer recall lookups
invalid-email-address Nov 18, 2026
b28e68a
Website fills in a late manufacturer recall status in place
invalid-email-address Nov 18, 2026
fa6c31a
Document pending recall status; VinClient.decode recallWait option
invalid-email-address Nov 18, 2026
c520758
Reports stop waiting on NHTSA's complaint list too
invalid-email-address Nov 18, 2026
5094958
Document pending NHTSA complaints
invalid-email-address Nov 18, 2026
17f2203
Set the status line inside the in-place redraw
invalid-email-address Nov 18, 2026
1764e12
Replace IMAGIN photos with NHTSA's own crash-test vehicle photos
invalid-email-address Nov 18, 2026
2567a00
NHTSA photos: post-test crash views only, newer listings, tests
invalid-email-address Nov 18, 2026
887565d
README: real photos example; keep the photo folder out of git
invalid-email-address Nov 18, 2026
b3da583
NHTSA photo index: 1,840 tests, 7,308 photos; data-sources entry
invalid-email-address Nov 18, 2026
79ac367
Stop asking manufacturers about a VIN: recall status becomes links
invalid-email-address Nov 18, 2026
e93a4e4
Website: recall card links to the maker and NHTSA; OGL-Canada credit …
invalid-email-address Nov 18, 2026
3f3f964
Docs and pages: no VIN recall status claims; sources, independence an…
invalid-email-address Nov 18, 2026
2093c41
Importers: honest client name instead of a desktop Chrome user agent
invalid-email-address Nov 18, 2026
0b83497
Tests fail closed on outbound requests; prove no maker can be reached
invalid-email-address Nov 18, 2026
a5467fa
Car sheet: campaigns first, then where to check this VIN; larger Copy…
invalid-email-address Nov 19, 2026
ffa4255
docs: car sheet recall row is links, not a status
invalid-email-address Nov 19, 2026
1d958db
Credit Transport Canada's licence in llms.txt, llms-full.txt and docs…
invalid-email-address Nov 19, 2026
cac86be
Merge safe-sources (#29, #30, #35) onto main (#31-#34)
invalid-email-address Nov 19, 2026
55667a7
Late complaints keep the page still under the sticky tab bar
invalid-email-address Nov 19, 2026
dfe9925
Recall links stay in view when NHTSA lists related-model campaigns
invalid-email-address Nov 19, 2026
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__/
46 changes: 42 additions & 4 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 Expand Up @@ -239,7 +275,9 @@ charting or document tools to create figures and analysis. Custom chart renderin
in the agent's tools. The API supplies comparisons, scenario calculations, provenance and JSON.
Configuration/model-year data and VIN-specific facts retain their distinct scopes.

VIN recall repair status: Tesla and Ford open/completed statuses, GM open/completed or administratively closed records, Honda and Acura active safety recalls, Subaru completed/incomplete safety recalls, Volkswagen, Audi, Land Rover and Jaguar recalls as reported by each maker, positive Nissan open safety recalls, and Mopar VIN-matched open recall/campaign records are included in reports and comparisons, with `vin_recall_status`, `GET /api/vin/{vin}/recall-status` and `VinClient.recallStatus(vin)`. Mopar safety-recall count and completed history remain unknown because its feed mixes campaign types. GM repair dates are shown only when explicitly supplied; administrative closing dates remain separate. Ford customer-satisfaction and GM non-recall programs stay separate from recall counts. Honda covers active safety recalls from the past 15 calendar years and does not supply completed history. Nissan requires matching full VINs and verified safety classifications; empty results remain unknown. Toyota/Lexus/Scion, Hyundai and Kia require interactive official verification. Other makes remain unknown. See the [source and coverage notes](docs/data-sources.md#vin-specific-recall-repair-status).
VIN recall repairs: mcp.vin does not check them and does not ask any manufacturer about a VIN. Every report's `recall_status` links to the manufacturer's own recall page (the VIN filled in where the page takes it from the link: Ford, Tesla, Honda, Acura, Subaru, Hyundai) and to NHTSA's VIN recall page, with `open_count` and `completed_count` null (unknown, never zero); `vin_recall_status`, `GET /api/vin/{vin}/recall-status` and `VinClient.recallStatus(vin)` return the same block. Makes without a listed page get NHTSA's link only. `?recall_wait` (REST) and `recall_wait` (MCP) are ignored. NHTSA's complaint list (5-17 s for a common model) can arrive after the report: `complaints.pending: true` with `status_url` `/api/vin/{vin}/complaints`. See the [source and coverage notes](docs/data-sources.md#vin-recall-repairs-links-only-since-18-november-2026).

mcp.vin is an independent free service, not affiliated with or endorsed by NHTSA, EPA, the U.S. Department of Energy, Transport Canada, the Federal Reserve or any vehicle manufacturer. Transport Canada dimensions: contains information licensed under the [Open Government Licence – Canada](https://open.canada.ca/en/open-government-licence-canada).

Deployment caching: HTML must revalidate, API responses must not be stored by shared caches, and changed JavaScript/PDF links use a content-hash query version generated by `node scripts/version-assets.mjs`. API clients also bypass stored browser responses. Preserve these policies in any reverse proxy so updated recall records are rendered by the matching client code.

Expand Down
2 changes: 1 addition & 1 deletion cli.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ import { VinClient } from './public/client.mjs';
const client=new VinClient({baseUrl:process.env.VIN_BASE_URL||'http://127.0.0.1:3200'});
const [command,arg,extra]=process.argv.slice(2);
const parse=s=>JSON.parse(s||'{}');
const commands={investigations:()=>client.investigations(parse(arg)),rates:()=>client.rateBenchmarks(),'owner-mpg':()=>client.ownerMpg(arg),capabilities:()=>client.capabilities(),decode:()=>client.decode(arg),validate:()=>client.validate(arg),catalog:()=>client.catalog(arg,parse(extra)),vehicle:()=>client.vehicle(arg),emissions:()=>client.emissions(arg),dimensions:()=>client.dimensions(parse(arg)),communications:()=>client.communications(parse(arg)),prices:()=>client.fuelPrices(),compare:()=>client.compare(parse(arg)),batch:()=>client.batch(parse(arg)),scenario:()=>client.scenario(parse(arg))};
const commands={investigations:()=>client.investigations(parse(arg)),rates:()=>client.rateBenchmarks(),'owner-mpg':()=>client.ownerMpg(arg),capabilities:()=>client.capabilities(),decode:()=>client.decode(arg),'recall-links':()=>client.recallStatus(arg),validate:()=>client.validate(arg),catalog:()=>client.catalog(arg,parse(extra)),vehicle:()=>client.vehicle(arg),emissions:()=>client.emissions(arg),dimensions:()=>client.dimensions(parse(arg)),communications:()=>client.communications(parse(arg)),prices:()=>client.fuelPrices(),compare:()=>client.compare(parse(arg)),batch:()=>client.batch(parse(arg)),scenario:()=>client.scenario(parse(arg))};
if(!command||command==='help'){console.log('vin-tools <'+Object.keys(commands).join('|')+'> [argument] [JSON]\nDefault server: http://127.0.0.1:3200; override VIN_BASE_URL. Start the source build before use.');}
else if(!commands[command]){console.error('Unknown command. Run vin-tools help.');process.exitCode=1;}
else{try{console.log(JSON.stringify(await commands[command](),null,2));}catch(e){console.error(e.message);process.exitCode=1;}}
Loading
Loading