coupang-product-search

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Coupang Product Search

What this skill does

该技能的功能

retention-corp/coupang_partners 저장소의 로컬 Coupang MCP 호환 레이어를 사용해 쿠팡 상품 조회 도구를 실행한다. 기존 유지보수형 HF Space MCP 엔드포인트 대신, 이 저장소의

bin/coupang_mcp.py

가 제공하는

local://coupang-mcp

계약을 호출한다.

키워드 상품 검색
로켓배송 전용 필터 검색
가격대 범위 검색
상품 비교표 생성
카테고리별 베스트 상품
골드박스 당일 특가
인기 검색어/계절 상품 추천

使用retention-corp/coupang_partners仓库的本地Coupang MCP兼容层运行Coupang商品查询工具。替代原有的维护型HF Space MCP端点，调用该仓库

bin/coupang_mcp.py

提供的

local://coupang-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 hosted MCP 엔드포인트를 사용하거나 새로 지어내지 않는다.

upstream 저장소는

https://github.com/retention-corp/coupang_partners.git

만 사용한다.

```
tools
```
와
```
init
```
은 로컬 MCP 계약 확인용으로 먼저 실행한다.

Claude Code / Codex
  → coupang-product-search/scripts/coupang_partners_mcp.py
    → git clone/update retention-corp/coupang_partners (用户缓存)
      → python3 bin/coupang_mcp.py
        → local://coupang-mcp 兼容工具层
          ├─ Coupang Partners API client (已配置运营密钥)
          └─ 托管回退 → https://a.retn.kr/v1/public/assist (无密钥)

硬性规则：

```
COUPANG_MCP_ENDPOINT
```
仅作为兼容性开关保留，默认值为
```
local://coupang-mcp
```
。
禁止使用旧版HF Space托管MCP端点或新建此类端点。

仅使用上游仓库

https://github.com/retention-corp/coupang_partners.git

。

```
tools
```
和
```
init
```
需先执行以验证本地MCP协议。

Execution paths

执行路径

retention-corp/coupang_partners

는 하나의 CLI 뒤에서 두 가지 경로를 자동으로 선택한다. 래퍼(

coupang_partners_mcp.py

)는 두 경로 모두를 그대로 통과시킨다.

Operator (local HMAC) path —
```
COUPANG_ACCESS_KEY
```
와
```
COUPANG_SECRET_KEY
```
가 둘 다 설정된 경우. upstream이 Coupang Partners API를 HMAC 서명해 직접 호출한다. 키/시크릿은 절대 답변·문서·커밋에 노출하지 않는다.
Credentialless hosted fallback path — 위 두 키 중 하나라도 없는 경우(또는
```
OPENCLAW_SHOPPING_FORCE_HOSTED=1
```
). upstream이 자동으로 Retention Corp의 hosted 백엔드(
```
https://a.retn.kr/v1/public/assist
```
)로 떨어진다. 이 경로는
```
X-OpenClaw-Client-Id
```
allowlist로 게이트되어 있으며, upstream이 기본으로 실어 보내는
```
openclaw-skill
```
값이 현재 Retention Corp allowlist에 등록된 값이다. 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/...

형태로 온다.

retention-corp/coupang_partners

会在单个CLI后自动选择两种路径，封装器(

coupang_partners_mcp.py

)会直接传递两种路径的请求。

运营者（本地HMAC）路径 — 当
```
COUPANG_ACCESS_KEY
```
和
```
COUPANG_SECRET_KEY
```
均已配置时，上游会通过HMAC签名直接调用Coupang Partners API。密钥绝对不能在回复、文档或提交中泄露。
无凭据托管回退路径 — 当上述两个密钥任一缺失时（或设置
```
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

)完全一致，因此回复逻辑无需区分路径。短链接在托管回退路径中为

https://a.retn.kr/s/...

格式，在运营者路径中为

https://link.coupang.com/...

格式。

환경변수	역할	기본값
`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 allowlist에 등록되어 있다. k-skill 래퍼는 이 변수를 오버라이드하지 않는 것을 권장한다.	`openclaw-skill`
`OPENCLAW_SHOPPING_FORCE_HOSTED`	`1` 이면 키가 있어도 hosted 경로를 강제한다.	비어있음
`OPENCLAW_SHOPPING_BASE_URL`	hosted 백엔드 base URL 오버라이드. 스테이징/로컬 backend 테스트용.	`https://a.retn.kr`

环境变量	作用	默认值
`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` 时，即使存在密钥也强制使用托管路径。	空
`OPENCLAW_SHOPPING_BASE_URL`	覆盖托管后端基础URL，用于 staging/本地后端测试。	`https://a.retn.kr`

MCP endpoint / contract

MCP端点/协议

local://coupang-mcp

프로토콜 호환 버전: MCP

2025-03-26

. 네트워크로 붙는 Streamable HTTP 서버가 아니라, upstream 저장소의 로컬 MCP 호환 CLI가 같은 도구 이름과 JSON-RPC 모양의 payload를 반환한다.

