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.

Commands

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

Paid model-routing evals are intentionally separate:

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.