Shopify Catalog MCP 中文指南：迁移前先分清全局目录与单店目录

如果你的团队正在维护 Shopify 商品搜索、比价工具或购物智能体，Shopify Catalog MCP 现在首先是一个迁移和边界问题，不是一个“接上就会自动卖货”的开关。

Shopify 已经公告，Global Catalog REST API 会在 2026 年 11 月 2 日停止服务。受影响的是仍然调用 https://discover.shopifyapps.com/global/... 的应用。普通商家是否需要动作，取决于自己的应用或供应商是否真的使用了这些旧路径，而不是取决于商店是否听说过 MCP。

本文是一份面向中文 Shopify 团队的来源审阅指南。它不代表 KumoCart 做过接口实测，也不提供速度、覆盖率、推荐排名、转化或收入结果。先确认范围，再安排迁移。

先回答：你用的是哪一类 Catalog

Shopify 把商品发现分成两个目录接口。选择错误的范围，会让产品文案、日志和买家预期一起出错。

接口	商品范围	适合的工作	典型承诺
Global Catalog	所有 Shopify 商家	跨商家搜索、比较和发现	“从多个商家中寻找匹配商品”
Storefront Catalog	单个商店	某个品牌自己的导购或站内智能体	“在这个商店里寻找商品”

Shopify 的 Catalog 文档{rel=“nofollow noopener noreferrer”}列出了两者的端点和范围。Global Catalog 使用 https://catalog.shopify.com/api/ucp/mcp，Storefront Catalog 使用 https://{storeDomain}/api/ucp/mcp。两者都暴露 search_catalog、lookup_catalog 和 get_product，但相同的工具名称不代表相同的搜索范围。

因此，第一步不是安装插件，而是查请求记录、代码、环境变量和供应商文档：系统是否出现过 discover.shopifyapps.com/global/？如果没有，不要因为关键词相似就把 Admin API、Storefront API 或单店 Catalog 接入强行套进这次迁移。

2026 年 11 月 2 日前要映射什么

Shopify 的开发者更新{rel=“nofollow noopener noreferrer”}给出了旧接口到 UCP 工具的对应关系。旧接口停止服务后，相关请求会失败，保存的目录路径也在范围内。

旧 Global Catalog REST 调用	新的 UCP Catalog 工具	迁移时要确认的输入
GET /global/v2/search	search_catalog	查询词、筛选器、分页和买家上下文
GET /global/v2/p/{upid}	get_product	使用 gid://shopify/p/{upid}
GET /global/v2/p/by-variant/{vid}	get_product	使用 gid://shopify/ProductVariant/{id}
POST /global/v2/lookup	lookup_catalog	批量商品或变体标识符，每次最多 50 个

新请求发往 https://catalog.shopify.com/api/ucp/mcp。每次请求还要带上 meta.ucp-agent.profile，保存的目录要把 ID 放进 catalog.catalog_id，而不是继续依赖旧的保存目录 URL。Shopify 说明，Dev Dashboard 生成 bearer token 的方式不变，但请求和响应要迁移到 UCP Catalog 的新结构。

这也是为什么“换 URL”不够。独立分析 Shopify Catalog：verify the integration before 2 November{rel=“nofollow noopener noreferrer”}建议先找出真实请求路径，再在独立环境中核对每条路径的响应契约。该页面明确说明自己是基于已标注来源的编辑分析，不等于独立验证，因此这里只把它作为工作流交叉检查，截止日期和接口映射仍以 Shopify 官方更新为准。

用两个阶段理解 Global Catalog

Global Catalog MCP 文档{rel=“nofollow noopener noreferrer”}把商品发现拆成两个阶段：先发现，再评估。

1. 发现候选商品

用 search_catalog 或 lookup_catalog 找到候选商品。搜索结果可能来自多个商家，并按 Universal Product ID 聚合。此时得到的是候选集合，不是已经确认可以购买的最终变体。

2. 评估具体商品和变体

再用 get_product 检查商品或变体的可选项、可用性、价格以及卖家结账链接。买家说“黑色、中号、寄到某地”时，系统必须把这些条件留在上下文中，而不是把第一次搜索结果直接当成结账事实。

一个适合小团队的记录表至少应包含：

记录	保存什么	人工要问什么
请求范围	Global 还是 Storefront，端点和 profile URL	这次回答是否真的覆盖了产品声称的范围？
候选结果	查询词、筛选器、UPID、商家和时间	是否把跨商家的候选说成了一个品牌的商品？
变体评估	商品 ID、变体 ID、选项、可用性和价格	变体是否与买家的尺寸、地区和兼容性要求一致？
交接信息	卖家、结账链接、未确认条件	人是否在付款或承诺前看过最终信息？

一份可回放的迁移检查清单

下面是操作模型，不是 KumoCart 已完成的测试。它的目的，是让团队能发现“请求成功但含义变了”的情况。

