coupang-product-search

Coupang Product Search

What this skill does

使用 retention-corp/coupang_partners 儲存庫的本機 Coupang MCP 相容層來執行 Coupang 商品查詢工具。此 Skill 會呼叫該儲存庫中 bin/coupang_mcp.py 所提供的 local://coupang-mcp 協定，用以取代傳統維護型 HF Space MCP 端點。

關鍵字商品搜尋
火箭配送專用篩選搜尋
價格區間搜尋
建立商品比較表
分類熱銷商品
Goldbox 當日限時特價
熱門搜尋詞 / 季節商品推薦

How it works

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)

Hard rules:

COUPANG_MCP_ENDPOINT 僅保留作為相容性控制開關（knob）。預設值為 local://coupang-mcp。
切勿使用舊版的 HF Space 託管型 MCP 端點，也不要自行編造端點。
Upstream 儲存庫僅限使用 https://github.org/retention-corp/coupang_partners.git。
請先執行 tools 與 init 以確認本機 MCP 協定。

Execution paths

retention-corp/coupang_partners 會在單一 CLI 架構下自動選擇以下兩種路徑之一。包裝腳本（coupang_partners_mcp.py）會將這兩種路徑原封不動地透傳（pass through）：

Operator (local HMAC) path — 當同時設定了 COUPANG_ACCESS_KEY 與 COUPANG_SECRET_KEY 時啟用。Upstream 會直接對 Coupang Partners API 進行 HMAC 簽署並發送呼叫。金鑰 / 金鑰密碼（Secret）絕不能暴露在回覆、文件或 Git Commit 中。
Credentialless hosted fallback path — 當上述任一金鑰缺失時（或設定了 OPENCLAW_SHOPPING_FORCE_HOSTED=1）啟用。Upstream 會自動退回（fallback）至 Retention Corp 的託管後端（https://a.retn.kr/v1/public/assist）。此路徑透過 X-OpenClaw-Client-Id 白名單進行存取管制，而 Upstream 預設傳送的 openclaw-skill 值目前已登錄於 Retention Corp 的白名單中。k-skill 包裝腳本不會另外設定 OPENCLAW_SHOPPING_CLIENT_ID，而是直接採用 Upstream 的預設值。

兩種路徑的回傳 JSON 外殼（envelope，包含 ok / data.session_id / data.tool / data.payload / data.result）結構完全一致，因此回覆邏輯無須區分路徑。短網址（short deeplink）在 hosted fallback 路徑下格式為 https://a.retn.kr/s/...，而在 operator path 下則為 https://link.coupang.com/...。

MCP endpoint / contract

local://coupang-mcp

協定相容版本：MCP 2025-03-26。這不是一個透過網路連線的 Streamable HTTP 伺服器，而是由 Upstream 儲存庫的本機 MCP 相容 CLI 回傳具有相同工具名稱與 JSON-RPC 格式的 payload。

When to use

「幫我查一下 Coupang 上礦泉水的價格」
「幫我找支援火箭配送的 AirPods」
「推薦 20 萬韓元以下的鍵盤」
「iPad vs Galaxy Tab 比較」
「今天 Coupang 有什麼限時特價？」
「顯示電子產品熱銷排行榜」

When not to use

需要登入、購物車或自動化結帳流程時
需要存取 Coupang 帳號 / Session 時
需要 100% 確保即時庫存 / 是否售罄時（hosted fallback 與 Partners API 都可能存在快取或延遲）

Workflow

1. Clarify the need

若搜尋詞太過寬泛，請先收窄使用者的意圖。

建議提問：您會優先考慮哪種用途／預算／品牌／容量呢？

2. Bootstrap and check the tool contract

包裝腳本預設會將 Upstream 儲存庫 Clone 至 ~/.cache/k-skill/coupang_partners。若已經 Clone 過，則直接使用既有檔案；僅在需要更新時加上 --update。

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

如需指定既有的 checkout 目錄，或在 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. Call tools

根據使用者的具體需求呼叫 Upstream CLI 命令。結果會回傳包含 ok、data.tool、data.payload 與 data.result 的 JSON 格式。

# 一般搜尋（未提供金鑰亦可透過 hosted fallback 運作）
python3 coupang-product-search/scripts/coupang_partners_mcp.py search "32吋 4K 螢幕"

# 火箭配送篩選
python3 coupang-product-search/scripts/coupang_partners_mcp.py rocket "AirPods"

# 價格區間搜尋
python3 coupang-product-search/scripts/coupang_partners_mcp.py budget "鍵盤" --max-price 100000

# 商品比較
python3 coupang-product-search/scripts/coupang_partners_mcp.py compare "iPad vs Galaxy Tab"

# Goldbox 限時特價（Upstream 需營運者金鑰的路徑）
python3 coupang-product-search/scripts/coupang_partners_mcp.py goldbox

