# Used Parts MCP

Used Parts MCP is an open-source discovery-and-contact platform for current used car, truck, and motorcycle parts in the United States. It exposes one responsive search site, a versioned REST API, and a remote streamable-HTTP MCP server. Every result remains grouped by source and carries freshness, availability, fitment confidence, and the evidence behind that confidence.

> Beta scope: all current listings from the **enabled, authorized sources shown by `/v1/sources`**—not every used part advertised in the United States. The repository ships only fictional fixtures. eBay production, recycler partner feeds, and any additional marketplace remain disabled until their approvals and secrets are configured.

## What is included

- Four read-only MCP tools: `resolve_vehicle`, `search_used_parts`, `get_part_listing`, and `get_source_coverage`.
- REST endpoints under `/v1`, OAuth protected-resource metadata, health/readiness, and OpenAPI 3.1.
- NHTSA vPIC vehicle resolution with hashed cache keys; raw VINs are neither logged nor persisted.
- Concurrent direct-inventory and eBay queries with provider deadlines and partial responses.
- CSV snapshot, seller-managed SFTP, and HMAC delta contracts; no generic URL scraper.
- PostgreSQL 16 full-text/trigram search, PostGIS distance filtering, source policies, and audit metadata.
- A React/Vite buyer UI and an optional Codex/OpenAI plugin with the `find-used-auto-parts` skill.
- Terraform for an isolated Google Cloud beta and keyless GitHub Actions deployment.

## Architecture

```mermaid
flowchart LR
  Buyer["Buyer or repair shop"] --> Web["Responsive web"]
  AI["ChatGPT, Codex, Claude, Cursor, VS Code"] --> MCP["Streamable HTTP MCP /mcp"]
  Web --> API["Fastify REST + OAuth"]
  MCP --> API
  API --> Search["Concurrent search coordinator"]
  Search --> PG["Cloud SQL PostgreSQL + PostGIS"]
  Search --> Ebay["eBay Browse API (approval gated)"]
  API --> VPIC["NHTSA vPIC"]
  Scheduler["Cloud Scheduler hourly"] --> Worker["Cloud Run synchronization job"]
  Worker --> SFTP["Authorized seller SFTP"]
  Worker --> Raw["14-day raw-feed bucket"]
  Worker --> PG
```

See [architecture](docs/architecture.md), [data-source policy](docs/data-sources.md), [security](docs/security.md), and [operations](docs/operations.md).

## Local quick start

Requirements: Node 24, pnpm 10, and optionally Docker for PostgreSQL.

```bash
corepack enable
corepack prepare pnpm@10.15.1 --activate
pnpm install --frozen-lockfile
cp .env.example .env
pnpm dev
```

The default `AUTH_MODE=optional` and `EBAY_MODE=fixture` are local-only. Open `http://localhost:5173`. The API listens on `http://localhost:8080`.

To exercise PostgreSQL/PostGIS:

```bash
docker compose up -d postgres
pnpm db:migrate
pnpm test
pnpm build
```

## Example API request

```bash
curl -sS http://localhost:8080/v1/parts/search \
  -H 'content-type: application/json' \
  -d '{
    "vehicle":{"year":2019,"make":"Honda","model":"Accord"},
    "query":"transmission",
    "zip":"60614",
    "fulfillment":"either",
    "pageSize":20,
    "providerCursors":{}
  }'
```

Production uses Auth0 authorization-code + PKCE and requires the `search:read` scope. See [authentication setup](docs/authentication.md).

## MCP and skill

The portable core is `POST /mcp`. The optional plugin lives at [`plugins/used-parts-mcp`](plugins/used-parts-mcp) and adds a workflow for resolving ambiguity, preserving source groups, refreshing a shortlist, and never inventing fitment or availability.

Client-specific connection and smoke-test instructions are in [docs/connections.md](docs/connections.md).

## Data-source boundary

Car-Part.com is deliberately not automated. Its published terms prohibit automated access and bulk availability collection. The prospective connector remains disabled unless written permission is supplied and reviewed. There is no scraper framework in this repository.

## Google Cloud beta

- Organization: `createit.gg`
- Billing account display name: `Used Parts MCP`
- Project: `upmcp-neko-20260811-f9a3`
- Region: `us-central1`
- Monthly budget alert: `$50` at 50%, 80%, and 100%

Bootstrap and apply steps are in [docs/deployment.md](docs/deployment.md). Budgets are alerts, not hard spending caps.

## License

Apache-2.0. Sample feeds are fictional and carry no partner rights.