local://coupang-mcp

协议兼容版本：MCP

2025-03-26

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

When to use

使用场景

"쿠팡에서 생수 가격 좀 찾아줘"
"로켓배송 에어팟 찾아줘"
"20만원 이하 키보드 추천해줘"
"아이패드 vs 갤럭시탭 비교"
"오늘 쿠팡 특가 뭐 있어?"
"전자제품 베스트 보여줘"

"帮我找Coupang上的矿泉水价格"
"找支持火箭配送的AirPods"
"推荐20万韩元以下的键盘"
"对比iPad和Galaxy Tab"
"今天Coupang有什么特价？"
"展示电子产品热门商品"

When not to use

不适用场景

로그인, 장바구니, 결제 자동화가 필요한 경우
쿠팡 계정/session 접근이 필요한 경우
실시간 재고/품절 여부를 100% 보장해야 하는 경우 (hosted fallback과 Partners API 모두 캐시·지연이 있을 수 있다)

需要登录、购物车、支付自动化的情况
需要访问Coupang账户/session的情况
需要100%保证实时库存/缺货状态的情况（托管回退和Partners API均可能存在缓存/延迟）

Workflow

工作流程

1. Clarify the need

1. 明确需求

검색어가 너무 넓으면 먼저 의도를 좁힌다.

권장 질문:

어떤 용도/예산/브랜드/용량을 우선할까요?

若搜索词过于宽泛，先缩小用户意图。

推荐提问：

您优先考虑哪种用途/预算/品牌/容量？

2. Bootstrap and check the tool contract

2. 初始化并验证工具协议

래퍼는 기본적으로

~/.cache/k-skill/coupang_partners

에 upstream 저장소를 clone한다. 이미 clone되어 있으면 그대로 사용하고, 최신화가 필요할 때만

--update

를 붙인다.

bash

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

기존 checkout을 명시하거나 CI/검증에서 네트워크 clone을 막으려면:

bash

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

封装器默认会将上游仓库克隆到

~/.cache/k-skill/coupang_partners

。若已克隆则直接使用，仅在需要更新时添加

--update

参数。

bash

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

若要指定现有检出目录，或在CI/验证中禁止网络克隆：

bash

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

3. 调用工具

구체적인 사용자 요청에 맞춰 upstream CLI 명령을 호출한다. 결과는

ok

data.tool

data.payload

data.result

를 포함하는 JSON으로 반환된다.

bash

undefined

根据具体用户请求调用上游CLI命令，结果返回包含

ok

data.tool

data.payload

data.result

的JSON。

bash

undefined

일반 검색 (키 없이도 hosted fallback으로 작동)

普通搜索（无密钥时通过托管回退运行）

python3 coupang-product-search/scripts/coupang_partners_mcp.py search "32인치 4K 모니터"

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 rocket "AirPods"

가격대 검색

价格区间搜索

python3 coupang-product-search/scripts/coupang_partners_mcp.py budget "키보드" --max-price 100000

python3 coupang-product-search/scripts/coupang_partners_mcp.py budget "键盘" --max-price 100000

비교

商品对比

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

python3 coupang-product-search/scripts/coupang_partners_mcp.py compare "iPad vs Galaxy Tab"

골드박스 (운영자 키가 필요한 upstream 경로)

GoldBox（需运营者密钥的上游路径）

python3 coupang-product-search/scripts/coupang_partners_mcp.py goldbox

undefined

python3 coupang-product-search/scripts/coupang_partners_mcp.py goldbox

undefined

4. (optional) hosted fallback 강제

4.（可选）强制使用托管回退

운영자 키가 있는 상태에서도 hosted fallback 경로를 점검하고 싶으면

OPENCLAW_SHOPPING_FORCE_HOSTED=1

만 추가하면 된다.

OPENCLAW_SHOPPING_CLIENT_ID

는 upstream이 보내는 기본값

openclaw-skill

이 현재 Retention Corp allowlist에 등록된 값이므로 별도로 설정하지 않는다.

bash

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

若已配置运营者密钥但仍需检查托管回退路径，只需添加

OPENCLAW_SHOPPING_FORCE_HOSTED=1

。上游默认携带的

openclaw-skill

已在Retention Corp白名单中，无需单独设置

OPENCLAW_SHOPPING_CLIENT_ID

。

bash

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`	로켓배송만 필터링	`"에어팟"`
`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

는 upstream 기준 Coupang Partners API 권한이 필요한 경로이므로, 키가 없는 환경에서는 실패할 수 있다. 이런 경우 에러 메시지를 그대로 전달하고 hosted fallback이 커버하는

search

rocket

budget

compare

경로로 우회 제안한다.

工具名	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

基于上游Coupang Partners API权限，无密钥环境下可能失败。此时需直接传递错误信息，并建议切换到托管回退支持的

search

rocket

budget

compare

路径。

Response format

