{
  "markdown": "# xurprise MCP\n\n> **Agent-native commerce · xurprise.**\n> One HTTPS endpoint. Six tools. Zero setup. Multilingual.\n\n[![Languages](https://img.shields.io/badge/search-EN%20%7C%20%E4%B8%AD%E6%96%87%20%7C%20MS%20%7C%20ID%20%7C%20VI%20%7C%20TH%20%7C%20%E6%97%A5%E6%9C%AC%E8%AA%9E%20%7C%20%ED%95%9C%EA%B5%AD%EC%96%B4-blue)](#multilingual-search)\n[![Live demo](https://img.shields.io/badge/live_demo-xurprise.ai%2Fdemo-d97757)](https://xurprise.ai/demo/)\n\n![xurprise MCP demo — three brands, three languages, three brand colours (Sephora · JD Sports · Xiaomi)](./assets/demo.gif)\n\n> **This GIF is recorded from a real page**, not a mockup.\n> Visit **[xurprise.ai/demo](https://xurprise.ai/demo/)** to watch it render live in your browser. It runs the official [`@openuidev/react-lang`](https://github.com/thesysdev/openui) `<Renderer>` against a custom `BrandCard` component, driven by hand-authored openui-lang snippets that wrap the exact JSON `xurprise.ai/api/mcp` returns — so what you see *is* what any OpenUI-based chat client gets when it calls our MCP.\n\nThe **xurprise MCP server** lets any MCP-compatible agent\n(Claude, Cursor, Cline, Continue, Goose, etc.) discover merchant\nbrands and get attribution-tracked click-through URLs across a curated\ncatalogue spanning Taobao, Shopee, Shein, Xiaomi, Sephora, JD Sports,\nAirpaz, WPS, FusionHome AI, and more — with **region matching built in**\nso agents don't recommend Singapore-only merchants to users in Germany.\n\n**Hosted endpoint:** `https://xurprise.ai/api/mcp`\n\n**Protocol:** Model Context Protocol (MCP) `2024-11-05` over\n[Streamable HTTP](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#streamable-http).\nStateless, no auth required, no SDK needed.\n\n---\n\n## Why\n\nCommerce in the agent era has a cold-start problem: when an agent wants\nto recommend a real merchant, it typically:\n\n1. Searches the open web, picks a result based on SEO ranking, and\n   hopes the merchant ships to its user's country.\n2. Or hardcodes a handful of well-known brands and misses region fit.\n\nxurprise MCP solves this for the niche we cover by giving agents a\n**machine-readable, region-aware brand catalogue** — one call and you\nget back a structured list of merchants the user can actually buy\nfrom, with canonical storefront URLs and click-through URLs that log\nattribution for us and pass through any `aff_sub` tag the agent\nsupplies.\n\n---\n\n## Quick start\n\n### Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json`\n(macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows).\n\n**Option A — native remote HTTP** (Claude Desktop ≥ early 2025):\n\n```json\n{\n  \"mcpServers\": {\n    \"xurprise\": {\n      \"type\": \"http\",\n      \"url\": \"https://xurprise.ai/api/mcp\"\n    }\n  }\n}\n```\n\n**Option B — via `mcp-remote` bridge** (any Claude Desktop version):\n\n```json\n{\n  \"mcpServers\": {\n    \"xurprise\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-remote\", \"https://xurprise.ai/api/mcp\"]\n    }\n  }\n}\n```\n\nRestart Claude Desktop, open a new conversation, and type something like:\n\n> I'm in Singapore. Any good beauty brands I can shop online?\n\nClaude will call `search_brands(query=\"beauty\", region=\"Singapore\")` and\nsurface Sephora SG with a click-through URL.\n\n### Cursor\n\nAdd to `~/.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"xurprise\": {\n      \"url\": \"https://xurprise.ai/api/mcp\"\n    }\n  }\n}\n```\n\n### Cline / Continue / Goose\n\nSame remote HTTP URL — see each client's docs for the exact config\npath. If your client only supports stdio, use `mcp-remote` as the\nbridge (see Option B above).\n\n### Raw HTTP (curl, Python, anywhere)\n\n```bash\ncurl -X POST https://xurprise.ai/api/mcp \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"id\": 1,\n    \"method\": \"tools/call\",\n    \"params\": {\n      \"name\": \"search_brands\",\n      \"arguments\": { \"query\": \"badminton\", \"region\": \"Singapore\" }\n    }\n  }'\n```\n\n---\n\n## Tools\n\n> **Note on response shape.** MCP tools/call returns an object with\n> two fields: `content[]` (text blocks containing JSON) and\n> `structuredContent` (the typed result). Per the MCP spec,\n> `structuredContent` must be a record (object), not an array —\n> so tools that logically return a list wrap it in a record with\n> a `results` / `regions` / `categories` key. All MCP-compatible\n> clients (Claude Desktop, Cursor, Cline, Continue, Goose, etc.)\n> auto-handle this; you only see it if you're decoding the raw\n> JSON-RPC response yourself.\n\n### Multilingual search\n\nThe `search_brands` tool is indexed across **9 language variants** so\nagents serving SEA users don't have to translate queries to English:\n\n- English, Simplified + Traditional Chinese\n- Malay, Indonesian, Vietnamese, Thai\n- Japanese, Korean\n\nVerified: 20 test queries in 8 languages, all resolve the same consumer\nintent to the same brand. A few examples:\n\n| query | language | top-1 match |\n|---|---|---|\n| `beauty Singapore` | EN | sephora-sg |\n| `新加坡 美妆` | ZH | sephora-sg |\n| `kecantikan Singapura` | MS | sephora-sg |\n| `mỹ phẩm Singapore` | VI | sephora-sg |\n| `เครื่องสำอาง สิงคโปร์` | TH | sephora-sg |\n| `シンガポール 化粧品` | JA | sephora-sg |\n| `싱가포르 화장품` | KO | sephora-sg |\n| `小米 手机` | ZH | xiaomi-sg |\n| `샤오미` | KO | xiaomi-sg |\n| `机票` / `航空券` / `항공권` | ZH/JA/KO | airpaz-global |\n| `希音` | ZH | shein-global |\n\nThe per-brand keyword index covers brand aliases (transliterated names\nlike `小米` / `샤오미` / `シャオミ` for Xiaomi), category synonyms\n(Fashion / 时尚 / fesyen / thời trang / แฟชั่น / ファッション / 패션),\nand region aliases (Singapore / 新加坡 / 싱가포르 / สิงคโปร์ / Singapura).\nCJK and Thai queries are tokenized with 2-char n-grams since those\nscripts have no whitespace word boundaries.\n\n### `search_brands`\n\nFree-text search over the catalogue. Results are rank-scored on the\nquery against brand name, headline, category, and the multilingual\nkeyword index above.\n\n```ts\nsearch_brands({\n  query: string,           // required — e.g. \"skincare\", \"Taobao\", \"athletic shoes\"\n  region?: string,         // optional — full country name or \"International\"\n  category?: string,       // optional — \"Fashion\", \"Electronics\", etc.\n  limit?: number,          // optional — default 10, max 50\n}) => { results: Brand[], count: number, query: string }\n```\n\n### `get_brand`\n\nFetch the full record for a slug.\n\n```ts\nget_brand({ slug: string }) => Brand\n```\n\n### `list_regions`\n\nAll shipping regions represented in the catalogue (use before\nrecommending to confirm user's country is covered).\n\n```ts\nlist_regions() => { regions: string[], count: number }\n```\n\n### `list_categories`\n\nAll categories represented in the catalogue.\n\n```ts\nlist_categories() => { categories: string[], count: number }\n```\n\n### `get_click_url`\n\nBuild the canonical click-through URL. Use this (not the merchant URL\ndirectly) so the click gets logged for attribution, and any `aff_sub`\nyou pass will be propagated downstream.\n\n```ts\nget_click_url({\n  slug: string,\n  aff_sub?: string,        // optional — up to 200 chars, recommended:\n                           // your agent's session id or similar\n}) => { click_url: string, slug: string, name: string }\n```\n\n### `wrap_product_url`\n\n**Product-level attribution.** Use when the user wants a specific item\n(a particular Sony headphone, a specific Shein dress, etc.) rather\nthan the brand's homepage. You supply any URL on a supported\nmerchant's site — xurprise wraps it into a click-through URL that\nlands the user on that exact product while preserving attribution\ntracking.\n\nThe agent is expected to discover the merchant URL itself (via its\nown web search, training knowledge, or MCP tool composition). xurprise\nis the attribution layer, not the catalogue — this lets you leverage\nwhatever product-discovery capabilities your client already has.\n\n```ts\nwrap_product_url({\n  merchant_url: string,    // required — full https URL on a supported merchant\n                           // e.g. \"https://shopee.sg/Sony-WH-1000XM5-i.12345.67890\"\n  product_name?: string,   // optional — surfaces in attribution logs\n  aff_sub?: string,        // optional — e.g. your chat session id\n}) => {\n  click_url: string,       // https://xurprise.ai/go/p?u=...  (302s to the product)\n  merchant_url: string,    // canonicalized input\n  merchant_hostname: string,\n  slug: string,            // which brand the domain maps to\n  brand: string,\n  name: string,\n}\n```\n\n**Supported merchant domains** (product-level attribution works on any\nURL within these, even deep paths):\n\n| Brand | Accepted hostname (incl. subdomains) |\n|---|---|\n| Shopee SG | `shopee.sg` |\n| Xiaomi SG | `mi.com` |\n| Sephora SG | `sephora.sg` |\n| JD Sports SG | `jdsports.com.sg` |\n| Shein | `shein.com` (any regional subdomain) |\n| Airpaz | `airpaz.com` |\n| WPS Office | `wps.com` |\n| FusionHome AI | `fusionhome.ai` |\n| The Trade Wizard | `thetradewizard.com` |\n\nTaobao is deliberately excluded from product-level wrapping — the\nupstream routing for Taobao is whitelist-locked or brand-only, so\nproduct-level attribution isn't reliable there. For Taobao, use\n`get_click_url` with the brand-level slug instead.\n\n---\n\n## Brand schema\n\nEvery brand record has:\n\n| Field | Type | Example |\n|---|---|---|\n| `slug` | string | `shopee-sg` |\n| `name` | string | `Shopee — Singapore` |\n| `brand` | string | `Shopee` |\n| `categories` | string[] | `[\"Marketplace\"]` |\n| `regions` | string[] | `[\"Singapore\"]` |\n| `currency` | string | `SGD` |\n| `merchant_url` | string | `https://shopee.sg/` |\n| `page_url` | string | `https://xurprise.ai/brands/shopee-sg/` |\n| `click_url` | string | `https://xurprise.ai/go/shopee-sg` |\n| `headline` | string | (1–3 sentence description) |\n| `agent_note` | string? | Optional region-routing or caveat guidance |\n\n---\n\n## Current catalogue\n\nAs of the latest refresh, 43 brands across region-matched surfaces:\n\n- **Marketplace** — Shopee SG, Taobao (Ai Taobao International), Taobao (brand-level), Alibaba, Banggood, AliExpress\n- **Fashion** — JD Sports SG, Shein Global, Poplook, Rip Curl SG, Juice Store, Bernardelli\n- **Health & Beauty** — Sephora SG, Kinohimitsu SG, Papique\n- **Electronics** — Xiaomi SG, XP-PEN SG, Stryv SG\n- **Travel** — Airpaz, KKday, Zen Hotels, byFood, TrainPal, Kiwi.com, EasyBook, NINJA WiFi\n- **Digital Services / Software** — WPS, The Trade Wizard, Sider AI, Wegic, iMobie, MyRepublic SG\n- **Online Courses** — Udemy, International Open Academy\n- **Gaming / Entertainment** — UniPin, GameSeal, BINGE\n- **Gifting & Crafts** — Photobook SG, FlowerAdvisor SG\n- **Home & Living** — FusionHome AI, Homestyler\n- **Automotive** — Trapo SG\n- **Deals / Aggregation** — StackSocial\n\nRegional coverage: 12 Singapore-local, 2 Malaysia / SG multi-region, 7 SEA-regional, 22 global.\nA handful of brands are exposed as **brand-level entries only** (attribution redirects\npoint at the brand homepage, not individual products) — `get_brand` surfaces the distinction\nvia the `agent_note` field when relevant.\n\nFor the live list, call `list_categories` + `search_brands` or visit\n[https://xurprise.ai/brands/](https://xurprise.ai/brands/).\n\n---\n\n## FAQ\n\n**Is the catalogue curated or crawled?**\nCurated. Every brand goes through a partner-approval flow and is\ngiven a hand-authored headline. We do not scrape.\n\n**How fresh is the data?**\nRegenerated from our internal catalogue on each deploy.\nSee `page_url` on each brand and the [sitemap lastmod](https://xurprise.ai/sitemap.xml).\n\n**Do you track my users?**\nThe `/go/{slug}` redirect logs `{timestamp, slug, user-agent,\nASN, country, referer}` — enough to distinguish crawler traffic\nfrom human traffic and to attribute clicks across sessions. We do\nNOT log raw IPs. Beyond `/go/`, we do not set cookies or run analytics\non the merchant storefront (that's Shopee/Shein/etc.'s own page).\n\n**What happens after a click?**\nA 302 redirect chain takes the user to the canonical merchant\nstorefront with attribution preserved end-to-end. Any `aff_sub` you\npass through `get_click_url` is carried through the chain.\n\n**Can I add my brand?**\nMerchant onboarding is by introduction today. Email\n<xwow.dev@gmail.com> if you run a brand in our covered regions\n(Southeast Asia + China + global-shipping) and want to discuss\ninclusion.\n\n**Who operates this?**\nXWOW Pte. Ltd. (Singapore). Contact: Jiaqi Ge,\n<xwow.dev@gmail.com>. xurprise is an independent third-party\ndiscovery layer — we don't operate any of the merchant storefronts\nlisted here.\n\n---\n\n## Protocol conformance notes\n\n- Transport: Streamable HTTP (stateless mode — no session id required)\n- JSON-RPC 2.0 single requests and batch requests are both supported\n- Notifications (no `id`) return `HTTP 202 No Content`\n- `ping` method is supported for health checks\n- CORS is wide open (`*`) — browser-based MCP clients work\n\n---\n\n## Related\n\n- **[xurprise.ai](https://xurprise.ai/)** — the human landing + per-brand schema.org pages\n- **[xurprise.ai/llms.txt](https://xurprise.ai/llms.txt)** — LLM-friendly site index\n- **[xurprise.ai/sitemap.xml](https://xurprise.ai/sitemap.xml)**\n\n---\n\n## License\n\nDocs in this repo: MIT (see `LICENSE`). The MCP server source code is\nseparate and proprietary to XWOW Pte. Ltd.\n",
  "bytes": 13125,
  "sha": "8bcf687ecb06fa027a7518ab770443de50fb8d60e0277095cd1e1ec25a197b83",
  "repo_slug": "nimo1987/xurprise-mcp-docs",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_xurprise_mcp_c70b7f1a/readme"
}