4. (optional) 強制使用 hosted fallback

若想在已設定營運者金鑰的狀態下檢查 hosted fallback 路徑，只需加入 OPENCLAW_SHOPPING_FORCE_HOSTED=1 即可。OPENCLAW_SHOPPING_CLIENT_ID 保持預設即可，因為 Upstream 發送的預設值 openclaw-skill 目前已登錄於 Retention Corp 的白名單中。

export OPENCLAW_SHOPPING_FORCE_HOSTED=1
python3 coupang-product-search/scripts/coupang_partners_mcp.py search "AirPods"

Available tools

工具名稱	CLI 命令	功能	參數範例
`search_coupang_products`	`search`	一般商品搜尋	`"礦泉水"`
`search_coupang_rocket`	`rocket`	僅篩選火箭配送	`"AirPods"`
`search_coupang_budget`	`budget`	價格區間搜尋	`"鍵盤" --max-price 100000`
`compare_coupang_products`	`compare`	建立商品比較表	`"iPad vs Galaxy Tab"`
`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 在 Upstream 中屬於需要 Coupang Partners API 權限的路徑，因此在未設定金鑰的環境下可能會失敗。遇到此情況時，請直接回傳錯誤訊息，並建議使用者改用 hosted fallback 支援的 search / rocket / budget / compare 等替代路徑。

Response format

Upstream 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/...          # hosted fallback 短網址
   或：     https://link.coupang.com/a/...     # operator HMAC 路徑深層連結

## normal (熱門精選)

1) 三星 QHD Odyssey G5 電競螢幕
   價格：283,000 韓元（僅供參考）
   前往查看：https://a.retn.kr/s/...

Response policy

若候選商品有多個，僅簡要比較前 3~5 個。
請明確標示「火箭配送」與「一般配送」的差異。
請提醒使用者價格、缺貨狀態與配送資訊可能即時變動。
若因 Upstream checkout、權限或 Coupang Partners 環境變數問題導致失敗，請簡要說明失敗原因並提供重試或設定方法。
聯盟行銷聲明（必填）：回覆中所包含的短網址（https://a.retn.kr/s/...）及 Coupang 直連深層連結（link.coupang.com/...?lptag=AF...）皆會追蹤至 Retention Corp 的 Coupang Partners（聯盟行銷）管道。若 Upstream 回傳的結果包含 disclosure 字串（如 "파트너스 활동을 통해 일정액의 수수료를 제공받을 수 있음"，意即「透過夥伴計畫購買，我們可能會獲得一定比例的佣金」），請直接顯示；若未包含，請在回覆末尾附上相同宗旨的聲明。

Done when

已透過 tools 和 init 或實際命令驗證 retention-corp/coupang_partners 本機 MCP 協定。
搜尋結果已清楚區分為火箭配送與一般配送並完成整理。
已根據使用者需求提供 TOP 3 推薦商品。
已包含價格、配送資訊及其可能變動的提示。
回覆中已包含聯盟行銷聲明（disclosure）。

您可能也喜歡

trello

386Kbackend-api

Manage Trello boards, lists, and cards via the Trello REST API.

openclaw

獲取

xurl

385Kbackend-api

適用於已驗證身份之 X 發文、回覆、檢視/搜尋、私訊、媒體上傳、追蹤者管理、驗證狀態查詢及原始 v2 API 呼叫的 xurl CLI 工具。

steipete

獲取

kubernetes-patterns

240Kbackend-api

Kubernetes workload patterns, resource management, RBAC, probes, autoscaling, ConfigMap/Secret handling, and kubectl debugging for production-grade deployments. Use when writing or reviewing Kubernetes manifests, or debugging probes, RBAC, autoscaling, or resource limits.

affaan-m

獲取

繼續探索

瀏覽 backend-api 熱門 Skills 最近更新

環境變數	作用	預設值
`COUPANG_ACCESS_KEY`, `COUPANG_SECRET_KEY`	營運者 Coupang Partners API 金鑰。兩者皆存在時才會啟用本機 HMAC 路徑。	無（若未提供則退回至 hosted fallback）
`OPENCLAW_SHOPPING_CLIENT_ID`	hosted fallback 發送的 `X-OpenClaw-Client-Id`。Upstream 預設發送 `openclaw-skill`，該值目前已在 Retention Corp 的白名單中。建議 k-skill 包裝腳本不要覆寫此變數。	`openclaw-skill`
`OPENCLAW_SHOPPING_FORCE_HOSTED`	設為 `1` 時，即使已設定金鑰也會強制使用 hosted 路徑。	空值
`OPENCLAW_SHOPPING_BASE_URL`	覆寫 hosted 後端 Base URL，用於 Staging 或本機後端測試。	`https://a.retn.kr`