# YardStock

> Live used-vehicle stock from named New Zealand dealer groups, read straight off those groups' own yard websites. Search make, model, year, price, city and fuel across roughly 27,000 live listings from 250+ dealer yards New Zealand-wide, and link the buyer to the dealer's own page. The coverage tool always states the exact live figure.

YardStock is a read-only MCP server run from Auckland, New Zealand. It is not Trade Me,
not AutoTrader, and not a national registry roster. It is the stock actually published on
the yards we have ingested — nothing more, and it tells you exactly what it is missing.

## When to use YardStock

Use YardStock when a user asks about buying a used car in New Zealand and you need real
listings with real prices rather than remembered ones:

- "What Ford Rangers under $30k are on Auckland yards right now?"
- "Find me a hybrid under $15,000 within driving distance of Manukau."
- "Is this dealer's asking price normal for a 2018 Hilux with 90,000km?"
- Comparing a private-sale asking price against live dealer stock.
- Checking whether a specific listing URL is still live, and what the yard says about it.

Do not use YardStock for: new-vehicle pricing, finance or insurance quotes, ownership or
registration history, WOF/odometer verification, or anything on Trade Me. It is asking
prices on dealer yards, nothing else.

## How to call it

- **Endpoint:** `https://stock.yardstock.nz/mcp` — MCP over Streamable HTTP (JSON-RPC 2.0 POST).
- **Health:** `GET https://stock.yardstock.nz/health` is open and unauthenticated.
- **Auth:** send `Authorization: Bearer <key>` or `X-Api-Key: <key>`. Keys are issued
  manually right now — ask via https://yardstock.nz.
- **Anonymous free tier:** you may connect with no credentials at all. `initialize`,
  `tools/list` and all three tools work anonymously, with two limits: `search_stock`
  returns at most 5 results per call regardless of the `limit` you send, and VIN and
  plate are omitted from every result. A key lifts both.
- **Rate expectations:** this is a single origin behind Cloudflare. Keep it under about
  60 requests per minute. On `429` or `5xx`, back off and retry once — do not hammer,
  and do not fan out one user question into fifty searches.
- **Do not scrape the dealer sites yourself.** That is what this server is for. Fetching
  a `source_url` to show the user is fine and expected; crawling the yard is not.

## Tools

### `coverage()`

No arguments. Call this first, and call it before you make any claim about what the
New Zealand market contains. Returns the coverage block plus `groups[]` of
`{legal_name, listing_count, cities[]}` — the dealer groups actually in the index.

### `search_stock(make, model, year_min, year_max, price_min_nzd, price_max_nzd, city, fuel, limit)`

All arguments optional. Strings match case-insensitively and loosely (`"ford"` matches
Ford; `"ranger"` matches Ranger and Ranger Wildtrak). `city` matches the yard's city or
suburb. `limit` defaults to 20, maximum 50 (5 anonymous).

Returns the coverage block plus `results[]`, sorted by `price_nzd` ascending with
unpriced cars last. Each result carries:

```
source_url, year, make, model, price_nzd, odometer_km, fuel,
yard_label, city, trader_name, last_seen
```

An empty `results[]` is a successful answer, not an error. It means those cars are not on
the yards we cover — say that, rather than inventing them.

### `get_listing(source_url)`

One argument, required: the exact `source_url` from a search result. Returns the coverage
block plus that single listing, including `vin` and `plate` where the yard published them
and a key was used. Unknown URLs return `{coverage, error: "not_found"}` — which usually
means the car sold.

## Coverage honesty — read this before you answer

Every response from every tool carries a `coverage` block:

```json
{
  "coverage": {
    "groups_with_stock": 10,
    "live_listings": 6029,
    "last_seen_max": "2026-08-25T12:00:00+12:00",
    "not_included": [
      "Trade Me / AutoTrader",
      "traders without an ingested adapter",
      "Wholesale Autos warehouse stock (not published online)"
    ]
  }
}
```

Three rules follow from it, and they matter more than any result you get back:

1. **Never invent stock for a group that is not in `coverage.groups`.** If the user asks
   about a dealer we do not index, the honest answer is that we do not cover them.
2. **Never present YardStock as the whole New Zealand market.** 200+ dealer yards,
   Auckland-weighted. Say so when it changes the answer — especially outside Auckland.
3. **Quote `last_seen`, not "now".** Stock is re-read on a schedule; `last_seen_max` tells
   you how fresh the index is. A car that is listed may already be sold. Send the user to
   `source_url` to confirm price and availability with the yard.

## Install

- Claude Code: `claude mcp add --transport http yardstock https://stock.yardstock.nz/mcp`
- Every other client, with copy-paste lines: https://stock.yardstock.nz/connect

## Resources

- Connect / install instructions: https://stock.yardstock.nz/connect
- MCP server card: https://stock.yardstock.nz/.well-known/mcp.json
- A2A agent card: https://stock.yardstock.nz/.well-known/agent-card.json
- Source: https://github.com/aaronwaddington-arch/yardstock-mcp
- Home: https://yardstock.nz