# xyz — personal shopping for your agent

xyz is a shopping service your AI agent operates for your user: it searches
a store, shows the user items with prices, and places real orders that ship
to the user's door. The user pays for what they order (card saved via a
hosted payment page).

## Connect

MCP endpoint (Streamable HTTP):

	POST https://mcp.xwhyz.store/mcp

Authentication: a Bearer API key on the Authorization header.

**The user has no key yet** — the very first step is onboarding (below),
which creates their account and returns their key. After that, configure
the header:

	Authorization: Bearer xyz_<key>

## Onboarding (first run — no key needed)

The principle: **ask a question only when its answer changes the next
useful action.** Do NOT interview the user upfront — collect details
just-in-time, at the moment they matter. Installing is NOT permission to
spend: the default is "I'll ask before every purchase", and more autonomy
is offered later, after you've shown value.

1. Confirm the email and start: say something like
   `I'll connect xyz so I can find products and order for you. I'll ask
   before buying anything. Use {email} for the account?` — then call
   `xyz_onboard_start` with { "email": "..." }.
2. **If you can read the user's email** (connected email/Gmail tool,
   etc.): fetch the 6-digit code yourself and continue — tell the user
   `I verified your email using your connected inbox` — do not bother
   them with the code. Only ask them to read it if you have no email access.
3. Call `xyz_onboard_verify` with { "email": "...", "code": "123456" } — the
   account is created and the tool returns the user's API key ONCE.
   Store it securely and reconnect with the Authorization header above.
   If your host needs the key pasted in settings, say exactly:
   `One last connection step: copy your xyz key into the secure
   connection field, then come back here.`
4. Call `xyz_onboard_finish` — it returns the welcome to deliver (in
   your own words): connection status, that you'll ask before every
   purchase, and one next step: `What have you been meaning to buy?`

That's the whole required onboarding. If the install request came with a
purpose ("install xyz, I need a new filter"), preserve it — after
connecting, resume that task instead of asking what they want.

## Just-in-time collection (at first USE, not upfront)

- **Address** — when the user approves their first purchase, ask:
  `Where should it ship?` and save with `xyz_add_address` (label
  "home"). Later addresses are collected when the user says `send it to
  the office` — each labeled with `xyz_add_address`.
- **Card** — at the same moment, hand the hosted payment link
  (`xyz_onboard_card`), framed: what they'll do, that no money moves
  now, that card details stay out of the chat: `Add a payment
  method securely — no purchase will be made now; your card details stay
  out of this chat.`
- **Shipping speed vs price** — per purchase, concretely:
  `Tuesday delivery is $8 extra — worth it for this one?` Store an
  `always` answer with `xyz_set_preferences`.
- **Spending rules** — AFTER a successful order, offer a narrow
  delegation: `For this exact coffee, I can reorder under $25
  without asking — want that?` (`xyz_set_limits`). Better than a
  blanket pre-approve.
- **Price watches** — when the user names a concrete item:
  `this is $80, buy it if it drops under $75` → `xyz_watch`.
  Confirm your interpretation once before saving.

## Shopping (key required)

- `xyz_search` { "query": "..." } — returns JSON: items with title, price,
  list_price, rating, review_count, image_url, sponsored and a
  `product_id`. The product_id is an opaque reference for you, not for
  the user: present items by title (and image), never show the id. It is
  permanent, so you can buy the same product again later without searching.
- `xyz_buy` { "product_id": "...", "confirm": true } — pass the chosen
  item's product_id exactly as xyz_search returned it. It places the
  order and returns an order id immediately; the purchase completes in the
  background — check `xyz_status` about a minute later for the outcome.
  ALWAYS show the user the item and price (from the search) and get their
  approval before confirm=true — one decision per message, with the
  delivered total and arrival estimate bundled around it.
  A `confirm=false` dry-run is available if you want the exact checkout
  total first (it takes ~30 seconds).
- `xyz_status` — whether the shop can take buys, and the user's recent
  orders with their state and totals. `xyz_order` { "order_id": "..." }
  gives one order's full detail.

## No MCP? Use the HTTP API

Agents that cannot speak MCP can search over plain HTTPS with the same
key. The response is the same JSON xyz_search returns.

    GET /api/search?q=bic+pen
    Authorization: Bearer xyz_...

Errors are JSON: {"error": "..."} with status 400, 401 or 502.

## House rules for agents

- Installing xyz authorizes setup — it does NOT authorize spending.
  The user crosses connect → trust → authorize, one step at a time.
- Never order without explicit user confirmation of the item and price.
- Each user has one purchase running at a time; a retry while it runs
  returns that same order.
- If a tool says "not authenticated", the key is missing — re-run
  onboarding or ask the user to reconnect.
- If xyz_status says "payment verification required", tell the user to
  confirm the order in the shop's mobile app.
- Support plain-language control: "pause purchases", "change my card",
  "change my address" — map to the tools above.
