vin-decode-mcp 0.1.0__tar.gz

vin_decode_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: uv pip install --system ".[dev]"
+
+      - name: Build test database
+        run: python tests/fixtures/build_test_db.py
+
+      - name: Run tests
+        run: python -m pytest tests/ -v
+
+      - name: Lint with ruff
+        run: python -m ruff check src/ tests/
+
+      - name: Check formatting
+        run: python -m ruff format --check src/ tests/

vin_decode_mcp-0.1.0/.github/workflows/rebuild-db.yml

@@ -0,0 +1,129 @@
+name: Rebuild Database
+
+on:
+  workflow_dispatch:
+    inputs:
+      vintage:
+        description: "NHTSA vintage to rebuild from (e.g. 2026_08)"
+        required: false
+        default: ""
+  schedule:
+    # Twice yearly: January 1st and July 1st
+    - cron: "0 0 1 1,7 *"
+
+env:
+  HUGGING_FACE_REPO: "joakes90/vpic-database"
+
+jobs:
+  rebuild:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install dependencies
+        run: uv pip install --system ".[dev,build]" huggingface_hub
+
+      - name: Install pg_restore
+        # Only the client is needed. convert_to_sqlite.py renders the archive
+        # to plain SQL with `pg_restore --file`; no server, no database.
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y --no-install-recommends postgresql-client
+          pg_restore --version
+
+      - name: Determine vintage
+        id: vintage
+        run: |
+          if [ -n "${{ github.event.inputs.vintage }}" ]; then
+            echo "vintage=${{ github.event.inputs.vintage }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "vintage=$(date +%Y_%m)" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Download NHTSA database
+        run: |
+          mkdir -p tools/tmp_download
+          set -o pipefail
+          for v in "${{ steps.vintage.outputs.vintage }}" \
+                   "$(date -d '1 month ago' +%Y_%m)" \
+                   "$(date -d '2 months ago' +%Y_%m)"; do
+            [ -n "$v" ] || continue
+            URL="https://vpic.nhtsa.dot.gov/downloads/vPICList_lite_${v}.custom.zip"
+            echo "Trying: $URL"
+            if curl -fsSL -o tools/tmp_download/vpic.custom.zip "$URL"; then
+              echo "vintage=$v" >> "$GITHUB_ENV"
+              break
+            fi
+          done
+          test -s tools/tmp_download/vpic.custom.zip
+          ls -lh tools/tmp_download/
+
+      - name: Convert PostgreSQL archive to SQLite
+        # Fails the build if COPY decoding regresses and NULLs are stored as
+        # the literal string '\N' — the defect that shipped a database in
+        # which most VINs decoded to a model year and nothing else.
+        run: |
+          python3 tools/convert_to_sqlite.py \
+            --custom tools/tmp_download/vpic.custom.zip \
+            --output tools/out/vpic_lite.db
+
+      - name: Build curated database
+        run: |
+          python3 tools/vpic_pare_down.py \
+            --source tools/out/vpic_lite.db \
+            --output tools/out/curated_vpic.db \
+            --overlay tools/overlay.json \
+            --curation tools/curation.json
+
+      - name: Verify curated database
+        # The curated file is what the MCP server downloads, so it is what
+        # must be checked. Referential integrity across the ID spaces is the
+        # invariant the previous build broke.
+        run: |
+          cp tools/out/curated_vpic.db curated_vpic.db
+          python3 - <<'PY'
+          import sqlite3
+          c = sqlite3.connect("file:curated_vpic.db?mode=ro", uri=True)
+          q = lambda s: c.execute(s).fetchone()[0]
+          for table in ("make", "model", "make_model", "model_years",
+                        "wmi", "wmi_vinschema", "vin_pattern"):
+              print(f"  {table}: {q(f'SELECT COUNT(*) FROM {table}'):,}")
+          assert q("SELECT COUNT(*) FROM vin_pattern p LEFT JOIN model m "
+                   "ON m.id = p.modelid WHERE m.id IS NULL") == 0, \
+              "vin_pattern.modelid does not resolve against model.id"
+          assert q("SELECT COUNT(*) FROM wmi") > 1000, "wmi table is too small"
+          assert 400 < q("SELECT COUNT(*) FROM make") < 800, "make curation looks wrong"
+          PY
+          python3 -m pytest tests/ -q
+
+      - name: Upload to Hugging Face
+        env:
+          HF_TOKEN: ${{ secrets.HUGGING_FACE_TOKEN }}
+        run: |
+          if [ -z "${HF_TOKEN}" ]; then
+            echo "::warning::HUGGING_FACE_TOKEN not set; skipping upload"
+            exit 0
+          fi
+          hf upload "${HUGGING_FACE_REPO}" \
+            tools/out/curated_vpic.db \
+            curated_vpic.db \
+            --repo-type dataset \
+            --commit-message "Rebuild from NHTSA vintage ${vintage}"
+          echo "Uploaded curated_vpic.db to ${HUGGING_FACE_REPO}"
+
+      - name: Upload build artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: curated_vpic.db
+          path: tools/out/curated_vpic.db
+          if-no-files-found: warn

