Merchant Web MCP — Prototipo de analítica de agentes y operabilidad

Convierte cualquier escaparate de comercio electrónico en una plataforma observable, medible y transaccional para agentes de compra de IA.

[!NOTE] Aviso de prototipo y simulación: Este repositorio contiene un cockpit de simulación interactivo y un prototipo de la arquitectura propuesta del plugin BigCommerce / Merchant Web MCP. El motor de simulación se ejecuta en el lado del cliente con latencia simulada, firma HMAC-SHA256 genuina mediante Web Crypto, temporizadores reales de reserva de inventario con TTL de 15 minutos y un panel ejecutivo de Agent Intent Analytics.

🎯 El problema central y la propuesta de valor

La realidad a corto plazo: ceguera ante el tráfico de agentes

Hoy en día, los comerciantes no tienen visibilidad sobre los agentes de compra de IA (ChatGPT Agent, Claude, Perplexity, Apple Intelligence). Cuando los bots extraen páginas de productos:

• El tráfico es indistinguible del de los scrapers web básicos.

• El scraping visual consume entre 6.000 y 10.000 tokens por página y con frecuencia falla con la hidratación de React o los rediseños del DOM.

• Los comerciantes tienen cero visibilidad sobre qué productos buscan los agentes, qué consultas fallan y qué demanda comercial se escapa sin capturar.

La solución: BigCommerce Merchant Web MCP

1. Agent Intent Analytics (Valor SaaS inmediato): Captura las sesiones de agentes entrantes, las ejecuciones de herramientas, el valor de intención descubierto (pipeline de 124.000 £+), el desglose por proveedor y las brechas de demanda del catálogo.

2. Interfaz MCP determinista: Expone herramientas JSON-RPC estructuradas (search_products, get_product_details, check_variant_stock, apply_promotions, add_to_cart_session, create_checkout_session).

3. Traspaso criptográfico verificado: Genera URL de pago firmadas usando tokens HMAC-SHA256 genuinos de Web Crypto con bloqueos temporales de inventario de 15 minutos.

Related MCP server: Shopify Agentic MCP Gateway

🏗️ Descripción general de la arquitectura

┌────────────────────────────────────────────────────────┐
│                   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)     │
└───────────────────────┘       └───────────────────────┘

🚀 Ejecutar el cockpit y las pruebas

Inicio rápido

# 1. Install dependencies
bun install

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

# 3. Start development server
bun run dev

Despliegues en vivo

• Cockpit de simulación interactivo: https://merchant-web-mcp.web.app

• Demo independiente del proyector (HTML de un solo archivo): https://merchant-web-mcp.web.app/demos/merchant-web-mcp-demo-v2.html

🛡️ Aspectos destacados de seguridad e integridad en este repositorio

• HMAC-SHA256 genuino de Web Crypto: Implementado en src/mcp/cryptoAuth.ts usando el estándar crypto.subtle. Las firmas se verifican criptográficamente al generar la sesión de pago.

• Expiración activa de inventario por TTL: Implementado en src/mcp/merchantMcpEngine.ts. Las reservas efímeras expiran después de 900 segundos (15 minutos), devolviendo automáticamente el stock al inventario disponible y notificando al HUD del cliente en tiempo real.

• Defensa en profundidad por capas: Implementado en src/mcp/securityGuard.ts. Normaliza la ofuscación Unicode/de ancho cero y analiza las reseñas de clientes, las consultas de búsqueda y los argumentos de promociones.

• Aislamiento multi-carrito: El motor asigna los carritos explícitamente por cart_id, rechazando los intentos de pago en sesiones de carrito no válidas o ajenas.

🗺️ Hoja de ruta y especificación de producción

Para la especificación del servidor edge previsto de Cloudflare Worker + BigCommerce, consulta ROADMAP.md.