Claude for Commerce + China Sourcing: HIOBuy Agent API and MCP Example

If you are wiring a shopping agent to live China catalogs, the hard part is not the chat UI. It is marketplace auth, normalized product fields, and a tool surface your agent can call without scraping.

HIOBuy just published an open-source example that does exactly that: hiobuy/claude-for-commerce-examples. It implements Anthropic's commerce-agents StorefrontBackend against live 1688 and Taobao data through HIOBuy Agent API or MCP.

This guide walks through what shipped, how the architecture fits together, and how to run it locally.

What shipped

Item	Detail
Repo	github.com/hiobuy/claude-for-commerce-examples
License	Apache-2.0
Runtime	Python 3.11+, local FastAPI/uvicorn demo
Marketplaces (live)	1688, Taobao
Marketplaces (not live yet)	Weidian — placeholder upstream; intentionally disabled
Modes	HIOBUY_MODE=agent-api (default) or mcp

The example installs Anthropic's shopping-agent-core, shopping-agent-runtime, and commerce-common packages at a fixed Git commit and implements their backend contract. It does not invent a new agent platform or call marketplaces directly.

Independent developer implementation based on Anthropic's commerce-agents blueprint — not maintained, sponsored, or endorsed by Anthropic or Shopify.

Why this shape

HIOBuy already exposes China sourcing as:

Surface	Role
REST /v1/*	Traditional backend / storefront integration
Agent API /ai/v1/*	Tool discovery + tool calls for LLM agents
MCP /mcp	Same tools for MCP clients
Starter / AI Product Finder	General app demos

This new repo is the Anthropic commerce-agents adapter: a thin translation layer between those APIs and Claude's shopping workflow (search, inspect variants, compare options, image search).

Architecture

Browser chat / image upload
          ↓ local Python server (credentials stay here)
Claude ↔ Anthropic ShoppingAgent / skills / provenance gates
          ↓ HioBuyStorefrontBackend
          ├─ Mode A: GET /ai/v1/tools → POST /ai/v1/tools/call
          └─ Mode B: /mcp → initialize / tools/list / tools/call
          ↓ HIOBuy Gateway
          ↓ 1688 / Taobao

Keys never leave the Python server. The UI does not request or receive credentials. In MCP mode, backend methods call HIOBuy's existing MCP endpoint server-side — the Messages API runtime does not take an arbitrary remote MCP server as a constructor argument.

Capabilities (what the agent can do)

Capability	1688	Taobao	Weidian
Keyword search / CNY price filter	Yes	Yes	Unavailable
Product detail / seller data	Yes	Yes	Disabled
Variants / SKUs	Yes	Yes	Disabled
Image upload → similarity search	Yes	Yes	Not supported
Compare / recommend from returned facts	Yes	Yes	Disabled

Important honesty constraints from the README (keep these in your product copy too):

• Search results do not provide stock; unknown data stays unknown.
• No purchases, carts, checkout, orders, fulfillment, or inventory writes in this example.
• No supplier quality or authenticity is inferred.
• Your Live key must have scopes and channel authorization for the marketplace you select.

Prerequisites

1. Python 3.11+, Git
2. An Anthropic API key with model access
3. A HIOBuy Live key (hio_live_*) from the Developer Portal
4. Scopes at minimum:
   • product:search — product.search, product.upload_image, product.search_by_image
   • product:detail — product.get_detail
5. Channel authorization for 1688 and/or Taobao on that application

Sandbox keys (hio_test_*) do not work on /ai/v1 or /mcp. See the Agent API & MCP docs.

Quick start

git clone https://github.com/hiobuy/claude-for-commerce-examples.git
cd claude-for-commerce-examples
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.lock.txt
cp .env.example .env
# Fill ANTHROPIC_API_KEY and HIOBUY_API_KEY
python -m uvicorn examples.china_sourcing.app:app --host 127.0.0.1 --port 8000

Open http://127.0.0.1:8000. The page starts without keys and explains what is missing — it never silently falls back to generated products.

Environment variables

Name	Required	Notes
ANTHROPIC_API_KEY	For chat	Server-side only
HIOBUY_API_KEY	For product calls	Live key; server-side only
HIOBUY_MODE	No	agent-api (default) or mcp
HIOBUY_BASE_URL	No	Default https://api.hiobuy.com (HTTPS only)
ANTHROPIC_MODEL	No	Pinned blueprint default in the example

Agent API mode (default)

With HIOBUY_MODE=agent-api:

1. Server calls GET /ai/v1/tools and caches permitted tools.
2. It keeps the four product tools and validates arguments against each tool's JSON Schema.
3. Invocations go to POST /ai/v1/tools/call with { "tool_id": "...", "arguments": { ... } }.

Typical tool chain (same as the public Agent API):

product.search  →  product.get_detail
product.upload_image  →  product.search_by_image  →  product.get_detail

Example call shape from the docs:

POST /ai/v1/tools/call
Authorization: Bearer hio_live_xxx
Content-Type: application/json

{
  "tool_id": "product.search",
  "arguments": {
    "channel": "1688",
    "keyword": "wireless earbuds",
    "price_end": "30",
    "page_size": 8,
    "language": "en"
  }
}

Success envelope: { "tool_id", "ok": true, "data", "request_id" }. Keep request_id for support tickets.

MCP mode

Set HIOBUY_MODE=mcp and restart. The same chat, comparison, and image flows use HIOBuy's Streamable HTTP MCP endpoint (/mcp): initialize a session, accept the negotiated protocol version, tools/list, then tools/call. Tool payloads unwrap to the same JSON envelope as Agent API.

If you only need MCP inside Cursor (without this Python demo), the portal docs show a direct client config:

{
  "mcpServers": {
    "hiobuy": {
      "url": "https://api.hiobuy.com/mcp",
      "headers": {
        "Authorization": "Bearer hio_live_xxx"
      }
    }
  }
}

Prompts to try

• Find wireless earbuds under ¥30 on 1688. Inspect details and recommend a shortlist.
• Find canvas tote bags on Taobao. Compare three products and recommend one.
• Show available colors and sizes for a returned taobao: / 1688: product id.
• Use Search by image (JPEG/PNG up to 2 MB) — the server calls product.upload_image, then product.search_by_image with the returned image_id. Images go to HIOBuy, not into Claude's text prompt.

ID tip: Use IDs exactly as returned. Taobao id is its opaque mi_id, not necessarily the numeric marketplace product id. The adapter qualifies IDs with the marketplace so cross-marketplace identities stay distinct.

Smoke checks (no Claude required)

After configuring a Live key:

python -m examples.china_sourcing.smoke --mode agent-api --channel 1688
python -m examples.china_sourcing.smoke --mode mcp --channel taobao
python -m examples.china_sourcing.smoke --mode agent-api --channel 1688 --image ./product.jpg

These hit HIOBuy only. Verify the five prompt flows manually in the UI with an Anthropic key before you treat the stack as production-ready.

What this is not

• Not a hosted multi-tenant agent SaaS — binds to loopback, rejects foreign Host headers and cross-origin POSTs.
• Not a white-label storefront.
• Not Weidian-ready until the live Gateway adapter is verified.
• Not a substitute for reading HIOBuy API docs for scopes, quotas, and product field semantics.

Where to go next

1. Clone and run the example: hiobuy/claude-for-commerce-examples
2. Read Agent API & MCP: hiobuy.com/en/api-docs/agent-api
3. For a Next.js Product API starter (non-agent), see hiobuy/starter
4. For conversational search UI, see hiobuy/ai-product-finder

Questions on scopes, channels, or request_id errors: support@hiobuy.com.

---

Next step

If you already understand the workflow, move to the API reference for exact request and response fields, or open the developer console to create your application.