coupang-product-search

Coupang Product Search

此 Skill 的作用

基于 retention-corp/coupang_partners 仓库的本地 Coupang MCP 兼容层，运行 Coupang 商品查询工具。本 Skill 不再使用旧版维护在 HF Space 上的 MCP Endpoint，而是直接调用该仓库 bin/coupang_mcp.py 提供的 local://coupang-mcp 协议契约。

• 关键词商品搜索
• 火箭配送（Rocket Delivery）专属筛选搜索
• 价格区间搜索
• 生成商品对比表
• 各品类热销榜单商品
• Goldbox 每日限时特惠
• 热门搜索词 / 季节限定商品推荐

工作原理

Claude Code / Codex
  → coupang-product-search/scripts/coupang_partners_mcp.py
    → git clone/update retention-corp/coupang_partners (user cache)
      → python3 bin/coupang_mcp.py
        → local://coupang-mcp compatible tool layer
          ├─ Coupang Partners API client (operator keys present)
          └─ hosted fallback → https://a.retn.kr/v1/public/assist (no keys)

硬性规则：

• COUPANG_MCP_ENDPOINT 仅作为兼容性开关保留，默认值为 local://coupang-mcp。
• 切勿使用旧版 HF Space 托管的 MCP Endpoint，也不要凭空捏造新的 Endpoint。
• 上游仓库仅限使用 https://github.com/retention-corp/coupang_partners.git。
• 优先运行 tools 和 init 以验证本地 MCP 契约。

执行路径

retention-corp/coupang_partners 在单个 CLI 底层会自动选择两条路径之一。封装脚本（coupang_partners_mcp.py）会对这两条路径原样透传。

1. 运营者（本地 HMAC）路径 — 当同时配置了 COUPANG_ACCESS_KEY 和 COUPANG_SECRET_KEY 时启用。上游会通过 HMAC 签名直接调用 Coupang Partners API。切记绝不能在回答、文档或提交中泄露 API Key / Secret。
2. 无凭证托管降级路径（Credentialless hosted fallback path） — 缺少上述任意 Key 时（或设置了 OPENCLAW_SHOPPING_FORCE_HOSTED=1）。上游会自动降级回退到 Retention Corp 的托管后端（https://a.retn.kr/v1/public/assist）。该路径受到 X-OpenClaw-Client-Id 白名单限制，上游默认发送的 openclaw-skill 值即为目前已注册在 Retention Corp 白名单中的值。k-skill 封装层无需另行配置 OPENCLAW_SHOPPING_CLIENT_ID，直接沿用上游默认值即可。

无论走哪条路径，返回的 JSON 外壳格式（包含 ok/data.session_id/data.tool/data.payload/data.result）完全一致，因此回答逻辑无需区分具体路径。短链（short deeplink）在托管降级路径下呈现为 https://a.retn.kr/s/...，而在运营者路径下则呈现为 https://link.coupang.com/...。

相关环境变量

环境变量	作用	默认值
COUPANG_ACCESS_KEY, COUPANG_SECRET_KEY	运营者 Coupang Partners API 凭证。只有两者均存在时才会激活本地 HMAC 路径。	无（缺失时自动降级到托管路径）
OPENCLAW_SHOPPING_CLIENT_ID	托管降级路径要发送的 X-OpenClaw-Client-Id。上游默认携带 openclaw-skill，该值已登记在 Retention Corp 白名单中。建议 k-skill 封装层不要覆盖此变量。	openclaw-skill
OPENCLAW_SHOPPING_FORCE_HOSTED	设为 1 时，即使存在 Key 也会强制使用托管路径。	留空
OPENCLAW_SHOPPING_BASE_URL	覆盖托管后端 Base URL。用于 Staging 环境或本地后端测试。	https://a.retn.kr

MCP Endpoint / 契约

local://coupang-mcp

协议兼容版本：MCP 2025-03-26。并非通过网络连接的 Streamable HTTP 服务器，而是上游仓库的本地 MCP 兼容 CLI 返回相同工具名称与 JSON-RPC 格式的 payload。

适用场景

• “帮我在 Coupang 上查一下矿泉水价格”
• “帮我找找火箭配送的 AirPods”
• “推荐一款 200,000 韩元以内的键盘”
• “对比一下 iPad 和 Galaxy Tab”
• “今天 Coupang 有什么限时特惠？”
• “看看数码家电类的热销榜”

不适用场景

• 需要登录、购物车、自动下单结算的场景
• 需要访问 Coupang 账号 / Session 的场景
• 需要 100% 保证实时库存 / 缺货状态的场景（托管降级路径和 Partners API 都可能存在缓存或延迟）

工作流

1. 确认需求

如果搜索词过于宽泛，先引导用户收敛需求意图。

• 推荐提问：请问您优先考虑什么用途/预算/品牌/容量？

2. 初始化并检查工具契约

封装脚本默认会将上游仓库 clone 至 ~/.cache/k-skill/coupang_partners。若已存在克隆副本则直接使用，仅在需要更新时添加 --update 参数。

python3 coupang-product-search/scripts/coupang_partners_mcp.py tools
python3 coupang-product-search/scripts/coupang_partners_mcp.py init