第一步：盘点真实调用

搜索代码仓库、日志、任务队列和供应商文档，列出旧的四类调用。给每条调用标记负责人、环境、用途和下游页面。若只找到单店端点或其他 Shopify API，把它从这次 Global Catalog 迁移范围中移出，并保留理由。

第二步：建立最小回放样例

至少准备这些输入：

• 一个自然语言商品查询，包含买家地区和可售条件。
• 一个已知商品标识符和一个已知变体标识符。
• 一个批量查询，包含有效、无效和已下架的标识符。
• 一个没有结果的查询，以及一个筛选器过严的查询。
• 一个保存目录 ID，如果系统确实使用保存目录。
• 一个需要在 get_product 阶段选择颜色、尺寸或其他选项的场景。

每个样例都要保存请求范围、profile、原始响应、解析后的字段、错误、时间和复核人。不要为了让商品卡完整而补写缺失的价格、库存、选项或配送事实。

第三步：验证契约，不只验证 HTTP 状态

回归检查应覆盖：

1. 旧调用是否映射到正确的工具，而不是仅仅返回 200。
2. UPID、商品 ID 和变体 ID 是否被转换成正确的 gid 形式。
3. catalog.catalog_id 是否能代替旧的保存目录路径。
4. meta.ucp-agent.profile 是否在每个请求中存在且指向可维护的 profile。
5. 分页、空结果、无效 ID、变体可用性和买家上下文是否仍被正确解释。
6. 下游页面是否仍然把 Global 结果、单店结果和卖家结账链接分开显示。

Shopify 的 认证和速率限制文档{rel=“nofollow noopener noreferrer”}还说明，不同的识别层级会影响能力和速率限制。把测试脚本升级成高频抓取器，或把结账请求当成普通搜索请求反复调用，都不是安全的默认值。先确定请求目的，再申请所需的最小能力。

第四步：设置人工交接门

在进入生产环境前，让负责人逐项确认：

• 端点确实属于目标目录范围。
• 请求中使用了正确的 profile、认证方式和目录 ID。
• 变体、价格、可用性和卖家信息有明确来源。
• 空结果和冲突数据会停止或转人工，而不是由模型猜测。
• 结账链接对应正确商家，买家能看到最终价格、配送和政策。
• 回滚方式、日志保留和异常负责人已经写入运行手册。

价格、库存、退款、取消、付款、商品下架和客户承诺都不应因为“测试 Catalog MCP”而获得额外的模型写权限。Catalog 发现是读取商品事实，不能自动升级为允许智能体改变商店状态。

开源仓库可以帮什么，不能证明什么

如果团队需要命令行方式试用 UCP 路径，可以查看 Shopify AI Toolkit{rel=“nofollow noopener noreferrer”}。在 2026 年 10 月 27 日检查时，仓库显示 MIT 许可证，最新发布版本为 v2.2.0。README 将它描述为面向 CLI 和 IDE 的智能体插件与扩展，同时写明 pull request 会自动关闭。它可以帮助开发者接触工具，但不能替代 Shopify 当前文档、契约回放和权限审查。

Universal Commerce Protocol 仓库{rel=“nofollow noopener noreferrer”}显示 Apache-2.0 许可证，并把 UCP 描述为开放标准。仓库也在持续演进，所以接入前要锁定并复核使用的规范版本、工具 schema 和兼容性。星标数、仓库活跃度或一个命令能否运行，都不能证明你的商品目录已经正确迁移。

什么时候应该停止

出现下面任一情况，先保留在草稿或测试环境：

• 找不到旧请求的真实调用位置，只能根据关键词猜测系统受影响。
• 把 Global Catalog 的跨商家结果展示成单个品牌的库存或推荐。
• 商品 ID、变体 ID、保存目录 ID 或 profile 没有可追溯来源。
• 新响应缺少字段，团队打算用模型生成值来填充商品事实。
• 空结果、地区限制、不可售变体或商家冲突没有停止和升级规则。
• 迁移测试要求开放改价、改库存、退款、取消或付款权限。
• 团队把一次接口成功、一个教程视频或一次社区讨论当成兼容性或商家结果证明。

给中文 Shopify 团队的最小交付物

一次合格的 Catalog MCP 迁移，不应只交付一个新端点。至少留下四份可复核记录：

1. 受影响旧请求及负责人清单。
2. Global 与 Storefront 范围选择及其产品文案。
3. 输入、原始响应、解析字段和失败路径组成的回放样例。
4. 人工确认、回滚、日志和权限边界组成的上线记录。

如果清单证明系统根本没有调用 Global Catalog REST API，最好的结果可能是一次有证据的“不迁移”。如果系统确实受影响，先把范围、工具、标识符和响应契约核对清楚，再谈自动化。MCP 提供的是可调用的商品发现能力，安全的 Shopify 运营仍然需要清楚的边界和人在关键动作前的确认。