Shopify Storefront MCP 怎么建 AI 导购：搜索、购物车与结账边界

这篇文章面向要实现 AI 导购的开发者。这里的“导购”不是一个可以随意替顾客下单的机器人，而是一条有证据、有权限、有状态的调用链：先从指定 Shopify 店铺的目录中搜索，再把顾客确认过的商品放进购物车，读取与回答相关政策，最后把用户带到当前文档允许的结账交接点。Storefront MCP 连接的是特定 Shopify 店铺的 catalog、cart 和 policies；它不等于所有 AI 系统都能付款，也不等于可以绕过结账或省略消费者确认。

先定义 Storefront MCP AI 导购的真实边界

目标是受控的店铺上下文，而不是通用商品搜索

实现的第一原则是把“这个 AI 知道什么”限定在一个经过授权的店铺上下文中。用户说“找一件适合夏天的亚麻衬衫”时，搜索应落到该店铺的可用目录、价格和可选变体，而不是把模型记忆里的商品、另一个店铺的库存或未经验证的网页片段混进答案。目录结果仍然需要以店铺返回的数据为准，并在界面上把名称、价格、变体和库存状态展示给用户核对。

AI 输出可能错误，审阅是流程的一部分

Shopify 对 AI 工具的边界提示是：生成的建议或任务结果可能错误，商家需要审阅输出和拟议变更。对购物 agent 来说，审阅不只发生在商家后台，也发生在消费者操作上：展示搜索结果时让人确认商品和变体；加入购物车时让人确认数量、价格和适用政策；进入结账时不要把“模型已经说可以”当成付款授权。任何自动生成的商品解释都不能覆盖目录事实或店铺政策。

“能调用工具”不等于“能完成交易”

截至 2026-08-30，Shopify 官方 Storefront MCP server 文档列出标准 Storefront MCP endpoint 为 https://{shop}.myshopify.com/api/mcp，用于标准购物车与政策工具；UCP catalog 工具使用 https://{shop}.myshopify.com/api/ucp/mcp，工具名为 search_catalog、lookup_catalog 和 get_product。UCP catalog 请求需要在每次请求中提供 meta.ucp-agent.profile 的 agent profile；标准 Storefront MCP server 请求不要求认证。购物车工具的当前 UCP 版本也在 /api/ucp/mcp 上提供 create_cart、get_cart、update_cart 和 cancel_cart；截至该日期，旧的 /api/mcp 购物车工具处于弃用过渡期，update_cart 需要按文档的完整购物车语义处理。具体店铺是否限制访问、返回字段与结账能力，仍需在隔离环境验证。

把搜索、购物车、政策与结账拆成四段状态

第一段：搜索只返回可验证的选项集

搜索阶段输入的是用户意图，输出的是一组可以追溯到店铺目录的可选商品。代码应保存查询词、过滤条件、返回时间、商品标识、变体标识和展示给用户的价格快照。不要把模型的“适合”“热销”“一定有货”等措辞写回目录；这些词如果要展示，必须有相应的可验证字段或明确标注为推荐理由，而不是事实保证。

第二段：购物车是有状态的顾客动作

加入购物车不是一次孤立的文本生成。实现需要把购物车标识、商品变体、数量和当前店铺上下文绑定起来。每次变更前都要确认对象仍属于当前店铺和当前会话，变更后重新读取购物车状态，再向顾客呈现价格、数量和商品摘要。若购物车标识丢失、过期、属于另一店铺或商品已经不可选，agent 应停止继续推进，提示用户重新检索或重新建立购物车，而不是猜测一个新状态。

第三段：政策问答要回到当前店铺政策

退货、配送、支付、隐私或取消问题都属于政策读取与解释。AI 可以把政策内容整理成易懂的回答，但不能把缺少证据的句子补成承诺。回答应携带政策来源或至少让用户能回到店铺政策页；对“我能不能在某个地区退货”“税费是否包含”“付款是否成功”这类问题，要标出适用市场、币种、结账条件或仍待确认的字段。关于退货策略的独立治理可衔接 Shopify AI 售后与退货分流，本文只处理 agent 如何读取和交接政策。

