coupangctl

왜 필요한가요?

“200만 원 안에서 데스크탑을 고르고 싶다”는 요청에는 검색 이상의 일이 필요합니다. 카테고리마다 다른 필터를 확인하고, 판매 옵션의 가격과 사양을 비교하고, 빠진 정보도 찾아야 하죠. 내 소비를 돌아볼 때도 화면에 보이는 몇 건만으로 전체 구매 패턴을 말할 수는 없습니다.

coupangctl은 이 과정을 CLI와 MCP 도구로 연결합니다. 상품은 현재 소스에서 읽고, 주문은 사용자가 동기화한 범위 안에서 로컬로 분석합니다. 확인한 사실, 계산한 값, 추론을 구분해 AI가 판단의 근거를 설명하도록 돕습니다.

Related MCP server: ECommerce MCP Server

이런 일을 맡길 수 있어요

위 문장은 사용 예시이며 실제 조회 결과가 아닙니다. MCP를 연결한 AI가 요청을 조건으로 바꿉니다. CLI 자체가 자연어를 해석하는 것은 아닙니다. 구매 이력을 추천에 쓰려면 --use-purchase-history로 따로 요청해야 합니다.

추천에 이르는 과정

추천의 출발점은 “몇 개를 보여줄까?”가 아니라 “어떤 조건을 확인해야 할까?”입니다.

1. 필터를 발견합니다. 기본 검색의 coverage.facets에서 현재 카테고리의 선택지를 읽습니다.

2. 범위를 좁힙니다. 실제 제공된 필터만 적용하고 최종 선택 상태를 확인합니다.

3. 판매 옵션을 조사합니다. 같은 상품이라도 옵션별 가격·사양을 구분합니다. 검색 제목을 확정 사양으로 쓰지 않습니다.

4. 근거를 남깁니다. 조건부 후보뿐 아니라 제외 이유, 미확인 정보, 다음 확인 항목도 보고서에 담습니다.

--limit은 표시 개수일 뿐, 조사 깊이나 적절한 추천 개수의 근거가 아닙니다. complete도 정해진 범위의 조사 완료를 뜻하며 “시장 전체에서 최고”라는 판정은 아닙니다. 이 그림은 기능 흐름이지 특정 상품을 실제 조사한 기록은 아닙니다.

./coupangctl products recommend \
  --query '조립PC' --max-price 2000000 --proceed --no-affiliate

--proceed를 생략하면 관찰된 필터를 바탕으로 선택 질문 후보를 반환합니다. 조사 결과는 needs_input, no_matches, incomplete, complete로 구분합니다. 가격이나 필수 조건의 근거가 없으면 조건을 충족했다고 처리하지 않습니다.

기존 결과를 recommendation.json으로 저장했다면 다음처럼 보고서를 만듭니다. 아래 변환에는 별도 도구인 jq가 필요합니다.

jq '{schema_version: 2, title: "상품 비교 근거", recommendation: .}' recommendation.json |
  ./coupangctl products report --input - --output comparison.html

보고서 생성은 상품을 다시 조회하지 않습니다. 기존 출력 파일도 덮어쓰지 않습니다. 결과는 개인용 private_local이며, HTML을 열면 외부 상품 이미지가 로드될 수 있습니다. 조건 입력·보고서 응답 계약

빠른 시작

현재는 소스에서 빌드해 사용합니다. 빌드에는 Go 1.26 이상이 필요합니다. 사이트 조회에는 Node 22 이상과 검증해 설치한 Camofox 서버·Camoufox 엔진이 필요합니다. camofox setup은 설치된 런타임을 등록하며 다운로드나 업데이트를 대신하지 않습니다.

1. CLI 빌드

git clone https://github.com/JungHoonGhae/coupang-ctl.git
cd coupang-ctl
go build -o ./coupangctl ./cmd/coupangctl

이 안내는 macOS에서 실측한 경로를 기준으로 합니다. Windows·Linux의 빌드 및 합성 테스트 통과는 실제 브라우저 동작 검증과 다릅니다. 다운로드한 릴리스를 사용할 때는 산출물 검증 절차를 따르세요.

2. 전용 브라우저 등록

아래 경로를 설치된 Camofox 서버 폴더와 Camoufox 엔진 폴더로 바꿔 실행하세요.

./coupangctl camofox setup \
  --runtime /absolute/path/to/camofox \
  --engine-dir /absolute/path/to/camoufox
./coupangctl doctor

조회는 창 없이 전용 세션에서 실행합니다. 일상용 Chrome·Aside와 프로필을 공유하지 않으며, 확장 프로그램·Swift·Orca는 필요하지 않습니다. 설정이나 접근에 문제가 생겨도 다른 브라우저로 자동 전환하지 않습니다. doctor는 로컬 설치 점검입니다. 로그인 확인은 다음 단계에서 합니다. 런타임·저장소·재연결 상세

3. 로그인하고 첫 검색

직접 인증할 때만 전용 창을 엽니다. 이미 인증된 세션이면 새 로그인 창을 열지 않습니다.

./coupangctl login --manual
./coupangctl auth status
./coupangctl products search --query '미니 식기' --limit 3 --no-affiliate

휴대폰 앱에서 승인하려면 login --qr --link를 선택하세요. 일회성 링크와 확인 숫자는 공유하거나 저장하지 마세요. 앱에서 링크가 열리지 않으면 --manual 화면에서 직접 로그인할 수 있습니다. SMS 발송·OTP 자동 입력은 지원하지 않습니다.

