xurprise

xurprise MCP

为 Agent 打造的电商体验 · xurprise。 一个 HTTPS 端点。六个工具。零配置。支持多语言。

此 GIF 录制自真实页面，并非模型图。 访问 xurprise.ai/demo，观看它在浏览器中实时渲染。演示使用官方 @openuidev/react-lang <Renderer> 渲染自定义 BrandCard 组件，内容由手动编写的 openui-lang 片段驱动，这些片段封装了 xurprise.ai/api/mcp 返回的确切 JSON。因此，你看到的内容，就是任何基于 OpenUI 的聊天客户端调用我们的 MCP 时所获得的内容。

xurprise MCP 服务让任何兼容 MCP 的 Agent （Claude、Cursor、Cline、Continue、Goose 等）都能发现商家 品牌，并获取带有归因跟踪的点击跳转链接。其精选目录涵盖 Taobao、Shopee、Shein、Xiaomi、Sephora、JD Sports、 Airpaz、WPS、FusionHome AI 等品牌，且内置地区匹配功能， 因此 Agent 不会向德国用户推荐仅限新加坡的商家。

托管端点： https://xurprise.ai/api/mcp

协议： Model Context Protocol (MCP) 2024-11-05，通过 Streamable HTTP 传输。 无状态，无需身份验证，也无需 SDK。

---

为什么

Agent 时代的电商面临冷启动问题：当 Agent 想要推荐一家真实商家时，通常会：

1. 搜索公开网络，根据 SEO 排名选择结果，并 希望商家能配送到用户所在国家／地区。
2. 或者硬编码几个知名品牌，却忽略地区适配性。

对于我们覆盖的细分领域，xurprise MCP 通过向 Agent 提供 机器可读、感知地区的品牌目录来解决这一问题——只需一次调用， 即可获取用户实际能够购买的商家结构化列表，其中包含规范的店铺 URL 和点击跳转 URL。后者会为我们记录归因，并传递 Agent 提供的任何 aff_sub 标签。

---

快速开始

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）。

选项 A — 原生远程 HTTP（Claude Desktop ≥ 2025 年初）：

{
  "mcpServers": {
    "xurprise": {
      "type": "http",
      "url": "https://xurprise.ai/api/mcp"
    }
  }
}

选项 B — 通过 mcp-remote 桥接（适用于任何版本的 Claude Desktop）：

{
  "mcpServers": {
    "xurprise": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://xurprise.ai/api/mcp"]
    }
  }
}

重启 Claude Desktop，打开新对话，然后输入类似这样的内容：

我在新加坡。有什么值得在线购买的美妆品牌吗？

Claude 将调用 search_brands(query="beauty", region="Singapore")， 并展示 Sephora SG 及其点击跳转 URL。

Cursor

添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "xurprise": {
      "url": "https://xurprise.ai/api/mcp"
    }
  }
}

Cline / Continue / Goose

远程 HTTP URL 相同——具体配置路径请参阅各客户端的文档。 如果客户端仅支持 stdio，请使用 mcp-remote 进行桥接 （参见上面的选项 B）。

原始 HTTP（curl、Python、任意环境）

curl -X POST https://xurprise.ai/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_brands",
      "arguments": { "query": "badminton", "region": "Singapore" }
    }
  }'

---

工具

关于响应格式的说明。 MCP tools/call 会返回一个包含 两个字段的对象：content[]（包含 JSON 的文本块）和 structuredContent（类型化结果）。根据 MCP 规范， structuredContent 必须是记录（对象），而不是数组—— 因此，逻辑上返回列表的工具会将列表封装在记录中，并使用 results／regions／categories 键。所有兼容 MCP 的 客户端（Claude Desktop、Cursor、Cline、Continue、Goose 等） 都会自动处理；只有在自行解析原始 JSON-RPC 响应时，才会看到这一点。

多语言搜索

search_brands 工具已建立 9 种语言变体的索引，因此服务东南亚用户的 Agent 无需将查询翻译成英语：

• 英语、简体中文和繁体中文
• 马来语、印度尼西亚语、越南语、泰语
• 日语、韩语

已验证：使用 8 种语言进行的 20 条测试查询，均将相同的消费意图匹配到同一品牌。以下是一些示例：