第四段：结账是消费者确认的交接点

结账阶段要把购物车摘要、市场、语言、显示币种、配送信息和可能的税费条件交给用户复核。即便上游搜索和购物车操作都成功，也不能声称绕过结账、无需消费者确认，或所有 AI 都能直接付款。实现要以当前官方文档对可用结账能力的定义为准；如果文档或权限只允许生成交接信息，就只生成交接信息，并在 UI 中明确“请在结账页面复核并确认”。

endpoint、tool、权限与失败路径表

下表是开发前的门禁表，不是对当前协议字符串的臆测。每一项的具体值都要在接入前打开官方来源列出的 Shopify 官方页面复测，并把复测结果记录到版本化配置或测试报告。

为什么要同时写“权限”和“失败路径”

很多集成文档只写 happy path：搜索成功、加入购物车成功、然后打开结账。生产事故往往发生在另一侧：tool 名称变了、认证过期、返回的变体不是用户选的、价格在市场切换后改变，或者 agent 把“政策摘要”说成“订单承诺”。把每个权限和失败路径一起写入验收表，才能确保失败时不会继续向付款方向推进。

用已核验值驱动实现而不是猜测

截至 2026-08-30，标准 Storefront MCP endpoint 是 https://{shop}.myshopify.com/api/mcp；UCP catalog endpoint 是 https://{shop}.myshopify.com/api/ucp/mcp，目录工具为 search_catalog、lookup_catalog 和 get_product。标准 server 请求不要求认证；UCP catalog 与 UCP Cart 请求需要 meta.ucp-agent.profile。实现仍要在隔离环境核对目标店铺的资格、请求与返回 schema、权限和结账能力，不能把一个示例店铺或 profile 当成所有商家的固定配置。

最小 JSON-RPC 形状示例：只作为示意

请求形状

下面的请求以官方当前示例为基础，发送到 https://{shop}.myshopify.com/api/ucp/mcp，调用 search_catalog。代码中的店铺域名、查询词和 agent profile 仅用于隔离测试；完整响应字段仍按 UCP catalog schema 和目标店铺返回值验证。

``json { "jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": { "name": "search_catalog", "arguments": { "meta": { "ucp-agent": { "profile": "https://shopify.dev/ucp/agent-profiles/examples/2026-04-08/valid-with-capabilities.json" } }, "catalog": { "query": "blue linen shirt", "context": { "address_country": "US", "language": "en", "currency": "USD" } } } } } ``

请求目标是 https://{shop}.myshopify.com/api/ucp/mcp；search_catalog 的参数放在 catalog 对象中，agent profile 放在 meta.ucp-agent.profile。店铺域名与测试 profile 在执行时使用隔离配置，不把示例店铺当成实际商家。

结果形状与证据校验

``json { "jsonrpc": "2.0", "id": 1, "result": { "structuredContent": { "ucp": {"version": "2026-04-08"}, "products": [ {"id": "gid://shopify/Product/123", "title": "Example product"} ] } } } ``

测试器应确认返回的 UCP metadata、商品、变体、价格和分页字段都能映射到展示模型。若返回的是错误，应保留原始错误类别和 request id；不要把错误对象改写成“没有找到商品”，除非当前响应确实表达了空结果。

从搜索继续到购物车的最小状态

搜索通过后，应用内部至少要保存 store_context、目录商品标识、变体标识、用户确认时间和即将写入的数量。加入购物车成功后再保存购物车标识和读取到的摘要。每一个字段都要有来源：用户输入、目录响应、购物车响应或当前政策。模型生成的自然语言只能是呈现层，不能成为商品标识、金额或权限的唯一来源。

何时必须停止而不是自动补全

出现未知 tool、认证失败、店铺上下文不一致、商品/变体不能映射、政策适用市场不明确、结账能力未确认或消费者没有确认时，状态机必须进入 needs_review 或 blocked。自动补全一个看似合理的 endpoint、价格、政策例外或结账链接，会把可诊断的失败变成不可追责的交易风险。

