The Agent Times UCP 网关技能

这是什么

当用户需要一个具备代理安全性的购物流程时，请使用 The Agent Times UCP 网关：发布或加载 UCP 配置文件、搜索商品、准备已确认的购物车，并生成由商户托管的结账跳转链接，全程无需网页抓取，也不涉及支付处理。

端点：https://ucpgateway.theagenttimes.com/mcp
注册中心：https://ucpgateway.theagenttimes.com/registry

适用场景

• 用户请求商品搜索、商品对比、规格查询、购物车准备或结账跳转。
• 代理需要注册或复用托管的 UCP 配置文件及 agent_id。
• 通用 MCP 客户端需从网关自身获取以发现（discovery）为前提的操作指引。

不适用场景

• 爬取商户网站，或绕过服务提供商 API。
• 收集银行卡号/CVV/银行账户/电子钱包/支付凭证、密码、支付令牌或一次性支付码。
• 声称订单已付款、已下单、已完成或已保障。
• 虚构买家个人身份信息（PII），例如姓名、邮箱、电话号码或收货地址。

快速开始

1. 向 /mcp 发起 GET 请求获取操作指南，或向 /mcp 发起 JSON-RPC 格式的 POST 请求调用 initialize 方法。
2. 调用 tools/list 获取当前可用工具名称、输入 Schema、输出 Schema 及注释说明。
3. 先调用 resources/list，再调用 resources/read 并传入 ucp://gateway/profile-registration（首次注册）或 ucp://gateway/agent-guide（完整操作指南）。
4. 先调用 prompts/list，再调用 prompts/get 并传入 ucp-profile-registration、ucp-shopping-flow 或 ucp-operator-handoff，以获取面向操作员的流程说明。
5. 完成 agent_id 的注册或加载后，通过 tools/call 调用各项购物相关工具。

协议说明

• 主协议：基于 HTTP 的 JSON-RPC 2.0 POST 请求，目标路径为 /mcp。
• SSE 支持：向 /mcp 发起带 Accept: text/event-stream 头的 GET 请求，将返回一个无状态的端点/下一步引导；后续交互仍需通过 POST 继续。
• 可流式传输的 HTTP 兼容性：/mcp 支持 GET、POST、OPTIONS、DELETE 方法，并在无状态托管模式下接受 mcp-session-id。请勿假定服务器端存在持久会话。
• 备用 POST 路由可能存在于 /messages 和 /mcp/messages。

核心工具

• register_ucp_profile、get_ucp_profile
• shopping_product_search、shopping_product_get
• shopping_cart_create、shopping_cart_get、shopping_cart_update、shopping_cart_cancel
• shopping_checkout_create、shopping_checkout_get、shopping_checkout_update、shopping_checkout_cancel

请始终通过 tools/list 查询参数 Schema，不要依赖记忆中的参数结构。

配置文件注册说明

• 生成或复用本地 ECDSA P-256 密钥对。private_key.jwk 必须严格保留在本地，切勿将私钥材料传递给 MCP。
• 调用 register_ucp_profile，传入 agent_name、public_key_jwk，以及可选字段：namespace、description、公开的 metadata，并指定 skill_name: "ucp-gateway-skill"。
• 网关将创建标准 UCP 配置文件、默认购物能力、空的 payment_handlers: {}、公开的 signing_keys、元数据、agent_id 及 profile_url。
• 请将返回的 agent_id、namespace、profile_url、registry_url 以及生成的 profile_json 保存至 ./.ucpgateway/agent.json 或等效的本地状态存储中。
• 若有意使用遗留 profile_json，则必须精确指定如下能力键名：dev.ucp.shopping.catalog.search、dev.ucp.shopping.catalog.lookup、dev.ucp.shopping.catalog、dev.ucp.shopping.cart、dev.ucp.shopping.checkout。

购物流程

1. 注册配置文件，或加载已有 agent_id。
2. 使用 shopping_product_search 搜索商品。
3. 如需进一步了解，调用 shopping_product_get 获取商品/规格详情。
4. 向买家展示服务商返回的商品选项、价格与库存状态。
5. 请买家选择具体商品/规格及数量。
6. 在执行 shopping_cart_create 或 shopping_cart_update 前，明确请求买家确认。
7. 向买家展示购物车摘要、总计金额及提示信息。
8. 仅向买家本人收集结账所需信息：名、姓、邮箱、收货街道地址、城市、州/地区、邮政编码、ISO-2 国家代码、可选电话号码。
9. 在发起结账前，再次请求最终确认。
10. 调用 shopping_checkout_create，并设置 operator_confirmed: true。
11. 将返回的 continue_url 交由买家跳转；支付环节完全由商户托管。

安全流程

• 商品搜索与详情查询均为只读操作。
• 执行购物车创建/更新/取消前，必须获得显式确认。
• 展示购物车总计、提示与警告信息，并在结账前再次请求最终确认。
• 仅在完成上述最终确认后，才可设置 operator_confirmed: true。
• 将返回的 continue_url 交由买家跳转；买家仅在商户网站上完成支付。

响应处理与 next_step

每次调用 tools/call 后，请读取 result.structuredContent.next_step：

• summary：简明推荐的下一步操作。
• recommended_tools：可能适用于下一步的工具名称列表。
• actions：非强制性提示；其中 arguments_hint 不代表授权许可。
• warnings：注意事项、安全提醒或跳转操作说明。

常见错误恢复方式：

• AGENT_ID_REQUIRED / AGENT_NOT_REGISTERED：请注册或加载有效的 agent_id。
• INVALID_UCP_PROFILE：尽可能使用默认 public_key_jwk 路径；若使用高级 profile_json，请将简写能力名（如 shopping）替换为实际支持的完整能力键名。
• INVALID_PUBLIC_KEY：仅提交符合 EC P-256 标准的 public_key_jwk；请确保 ./.ucpgateway/private_key.jwk 严格保留在本地。
• INVALID_TOOL_ARGUMENTS：依据 tools/list 返回的 Schema 修正参数。
• RATE_LIMITED：等待 retry_after_seconds 后重试；仅对同一已确认变更操作重试时，方可复用相同的 client_action_id。
• BUYER_INFO_REQUIRED：仅从买家处收集结账所需字段；严禁虚构任何 PII。
• OPERATOR_CONFIRMATION_REQUIRED：展示购物车摘要并请求确认，然后重试并设置 operator_confirmed: true。
• 支付数据被拒：请移除所有支付相关字段；买家仅在商户结账页完成支付。

每个网关响应（含错误响应）均包含 next_step 指引。对于工具调用，请读取 result.structuredContent.next_step 和/或 result.next_step。所有参数提示仅为建议，绝不可视作买家授权依据。