auth status의 성공은 사이트의 로그인 상태 확인입니다. 현재 계정과 로컬 DB의 연결, 주문 조회, 전체 이력 확보까지 보증하지는 않습니다. 로그인 방식과 제한

4. AI에 연결

사용하는 AI 앱의 MCP 설정에 다음 내용을 넣으세요. command는 빌드한 바이너리의 절대경로로 바꿉니다.

{
  "mcpServers": {
    "coupangctl": {
      "command": "/absolute/path/to/coupangctl",
      "args": ["mcp"]
    }
  }
}

연결한 뒤 “미니 식기를 찾아줘. 사용 가능한 필터부터 확인해줘”처럼 요청하면 됩니다. MCP 연결과 도구 목록 확인은 브라우저나 주문 DB 없이 가능합니다. 사이트 조회 시에는 위의 런타임 설정이 필요합니다. 도구 목록·연결 계약

내 주문 확인과 분석

지금 주문만 볼 때는 preview, 이력을 모아 분석할 때는 sync를 사용합니다.

./coupangctl orders preview

preview는 첫 페이지를 읽고 주문 DB를 열거나 저장하지 않습니다. 다음 페이지 유무는 has_next_page로 확인하며 결과는 개인용 private_local입니다. 빈 결과를 “구매한 적 없음”으로, 첫 페이지를 전체 이력으로 해석하지 않습니다.

./coupangctl orders sync --max-pages 1
./coupangctl orders sync-status
./coupangctl orders stats

첫 명령은 한 페이지만 저장합니다. 수집을 이어가려면 orders sync를 다시 실행하세요. sync-status와 통계는 로컬 DB만 읽으며 브라우저를 시작하지 않습니다. 마지막 실행과 누적 수집 범위를 구분하고, 커서가 끝나도 전체 계정 이력 확보로 단정하지 않습니다.

분석·리캡은 저장된 자료의 범위와 누락을 함께 표시합니다. 쇼핑 유형은 규칙 기반 해석이며 성격이나 심리 진단이 아닙니다. 공유용 public_safe 리캡과 실제 상품·금액·날짜가 있는 개인용 보고서를 구분하세요.

주문 확인·수집 계약 · 분석·리캡 명령 · 유형의 근거

어디까지 확인됐나요?

2026-09-11 실측에서는 서로 다른 두 검색, 상품 상세, 로그인 상태, 주문 미리보기를 확인했습니다. 제한된 추천 조사는 review_budget_reached로 incomplete를 반환했습니다. 이 기록을 전체 기능이나 모든 계정의 성공으로 확대하지 않습니다. 실측 결과와 남은 검증

전체 구조

CLI와 MCP는 같은 typed core와 서비스를 사용합니다. 불안정한 사이트 응답은 좁은 소스 adapter에 격리하고, 로컬 분석·보고서 생성은 브라우저와 분리합니다. 구현 위치 · Pretendard 다이어그램 원본

내 데이터는 어떻게 다루나요?

• 쿠키·세션은 전용 로컬 상태 디렉터리에 보관하며 로그나 도구 응답으로 내보내지 않습니다.

• 원시 주문 응답은 저장하지 않습니다. sync로 정규화한 주문 DB와 개인 보고서는 내 컴퓨터에 남깁니다.

• 일반 CLI 검색은 DB 없이 실행합니다. 상세 조회와 MCP의 가격 기록은 확인된 옵션·가격 근거가 있을 때 시도합니다.

• 원본 쿠팡 URL을 보존합니다. 제휴 링크는 --no-affiliate 또는 COUPANGCTL_AFFILIATE_DISABLED=true로 끌 수 있습니다.

POSIX에서는 비공개 파일에 0600 권한을 적용합니다. Windows는 상속된 ACL을 사용하며 소유자 전용 접근을 보장하지 않습니다. AI 앱에 전달한 결과는 그 앱의 데이터 처리 정책도 확인하세요. 저장 경로·공유 범위 · 개인정보 안내

설정 필요·인증 필요·접근 거부·불완전한 응답은 구분해 반환합니다. 실패를 성공으로 바꾸거나 임의로 로그인 창을 열지 않습니다. CLI·MCP 오류 계약

더 알아보기

• 상세 사용 가이드 — 명령, JSON 응답, 검색 필터, 추천, 주문 분석

• 제품 의도 · 제품 원칙 — 만들려는 경험과 사실·계산·추론의 경계

• 가격 이력 · WOW 혜택 · 쇼핑 유형 — 지표의 의미와 제한

• 검증 기록 · GitHub Issues — 확인한 동작과 남은 작업

• 릴리스 검증 · 보안 제보

go test ./...
go vet ./...
npm ci
npm run typecheck
npm run test:camofox
go build ./cmd/coupangctl

새 지표에는 출처, 분모, 표본 수, 누락 처리와 합성 테스트가 필요합니다. 자세한 기준은 제품 원칙을 따릅니다. 버그 제보와 PR에는 실제 주문·쿠키·인증 정보 대신 합성 자료나 가린 메타데이터를 사용해 주세요.

쿠팡 파트너스 고지

쿠팡 홈 열기

이 링크를 통해 구매하면 쿠팡 파트너스 활동의 일환으로 일정액의 수수료를 제공받습니다. 제휴 링크 자체로 구매자에게 별도 수수료가 부과되지는 않습니다. 최종 가격과 혜택은 쿠팡 화면에서 확인하세요. 프로젝트 운영자의 본인 구매는 수익 인정 대상이 아닙니다. 제휴 링크 비활성화와 설정

라이선스

MIT. 쿠팡 및 관련 상표는 각 권리자에게 귀속됩니다.