用状态机实现可审阅的 shopping agent

建议的状态与允许动作

可以把流程写成以下受限状态，而不是让一个大 prompt 自由决定下一步：

DISCOVER → OPTIONS_READY → USER_CONFIRMED_ITEM → CART_SYNCED → POLICY_REVIEW → CHECKOUT_HANDOFF → CONSUMER_CONFIRMED。

DISCOVER 只能读取目录；OPTIONS_READY 只能呈现选项并等待确认；USER_CONFIRMED_ITEM 才允许准备购物车写入；CART_SYNCED 之后重新读取摘要；POLICY_REVIEW 只解释已获得的政策内容；CHECKOUT_HANDOFF 只做当前文档授权的交接；CONSUMER_CONFIRMED 不是 agent 自己推断的布尔值，必须有明确的界面动作或外部回执。任何错误都进入 NEEDS_REVIEW，而不是跳到下一状态。

把关键证据放在日志而非提示词里

日志至少应记录版本、店铺上下文的非敏感标识、工具调用类别、请求 id、失败类别、输入最小摘要、商品/变体标识、购物车状态变化和消费者确认事件。不要记录认证秘密、完整支付信息或不必要的个人资料。日志的目的是审计和回放测试，不是复制客户画像。对于隐私设计，要写明数据用途、适用的同意或权限、退出方式、保留期限、访问/删除处理和最小数据集；自动隐私设置不能代替法律意见。

人工介入不是异常，而是安全出口

当 agent 无法确定政策、商品状态、身份、付款或订单动作时，转人工并附上最小证据包：用户问题、当前店铺上下文、已展示的结果、失败类别和等待用户确认的事项。客服自动化的范围可以在 Shopify AI 客服与人工接管 单独展开；本文不把客服、退款或欺诈判断塞进 Storefront MCP 的购物流程。AI 不是退款、欺诈、合同或法律的最终裁决者。

多市场、语言、币种与结账条件要分开验收

四个看起来相似、实际不同的输入

用户所在地区不自动等于店铺当前市场；语言不自动改变域名；显示币种不自动保证支付处理；同一个商品也不自动适用同一退货政策。实现要分别读取或验证 market、locale、domain/subfolder、display currency、checkout、tax、payment processing 和 returns。不能用“国际化已开启”作为全部测试的通过条件。

结账前再做一次“显示值 vs. 事实源”对账

对账至少覆盖商品名称、变体、数量、单价、折扣（如果有来源）、显示币种、配送/税费提示、退货政策入口和市场。对账不通过时不应自动刷新成另一个商品，也不应把旧购物车强推到结账；应该让用户重新确认或使用店铺正常入口。尤其不要根据一个通用的汇率、翻译或模型记忆计算最终应付金额。

让链接和回退路径可被用户理解

如果当前文档允许生成结账交接链接，界面应告诉用户它将打开什么、哪些信息仍需填写、最终金额以何处为准以及是否需要重新登录。若没有可验证的交接能力，提供店铺购物车或正常结账入口，不要伪造一个看似官方的 URL。链接失效时保留错误记录，清除不再可靠的临时状态，再让用户重新开始。

安全、隐私与商家审阅门禁

凭据与店铺上下文最小化

服务端只为目标店铺保存完成当前动作所需的认证材料和配置。模型上下文不应包含秘密；前端日志不应输出 token、完整请求头、支付信息或不必要的客户识别信息。一个 agent 如果同时连接多个店铺，必须在每次 tool 调用前检查店铺上下文，不能因为用户上一轮浏览了 A 店铺就默认下一轮仍然是 A 店铺。

顾客数据要写清用途与生命周期

购物推荐可能不需要姓名、完整地址或历史订单。先定义用途，再判断是否需要同意或权限；提供退出方式；设定保留期限；准备访问和删除请求的处理路径；只传递最小字段。不要用“Shopify 自动隐私设置已开启”替代商家自身的隐私评估或法律意见，也不要将测试夹具中的假数据与真实客户资料混用。

