将任何电子商务店面转变为一个可观测、可量化、可交易的 AI 购物智能体平台。
[!NOTE] 原型与模拟说明： 本仓库包含所提议的 BigCommerce / Merchant Web MCP 插件架构的交互式模拟驾驶舱和原型。模拟引擎在客户端运行，具备模拟延迟、真实的 Web Crypto HMAC-SHA256 签名、真实的 15 分钟 TTL 库存预留计时器，以及一个面向高管的智能体意图分析仪表盘。
如今，商家对 AI 购物智能体（ChatGPT Agent、Claude、Perplexity、Apple Intelligence）一无所知。当机器人抓取产品页面时：
这类流量与普通网页爬虫无法区分。
可视化抓取每页消耗 6,000–10,000 个 token，并且经常因 React hydration 或 DOM 重新设计而失效。
商家对智能体正在搜索哪些产品、哪些查询失败、以及哪些商业需求未经捕获而白白流失，拥有零可见性。
智能体意图分析（即时 SaaS 价值）： 捕获传入的智能体会话、工具执行、已发现的意图价值（£124k+ 销售管道）、提供商细分以及目录需求缺口。
确定性 MCP 接口： 公开结构化的 JSON-RPC 工具（search_products、get_product_details、check_variant_stock、apply_promotions、add_to_cart_session、create_checkout_session）。
可验证的密码学交接： 使用真实的 Web Crypto HMAC-SHA256 令牌生成带签名的结账 URL，并带有 15 分钟临时库存软锁。
Related MCP server: Shopify Agentic MCP Gateway
┌────────────────────────────────────────────────────────┐
│ 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) │
└───────────────────────┘ └───────────────────────┘# 1. Install dependencies
bun install
# 2. Run test suite (7 tests, 27 assertions)
bun test
# 3. Start development server
bun run dev交互式模拟驾驶舱： https://merchant-web-mcp.web.app
独立投影演示（单文件 HTML）： https://merchant-web-mcp.web.app/demos/merchant-web-mcp-demo-v2.html
真实的 Web Crypto HMAC-SHA256： 在 src/mcp/cryptoAuth.ts 中使用标准 crypto.subtle 实现。生成结账会话时会以密码学方式验证签名。
主动 TTL 库存过期： 在 src/mcp/merchantMcpEngine.ts 中实现。临时预留会在 900 秒（15 分钟）后过期，自动将库存返还至可用库存，并通知客户端 wire HUD。
分层纵深防御： 在 src/mcp/securityGuard.ts 中实现。对 Unicode/零宽混淆进行规范化，并跨客户评论、搜索查询和促销参数进行扫描。
多购物车隔离： 引擎按 cart_id 显式映射购物车，拒绝针对无效或外部购物车会话的结账尝试。
有关目标 Cloudflare Worker + BigCommerce 边缘服务器规格，请参阅 ROADMAP.md。
This server cannot be deployed
AI shopping gateway for product search, inventory, carts, and merchant-hosted checkout.
AI-agent product catalog: search, lookup & purchase routing over verified merchant data.
Live product discovery for AI shopping agents, with shopper-approved retailer handoff.
The independent agent-commerce protocol for AI-agent checkout on any online store.
