Coupang Product Search

What this skill does

retention-corp/coupang_partners リポジトリのローカル Coupang MCP 互換レイヤーを使って、クーパン商品照会ツールを実行する。既存のメンテナンス型 HF Space MCP エンドポイントの代わりに、このリポジトリの bin/coupang_mcp.py が提供する local://coupang-mcp 契約を呼び出す。

• キーワード商品検索
• ロケット配送専用フィルター検索
• 価格帯範囲検索
• 商品比較表生成
• カテゴリ別ベスト商品
• ゴールドボックス当日特価
• 人気検索語/季節商品推奨

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 は互換性ノブとしてのみ維持する。デフォルト値は local://coupang-mcp だ。
• 旧式の HF Space ホステッド MCP エンドポイントを使用したり、新たに作成したりしない。
• upstream リポジトリは https://github.com/retention-corp/coupang_partners.git のみを使用する。
• tools と init はローカル MCP 契約確認用として最初に実行する。

Execution paths

retention-corp/coupang_partners は 1 つの CLI の背後で 2 つの経路を自動的に選択する。ラッパー（coupang_partners_mcp.py）は両経路をそのまま通す。

1. Operator (local HMAC) path — COUPANG_ACCESS_KEY と COUPANG_SECRET_KEY が両方設定されている場合。upstream が Coupang Partners API を HMAC 署名で直接呼び出す。キー/シークレットは回答・ドキュメント・コミットに露出させない。
2. Credentialless hosted fallback path — 上記 2 つのキーのいずれかが無い場合（または OPENCLAW_SHOPPING_FORCE_HOSTED=1）。upstream が自動的に 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 エンベロープ（ok/data.session_id/data.tool/data.payload/data.result）の形式は同じため、レスポンスロジックは経路を区別する必要がない。短いディープリンクはホステッド フォールバックでは https://a.retn.kr/s/... 形式で、operator パスでは https://link.coupang.com/... 形式で返される。

関連環境変数

環境変数	役割	デフォルト値
COUPANG_ACCESS_KEY, COUPANG_SECRET_KEY	オペレーター Coupang Partners API クレデンシャル。両方ある場合のみローカル HMAC パスが有効化される。	なし（なければホステッド フォールバック）
OPENCLAW_SHOPPING_CLIENT_ID	ホステッド フォールバックが送信する X-OpenClaw-Client-Id。upstream は openclaw-skill をデフォルトで送信し、この値は現在 Retention Corp アローリストに登録されている。k-skill ラッパーはこの変数をオーバーライドしないことを推奨する。	openclaw-skill
OPENCLAW_SHOPPING_FORCE_HOSTED	1 ならキーがあってもホステッド パスを強制する。	空
OPENCLAW_SHOPPING_BASE_URL	ホステッド バックエンド base URL オーバーライド。ステージング/ローカル backend テスト用。	https://a.retn.kr

MCP endpoint / contract

local://coupang-mcp

プロトコル互換バージョン: MCP 2025-03-26。ネットワークで接続する Streamable HTTP サーバーではなく、upstream リポジトリのローカル MCP 互換 CLI が同じツール名と JSON-RPC 形式のペイロードを返す。

When to use

• 「クーパンで生水の価格を探してくれ」
• 「ロケット配送でエアポッド探してくれ」
• 「20万円以下のキーボード推奨してくれ」
• 「iPad vs Galaxy Tab 比較」
• 「今日のクーパン特価は何があるか」
• 「電子製品のベストを見せてくれ」

When not to use

• ログイン、カートショッピング、決済自動化が必要な場合
• クーパン アカウント/セッション アクセスが必要な場合
• リアルタイム在庫/売り切れ状況を 100% 保証する必要がある場合（ホステッド フォールバックと Partners API の両方にキャッシュ・遅延がある可能性がある）

Workflow

1. Clarify the need

検索語が広すぎる場合は、まず意図を絞る。

• 推奨質問: どんな用途/予算/ブランド/容量を優先しますか?

2. Bootstrap and check the tool contract

ラッパーはデフォルトで ~/.cache/k-skill/coupang_partners に upstream リポジトリをクローンする。既にクローン済みなら、そのまま使用し、最新化が必要な場合のみ --update を付ける。

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

既存チェックアウトを明示するか、CI/検証でネットワーク クローンを防ぐには:

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 で返される。

# 一般検索（キーなしでもホステッド フォールバックで動作）
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 "iPad vs Galaxy Tab"

# ゴールドボックス（オペレーターキーが必要な upstream パス）
python3 coupang-product-search/scripts/coupang_partners_mcp.py goldbox

4. (オプション) ホステッド フォールバックの強制

オペレーター キーがある状態でも、ホステッド フォールバック パスを確認したい場合は 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 "エアポッド"

Available tools

ツール名	CLI コマンド	機能	パラメーター例
search_coupang_products	search	一般商品検索	"生水"
search_coupang_rocket	rocket	ロケット配送のみフィルタリング	"エアポッド"
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 権限が必要なパスなので、キーがない環境では失敗する可能性がある。その場合は、エラーメッセージをそのまま伝え、ホステッド フォールバックでカバーされている 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/...          # ホステッド フォールバック shortlink
   または:   https://link.coupang.com/a/...     # オペレーター HMAC パス ディープリンク

## normal (上位候補)

1) Samsung 電子 QHD オデッセイ G5 ゲーミング モニター
   価格: 283,000ウォン（参考用）
   を見る: https://a.retn.kr/s/...

Response policy

• 候補が複数ある場合は上位 3～5 個のみ短く比較する。
• ロケット配送/通常配送の区別を明示する。
• 価格/品切れ/配送情報はリアルタイム変動する可能性があることを案内する。
• upstream チェックアウト、権限、Coupang Partners 環境変数の問題で失敗した場合は、失敗原因と再試行/設定方法を短く案内する。
• アフィリエイト表示（必須）: レスポンスに含まれるショートリンク（https://a.retn.kr/s/...）と直接 coupang ディープリンク（link.coupang.com/...?lptag=AF...）は Retention Corp のクーパン パートナーズ（アフィリエイト）チャネルで追跡される。upstream が返す disclosure 文字列（「パートナーズ活動を通じて一定額の手数料を受け取ることができます」）がある場合はそのまま露出し、ない場合は同じ趣旨の表示をレスポンスの末尾に追加する。

Done when

• tools と init またはその実際のコマンドで retention-corp/coupang_partners ローカル MCP 契約を確認した。
• 検索結果がロケット配送/通常配送で区別されて整理された。
• ユーザーニーズに合わせた推奨 TOP 3 が提示された。
• 価格/配送情報と変動可能性案内が含まれた。
• アフィリエイト表示（disclosure）がレスポンスに含まれた。