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

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, data-source policy, security, and operations.

Local quick start

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

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:

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

Example API request

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.

MCP and skill

The portable core is POST /mcp. The optional plugin lives at 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.

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. Budgets are alerts, not hard spending caps.

License

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