# Commerce MCP App

A cross-platform MCP App for product discovery, session-scoped carts, and confirmation-gated checkout.

## Tool contract

- `search_products` — the only model-facing product discovery tool. Handles browsing, natural-language queries, categories, price constraints, attributes, ranking, and pagination.
- `list_products` — app-only unfiltered catalog loader; hidden from the model to prevent routing ambiguity.
- `add_to_cart` — adds an exact product ID to the current session cart.
- `remove_from_cart` — removes an exact product ID from the current session cart.
- `view_cart` — returns the current session cart.
- `checkout_cart` — previews checkout unless `confirmed=true`; accepts an idempotency key for safe retries.

The React UI is served at `ui://products/index.html`. Every UI-backed tool also returns text content for hosts without MCP Apps support.

## Product accuracy pipeline

`search_products` does not send a conversational sentence to the upstream literal search endpoint. It:

1. Normalizes common product synonyms and categories.
2. Extracts price bounds and ranking intent from ordinary shopping language.
3. Retrieves the full catalog through the resilient API client.
4. Applies deterministic constraints.
5. Ranks matching candidates by title, category, description, tags, rating, or requested price order.
6. Returns the normalized intent in `structuredContent` for debugging and evaluation.

This local retrieval pipeline is appropriate for the small DummyJSON catalog. For a large production catalog, replace candidate retrieval with a search index while retaining the same intent and ranking contract.

## Reliability and safety

- Retry with exponential backoff for network, 429, and 5xx failures.
- Request timeout, ETag revalidation, LRU caching, and stale-cache fallback.
- Zod validation at the upstream catalog boundary.
- Optional bearer-token authentication with explicit 401 responses.
- Cart isolation by MCP transport session; stdio processes are naturally one client per process.
- Cumulative per-product quantity limits.
- Explicit confirmation and idempotent replay for checkout.
- MCP annotations describing read-only, destructive, and idempotent behavior.

The sample checkout produces a local receipt. A real deployment must replace it with transactional inventory, order, and payment services.

## Screenshots

App Screenshots:
<img width="873" height="1161" alt="image" src="https://github.com/user-attachments/assets/b486e82e-d58f-40f2-ba1d-bd6012da8b84" />
<img width="1505" height="958" alt="image" src="https://github.com/user-attachments/assets/67ff01f1-8cc8-4de8-b32b-cb43046bc774" />
<img width="1510" height="788" alt="image" src="https://github.com/user-attachments/assets/180215ab-356e-4068-8e72-29bce7d9f3de" />

AI Host Chat screenshot:

<img width="377" height="692" alt="Screenshot 2026-08-13 115818" src="https://github.com/user-attachments/assets/a69bb353-25f0-4998-a083-1d06def0fc77" />

## Commands

```powershell
npm install
npm run check
npm test
npm run build
npx -y @mcpjam/inspector@latest
```

Paid model-routing evals are intentionally separate:

```powershell
npm run eval
```

## Configuration

- `PRODUCTS_API_ENDPOINT` — defaults to `https://dummyjson.com/products`
- `PRODUCTS_API_BEARER_TOKEN` — optional
- `PRODUCTS_API_TIMEOUT_MS` — defaults to `8000`
- `PRODUCTS_API_MAX_RETRIES` — defaults to `3`
- `PRODUCTS_API_BASE_BACKOFF_MS` — defaults to `300`
- `PRODUCTS_API_MAX_BACKOFF_MS` — defaults to `3000`
- `PRODUCTS_API_CACHE_TTL_MS` — defaults to `30000`
- `PRODUCTS_API_CACHE_MAX_ENTRIES` — defaults to `100`

## Evaluation strategy

`npm test` is deterministic and covers API resilience, response validation, query parsing, ranking, cart isolation, quantity constraints, and UI behavior. `npm run eval` measures model tool selection and argument extraction without a routing answer sheet. Product-result correctness is covered by deterministic golden-set tests so provider outages or exhausted credits cannot masquerade as zero product accuracy.