Merchant Web MCP — Agent Analytics & Operability Prototype

Turn any e-commerce storefront into an observable, measurable, and transactable platform for AI shopping agents.

This repository holds two apps on the same agentic-commerce ground. This document is the merchant cockpit. The seller-side product thesis stays in its own briefing.

🎯 The Core Problem & Value Proposition

The Near-Term Reality: Blindness to Agent Traffic

Today, merchants are blind to AI shopping agents (ChatGPT Agent, Claude, Perplexity, Apple Intelligence). When bots scrape product pages:

• Traffic is indistinguishable from dumb web scrapers.

• Visual scraping consumes 6,000–10,000 tokens per page and frequently breaks on React hydration or DOM redesigns.

• Merchants have zero visibility into what products agents are searching for, what queries fail, and what commercial demand passes through uncaptured.

The Solution: BigCommerce Merchant Web MCP

1. Agent Intent Analytics (Immediate SaaS Value): Captures incoming agent sessions, tool executions, discovered intent value (£124k+ pipeline), provider breakdown, and catalog demand gaps.

2. Deterministic MCP Interface: Exposes structured JSON-RPC tools (search_products, get_product_details, check_variant_stock, apply_promotions, add_to_cart_session, create_checkout_session).

3. Demo checkout handoff: The cockpit labels the session DEMO ONLY - not signed. Real HMAC-SHA256 signing runs only in the Cloudflare Worker.

Related MCP server: Shopify Agentic MCP Gateway

🏗️ Architecture Overview

┌────────────────────────────────────────────────────────┐
│                   AI Shopping Agent                    │
│             (Claude / ChatGPT / Perplexity)            │
└───────────────────────────┬────────────────────────────┘
                            │ (1) Discover: /.well-known/mcp.json
                            │ (2) Transport: HTTP / SSE Stream
                            ▼
┌────────────────────────────────────────────────────────┐
│             Merchant Web MCP Plugin Engine             │
│  ┌──────────────────────────────────────────────────┐  │
│  │ Layered Security Guard (Unicode Filter & Regex)  │  │
│  └────────────────────────┬─────────────────────────┘  │
│                           │                             │
│  ┌────────────────────────▼─────────────────────────┐  │
│  │ Standardized MCP Tools:                          │  │
│  │  • search_products(query, max_price, waterproof) │  │
│  │  • check_variant_stock(variant_id, postal_code)  │  │
│  │  • apply_promotions(promo_code, subtotal)        │  │
│  │  • add_to_cart_session(variant_id, qty) [15m TTL]│  │
│  │  • create_checkout_session (demo label in cockpit)│  │
│  │  • get_store_policies()                          │  │
│  └────────────────────────┬─────────────────────────┘  │
└───────────────────────────┼────────────────────────────┘
                            │
            ┌───────────────┴───────────────┐
            ▼                               ▼
┌───────────────────────┐       ┌───────────────────────┐
│ Merchant Catalog / DB │       │ Storefront Cart & DOM │
│ (BigCommerce / D1)    │       │ (Live State Sync)     │
└───────────────────────┘       └───────────────────────┘

🚀 Running each app

1. Merchant Web MCP cockpit

# Install dependencies
bun install

# Test suite
bun test

# Development server (Vite)
bun run dev

Live deployments:

• Interactive Simulation Cockpit: https://merchant-web-mcp.web.app

• Standalone projector demo (single source demos/merchant-web-mcp-demo-v2.html; Vite dev, preview, and build publish it to /demos/merchant-web-mcp-demo-v2.html and /merchant-web-mcp-demo-v2.html): https://merchant-web-mcp.web.app/demos/merchant-web-mcp-demo-v2.html

2. Seller Agent Console

PSP-hosted control plane for managed seller agents (Mandate Gate, human approve, SP-API writes). Demo merchant: North Harbour Gear. Branding: Meridian Pay.

Product thesis, architecture, and what is simulated vs real: apps/seller-agent-console/BRIEFING.md. App notes: apps/seller-agent-console/README.md.

No build step. The prototype is static HTML/CSS/JS.

# from the repo root
bun run dev:seller
# → http://localhost:8931  (prototype/index.html)

# or open the file directly
open apps/seller-agent-console/prototype/index.html

Architecture diagrams: apps/seller-agent-console/prototype/architecture.html.

Imported from seller-agent-console at 3ff17182f74373d08c2cab1dbd45f40dd5db5b19 (subtree; see apps/seller-agent-console/ORIGIN.md).

🛡️ Security & Integrity Highlights in this Repo

• Checkout HMAC stays on the Worker: server-examples/checkoutHmac.ts signs and verifies with the MERCHANT_HMAC_SECRET Worker secret. Signing throws if that secret is unset. Verification returns false and logs. The browser cockpit never receives the secret. Its handoff is labelled DEMO ONLY - not signed.

• Active TTL Inventory Expiration: Implemented in src/mcp/merchantMcpEngine.ts. Ephemeral reservations expire after 900 seconds (15 mins), automatically returning stock to available inventory and notifying the client wire HUD.

• Layered Defense-in-Depth: Implemented in src/mcp/securityGuard.ts. Normalizes Unicode/zero-width obfuscation and scans across customer reviews, search queries, and promo arguments.

• Multi-Cart Isolation: Engine maps carts explicitly by cart_id, rejecting checkout attempts on invalid or foreign cart sessions.

🗺️ Roadmap & Production Specification

For the target Cloudflare Worker + BigCommerce edge server specification, see ROADMAP.md.