商家要审阅行为和拟议变更

商家审阅清单应包括：工具是否只暴露必要动作、政策来源是否当前、价格和市场是否可见、失败是否会停止、日志是否最小化、是否有人工出口。任何自动生成的商品说明、推荐理由或政策摘要都要经过相应审阅；不能以“模型很有把握”作为正式接入依据。若 agent 进一步触及订单、退款、欺诈或合同事项，必须保留人和店铺证据在环。

可复现失败/回退演练（runbook/test fixture）

夹具说明：不是客户案例

以下是一个可复现的 runbook/test fixture，不代表任何真实客户、订单或生产事故。使用隔离的测试店铺或模拟响应，商品、价格、购物车标识、用户信息和认证材料全部为假值。测试日期记录为 last verified 2026-08-30，正式执行仍要填入实际环境、文档版本和签字人。

夹具输入与前置条件

* 目标店铺：fixture-store-10076；不能连接真实生产店铺。 * 用户查询：blue linen shirt；预置两个选项，一个有可选变体，一个在第二次读取时标记为不可用。 * 市场：fixture-market-A；语言和显示币种使用测试环境配置，不把名称当作 Shopify 官方值。 * 认证：使用短期测试凭据或模拟“过期”响应；禁止把真实 token 放入夹具。 * 文档配置：endpoint、tool 名、返回字段全部从当前官方文档复测后填入测试记录；未填则测试只能判定为阻塞。

执行步骤与预期回退

1. 在隔离环境发起搜索，验证请求包含可审计 id 和正确店铺上下文。若 endpoint 未确认、认证失败或响应不是当前文档形状，预期状态是 NEEDS_REVIEW，界面显示无法连接目录，并保留人工入口。
2. 让测试用户选择第一个选项，再执行购物车写入。模拟商品变体校验失败或购物车标识过期。预期系统不创建猜测的变体、不重复写入，不进入结账；系统清除失效的临时状态并要求重新选择。
3. 让购物车读取返回与用户选择不同的数量或币种。预期系统显示最新返回和差异，要求明确确认；不能用旧值覆盖最新值。
4. 让政策响应缺少当前市场适用范围。预期 agent 说明“适用范围待确认”，不生成退货或税费承诺，并提供政策页/人工出口。
5. 让结账交接能力未在当前文档中确认。预期流程停在购物车摘要，不产生伪造链接、不声称支付成功，并提示用户从店铺正常入口继续。

通过标准、失败信号与回退动作

通过标准是：每次阻断都有明确原因类别；没有敏感凭据进入日志；商品、变体、金额和政策没有被模型自创；没有未经消费者确认的结账推进；重新开始后不会复用失效购物车状态。失败信号包括“自动换了商品”“把权限错误说成空结果”“把示意 method 当真实 tool”“结账链接打开后无来源”“日志出现 token”或“用旧币种覆盖新返回”。发现任一信号，冻结该版本的该版本，回退到仅提供人工/店铺正常浏览入口的配置，保存脱敏证据并重新执行测试。

接入前的文档复测与运营 QA

官方文档复测清单

采用时逐项复测 Shopify 的 Storefront MCP overview、Storefront MCP server、agentic commerce 文档，并按需要复测 AI-powered tools 的审阅边界。记录访问日期、页面标题、endpoint/tool/auth 可用性、适用条件和与当前实现的差异。任何变化只影响受影响的页面和配置，不要用一篇旧文章的成功经验推断整个批次仍然有效。

结构与内容验收

正文必须保留四类独有证据：endpoint/tool/权限/失败路径表；多市场验收表；最小 JSON-RPC 形状示例；runbook/test fixture。检查正文是否明确“仅示意、需按当前文档复测”，是否明确搜索→购物车→结账/消费者确认边界，是否避免绕过结账、无需确认、所有 AI 直接付款、实时保证和 universal compatibility 等说法。结构化数据若在页面层添加，也必须与可见内容一致，不创建 AI/GEO 专用 schema。

