# alldata-mcp-server

> **Notice:** Open-source local tooling provided AS IS by the authors and contributors; not affiliated with ALLDATA, AutoZone, PartsGeek, or any OEM—use only with accounts you control and at your own risk (see [DISCLAIMER.md](DISCLAIMER.md)).

**License: MIT**

Local [Model Context Protocol](https://modelcontextprotocol.io) server for **your** [ALLDATA](https://my.alldata.com) repair subscription. Runs on **your machine**, uses **your** login/session, and exposes search, labor times, procedures, TSBs, DTCs, and wiring helpers to an AI agent (Grok, Hermes, Claude, etc.).

## What it does

| Tool | Purpose |
|------|---------|
| `list_vehicle_options` | List engines/drivelines for Y/M/M |
| `select_vehicle_option` | Bind carid after listing |
| `lookup_vin` | Fast VIN → vehicle + carid |
| `get_labor` | Parts & Labor standard hours (quoting) |
| `search_alldata` / `get_procedure` | Repair content |
| `search_tsbs` | Bulletins newest-first |
| `lookup_dtc` | DTC lookup |
| `get_wiring_diagram` | Wiring assets |
| `build_connector_pinout` | Multi-diagram pinout (pin + wire color + far end) |
| `import_browser_cookies` | **Optional local auth** from a browser you name |
| `get_session_status` | Auth health |
| `cleanup_screenshots` | GC debug screenshots |

### Connector pinouts (fast)

When ALLDATA has no single pinout article for a harness connector (e.g. Toyota `IA8`):

```bash
# Offline fixtures / local Non-OE SVGs
python -m alldata_mcp_server.pinout_cli --connector IA8 \
  --fixture-dir tests/fixtures/pinout --carid 54401

# Live Non-OE multi-system scan (cookies required)
python -m alldata_mcp_server.pinout_cli --connector IA8 --live \
  --year 2015 --make Toyota --model Camry --engine "L4-2.5L (2AR-FE)"
```

Or MCP: `build_connector_pinout(connector="IA8", year=2015, make="Toyota", model="Camry", ...)`.

Output includes **pin**, **wire color**, and **far end** (module name, or other connector pin + color).  
Cache: `~/.cache/alldata-pinouts` (40 MiB cap). **Disk hygiene:** live scans set
`ALLDATA_WIRING_EPHEMERAL=1` so SVGs land under `~/.cache/alldata-pinouts/work`,
are deleted after each diagram extract, and the work/raw dirs + carid wiring dumps
are wiped at the end of every pinout run (`keep_raw=False` default). Only small
extract JSON + connector→systems index is retained (for faster re-scans).

## Requirements

- Python ≥ 3.10  
- Active ALLDATA subscription you are authorized to use  
- Optional: Playwright Chromium for SPA-heavy paths  

## Install

```bash
git clone <this-repo-url> alldata-mcp-server
cd alldata-mcp-server
pip install -e .
# optional SPA support:
pip install playwright browser-cookie3
playwright install chromium
```

Register with your agent host (examples):

```toml
# ~/.grok/config.toml
[mcp_servers.alldata]
command = "alldata-mcp"
enabled = true
```

```bash
hermes mcp add alldata --command alldata-mcp
```

## Authentication (local cookies)

**Secrets never belong in git.** Default cookie file:

```text
~/.config/alldata_cookies.json
```

### Recommended: AI-assisted browser import

1. Log into https://my.alldata.com in a browser on **this computer**.
2. When the agent asks, tell it **which browser** (e.g. `brave`, `chrome`, `firefox`).
3. Agent calls `import_browser_cookies(browser="brave")` **only after you consent**.
4. Cookies are written **on disk under your home directory** and used for subsequent API calls.

### CLI (same thing)

```bash
python scripts/export_browser_cookies.py --browser brave
# → ~/.config/alldata_cookies.json
```

### Env (optional)

| Variable | Meaning |
|----------|---------|
| `ALLDATA_COOKIES_FILE` | Path to JSON cookie map (default above) |
| `ALLDATA_COOKIES` | Inline JSON (prefer file) |
| `ALLDATA_USERNAME` / `ALLDATA_PASSWORD` | Less reliable than cookies |
| `ALLDATA_DEBUG=1` | Extra logging / screenshots |

## Data handling

- Cookie export and session files stay **on your device**.
- Network calls go to ALLDATA hosts for the subscription you already use.
- The authors do not operate a backend that harvests your credentials.
- Full terms: **[DISCLAIMER.md](DISCLAIMER.md)**.

## Honda / truck note

For CR-V, Pilot, Ridgeline, Odyssey, Passport, HR-V, etc., pass `make="Honda Truck"`.

## Pair with shop quoting

Use with **azpro** (commercial cost + list) and the **shop-quote** skill for full RO format.

## Development

```bash
pytest -q
```

## License

MIT — see [LICENSE](LICENSE).