响应格式

upstream CLI는 JSON을 출력한다.

data.result

안의 상품 배열 또는 도구별 객체를 읽고, 답변에서는 로켓배송(rocket)과 일반배송(normal)을 구분한다.

json

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

사용자에게 보여줄 때는 다음처럼 짧게 정리한다.

undefined

上游CLI输出JSON，读取

data.result

中的商品数组或工具专属对象，回复中需区分火箭配送(rocket)和普通配送(normal)。

json

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

展示给用户时需简化整理：

undefined

rocket (상위 후보)

rocket（优先候选）

LG전자 4K UHD 모니터 가격: 397,750원 (참고용) 보러가기: https://a.retn.kr/s/... # hosted fallback shortlink 또는: https://link.coupang.com/a/... # operator HMAC 경로 딥링크

LG电子4K UHD显示器价格：397,750韩元（参考价）查看链接：https://a.retn.kr/s/... # 托管回退短链接或： https://link.coupang.com/a/... # 运营者HMAC路径深度链接

normal (상위 후보)

normal（优先候选）

삼성전자 QHD 오디세이 G5 게이밍 모니터 가격: 283,000원 (참고용) 보러가기: https://a.retn.kr/s/...

undefined

三星电子QHD奥德赛G5电竞显示器价格：283,000韩元（参考价）查看链接：https://a.retn.kr/s/...

undefined

Response policy

响应规则

후보가 여러 개면 상위 3~5개만 짧게 비교한다.
로켓배송/일반배송 구분을 명시한다.
가격/품절/배송 정보는 실시간 변동될 수 있음을 안내한다.
upstream checkout, 권한, Coupang Partners 환경변수 문제로 실패하면 실패 원인과 재시도/설정 방법을 짧게 안내한다.
Affiliate 고지(필수): 응답에 포함되는 shortlink(
```
https://a.retn.kr/s/...
```
)와 직접 coupang 딥링크(
```
link.coupang.com/...?lptag=AF...
```
)는 Retention Corp의 쿠팡 파트너스(affiliate) 채널로 트래킹된다. upstream이 돌려주는
```
disclosure
```
문자열(
```
"파트너스 활동을 통해 일정액의 수수료를 제공받을 수 있음"
```
)이 있으면 그대로 노출하고, 없으면 같은 취지의 고지를 답변 말미에 덧붙인다.

若有多个候选，仅简化对比前3~5个。
明确区分火箭配送/普通配送。
需提示价格/缺货/配送信息可能实时变动。
若因上游检出、权限、Coupang Partners环境变量问题失败，需简要说明失败原因及重试/配置方法。
联盟营销告知（必填）：回复中包含的短链接(
```
https://a.retn.kr/s/...
```
)和直接Coupang深度链接(
```
link.coupang.com/...?lptag=AF...
```
)均通过Retention Corp的Coupang Partners（联盟营销）渠道追踪。若上游返回
```
disclosure
```
字符串(
```
"通过联盟营销活动可获得一定比例佣金"
```
)，需直接展示；若无，则在回复末尾添加相同含义的告知。

Done when

完成标准

```
tools
```
와
```
init
```
또는 실제 명령으로 retention-corp/coupang_partners 로컬 MCP 계약을 확인했다.
검색 결과가 로켓배송/일반배송으로 구분되어 정리되었다.
사용자 니즈에 맞는 추천 TOP 3이 제시되었다.
가격/배송 정보와 변동 가능성 안내가 포함되었다.
affiliate 고지(disclosure)가 답변에 포함되었다.

通过
```
tools
```
和
```
init
```
或实际命令验证了retention-corp/coupang_partners本地MCP协议。
搜索结果已按火箭配送/普通配送分类整理。
提供了符合用户需求的Top3推荐。
包含价格/配送信息及变动可能性提示。
回复中包含联盟营销告知(disclosure)。

coupang-product-search

Original

Translation

Coupang Product Search

Coupang Product Search

What this skill does

该技能的功能

How it works

工作原理

Execution paths

执行路径

관련 환경변수

相关环境变量

MCP endpoint / contract

MCP端点/协议

When to use

使用场景

When not to use

不适用场景

Workflow

工作流程

1. Clarify the need

1. 明确需求

2. Bootstrap and check the tool contract

2. 初始化并验证工具协议

3. Call tools

3. 调用工具

일반 검색 (키 없이도 hosted fallback으로 작동)

普通搜索（无密钥时通过托管回退运行）

로켓배송 필터

火箭配送筛选

가격대 검색

价格区间搜索

비교

商品对比

골드박스 (운영자 키가 필요한 upstream 경로)

GoldBox（需运营者密钥的上游路径）

4. (optional) hosted fallback 강제

4.（可选）强制使用托管回退

Available tools

可用工具

Response format

响应格式

rocket (상위 후보)

rocket（优先候选）

normal (상위 후보)

normal（优先候选）

Response policy

响应规则

Done when

完成标准