与相邻主题保持分工

本文聚焦 Storefront MCP 的开发边界。客服自动化和人工升级见 Shopify AI 客服与人工接管；退货政策治理见 Shopify AI 售后与退货分流；与 Shopify B2B AI 销售助手 的衔接只保留为系列导航，具体范围以该页自身官方来源为准。不要把这些文章合并成一篇“AI 电商全能指南”，否则 endpoint、订单安全、政策写作和其他意图会互相稀释，也会让读者误以为一个工具拥有所有权限。

常见问题

FAQ 1：Storefront MCP 能让 AI 直接替顾客付款吗？

不能从 Storefront MCP 的目录、购物车和政策连接能力推导出直接付款能力。结账、支付和消费者确认是独立边界，具体以当前 Shopify 官方文档和目标店铺条件为准。实现应把用户带到文档允许的结账交接点，并让用户复核和确认；不要声称绕过结账、无需消费者确认或所有 AI 都能直接付款。

FAQ 2：为什么要区分两个 MCP endpoint？

标准 Storefront MCP 使用 https://{shop}.myshopify.com/api/mcp；UCP catalog 使用 https://{shop}.myshopify.com/api/ucp/mcp，并调用 search_catalog、lookup_catalog、get_product。标准 server 请求不要求认证，UCP catalog 请求要带 meta.ucp-agent.profile。购物车的当前 UCP 工具也使用 /api/ucp/mcp；按目标店铺和当前 schema 验证后再接入。

FAQ 3：搜索后可以自动加入购物车吗？

只有在用户明确确认商品、变体和数量，并且当前文档、权限和购物车状态都通过校验时，才应执行写入。搜索结果本身不是用户授权；写入成功后还要重新读取购物车，让用户核对最新数量、价格、币种和政策入口。任何映射、认证或状态失败都应停下并要求重新选择。

FAQ 4：如果政策回答和顾客看到的页面不一致，哪个优先？

以当前店铺政策页面、适用市场和实际结账信息为准，AI 摘要需要被纠正或交给人工复核。agent 不能把自己的回答当成退货、税费、支付或合同承诺，也不能为了让对话继续而补写例外。应保存脱敏失败证据并改正数据来源或提示文案。

FAQ 5：最小测试什么时候算通过？

至少要证明：官方 endpoint/tool/auth 已在当前文档复测；搜索、购物车和政策结果能映射到事实源；权限拒绝、过期购物车、市场/币种不一致和未确认结账都会停止并回退；日志无秘密；消费者确认前不会推进结账。本文的 runbook 是可执行规格，不是已执行结果；本文不把测试规格冒充真实店铺执行结果。

官方来源与核验日期

1. Shopify Storefront MCP overview — 说明 Storefront MCP 的定位与店铺上下文边界；last verified 2026-08-30。
2. Shopify Storefront MCP server — 核对标准 endpoint、工具范围、认证和可用性；last verified 2026-08-30。
3. Shopify Storefront Catalog MCP — 核对 UCP catalog endpoint、agent profile、search_catalog、lookup_catalog 和 get_product；last verified 2026-08-30。
4. Shopify Cart MCP — 核对 UCP Cart 的 create_cart、get_cart、update_cart 和 cancel_cart 及其请求边界；last verified 2026-08-30。
5. Shopify Storefront MCP cart-tool changelog — 核对旧 /api/mcp 购物车工具的弃用过渡；last verified 2026-08-30。
6. Shopify agentic commerce — 核对搜索、购物车、结账交接和消费者确认的能力边界；last verified 2026-08-30。
7. Shopify AI-powered tools — 核对 AI 输出可能错误、商家需要审阅的使用边界；last verified 2026-08-30。

这些来源支持本文的实现边界，但不构成永久协议保证。实际接入时重新核对目标店铺的 endpoint、UCP profile、工具 schema、权限、结账能力以及市场、币种、税费、支付和退货条件；不确定项只影响对应能力，不应扩散到整条购物链路。