Merchant Web MCP — Agent Analytics & Operability Prototype

Verwandle jeden E-Commerce-Storefront in eine beobachtbare, messbare und transaktionsfähige Plattform für KI-Einkaufsagenten.

[!NOTE] Prototyp- & Simulationshinweis: Dieses Repository enthält ein interaktives Simulations-Cockpit und einen Prototyp der vorgeschlagenen BigCommerce / Merchant Web MCP-Plugin-Architektur. Die Simulationsengine läuft clientseitig mit simulierter Latenz, echter Web-Crypto-HMAC-SHA256-Signierung, echten 15-Minuten-TTL-Inventarreservierungs-Timern und einem Executive-Dashboard für Agent Intent Analytics.

🎯 Das Kernproblem & Wertversprechen

Die kurzfristige Realität: Blindheit gegenüber Agent-Traffic

Heutzutage sind Händler blind gegenüber KI-Einkaufsagenten (ChatGPT Agent, Claude, Perplexity, Apple Intelligence). Wenn Bots Produktseiten scrapen:

• Der Traffic ist von dummen Web-Scrapern nicht zu unterscheiden.

• Visuelles Scraping verbraucht 6.000–10.000 Tokens pro Seite und scheitert häufig an React-Hydration oder DOM-Redesigns.

• Händler haben keinerlei Sichtbarkeit darauf, nach welchen Produkten Agenten suchen, welche Suchanfragen fehlschlagen und welche kommerzielle Nachfrage unerfasst durchgeht.

Die Lösung: BigCommerce Merchant Web MCP

1. Agent Intent Analytics (Sofortiger SaaS-Wert): Erfasst eingehende Agent-Sessions, Tool-Ausführungen, entdeckten Intent-Wert (£124k+ Pipeline), Provider-Aufschlüsselung und Katalog-Nachfragelücken.

2. Deterministische MCP-Schnittstelle: Stellt strukturierte JSON-RPC-Tools bereit (search_products, get_product_details, check_variant_stock, apply_promotions, add_to_cart_session, create_checkout_session).

3. Verifizierte kryptografische Übergabe: Erzeugt signierte Checkout-URLs mithilfe echter Web-Crypto-HMAC-SHA256-Tokens mit 15-minütigen ephemeren Inventar-Soft-Locks.

Related MCP server: Shopify Agentic MCP Gateway

🏗️ Architekturübersicht

┌────────────────────────────────────────────────────────┐
│                   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 (WebCrypto HMAC SHA256│  │
│  │  • get_store_policies()                          │  │
│  └────────────────────────┬─────────────────────────┘  │
└───────────────────────────┼────────────────────────────┘
                            │
            ┌───────────────┴───────────────┐
            ▼                               ▼
┌───────────────────────┐       ┌───────────────────────┐
│ Merchant Catalog / DB │       │ Storefront Cart & DOM │
│ (BigCommerce / D1)    │       │ (Live State Sync)     │
└───────────────────────┘       └───────────────────────┘

🚀 Cockpit & Tests ausführen

Schnellstart

# 1. Install dependencies
bun install

# 2. Run test suite (7 tests, 27 assertions)
bun test

# 3. Start development server
bun run dev

Live-Bereitstellungen

• Interaktives Simulations-Cockpit: https://merchant-web-mcp.web.app

• Eigenständige Projector-Demo (Single-File-HTML): https://merchant-web-mcp.web.app/demos/merchant-web-mcp-demo-v2.html

🛡️ Sicherheits- & Integritäts-Highlights in diesem Repo

• Echte Web-Crypto-HMAC-SHA256-Signierung: Implementiert in src/mcp/cryptoAuth.ts unter Verwendung des standardmäßigen crypto.subtle. Signaturen werden bei der Checkout-Sitzungserstellung kryptografisch verifiziert.

• Aktive TTL-Inventarablaufzeit: Implementiert in src/mcp/merchantMcpEngine.ts. Ephemere Reservierungen laufen nach 900 Sekunden (15 Minuten) ab, wodurch der Bestand automatisch in das verfügbare Inventar zurückgeführt und der Client-Wire-HUD benachrichtigt wird.

• Mehrschichtige Defense-in-Depth: Implementiert in src/mcp/securityGuard.ts. Normalisiert Unicode-/Zero-Width-Verschleierung und scannt Kundenbewertungen, Suchanfragen und Promo-Argumente.

• Multi-Cart-Isolation: Die Engine ordnet Warenkörbe explizit über cart_id zu und lehnt Checkout-Versuche bei ungültigen oder fremden Warenkorb-Sitzungen ab.

🗺️ Roadmap & Produktionsspezifikation

Für die angestrebte Cloudflare Worker + BigCommerce Edge-Server-Spezifikation siehe ROADMAP.md.