vin_decode_mcp-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Compiled DB (build artifacts)
+*.db
+*.db-shm
+*.db-wal
+!tests/fixtures/build_test_db.py
+
+# Build pipeline scratch (tools/rebuild.sh, tools/vpic_pare_down.py)
+tools/out/diff_report.txt
+tools/tmp_download/
+
+# Environment variables
+.env
+
+# Hugging Face CLI cache
+.huggingface/
+
+# macOS
+.DS_Store
+
+# Node (irrelevant)
+node_modules/
+package-lock.json

vin_decode_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 VIN Decode MCP Contributors
+
+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.

vin_decode_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,302 @@
+Metadata-Version: 2.5
+Name: vin-decode-mcp
+Version: 0.1.0
+Summary: MCP server for decoding VINs and querying vehicle data from a curated NHTSA vPIC SQLite database
+Project-URL: Homepage, https://github.com/joakes90/vin-decode-mcp
+Project-URL: Repository, https://github.com/joakes90/vin-decode-mcp
+Project-URL: Bug Tracker, https://github.com/joakes90/vin-decode-mcp/issues
+Project-URL: Documentation, https://github.com/joakes90/vin-decode-mcp#readme
+Author: Justin Oakes
+License-Expression: MIT
+License-File: LICENSE
+Keywords: fastmcp,mcp,nhtsa,sqlite,vehicle,vin,vpic
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: fastmcp>=3.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: huggingface-hub>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: structlog>=24.0.0
+Provides-Extra: build
+Requires-Dist: hatchling>=1.22.0; extra == 'build'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# vin-decode-mcp
+
+**Decode VINs and query vehicle data from a curated NHTSA vPIC database — powered by the Model Context Protocol.**
+
+A standalone, offline-capable MCP server for LLMs to decode Vehicle Identification Numbers (VINs) and look up makes, models, and vehicle specifications using data from [NHTSA's vPIC](https://vpic.nhtsa.dot.gov/).
+
+```
+pip install vin-decode-mcp
+vin-decode-mcp  # Start the MCP server
+```
+
+## Why?
+
+- **Offline**: Works without internet access. The curated SQLite database (~4.5 MB) is self-contained.
+- **No rate limits**: Unlike calling the vPIC API directly, local queries are unlimited.
+- **Fast**: Pattern matching against the SQLite database takes microseconds.
+- **LLM-native**: Tools with rich docstrings, schema resources, and structured JSON output.
+- **Open data**: NHTSA vPIC is US government open data — free, no API key required.
+
+## Data Coverage
+
+- US-market vehicles, model year **1981 and forward**
+- **536 makes**, **9,284 models**, **88,267 VIN patterns** (2026-08 vintage)
+- Passenger Cars, Trucks, MPVs, Motorcycles, Off-Road Vehicles
+- Excludes: Buses, Trailers, Low-Speed Vehicles, Incomplete Vehicles
+
+> **Specifications only** — this database does not include title, accident, odometer,
+> or theft history (those require NMVTIS/commercial data sources).
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install vin-decode-mcp
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/<org>/vin-decode-mcp.git
+cd vin-decode-mcp
+pip install -e .
+```
+
+### Running
+
+```bash
+# Default: stdio transport (for Claude Desktop, Cursor, etc.)
+vin-decode-mcp
+
+# HTTP transport
+vin-decode-mcp --transport http --port 8765
+```
+
+### Using with Claude Desktop
+
+Create a dedicated venv so the binary lands where you can reference it:
+
+```bash
+python3 -m venv ~/.local/venvs/vin-decode
+source ~/.local/venvs/vin-decode/bin/activate
+pip install vin-decode-mcp
+deactivate
+```
+
+Add to `~/.config/claude-desktop/config.json` (or `~/Library/Application Support/claude-desktop/config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "vin-decode": {
+      "command": "~/.local/venvs/vin-decode/bin/vin-decode-mcp"
+    }
+  }
+}
+```
+
+Replace the path with wherever you put the venv. Restart Claude Desktop. The model can now use VIN decoding tools in conversations.
+
+> **Note:** Claude Desktop spawns processes with a minimal `$PATH` that doesn't include conda environments or virtualenvs, so always use the **absolute path** to the binary — just putting `"vin-decode-mcp"` won't work.
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `decode_vin(vin, model_year?)` | Decode a VIN → make, model, year, vehicle type |
+| `decode_partial_vin(pattern, limit?)` | Match a partial VIN with `*` wildcards |
+| `get_all_makes()` | List all vehicle makes |
+| `get_models_for_make(make, vehicle_type?)` | List models for a make |
+| `get_model_years(make, model)` | Get production year range |
+| `get_wmi_info(wmi)` | Decode a WMI → manufacturer info |
+| `get_vehicle_types()` | List available vehicle types |
+| `get_make_vehicle_types(make)` | List vehicle types for a make |
+
+### Examples
+
+```
+>>> 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"}]
+```
+
+## Database
+
+### Download
+
+The compiled database is hosted on Hugging Face:
+
+**Dataset**: https://huggingface.co/datasets/joakes90/vpic-database
+**Direct download**: https://huggingface.co/datasets/joakes90/vpic-database/resolve/main/curated_vpic.db
+
+### Custom Database Path
+
+```bash
+# 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
+```
+
+### Rebuilding
+
+The database is rebuilt from NHTSA's standalone PostgreSQL databases approximately every 6-12 months:
+
+```bash
+# 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
+```
+
+See [`docs/hf-setup.md`](docs/hf-setup.md) for Hugging Face setup instructions.
+
+## Data Source & Attribution
+
+Vehicle data sourced from [NHTSA's vPIC](https://vpic.nhtsa.dot.gov/) — the National
+Highway Traffic Safety Administration's Vehicle Product Information Catalog and
+Vehicle Listing. NHTSA is a United States government agency.
+
+- **Data license**: US Government work (public domain)
+- **API**: No key or registration required
+- **Refresh frequency**: ~6-12 months
+- **Report errors**: Contact the NHTSA Manufacturer Helpdesk at manufacturerinfo@dot.gov or 1-888-399-3277
+
+## Architecture
+
+```
+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
+└──────────────────┘
+```
+
+## Project Structure
+
+```
+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
+```
+
+## Development
+
+```bash
+# 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/
+```
+
+## Comparison with Other Solutions
+
+| | **vin-decode-mcp** | **NHTSA vPIC API** | **vin-mcp (NLMA)** |
+|---|---|---|---|
+| **Transport** | Local SQLite | HTTP REST | HTTP REST |
+| **Offline** | ✅ | ❌ | ❌ |
+| **Rate limited** | No | Yes | Yes |
+| **Data size** | ~4.5 MB | N/A | N/A |
+| **VIN fields** | Make + Model + Year | ~130 fields | ~130 fields |
+| **Makes/Models** | ✅ 536/9,284 | ✅ Full catalog | ✅ Full catalog |
+| **Install** | `pip install` | None | `pip install` |
+
+## License
+
+**MIT License** — Code is MIT. Data is US Government public domain.
+
+See [`LICENSE`](LICENSE) for details.
+
+## Contributing
+
+Contributions welcome! Please:
+
+1. Fork and create a feature branch
+2. Add tests for new functionality
+3. Ensure CI passes
+4. Submit a pull request
+
+For major changes, open an issue first to discuss the approach.