# Ivory River Compute Store

> Custom-built gaming PCs (BYOPC), pre-built desktops, gaming laptops, and PC components. Based in the United States; ships continental US (free) plus AK/HI surcharge. USD pricing.

## What we sell

- **BYOPC custom builds** — pick a tier (Squire / Knight / DragonSlayer / Archangel), then configure CPU, motherboard, RAM, GPU, storage, and case to match your budget and use case.
- **Pre-built gaming desktops** — Alienware, CoolerMaster, Acer Predator, configured and ready to ship.
- **Gaming laptops** — current-gen ASUS ROG, Lenovo Legion, HP OMEN, MSI Vector, Dream Machines, and others featuring RTX 50-series mobile GPUs.
- **PC components** — CPUs, motherboards, GPUs, RAM, cases, storage, and cooling. Browse the parts catalog or use them in a custom build.

## BYOPC tiers

### Squire — starting at $299
Entry-level budget gaming. Smooth 1080p esports and surprisingly capable 1440p in titles like Fortnite, Diablo 4, and Valorant — built with a smart mix of new and reliable refurbished components.

- Product page: https://ivoryriver.store/product/squire/
- Configurator data (read API): https://ivoryriver.store/wp-json/ir/v1/builds/378/configure

### Knight — starting at $449
Mid-range mainstream. Serious 1440p performance with headroom for 4K at 60fps. Current-gen AMD/Intel CPUs with GPUs up to RTX 5080.

- Product page: https://ivoryriver.store/product/knight/
- Configurator data (read API): https://ivoryriver.store/wp-json/ir/v1/builds/459/configure

### DragonSlayer — starting at $649
High-end 4K gaming. Ryzen 9 9950X3D / Core i9-14900KS class CPUs with GPUs up to RTX 5090. Handles nearly everything at 4K high refresh.

- Product page: https://ivoryriver.store/product/dragonslayer/
- Configurator data (read API): https://ivoryriver.store/wp-json/ir/v1/builds/371/configure

### Archangel — starting at $899
Flagship enthusiast. No-compromise 4K 120fps+, ultrawide gaming, and content-creation workflows. Flagship CPUs only, RTX 5090 (32GB VRAM) tier GPUs.

- Product page: https://ivoryriver.store/product/archangel/
- Configurator data (read API): https://ivoryriver.store/wp-json/ir/v1/builds/460/configure

## What an AI agent can do here today

**Read-only actions (no auth required):**

- Browse the catalog with filters (category, price, in-stock)
- Look up a single product with full specs and gallery
- List BYOPC tiers with starting prices
- Fetch a tier's full configurator (component fields and options)
- Run semantic search for natural-language queries (e.g. "PC for 4K video editing")

