pip install vin-decode-mcp
vin-decode-mcp  # Start the MCP server

pip install vin-decode-mcp

git clone https://github.com/<org>/vin-decode-mcp.git
cd vin-decode-mcp
pip install -e .

# Default: stdio transport (for Claude Desktop, Cursor, etc.)
vin-decode-mcp

# HTTP transport
vin-decode-mcp --transport http --port 8765

python3 -m venv ~/.local/venvs/vin-decode
source ~/.local/venvs/vin-decode/bin/activate
pip install vin-decode-mcp
deactivate

{
  "mcpServers": {
    "vin-decode": {
      "command": "~/.local/venvs/vin-decode/bin/vin-decode-mcp"
    }
  }
}

>>> decode_vin("1HGCM82633A004352")
{
  "vin": "1HGCM82633A004352",
  "make": "Honda",
  "model": "Accord",
  "year": 2003,
  "vehicle_type": "Passenger Car",
  "wmi": "1HG",
  "confidence": "full"
}

>>> get_model_years("Porsche", "911")
{"year_from": 1981, "year_to": null}

>>> decode_partial_vin("5UXWX7C5*BA")
[{"make": "BMW", "model": "X3", "year": 2011,
  "vehicle_type": "Passenger Car", "confidence": "partial_match"}]

# Set via environment variable
export VIN_MCP_DB_PATH=/path/to/curated_vpic.db
vin-decode-mcp

# Or via CLI flag
vin-decode-mcp --db-path /path/to/curated_vpic.db

# Requires PostgreSQL installed (pg_restore, psql)
bash tools/rebuild.sh

# Or step by step:
# 1. Download NHTSA data: https://vpic.nhtsa.dot.gov/Downloads/
# 2. Convert to SQLite
python3 tools/convert_to_sqlite.py --input dump.sql --output tools/out/vpic_lite.db
# 3. Build curated database
python3 tools/build_db.py --source tools/out/vpic_lite.db --output tools/out/curated_vpic.db

User / LLM Agent
       │
       ▼  MCP (stdio / HTTP)
┌──────────────────┐
│  vin-decode-mcp  │  pip install vin-decode-mcp
│  (FastMCP server)│  env: VIN_MCP_DB_PATH=/path/to/curated_vpic.db
└────────┬─────────┘
         │  sqlite3 (mode=ro)
         ▼
┌──────────────────────┐
│  curated_vpic.db     │  ~4.5 MB, curated
│    (Hugging Face)    │  makes + models + WMI + VIN patterns
└──────────────────────┘
         ▲
         │  rebuilds from
┌──────────────────┐
│ NHTSA vPIC PG DB │  69 MB, official
│ (NHTSA website)  │  refreshed 2x/year
└──────────────────┘

vin-decode-mcp/
├── src/vin_decode_mcp/
│   ├── __init__.py              # Package init
│   ├── server.py                # FastMCP server with all tools
│   ├── database.py              # SQLite layer + VIN decoder
│   └── cli.py                   # CLI entry point
├── tools/
│   ├── build_db.py              # Pipeline orchestrator
│   ├── convert_to_sqlite.py     # PG → SQLite converter (COPY text format)
│   ├── vpic_pare_down.py        # Curated pare-down + VIN decode tables
│   ├── rebuild.sh               # Full rebuild script
│   ├── curation.json            # Make/model curation rules
│   ├── overlay.json             # Grey-import classic additions
│   └── README.md                # Rebuild instructions
├── tests/
│   ├── conftest.py              # Test fixtures
│   ├── test_decode.py           # VIN decode canary + regression tests
│   ├── test_server.py           # Bulk lookup tests
│   ├── test_convert.py          # PostgreSQL COPY decoding tests
│   ├── test_real_db.py          # Smoke tests against the curated DB
│   └── fixtures/
│       ├── build_test_db.py     # Test database builder
│       └── test_vpic.db         # Minimal test database
├── .github/workflows/
│   ├── ci.yml                   # CI: test + lint
│   └── rebuild-db.yml           # Scheduled DB rebuild
├── docs/
│   └── hf-setup.md              # Hugging Face setup guide
├── pyproject.toml
├── LICENSE
└── README.md

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
python -m pytest tests/ -v

# Lint
python -m ruff check src/ tests/

# Format
python -m ruff format src/ tests/