查询	语言	排名第 1 的匹配结果
beauty Singapore	EN	sephora-sg
新加坡 美妆	ZH	sephora-sg
kecantikan Singapura	MS	sephora-sg
mỹ phẩm Singapore	VI	sephora-sg
เครื่องสำอาง สิงคโปร์	TH	sephora-sg
シンガポール 化粧品	JA	sephora-sg
싱가포르 화장품	KO	sephora-sg
小米 手机	ZH	xiaomi-sg
샤오미	KO	xiaomi-sg
机票 / 航空券 / 항공권	ZH/JA/KO	airpaz-global
希音	ZH	shein-global

每个品牌的关键词索引涵盖品牌别名（小米的音译名称，如 小米 / 샤오미 / シャオミ）、类别同义词（Fashion / 时尚 / fesyen / thời trang / แฟชั่น / ファッション / 패션）以及地区别名（Singapore / 新加坡 / 싱가포르 / สิงคโปร์ / Singapura）。由于中日韩文字和泰文没有空格作为词语分隔符，因此会将相关查询切分为 2 字符的 n 元词组。

search_brands

在目录中进行自由文本搜索。结果会根据查询与品牌名称、简介、类别以及上述多语言关键词索引的匹配情况进行排名评分。

search_brands({
  query: string,           // required — e.g. "skincare", "Taobao", "athletic shoes"
  region?: string,         // optional — full country name or "International"
  category?: string,       // optional — "Fashion", "Electronics", etc.
  limit?: number,          // optional — default 10, max 50
}) => { results: Brand[], count: number, query: string }

get_brand

获取指定 slug 的完整记录。

get_brand({ slug: string }) => Brand

list_regions

列出目录中涵盖的所有配送地区（在推荐前使用此工具，确认用户所在国家/地区在覆盖范围内）。

list_regions() => { regions: string[], count: number }

list_categories

列出目录中涵盖的所有类别。

list_categories() => { categories: string[], count: number }

get_click_url

生成规范的点击跳转 URL。请使用此 URL（不要直接使用商家 URL），这样点击才会记录归因信息，并且你传入的任何 aff_sub 都会传递到下游。

get_click_url({
  slug: string,
  aff_sub?: string,        // optional — up to 200 chars, recommended:
                           // your agent's session id or similar
}) => { click_url: string, slug: string, name: string }

wrap_product_url

商品级归因。 当用户想要某件具体商品时使用（例如某款 Sony 耳机、某条 Shein 连衣裙），而不是品牌主页。你提供支持的商家网站上的任意 URL，xurprise 会将其包装成点击跳转 URL，使用户直接进入该商品页面，同时保留归因跟踪。

Agent 需要自行发现商家 URL（通过自身的网页搜索、训练知识或 MCP 工具组合）。xurprise 是归因层，而不是商品目录——这让你可以利用客户端已有的任意商品发现能力。

wrap_product_url({
  merchant_url: string,    // required — full https URL on a supported merchant
                           // e.g. "https://shopee.sg/Sony-WH-1000XM5-i.12345.67890"
  product_name?: string,   // optional — surfaces in attribution logs
  aff_sub?: string,        // optional — e.g. your chat session id
}) => {
  click_url: string,       // https://xurprise.ai/go/p?u=...  (302s to the product)
  merchant_url: string,    // canonicalized input
  merchant_hostname: string,
  slug: string,            // which brand the domain maps to
  brand: string,
  name: string,
}

支持的商家域名（商品级归因适用于这些域名下的任意 URL，包括深层路径）：

品牌	可接受的主机名（含子域名）
Shopee SG	shopee.sg
Xiaomi SG	mi.com
Sephora SG	sephora.sg
JD Sports SG	jdsports.com.sg
Shein	shein.com（任意地区子域名）
Airpaz	airpaz.com
WPS Office	wps.com
FusionHome AI	fusionhome.ai
The Trade Wizard	thetradewizard.com

Taobao 有意不纳入商品级包装——Taobao 的上游路由受白名单锁定，或仅支持品牌级，因此无法可靠地进行商品级归因。对于 Taobao，请使用品牌级 slug 调用 get_click_url。

---

品牌架构

