Metadata-Version: 2.4
Name: nhtsa-mcp-connector
Version: 1.0.1
Summary: MCP server providing 5 tools for querying U.S. vehicle data from NHTSA APIs (VIN decode, recalls, complaints, safety ratings)
Project-URL: Homepage, https://github.com/sathiskumarjothi0-oss/nhtsa-mcp-connector
Project-URL: Repository, https://github.com/sathiskumarjothi0-oss/nhtsa-mcp-connector.git
Project-URL: Issues, https://github.com/sathiskumarjothi0-oss/nhtsa-mcp-connector/issues
Author: Sathiskumar Jothi
License-Expression: MIT
License-File: LICENSE
Keywords: ai,connector,llm,mcp,nhtsa,recalls,safety,vehicle,vin
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: requests>=2.31.0
Description-Content-Type: text/markdown

# NHTSA MCP Connector

[![PyPI](https://img.shields.io/pypi/v/nhtsa-mcp-connector)](https://pypi.org/project/nhtsa-mcp-connector/)
[![Python](https://img.shields.io/pypi/pyversions/nhtsa-mcp-connector)](https://pypi.org/project/nhtsa-mcp-connector/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Model Context Protocol (MCP) server that provides LLMs with access to real-time U.S. vehicle data from official NHTSA (National Highway Traffic Safety Administration) government APIs.

**No API key required** — all NHTSA endpoints are free and public.

### Highlights

- **Pydantic validation** — All tool inputs are validated (VIN format, year range, non-empty fields)
- **Parallel execution** — `full_vehicle_report` fetches recalls, complaints, and ratings concurrently via ThreadPoolExecutor
- **Streaming progress** — Tools report progress via MCP Context for real-time status in supporting clients
- **Standardized interface** — Works with any MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.)
- **Ollama support** — Included bridge script to use with local LLMs via Ollama

---

## Tools (5)

| # | Tool | Description |
|---|------|-------------|
| 1 | `decode_vin` | Decode a 17-character VIN into full vehicle specs (make, model, year, engine, transmission, body style, plant info) |
| 2 | `get_recalls_by_vin` | Get all safety recalls for a specific VIN (campaign numbers, descriptions, remedy info) |
| 3 | `get_complaints` | Get consumer complaints filed with NHTSA for a vehicle by make/model/year |
| 4 | `get_safety_ratings` | Get NCAP crash test safety ratings (1-5 stars: overall, frontal, side, rollover) |
| 5 | `full_vehicle_report` | Generate a comprehensive report combining decode + recalls + complaints + ratings from a single VIN |

---

## Installation

### From PyPI (recommended)

    pip install nhtsa-mcp-connector

### From source

    git clone https://github.com/sathiskumarjothi0-oss/nhtsa-mcp-connector.git
    cd nhtsa-mcp-connector
    pip install .

---

## Configuration

### Claude Code (CLI / Desktop App)

Run this command to add the NHTSA connector:

    claude mcp add nhtsa -- nhtsa-mcp-connector

Or manually add to `~/.claude/settings.json`:

    {
      "mcpServers": {
        "nhtsa": {
          "command": "nhtsa-mcp-connector"
        }
      }
    }

### Claude Desktop App

Add to your `claude_desktop_config.json`:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

    {
      "mcpServers": {
        "nhtsa": {
          "command": "nhtsa-mcp-connector"
        }
      }
    }

### Using uvx (no install needed)

    {
      "mcpServers": {
        "nhtsa": {
          "command": "uvx",
          "args": ["nhtsa-mcp-connector"]
        }
      }
    }

### Using pip + python

    {
      "mcpServers": {
        "nhtsa": {
          "command": "python",
          "args": ["-m", "nhtsa_mcp_connector.server"]
        }
      }
    }

---

## Usage Examples

Once configured, ask your AI assistant natural language questions:

**Decode a VIN:**
> "What car is VIN 1HGCM82633A004352?"

Calls `decode_vin` - Returns: 2003 Honda Accord, 3.0L V6, 5-speed automatic, sedan...

**Check Recalls:**
> "Are there any recalls on VIN 5YJSA1DN5DFP14705?"

Calls `get_recalls_by_vin` - Returns: list of recall campaigns with descriptions and remedies

**Get Complaints:**
> "What complaints have been filed for the 2020 Toyota Camry?"

Calls `get_complaints(make="Toyota", model="Camry", model_year=2020)` - Returns: consumer complaints with crash/injury data

**Safety Ratings:**
> "How safe is the 2023 Honda Civic in crash tests?"

Calls `get_safety_ratings(make="Honda", model="Civic", model_year=2023)` - Returns: NCAP star ratings

**Full Vehicle Report:**
> "Give me a full report on VIN 1HGCM82633A004352 - I am considering buying this car."

Calls `full_vehicle_report` - Returns: combined decode + recalls + complaints + safety ratings (fetched in parallel)

---

## Testing

### Run standalone

    nhtsa-mcp-connector

### Test with MCP Inspector

    npx @modelcontextprotocol/inspector nhtsa-mcp-connector

---

## Using with Ollama (Local LLMs)

Ollama does not natively support MCP, but this project includes a **bridge script** (`ollama_bridge.py`) that connects Ollama tool-calling models to the NHTSA tools directly.

### How It Works

    +----------------+    tool calls     +-------------------+     HTTP      +----------------+
    |  Ollama        | <---------------> |  ollama_bridge.py | <----------> |  NHTSA APIs    |
    |  (llama3.1)    |   function call   |                   |   REST/JSON   |  (public)      |
    +----------------+                   +-------------------+               +----------------+

1. User types a question in the terminal
2. Ollama model decides which NHTSA tool to call
3. Bridge executes the tool (calls NHTSA API directly)
4. Result is fed back to the model for a natural language response

### Prerequisites

    # Install Ollama: https://ollama.com/download
    ollama pull llama3.1
    pip install ollama requests

### Supported Models

Any Ollama model with tool-calling support:
- `llama3.1` (recommended)
- `llama3.3`
- `mistral`
- `qwen2.5`
- `command-r`

### Quick Start

    # Make sure Ollama is running
    ollama serve

    # Run the bridge (defaults to llama3.1)
    python ollama_bridge.py

### Change the Model

Edit the `OLLAMA_MODEL` variable at the top of `ollama_bridge.py`:

    OLLAMA_MODEL = "mistral"  # or "qwen2.5", "llama3.3", etc.

### Example Session

    ============================================================
      NHTSA Vehicle Intelligence (via Ollama - llama3.1)
      Tools: decode_vin, get_recalls_by_vin, get_complaints,
             get_safety_ratings, full_vehicle_report
    ============================================================
      Type 'quit' to exit

    You: What car is VIN 1HGCM82633A004352?

      [Tool Call] decode_vin({"vin": "1HGCM82633A004352"})
      [Tool Result] received (2847 chars)

    Assistant: This VIN belongs to a **2003 Honda Accord EX** with a 3.0L V6
    engine, 5-speed automatic transmission. Manufactured in Marysville, Ohio.

    You: Are there any recalls on this vehicle?

      [Tool Call] get_recalls_by_vin({"vin": "1HGCM82633A004352"})
      [Tool Result] received (1523 chars)

    Assistant: Yes, there are 2 recalls for this vehicle:
    1. Airbag inflator replacement (Takata recall)
    2. Power window switch - potential fire risk

---

## Data Sources

All data comes from official U.S. government APIs:

| API | Source |
|-----|--------|
| vPIC (VIN Decode) | https://vpic.nhtsa.dot.gov/api/ |
| Recalls | https://api.nhtsa.gov/recalls |
| Complaints | https://api.nhtsa.gov/complaints |
| Safety Ratings | https://api.nhtsa.gov/SafetyRatings |

---

## Architecture

    nhtsa-mcp-connector/
    ├── src/nhtsa_mcp_connector/
    │   ├── __init__.py      # Package version
    │   ├── __main__.py      # python -m entry point
    │   └── server.py        # MCP server with all 5 tools
    ├── ollama_bridge.py     # Ollama <-> NHTSA bridge (local LLMs)
    ├── mcp_server.py        # Backward-compatible entry point
    ├── pyproject.toml       # Package metadata and dependencies
    ├── requirements.txt     # Alt dependency file
    ├── LICENSE              # MIT
    └── README.md

### MCP Architecture

    +--------------------+     MCP Protocol      +----------------------+     HTTP      +----------------+
    |  MCP Client        | <---- stdio --------> |  nhtsa-mcp-server    | <----------> |  NHTSA APIs    |
    |  (Claude, Cursor)  |   tool calls/results  |  - Pydantic valid.   |   REST/JSON   |  (public)      |
    +--------------------+                       |  - Parallel exec     |               +----------------+
                                                 |  - Progress stream   |
                                                 +----------------------+

1. Client sends a tool call (e.g. `decode_vin`) over MCP stdio
2. Server validates input with Pydantic (rejects bad VINs, empty fields, etc.)
3. Server calls NHTSA public APIs, streaming progress back to the client
4. `full_vehicle_report` runs 3 API calls in parallel after the initial VIN decode
5. JSON result is returned to the client

---

## Input Validation

| Field | Rule |
|-------|------|
| `vin` | Exactly 17 alphanumeric chars, no I/O/Q, auto-uppercased |
| `make` | Non-empty string, auto-trimmed |
| `model` | Non-empty string, auto-trimmed |
| `model_year` | Integer between 1900 and 2030 |

Invalid inputs return a clear Pydantic validation error before any API call is made.

---

## Developer Guide — Publishing to PyPI

### Prerequisites

    pip install build twine

### Step 1: Build the package

    cd nhtsa-mcp-connector
    python -m build

This creates two files in `dist/`:
- `nhtsa_mcp_connector-X.X.X.tar.gz` (source)
- `nhtsa_mcp_connector-X.X.X-py3-none-any.whl` (wheel)

### Step 2: Create a PyPI API token

1. Go to https://pypi.org/manage/account/token/
2. Create a new token with scope: **"Entire account"**
   > **Important:** For a brand-new package that doesn't exist yet on PyPI, project-scoped tokens will NOT work. You must use an "Entire account" scoped token for the first upload. After the first successful upload, you can create a project-scoped token and switch to it.
3. Copy the token — it starts with `pypi-...`

### Step 3: Upload to PyPI

    python -m twine upload dist/* --verbose

When prompted:
- **Username:** `__token__`
- **Password:** paste the full token including the `pypi-` prefix

**Alternative** — pass credentials inline:

    python -m twine upload dist/* --username __token__ --password pypi-YOUR_FULL_TOKEN_HERE

### Step 4 (optional): Save credentials for reuse

Create `~/.pypirc` so you don't have to paste the token every time:

    [pypi]
    username = __token__
    password = pypi-YOUR_FULL_TOKEN_HERE

### Uploading to TestPyPI first (recommended for testing)

    python -m twine upload --repository testpypi dist/*

Then test the install:

    pip install --index-url https://test.pypi.org/simple/ nhtsa-mcp-connector

### Version bumps

Update the version in **two places** before rebuilding:
1. `src/nhtsa_mcp_connector/__init__.py` → `__version__`
2. `pyproject.toml` → `version`

Then clean, rebuild, and upload:

    rm -rf dist/ build/
    python -m build
    python -m twine upload dist/*

### Troubleshooting

| Error | Cause | Fix |
|-------|-------|-----|
| `403 Forbidden` | Token lacks permission | Use an "Entire account" scoped token for first upload |
| `400 File already exists` | Same version already uploaded | Bump version in `pyproject.toml` and `__init__.py` |
| `401 Unauthorized` | Invalid or expired token | Generate a new token at https://pypi.org/manage/account/token/ |

---

## License

MIT
