Skip to main content
Glama
nitrovin

nitrovin

by joshuasprow

nitrovin

An offline VIN decoder that answers like NHTSA's vPIC. It is a Go port of spVinDecode, the decoding procedure NHTSA publishes inside its monthly vPIC database, and it ships as one binary with a month of vPIC data inside. No network, no database, no API key.

Its goals are compatibility, answering exactly as vPIC does, and interoperability, working with other systems through vPIC's ids, its output shapes and standard formats; speed serves them, and is not one of them.

Every data month is checked against NHTSA's own procedure running in Postgres before it ships: every row of every VIN in an 18,318-VIN corpus must match, byte for byte, or the month does not ship (what parity means).

$ nitrovin decode -o text 1HGCM82633A004352 | grep -E '^(VIN|Make|Manufacturer Name|Model|Model Year|Body Class|Plant City|Error Code) '
VIN                               1HGCM82633A004352
Body Class                        Coupe
Make                              HONDA
Manufacturer Name                 AMERICAN HONDA MOTOR CO., INC.
Model                             Accord
Model Year                        2003
Plant City                        MARYSVILLE
Error Code                        0

Those are 7 of the 43 elements this VIN decodes to (--shape nitrovin lists them).

The same decode is reachable six ways: a CLI, an HTTP server, JSON lines over stdio, an MCP server for AI assistants, a Go module and a C library. nitrovin.app runs the latest release's server for anyone: one page that decodes a VIN as you type it and shows the vehicle's names in every vocabulary loaded, where your own vocabularies (or EPA's, in one click) load into your browser and translate there without being uploaded, and a one-click demo set loads there the same way, the /v1 API (CORS open) and MCP at https://nitrovin.app/mcp, rate-limited per IP.

Status: v0.x prereleases. v0 means the release pipeline is not yet signed off, not that the API may change: the contract is frozen at /v1. v1.0.0 waits on the gates in ADR 0007. nitrovin is not affiliated with or endorsed by NHTSA.

Install

Every release embeds one vPIC data month; nitrovin --version names it.

Channel

Command

Platforms

Homebrew

brew install joshuasprow/tap/nitrovin

macOS, Linux

Scoop

scoop bucket add joshuasprow https://github.com/joshuasprow/scoop-bucket then scoop install nitrovin

Windows amd64, arm64

winget

JoshuaSprow.Nitrovin, not yet submitted (#78)

Windows

Docker

docker run --rm -p 8080:8080 ghcr.io/joshuasprow/nitrovin

linux/amd64, linux/arm64

Go 1.27+

go install github.com/joshuasprow/nitrovin/cmd/nitrovin@latest

anywhere Go builds

Archives

GitHub Releases: nitrovin_<version>_<os>_<arch>.tar.gz (.zip on Windows)

linux, darwin, windows × amd64, arm64

Linux packages

the same releases: sudo apt install ./nitrovin_<version>_linux_<arch>.deb, sudo dnf install ./nitrovin_<version>_linux_<arch>.rpm, sudo apk add --allow-untrusted ./nitrovin_<version>_linux_<arch>.apk

linux amd64, arm64

C library

the same releases: libnitrovin_<version>_<os>_<arch>

linux, darwin, windows × amd64, arm64

$ nitrovin --version
nitrovin v0.1.2 (data 2026_10)

The binary is about 80 MB, most of it the data; an archive is about 21 MB. The Docker image runs nitrovin serve --addr :8080 by default, as a non-root user, and takes any other command in its place (docker run --rm ghcr.io/joshuasprow/nitrovin decode 1HGCM82633A004352). Its tags are vX.Y.Z, vX.Y, vX, latest and data-<YYYY_MM>.

The Linux packages install /usr/bin/nitrovin and put LICENSE and NOTICE in /usr/share/doc/nitrovin; removing the package removes all three. They are release assets, not a package repository, so nothing signs them for apt, dnf or apk (hence --allow-untrusted): verify one with cosign before you install it,

TAG=v0.1.5
cosign verify-blob --bundle nitrovin_${TAG#v}_linux_amd64.deb.sigstore.json \
  --certificate-identity https://github.com/joshuasprow/nitrovin/.github/workflows/release.yml@refs/tags/$TAG \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com nitrovin_${TAG#v}_linux_amd64.deb

or check it against checksums.txt as Verify a release shows.

The binaries are not notarized by Apple. Homebrew removes the quarantine flag for you. A macOS binary downloaded with a browser is killed on launch until you remove it:

xattr -d com.apple.quarantine nitrovin

Related MCP server: vehicle-safety

Use it

Every surface takes the same request and returns the same decode (the API contract):

Request field

Default

Meaning

vin

required

1–17 characters; partial (*) and mistyped VINs decode too

model_year

none

a model year you already know, a hint

shape

vpic

vpic: vPIC's DecodeVinValues keys (Make, BodyClass); nitrovin: keyed by variable name, with element and attribute ids

full

false

add items, every row NHTSA's procedure emits, with its source and pattern

now

the clock

the instant the decode is as of; fix it for reproducible output

A VIN is never an error: what is wrong with it is in error_codes (vPIC's codes, [0] is clean), with corrected_vin and the possible values when the procedure suggests them. Every decode carries its data_month and decoder_version.

CLI

nitrovin decode 1HGCM82633A004352                           # JSON, pretty on a terminal
nitrovin decode -o text --model-year 2003 1HGCM82633A004352  # two columns
nitrovin decode --shape nitrovin --full 1HGCM82633A004352    # by variable name, with items
printf '1HGCM82633A004352,2003\n5YJ3E1EA2JF000316\n' | nitrovin decode -   # one JSON line per VIN
nitrovin info                                                # version, data month, artifact hash, elements

decode - reads one VIN per line, optionally followed by a comma or a tab and its model year. Exit status is 0 when every VIN was decoded, whatever its error codes; 1 when nitrovin could not answer (data that will not load, a refused input line); 2 for a mistake on the command line, such as an argument VIN over 17 characters. Problems go to stderr as one JSON line. CLI contract.

HTTP

nitrovin serve        # 127.0.0.1:8080; --addr, or $PORT, to change
curl localhost:8080/v1/decode/1HGCM82633A004352
curl 'localhost:8080/v1/decode/1HGCM82633A004352?model_year=2003&shape=nitrovin'
curl localhost:8080/v1/decode -d '[{"vin":"1HGCM82633A004352"},{"vin":"5YJ3E1EA2JF000316","shape":"nitrovin"}]'
curl localhost:8080/v1/info
curl 'localhost:8080/v1/translate?from.vin=1HGCM82633A004352'
curl localhost:8080/v1/vocabularies
curl 'localhost:8080/v1/vocabularies/vpic/entries?where.make=474&limit=5'

Open the address in a browser: one page, the VIN decoder, drawn as the VIN's diagram. Type a VIN on the plate, 17 cells under the six groups of a VIN (maker, vehicle, check digit, model year, plant, serial): each group's card fills as its characters are typed, a partial VIN included. A whole VIN gets the check digit's verdict, with its arithmetic behind a button, the decoder's error codes in NHTSA's words, and a suggested VIN as a link. Below the cards, "Also known as" shows the vehicle's names in every vocabulary loaded (Vocabularies), a doubt drawn dashed. A refusal is said below the plate. The page is rendered on the server and every answer is a shareable URL (/?from.vin=1HGCM82633A004352; older /?vin=, /ui/decode, /ui/translate, /vocab and /ui/vocabularies links redirect to it, with their VIN and nothing else). The page takes a VIN and nothing else: model_year, shape, full and now are the API's and the command line's, and the page ignores them. Three buttons in the header open the rest: VINs offers examples, the VINs you decoded lately and Surprise me; Vocabularies lists what is loaded; and Developers holds the page's URL, curl and nitrovin decode equivalents to copy, each the plain request for the VIN, the answer's JSON, a link to the same VIN on NHTSA's decoder, how to install, configure MCP and verify this version, and links to the API docs, its release and data month. Everything works without JavaScript; with it, the page answers as you type, the URL follows the plate, back and forward ask the server again, and copy buttons appear. The pages are not part of the API: they are not in the OpenAPI document and may change.

POST /v1/decode takes up to 1,000 requests and returns an array of decodes in order; POST /v1/translate does the same for translate requests, and GET /v1/translate takes one as dotted query parameters (from.vocabulary=fleet&from.entry.make=Dodge&from.entry.model=Ram%201500). GET /v1/vocabularies lists what is loaded and GET /v1/vocabularies/{name}/entries pages through one; GET and POST /v1/fit read a loaded catalog: a vehicle's part types, candidates and related vehicles, and a fitment's vehicles, with the shelf parts and yard vehicles of loaded stock sources when asked (Translation, Listing, Fit). Refusals are application/problem+json (RFC 9457) with a pointer to the offending value. GET /v1/openapi.json serves the OpenAPI 3.1 document; GET /healthz is the probe. There are no CORS headers unless --cors <origin> (or --cors '*') names the browsers that may call /v1 and /mcp. SIGINT or SIGTERM drains requests in flight and exits 0.

stdio (JSON lines)

printf '{"id":1,"vin":"1HGCM82633A004352"}\n{"id":2,"vin":"5YJ3E1EA2JF000316","shape":"nitrovin"}\nnot json\n' | nitrovin stdio

One request per line in, one line out per request, in order and flushed per line: {"id": …, "decode": {…}} or {"id": …, "error": {…}}. A line with "op": "translate", "op": "list" or "op": "fit" translates, lists or fits instead, through the --vocab files, and its reply is keyed translation, list or fit. A bad line gets an error line and the session goes on; EOF ends it. This is the easiest way to keep one decoder process open from another language (docker run --rm -i ghcr.io/joshuasprow/nitrovin stdio works too). stdio contract.

MCP

nitrovin mcp is an MCP server over stdio with the tools decode_vin, whose arguments are the request above, and translate, list and fit, which answer from the vocabularies and catalog --vocab loads (tool definitions). For Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows) and Cursor (~/.cursor/mcp.json) the entry is the same:

{
  "mcpServers": {
    "nitrovin": {
      "command": "/opt/homebrew/bin/nitrovin",
      "args": ["mcp"]
    }
  }
}

Use the absolute path which nitrovin prints: desktop apps do not see your shell's PATH. With Docker instead, "command": "docker" and "args": ["run", "--rm", "-i", "ghcr.io/joshuasprow/nitrovin", "mcp"]. A client that installs from the MCP Registry finds this server as io.github.joshuasprow/nitrovin: the Docker image at the release tag, run with mcp. To try it without a client, save the snippet as claude_desktop_config.json and call the tool with the MCP Inspector:

npx @modelcontextprotocol/inspector --cli --config claude_desktop_config.json --server nitrovin \
  --method tools/call --tool-name decode_vin --tool-arg vin=1HGCM82633A004352

nitrovin serve serves the same server over Streamable HTTP at /mcp, stateless and with JSON responses, for clients that take a URL instead of a command ("url": "http://127.0.0.1:8080/mcp"):

npx @modelcontextprotocol/inspector --cli http://127.0.0.1:8080/mcp --transport http \
  --method tools/call --tool-name decode_vin --tool-arg vin=1HGCM82633A004352

Or use the hosted one, https://nitrovin.app/mcp, with no install.

Go module

go get github.com/joshuasprow/nitrovin/pkg/nitrovin@latest
package main

import (
	"encoding/json"
	"fmt"
	"log"

	"github.com/joshuasprow/nitrovin/pkg/contract"
	"github.com/joshuasprow/nitrovin/pkg/nitrovin"
)

func main() {
	d, err := nitrovin.Embedded() // or nitrovin.Open("nitrovin-2026_10.artifact")
	if err != nil {
		log.Fatal(err)
	}
	req, err := contract.ParseRequest([]byte(`{"vin": "1HGCM82633A004352"}`))
	if err != nil {
		log.Fatal(err)
	}
	dec, err := d.Decode(req) // a VIN is never an error: see dec.ErrorCodes
	if err != nil {
		log.Fatal(err)
	}
	out, err := json.Marshal(dec)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(out))
}

A Decoder is safe for concurrent use. nitrovin.Embedded links the data, about 61 MB, into your binary, and the module download includes it (a 20 MB zip of github.com/joshuasprow/nitrovin-data); nitrovin.Open loads an artifact file instead, and a binary that never calls Embedded does not carry the data. Every pkg/ package is public API: pkg.go.dev.

C library

libnitrovin (.so, .dylib, .dll) and nitrovin.h carry no data: nitrovin_open loads an artifact, the same file --data takes, from a nitrovin-data release. nitrovin_decode takes one stdio request line and returns exactly the reply line nitrovin stdio would write; nitrovin_open_vocab opens the artifact with vocabularies beside it, for translate, list and fit lines (the C library).

#include <stdio.h>
#include "nitrovin.h"

int main(void) {
  char *err = NULL;
  nitrovin_t *h = nitrovin_open("nitrovin-2026_10.artifact", &err);
  if (h == NULL) {
    fprintf(stderr, "%s\n", err);
    nitrovin_free(err);
    return 1;
  }
  char *reply = nitrovin_decode(h, "{\"id\":1,\"vin\":\"1HGCM82633A004352\"}");
  puts(reply); /* {"id":1,"decode":{...}}, as `nitrovin stdio` writes it */
  nitrovin_free(reply);
  nitrovin_close(h);
  return 0;
}
cc -o decode decode.c -L. -lnitrovin -Wl,-rpath,. && ./decode

Free every returned string with nitrovin_free, never free(), and never unload the library. docs/c-library.md has the downloads, Python through ctypes, and the rules; the C ABI contract is authoritative.

Verify a release

Releases are signed with cosign keyless signatures from GitHub Actions: no key to fetch, the certificate names the workflow that built the release. Every asset has a <asset>.sigstore.json bundle and a line in checksums.txt.

nitrovin, from the directory you downloaded the assets to:

TAG=v0.1.2
cosign verify-blob --bundle checksums.txt.sigstore.json \
  --certificate-identity https://github.com/joshuasprow/nitrovin/.github/workflows/release.yml@refs/tags/$TAG \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com checksums.txt
sha256sum --check --ignore-missing checksums.txt
cosign verify ghcr.io/joshuasprow/nitrovin:$TAG \
  --certificate-identity https://github.com/joshuasprow/nitrovin/.github/workflows/release.yml@refs/tags/$TAG \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

nitrovin-data, the data releases (signed from main, not from a tag):

cosign verify-blob --bundle checksums.txt.sigstore.json \
  --certificate-identity https://github.com/joshuasprow/nitrovin-data/.github/workflows/release.yml@refs/heads/main \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com checksums.txt
sha256sum --check checksums.txt

cosign verify-blob --bundle <asset>.sigstore.json … <asset> checks one asset directly. A signature from any other workflow or tag is rejected.

The data

The data is NHTSA's vPIC (Vehicle Product Information Catalog). NHTSA publishes it once a month as a Postgres dump on its downloads page, and the decoding procedure this project ports ships inside that dump. NHTSA's terms of use say the information "is considered public information and may be distributed or copied", and NHTSA disclaims any warranty on it; as a work of the U.S. Government it has no copyright (17 U.S.C. § 105). The reading behind this is the dump research. See NOTICE.

A data month (YYYY_MM) names one dump. nitrovin converts a dump into an artifact, a 61 MB indexed file that is the same bytes whenever the same dump is converted, and nitrovin-data releases it as v<format>.<YYYYMM>.<rebuild> (v1.202610.1). Each data release keeps, forever: the artifact, NHTSA's dump zip (so a month can be re-checked after NHTSA stops hosting it), manifest.json (the dump's URL, size and SHA-256, the artifact's blake3, row counts, the importer commit), the month's frozen parity key, its stale-cache list and the EPA vocabulary (Vocabularies).

$ nitrovin info | jq '{decoder_version, data_month, data_source, artifact_hash}'
{
  "decoder_version": "v0.1.2",
  "data_month": "2026_10",
  "data_source": "embedded",
  "artifact_hash": "blake3:7518c5b46c4264fe94a8e5158cb1949b000e50803b36d388fec9ebe914a780cb"
}

To decode against another month, download its artifact and pass it with --data (any command) or NITROVIN_DATA; --data wins, then NITROVIN_DATA, then the embedded data:

nitrovin --data nitrovin-2026_10.artifact info
NITROVIN_DATA=nitrovin-2026_10.artifact nitrovin serve

An artifact loads when its format major matches the binary's (format 1 today); a mismatch is an error naming both. When NHTSA publishes a month, an unattended refresh builds it, gates it and, if it passes, cuts a patch release of nitrovin with it through every channel, so updating nitrovin is how you get new data. A month that fails ships nothing and the previous month stays current. There is no nitrovin update.

A decode is a function of the VIN, the model-year hint, now, the data month and the decoder version, and it carries all five; the same five give the same bytes. Live vPIC runs on newer data than any monthly dump, so it can answer differently from nitrovin on the same day.

Vocabularies

Your own names for vehicles and part types (a yard's inventory, a parts catalog's codes) load beside the data as vocabulary files, and nitrovin translates a VIN or a name into every loaded vocabulary's names. A file is JSON Lines, a header and one line per entry (vocabulary.schema.json), in one of three kinds: a vocabulary maps its entries onto vPIC's makes and models (by id, with optional model-year ranges and qualifiers such as Drive Type) or onto a part-type spine; an extension set mints the vehicles vPIC lacks; a spine declares the part types a part vocabulary maps onto. Matching is exact after one fixed normalization (case and spaces): rules and fuzzy matching belong to whoever builds the file. docs/vocabularies.md is how to write one, check it, and translate, list and fit on every surface. A catalog (which parts fit which vehicles) loads the same way, and nitrovin fit reads it, and so do stock files: shelf parts and yard vehicles a fit answers beside its candidates. A stock source can instead be a Postgres table or view read at request time, a connector: a stock file of one header line naming the relation and the environment variable holding its DSN (Connectors). It is the one thing nitrovin reads over a network, and only the nitrovin binary links its driver.

Name files or directories with --vocab (repeatable, any command) or NITROVIN_VOCAB. A file with a fault stops nitrovin from starting; where a file disagrees with the data month (an id NHTSA dropped, say) nitrovin warns on stderr and in nitrovin info, and serves it anyway. nitrovin vocab check fails on both, for your CI. From a checkout, with the synthetic vocabularies in testdata/vocab:

nitrovin vocab check testdata/vocab
nitrovin --vocab testdata/vocab list                                  # what is loaded
nitrovin --vocab testdata/vocab list fleet --where make=dodge         # a vocabulary's entries, paged
nitrovin --vocab testdata/vocab translate --to fleet 1C6RR7LT5FS123456 # a VIN to your names
nitrovin --vocab testdata/vocab serve                                 # /v1/translate, /v1/vocabularies

serve's page shows a VIN's names in every vocabulary loaded on vPIC's spine, the server's own files with or without JavaScript. Its Vocabularies button opens a dialog that lists what is loaded, each file marked by where it is kept and with its drift; with JavaScript, the dialog loads your own files, picked or dropped on the page, into your browser, where they stay: a Service Worker keeps them in IndexedDB and translates with the same Go, built to WebAssembly, linking them with the server's files, which serve publishes with the data month's spine bundle under /ui/r/<release>/ (docs/vocabularies.md). Release builds include the worker, and EPA's vocabulary (below) as a one-click load into the browser; a go install build serves the page without them, and says so.

The demo set in pkg/ui/demo is a small, invented catalog of popular vPIC models with its part and vehicle vocabularies, an extension set, a shelf and a yard, every number and stock row made up. With the worker, the dialog offers it as one Load demo, which compiles its catalog in your browser; nitrovin --vocab pkg/ui/demo serve serves the same files (The demo set).

Each data release also carries epa-vehicles.jsonl, a vocabulary of the names EPA's fuel-economy data (vehicles.csv) gives makes and models, mapped onto that month's vPIC makes and models with Drive Type and Series qualifiers where the name implies them. The monthly refresh builds it from that day's vehicles.csv against the new month and publishes it only if it loads with no fault; its version is EPA's newest record date and the data month (2026-11-03+2026_10), and the refresh PR reports its drift. Download it from the release of the month your binary embeds (nitrovin --version names it), or the latest:

curl -fsSLO https://github.com/joshuasprow/nitrovin-data/releases/latest/download/epa-vehicles.jsonl
nitrovin --vocab epa-vehicles.jsonl info | jq '.vocabularies[] | {name, version, drift}'
nitrovin --vocab epa-vehicles.jsonl translate --to epa-vehicles 1C6RR7LT5FS123456

A vocabulary built against another month loads too, with a drift warning for each id NHTSA has changed since. checksums.txt on the same release covers it (Verify a release). nitrovin ships no other vocabulary, and nitrovin.app loads none on the server: its page offers EPA's to load into your browser.

Parity

nitrovin's answer for a VIN is NHTSA's procedure's answer, not an approximation of it: every row the procedure emits, all 15 columns, exact strings, compared as a multiset per VIN. There is no tolerance and no per-VIN excuse list. The oracle is NHTSA's own spvindecode run in Postgres 17 on the month's dump, with one stale cache table emptied: the dump's cache of valid characters contradicts the dump's own pattern rows, and live vPIC answers the way the recomputation does. That is the one registered deviation, stale-cache, and the corpus VINs it touches are listed with each data release.

The 2026_10 data in v0.1.2 passed refresh run 42662006323: 18,339 calls and 966,232 rows, 0 disagreements; every one of the month's 13,014 WMIs and 25,283 of its 25,293 VinSchemas reached; 52 stale-cache calls; all 7 deviation witnesses agree with live vPIC on 253 fields. Its report is the body of the refresh PR.

docs/parity.md explains the corpus and the gates, where each month's report lives, and how to re-run a release's parity check yourself in a second.

Known limits

  • 10 VinSchemas are never exercised. In 2026_10, schemas 4329, 5046, 6173, 11117, 11146, 11395, 11396, 13555, 15597 and 21187 lose to another schema on the same WMI and years on every VIN tried, so no gated VIN reaches them (run 42662006323, #72).

  • Deviations are classes, never VINs. Where nitrovin disagrees with NHTSA's procedure, it is a bug unless a registered class proves a defect in NHTSA's data, with a mechanical detector and a VIN on which live vPIC agrees with nitrovin (ADR 0006, the registry). There is one class.

  • The vpic layout is not live DecodeVinValues byte for byte. It has no VIN key, has PlantAddress, lacks vPIC's ten always-empty legacy keys, and joins multi-valued elements in byte order where vPIC's order is unstable (details). Parity is gated on the items both layouts are built from.

  • Element names and codes are data, not API. NHTSA renames them between months; pin element_id and attribute_id for anything long-lived.

  • Over 17 characters is refused. NHTSA's procedure raises on it, so there is no answer to match.

  • Not drop-in for vPIC's URLs. serve has its own /v1 routes, not vPIC's /api/vehicles/....

  • winget is not live yet (#78). macOS binaries are not notarized (see Install).

  • The C library cannot be unloaded, needs glibc 2.17+ on Linux (no musl), and macOS 11+.

Benchmarks

Correctness first. On a random 2,000 of the corpus's VINs, nitrovin and ultravin each agree with the freshened Postgres oracle on 2,000 of 2,000 decodes; corgi v2 and v3 emit other output and are not comparable; NHTSA Postgres is the oracle itself; NHTSA MSSQL and the web API were not compared (the correctness aside). Speed is context for the goals, not one of them: a budget to meet, not a race to win.

How many VINs each engine decodes per second, every row measured on one machine over one corpus, against NHTSA's own spVinDecode in SQL Server (55.8 VIN/s here).

engine

VIN/s

vs NHTSA MSSQL

nitrovin: Go module, 12 cores, sorted input

154,313

~2,766× faster

nitrovin: Go module, 12 cores

146,881

~2,632× faster

nitrovin: Go module, 4 cores, sorted input

92,743

~1,662× faster

nitrovin: Go module, 4 cores

82,173

~1,473× faster

nitrovin: Go module, 1 core, sorted input

26,435

~474× faster

nitrovin: Go module, 1 core

23,987

~430× faster

nitrovin: CLI, nitrovin decode -, one process

14,524

~260× faster

ultravin: 12 cores, sorted input

5,288,394

~94,779× faster

ultravin: 12 cores

2,340,410

~41,945× faster

ultravin: 4 cores, sorted input

2,688,609

~48,186× faster

ultravin: 4 cores

1,062,987

~19,051× faster

ultravin: 1 core, sorted input

656,545

~11,767× faster

ultravin: 1 core

301,844

~5,410× faster

corgi v3: @cardog/corgi 3.0.1-beta.0 (binary index), not NHTSA's procedure

149,565

~2,681× faster

corgi v2: @cardog/corgi 2.0.1 (SQLite)

60

~1.1× faster

NHTSA MSSQL: spVinDecode (SQL Server)

55.8

1× (baseline)

NHTSA Postgres: spvindecode

66

~1.2× faster

NHTSA vPIC web API: rate limit, cited, not measured

~10

~5.6× slower

Measured 2026-11-10 on an Apple M5 Pro (6 performance and 12 efficiency cores, 48 GB): nitrovin v0.1.8 (4834e5c, data 2026_10), ultravin deb4e2f on the same month. The corpus is 20,000,000 unique synthetic VINs from ultravin's generator, about 95% valid and 5% with one realistic defect (a typo, a wrong check digit or two swapped characters); sorted rows decode the same VINs byte-sorted, and corgi v2 and the two SQL procedures a fixed random 2,000 of them. Each figure is the median of two fresh-process trials, the second round in reverse order, with the decode clock frozen where an engine has one. The method and the generator are ultravin's; its published figures, from another machine, are not used.

The host was shared with other work (one-minute load average 1.9 to 4.0 when trials started). SQL Server ran under Docker's x86 emulation, which understates it against native hardware. corgi v3 is a prerelease that answers about 20 summary fields from its own index and calls 19.5% of these VINs valid, so it does other work than the procedure. The web API row is a published rate limit, not a decode. On the sample, nitrovin and ultravin both agree with the freshened Postgres oracle on every element of all 2,000 VINs. Most of nitrovin's per-VIN time is the procedure's own work: its decode passes (up to four per VIN) take 46% of a CPU profile, filling in vehicle-type defaults 24%, laying out the vpic attributes 14%. A one-VIN nitrovin decode process takes about 10 ms and 32 MB of memory. Method, every trial, versions and how to reproduce each row.

Contributing

Issues and pull requests are welcome. CONTRIBUTING.md covers building, the tests, the Postgres oracle on your own machine, and the rules for a change that touches decoding. Decisions live in docs/adr/, words in GLOSSARY.md, and the plan in the wayfinder map.

Credits and licence

MIT, see LICENSE. The data is NHTSA's. The port's structure, its parity method and its deviation registry follow ultravin by Bryce Drennan (MIT), the reference implementation; no ultravin source is copied, and the committed parity corpus includes ultravin's VIN lists. Details in NOTICE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides comprehensive vehicle reports by aggregating data from multiple public sources to decode VINs, check recalls, and view safety ratings. It enables users to validate VINs locally and retrieve technical specifications, fuel economy, and vehicle photos without requiring API keys.
      12 npm
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to decode VINs, check stolen vehicle databases, and retrieve market valuations through natural language.
      3
      -
    • A
      license
      A
      quality
      D
      maintenance
      Enables LLMs to decode Vehicle Identification Numbers and look up vehicle makes, models, years, and specifications offline using a curated NHTSA vPIC database.
      8
      1
      MIT