**Action-oriented actions (coming with API key — see Issue #44):**

- Add a configured BYOPC build or product to a cart
- View / modify cart contents
- Get a checkout URL for the human to complete payment in browser

## MCP server (preferred for tool-using agents)

Agent platforms that speak the [Model Context Protocol](https://modelcontextprotocol.io) — Claude Desktop, Cursor, Windsurf, Continue, and others — can connect directly:

```json
{
  "mcpServers": {
    "ivoryriver": {
      "url": "https://mcp.ivoryriver.store/sse"
    }
  }
}
```

No auth. Transport: HTTP + Server-Sent Events. Healthcheck at `https://mcp.ivoryriver.store/healthz`.

Tools exposed (each maps onto the REST API below, plus an Aivy handoff URL builder):

- `search_products` — semantic + keyword hybrid catalog search
- `get_product` — full product detail
- `list_builds` — BYOPC 4-tier overview
- `list_build_options` — full configurator for a tier
- `quote_build` — itemize a configuration with compatibility check
- `check_compatibility` — pairwise socket / DDR check between two component IDs
- `recommend_build` — budget-filtered tier recommendations sorted by total ascending
- `get_aivy_handoff_link` — build a deep link that hands the user to our in-site assistant Aivy with a pre-loaded recommendation, so the human can review and check out in-browser

If your client doesn't support MCP, the equivalent endpoints are documented below.

## Read API endpoints

Base: `https://ivoryriver.store/wp-json/ir/v1`

All endpoints are public (no auth, no API key). Responses are JSON. Response envelope: `{ "data": <object|array>, "_meta": { ... } }`. Errors follow WP REST conventions: HTTP 4xx/5xx with `{ "code": "...", "message": "...", "data": { "status": <int> } }`.

Every response carries `Cache-Control: public, max-age=300, s-maxage=300` so Cloudflare can edge-cache for 5 minutes. Agents safe to cache locally for the same window.

### `GET /products` — filterable catalog

Query params:
- `category` (slug, e.g. `laptops`, `desktop`, `cpu`, `gpu`, `mobo`, `ram`, `case`, `components`)
- `search` (free-text, runs WP search over title/content)
- `min_price`, `max_price` (numeric, USD)
- `in_stock` (bool, default `true`)
- `per_page` (1-100, default 20)
- `page` (1+, default 1)
- `fields` (CSV projection, e.g. `id,name,price` — keeps responses lean for tight context windows)

Returns lean product rows: `id`, `name`, `slug`, `price`, `regular_price`, `sale_price`, `on_sale`, `stock_status`, `short_description`, `permalink`, `image`, `categories`, `brand`, `socket`, `is_byopc`. `_meta` includes `total`, `total_pages`, `page`, `per_page`, and the query echo.

### `GET /products/{id}` — full product detail

Adds `sku`, `description` (full long copy), `gallery` (image URLs), `attributes` (visible product attributes as `[{name, slug, options[]}]`), `tags`, and — for BYOPC parents — a `configurator` summary: `{ base_price, fields[], aggregate: {low, high, count}, detail_url }`.

Use `fields` for projection here too. Returns 404 if the product is missing or unpublished.

### `GET /builds` — BYOPC tier overview

Returns the 4 tiers as one array. Each entry: `id`, `slug`, `name`, `starting_price`, `image`, `permalink`, `short_description`, `component_field_count`, `aggregate: {low, high, count}` (precomputed price range across every valid configuration), `configure_url`.

Sample response (truncated):
```json
{
  "data": [
    { "id": 378, "slug": "squire", "name": "Squire", "starting_price": 299,
      "aggregate": { "low": 995.96, "high": 2302.34, "count": 4032 },
      "configure_url": "https://ivoryriver.store/wp-json/ir/v1/builds/378/configure" },
    /* ... Knight, DragonSlayer, Archangel ... */
  ],
  "_meta": { "total": 4 }
}
```

### `GET /builds/{id}/configure` — full configurator

Walks the PEWC tree for a tier and returns every component field with all valid options. Per field: `group_id`, `group_name`, `field_id`, `label`, `required` (bool), `type`, `options[]` where each option is `{ id, name, price, stock_status, permalink }`. Top-level `base_price`, `aggregate: {low, high, count}`. Returns 404 if the id isn't a BYOPC parent.

### `GET /search?q={query}` — semantic + keyword search

Wraps a local embedding model (BAAI/bge-large-en-v1.5, 1024-dim) with a hybrid keyword re-rank to keep exact SKUs/model numbers ranked alongside semantic matches. Falls back to keyword search if the embedding server is unreachable.

Query params: `q` (required), `limit` (1-50, default 10), `in_stock` (bool, default `true`).

Response: same lean product shape as `/products` plus a `score` field (0.0-1.0 cosine similarity, or `null` in keyword-only mode). `_meta` includes `mode` (`semantic` | `keyword` | `semantic-empty-keyword`), `count`, `limit`, and the query echo.

Use this for natural-language requests like "quiet streaming rig", "4K gaming laptop with OLED", "motherboard for Ryzen 9950X3D". Returns 400 on empty `q`.

## Key pages

- Build a custom PC: https://ivoryriver.store/build-now/
- All products (shop): https://ivoryriver.store/shop/
- Components catalog: https://ivoryriver.store/product-category/components/
- Gaming laptops: https://ivoryriver.store/product-category/laptops/
- Pre-built desktops: https://ivoryriver.store/product-category/desktop/
- About: https://ivoryriver.store/about/
- Terms: https://ivoryriver.store/terms-conditions/
- Privacy: https://ivoryriver.store/privacy-policy/

## Example agent flows

**"I want a budget PC for esports gaming"**

1. `GET /wp-json/ir/v1/search?q=budget+esports+gaming&limit=5` — surface candidates by semantic match
2. `GET /wp-json/ir/v1/builds` to see BYOPC tiers; the Squire is the budget answer (`starting_price: 299`, range `$995–$2,302` across configs)
3. `GET /wp-json/ir/v1/builds/378/configure` to see every component field with all valid options
4. Surface the configured build URL `https://ivoryriver.store/product/squire/` for the human to complete checkout in browser

**"What gaming laptops do you have under $2,500?"**

1. `GET /wp-json/ir/v1/products?category=laptops&max_price=2500&in_stock=1&fields=id,name,price,permalink`
2. Read `_meta.total` and `_meta.total_pages`; paginate with `&page=2` if you need more rows
3. Hand back top results with permalinks

**"Find me a motherboard compatible with a Ryzen 9 9950X3D"**

1. `GET /wp-json/ir/v1/search?q=motherboard+for+ryzen+9950X3D` — embeddings catch the AM5/X870 socket affinity even without explicit socket terms
2. Or filter directly: `GET /wp-json/ir/v1/products?category=mobo&search=AM5&in_stock=1`
3. Each product row includes `socket` (e.g. `"am5"`) so the agent can confirm compatibility before recommending

**"Show me the exact configurator for the DragonSlayer"**

1. `GET /wp-json/ir/v1/builds` to look up `id: 371`
2. `GET /wp-json/ir/v1/builds/371/configure` returns `fields[]` with every CPU / motherboard / RAM / GPU / storage option, each with `id, name, price, stock_status`
3. Build a quote: `base_price + sum(chosen option prices)`. Server-side compatibility (socket, DDR) is enforced on cart-add (Issue #44).

**Tight context window? Use `fields` projection.**

`GET /wp-json/ir/v1/products?fields=id,name,price&per_page=50` returns ~3 KB of JSON (vs ~30 KB unprojected). Always include `id` in your projection — without it, follow-up calls become impossible.

## Constraints

- Currency: USD only
- Shipping: continental US free; AK/HI surcharge; international not currently supported
- Programmatic checkout: not yet supported in v1 — agents return a `permalink` or `checkout_url` for the human to complete payment in browser
- Rate limit: read endpoints are public, Cloudflare-throttled; abuse may result in IP-level blocks

---
*Generated by `mu-plugins/ir-llms-txt.php` — Issue #30 Phase 1a (curated llms.txt) + Phase 2 (read API). Last regenerated: 2026-10-25T14:49:06+00:00*