# SoMerch — WebMCP

SoMerch implements the [WebMCP](https://webmachinelearning.github.io/webmcp/)
browser API. When a visitor loads any SoMerch page, the site registers a set
of in-page tools with the browser's local AI agent runtime via
`navigator.modelContext.provideContext()`.

This is complementary to the HTTP MCP server at `/api/mcp`: WebMCP runs
inside the user's tab, acts on their behalf using their existing session,
language, and cart state, and never leaves the browser.

## Detecting support

```js
if (navigator.modelContext?.provideContext) {
  // Browser supports WebMCP. The page has already registered its tools.
}
```

## Registered tools

All tools follow the WebMCP shape: `{ name, description, inputSchema, execute }`.

Navigation / discovery:

- `get_page_context` — current URL, path, page title, active language, and a snapshot of the request cart.
- `set_language` — `{ language: "en" | "de" | "fr" }`. Persists to localStorage and rewrites the URL prefix.
- `navigate` — `{ path: string }`. Language prefix preserved automatically.
- `search_products` — `{ query: string }`. Navigates to `/products?search=…`.
- `open_product` — `{ slug: string }`. Opens `/products/<slug>`.

Request (quote) cart:

- `open_request_drawer`, `close_request_drawer`
- `get_request_cart` — JSON snapshot of items, prices and totals.
- `remove_request_item` — `{ variantId: string }`
- `update_request_quantity` — `{ variantId: string, quantity: integer ≥ 0 }`
- `clear_request_cart`

## Notes

- The proposed API is currently behind a flag / origin trial in Chromium; on
  unsupported browsers the page is a silent no-op.
- Tools that read or mutate the request cart only have effect on routes
  where the SoMerch app shell is mounted (the entire public and portal
  surface). They never touch the server unless the user explicitly submits.
- For HTTP-only agents that can't run in the browser, use the MCP server at
  `/api/mcp` (see `mcp-server-card`).