如果要指定已有检出目录，或在 CI/验证环境中禁止网络 clone：

python3 coupang-product-search/scripts/coupang_partners_mcp.py \
  --repo-dir /path/to/coupang_partners \
  --no-clone \
  tools
python3 coupang-product-search/scripts/coupang_partners_mcp.py \
  --repo-dir /path/to/coupang_partners \
  --no-clone \
  init

3. 调用工具

根据用户的具体需求调用上游 CLI 命令。结果会以包含 ok、data.tool、data.payload 和 data.result 的 JSON 格式返回。

# 普通搜索（无密钥亦可通过托管降级路径正常工作）
python3 coupang-product-search/scripts/coupang_partners_mcp.py search "32인치 4K 모니터"

# 火箭配送筛选
python3 coupang-product-search/scripts/coupang_partners_mcp.py rocket "에어팟"

# 价格区间搜索
python3 coupang-product-search/scripts/coupang_partners_mcp.py budget "키보드" --max-price 100000

# 对比
python3 coupang-product-search/scripts/coupang_partners_mcp.py compare "아이패드 vs 갤럭시탭"

# Goldbox 特惠（需要上游运营者密钥的路径）
python3 coupang-product-search/scripts/coupang_partners_mcp.py goldbox

4. （可选）强制使用托管降级路径

即使在配置了运营者 Key 的情况下，如果想测试托管降级路径，只需添加 OPENCLAW_SHOPPING_FORCE_HOSTED=1 即可。由于上游默认发送的 OPENCLAW_SHOPPING_CLIENT_ID 值 openclaw-skill 目前已登记在 Retention Corp 白名单中，因此无需额外配置。

export OPENCLAW_SHOPPING_FORCE_HOSTED=1
python3 coupang-product-search/scripts/coupang_partners_mcp.py search "에어팟"

可用工具

工具名	CLI 命令	功能	参数示例
search_coupang_products	search	普通商品搜索	"생수"
search_coupang_rocket	rocket	仅筛选火箭配送	"에어팟"
search_coupang_budget	budget	价格区间搜索	"키보드" --max-price 100000
compare_coupang_products	compare	生成商品对比表	"아이패드 vs 갤럭시탭"
get_coupang_recommendations	recommendations	热门搜索词推荐	--category 전자제품
get_coupang_seasonal	seasonal	季节/场景推荐	"설날 선물"
get_coupang_best_products	best	各品类热销榜单	--category-id 1016
get_coupang_goldbox	goldbox	当日限时特惠信息	--limit 10

注意：get_coupang_goldbox 与 get_coupang_best_products 属于上游需要 Coupang Partners API 权限的路径，在缺少 Key 的环境下可能会执行失败。遇到此情况时，请原样透传错误信息，并建议用户改用托管降级路径支持的 search/rocket/budget/compare 命令。

响应格式

上游 CLI 会输出 JSON。请读取 data.result 中的商品数组或具体工具对象，并在回答中区分火箭配送（rocket）与普通配送（normal）。

{
  "ok": true,
  "data": {
    "session_id": "session-...",
    "tool": "search_coupang_products",
    "payload": {
      "jsonrpc": "2.0",
      "result": {
        "content": [
          {"type": "text", "text": "[...]"}
        ]
      }
    },
    "result": []
  }
}

向用户展示时，按照如下格式精简整理：

## rocket (热门推荐)

1) LG 4K UHD 显示器
   价格: 397,750 韩元 (仅供参考)
   直达链接: https://a.retn.kr/s/...          # 托管降级短链
   或:     https://link.coupang.com/a/...     # 运营者 HMAC 路径深度链接

## normal (热门推荐)

1) 三星 QHD 玄龙骑士 G5 电竞显示器
   价格: 283,000 韩元 (仅供参考)
   直达链接: https://a.retn.kr/s/...

回答规范

• 若候选商品较多，仅挑选前 3~5 个进行精简对比。
• 明确区分火箭配送与普通配送。
• 提醒用户价格、缺货状态及配送信息可能会实时变动。
• 若因上游检出、权限或 Coupang Partners 环境变量等问题导致失败，需简要说明失败原因并提供重试或配置建议。
• 佣金/返利声明（必选）：回答中包含的短链（https://a.retn.kr/s/...）和 Coupang 直接深度链接（link.coupang.com/...?lptag=AF...）会通过 Retention Corp 的 Coupang Partners（联盟营销）渠道进行追踪。若上游返回了 disclosure 声明字符串（如 "파트너스 활동을 통해 일정액의 수수료를 제공받을 수 있음"），请直接原样展示；若未返回，则需在回答末尾附上相同含义的声明（例如：“通过 Partners 推广链接购买，可能会产生一定比例的佣金收益”）。

验收标准

• 已通过运行 tools、init 或实际命令验证 retention-corp/coupang_partners 的本地 MCP 契约。
• 搜索结果已按火箭配送/普通配送分类整理完毕。
• 已根据用户需求给出 TOP 3 推荐商品。
• 已包含价格/配送信息及信息可能变动的提示。
• 已在回答中包含佣金/返利声明（disclosure）。