Skip to main content
Glama

commerce-mcp-sandbox

A zero-dependency mock commerce MCP server for building and testing shopping agents.

给购物类 AI agent 用的模拟商城后端:搜索、下单、模拟支付、物流自动推进、退款——全部内存模拟,没有任何真实商品与真实资金。让你在写购物 agent 时不用等真实电商接口,先把 agent 逻辑跑通。

English below | 中文说明见下半部分


Why

Every developer building a shopping agent hits the same wall: "I need a commerce backend to test against." Real APIs need credentials, contracts, and money. This sandbox gives you the full shopping lifecycle — search → order → pay → ship → deliver → refund — as an MCP server your agent can talk to, with deterministic in-memory state.

Related MCP server: Project Tango

Install & Run

Zero dependencies. Node ≥ 18.

npx commerce-mcp-sandbox          # stdio mode (for MCP hosts)
npx commerce-mcp-sandbox --http   # not supported yet; use node src/http.js 3300
# or clone & run:
node src/index.js                 # stdio
node src/http.js 3300             # HTTP mode: POST http://localhost:3300/mcp

MCP host configuration

{
  "mcpServers": {
    "commerce-sandbox": {
      "command": "npx",
      "args": ["commerce-mcp-sandbox"]
    }
  }
}

Streamable-HTTP hosts (Dify / Coze / web agents):

url: http://localhost:3300/mcp

Tools (7)

tool

说明

search_products

Search mock catalog (query/category/page). Prices in CNY cents.

get_product

Product detail with specs.

create_order

Create order. Requires receiver {name, phone, address}.

pay_order

Simulate payment. Shipping auto-advances in ~5s, delivery in ~15s — so agents can exercise the full lifecycle in seconds.

get_order

Status + event timeline (created/paid/shipped/delivered/refunded).

list_orders

List orders, filter by user_ref.

request_refund

Simulate refund (no real money).

Example flow

agent: search_products {query: "umbrella"}     → 1 item, ¥39.00
agent: create_order {items:[{sku:"UMB-001",qty:1}], receiver:{...}}
user:  pay_order {order_no:"MOCK100001"}       → paid
(wait ~5s) get_order → shipped (waybill SF...)
(wait ~15s) get_order → completed
agent: request_refund {order_no:"MOCK100001"}  → refunded (simulated)

Honest limits

  • In-memory only — restart wipes state. This is a test double, not a store.

  • No real payments — pay_order flips state; nothing is charged.

  • Single-instance — no persistence layer by design.

Building a real shopping agent?

This sandbox is built by 源头淘 (Yuantoutao) — an open product shelf + fulfillment network for AI agents in China (MCP + REST, WeChat Pay checkout, merchant drop-shipping via ERP, automated aftersales). When your agent is ready for real goods: same tool surface, swap the endpoint, done.

Docs: https://mcp.yuantoutao.com/docs/ · llms.txt: https://mcp.yuantoutao.com/llms.txt

License

MIT

Available Tools

7 tools
create_orderB

Create an order. Requires receiver {name, phone, address}. Idempotency is the caller's job in this sandbox (orders are in-memory).

Inputs: items (required), receiver (required), user_ref.

get_orderC

Order status + event timeline (created/paid/shipped/delivered/refunded).

Inputs: order_no (required).

get_productB

Product detail by sku, incl. specs. Read-only.

Inputs: sku (required).

list_ordersC

List orders, optionally filtered by user_ref.

Inputs: user_ref.

pay_orderA

Simulate a successful payment for an order. Shipping auto-advances (~5s) and delivery (~15s) so agents can exercise full flows.

Inputs: order_no (required).

request_refundB

Simulate a refund for a paid/shipped/completed order (no real money).

Inputs: order_no (required), reason.

search_productsC

Search the mock catalog. Prices in CNY cents (int). Read-only.

Inputs: page, query, category, page_size.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a distinct resource-action pair: product search/detail, order create/pay/get/list, and refund. No overlaps or ambiguous boundaries; an agent can easily select the right tool.

    Naming Consistency5/5

    All tools follow a consistent snake_case verb_noun pattern (search_products, get_product, create_order, pay_order, get_order, list_orders, request_refund). The convention is uniform and readable.

    Tool Count5/5

    Seven tools is well-scoped for a commerce sandbox, covering the essential product and order operations without excess. Each tool earns its place.

    Completeness4/5

    The surface covers the core commerce lifecycle: product search/detail, order creation, payment, status, listing, and refund. Minor gaps exist (e.g., no order cancellation or update), but agents can work around these for typical sandbox flows.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to perform e-commerce operations including product search, budget-constrained shopping recommendations, and sustainability analysis. Includes a secure HTTP bridge with OAuth integration and observability features for production deployment.
      -
    • A
      license
      A
      quality
      B
      maintenance
      A local-first Model Context Protocol server that provides LLM agents with structured access to e-commerce data (products, inventory, orders, sales analytics) using a realistic mock dataset, zero configuration, and a swappable DataProvider interface for live APIs.
      8
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables building and evaluating shopping/support agents against a deterministic synthetic retail store with in-memory fixtures. Provides tools, resources, and prompts for product search, cart and order flows, inventory, and policy retrieval over stdio or Streamable HTTP.
      6
      39 PyPI
      MIT