每条品牌记录包含：

字段	类型	示例
slug	string	shopee-sg
name	string	Shopee — Singapore
brand	string	Shopee
categories	string[]	["Marketplace"]
regions	string[]	["Singapore"]
currency	string	SGD
merchant_url	string	https://shopee.sg/
page_url	string	https://xurprise.ai/brands/shopee-sg/
click_url	string	https://xurprise.ai/go/shopee-sg
headline	string	（1–3 句描述）
agent_note	string?	可选的地区路由或注意事项说明

---

当前目录

截至最近一次更新，按区域匹配的渠道涵盖 43 个品牌：

• Marketplace — Shopee SG、Taobao (Ai Taobao International)、Taobao（品牌级）、Alibaba、Banggood、AliExpress
• 时尚 — JD Sports SG、Shein Global、Poplook、Rip Curl SG、Juice Store、Bernardelli
• 健康与美容 — Sephora SG、Kinohimitsu SG、Papique
• 电子产品 — Xiaomi SG、XP-PEN SG、Stryv SG
• 旅行 — Airpaz、KKday、Zen Hotels、byFood、TrainPal、Kiwi.com、EasyBook、NINJA WiFi
• 数字服务 / 软件 — WPS、The Trade Wizard、Sider AI、Wegic、iMobie、MyRepublic SG
• 在线课程 — Udemy、International Open Academy
• 游戏 / 娱乐 — UniPin、GameSeal、BINGE
• 礼品与手工艺品 — Photobook SG、FlowerAdvisor SG
• 家居与生活 — FusionHome AI、Homestyler
• 汽车 — Trapo SG
• 优惠 / 聚合 — StackSocial

区域覆盖：12 个新加坡本地品牌、2 个马来西亚 / 新加坡多区域品牌、7 个东南亚区域品牌、22 个全球品牌。 少数品牌仅以品牌级条目形式提供（归因重定向会跳转到品牌首页，而非具体商品）——在适用时，get_brand 会通过 agent_note 字段标明这一点。

如需查看实时列表，请调用 list_categories + search_brands，或访问 https://xurprise.ai/brands/。

---

常见问题

目录内容经过筛选还是抓取而来？ 经过筛选。每个品牌都需经过合作伙伴审批流程，并配有人工撰写的标题。我们不会抓取数据。

数据有多新？ 每次部署时都会根据我们的内部目录重新生成。 请查看各品牌的 page_url 和 站点地图的 lastmod。

你们会追踪我的用户吗？ /go/{slug} 重定向会记录 {timestamp, slug, user-agent, ASN, country, referer}——足以区分爬虫流量和真人流量，并跨会话归因点击。我们 不会记录原始 IP。除 /go/ 外，我们不会在商家店面设置 Cookie 或运行分析工具（那是 Shopee/Shein 等平台自己的页面）。

点击后会发生什么？ 302 重定向链会将用户带到商家的规范店面，并在整个过程中保留归因信息。你通过 get_click_url 传入的任何 aff_sub 都会沿着重定向链传递。

可以添加我的品牌吗？ 目前商家入驻需经引荐。如果你经营的品牌位于我们的覆盖区域（东南亚 + 中国 + 全球配送），并希望讨论收录事宜，请发送邮件至 [email protected]。

由谁运营？ XWOW Pte. Ltd.（新加坡）。联系人：Jiaqi Ge， [email protected]。xurprise 是独立的第三方发现层——我们不运营此处列出的任何商家店面。

---

协议符合性说明

• 传输方式：Streamable HTTP（无状态模式——无需会话 ID）
• 支持 JSON-RPC 2.0 单请求和批量请求
• 通知（无 id）返回 HTTP 202 No Content
• 支持 ping 方法以进行健康检查
• CORS 完全开放（*）——基于浏览器的 MCP 客户端可以使用

---

相关链接

• xurprise.ai — 面向用户的落地页 + 各品牌的 schema.org 页面
• xurprise.ai/llms.txt — 便于大模型读取的站点索引
• xurprise.ai/sitemap.xml

---

许可证

本仓库中的文档：MIT（参见 LICENSE）。MCP 服务源代码独立存在，归 XWOW Pte. Ltd. 所有且为专有代码。