market-kurly-search

SKILL.md

Market Kurly Search

What this skill does

마켓컬리 웹앱이 실제로 사용하는 비로그인 검색/상품 상세 표면을 사용해 아래 흐름을 처리한다.

키워드로 상품 후보를 검색한다.

현재 가격과 할인 여부를 확인한다.

품절 여부와 배송 타입을 확인한다.

상품 링크를 함께 반환한다.

주문/장바구니 같은 액션은 하지 않는다. 조회형으로만 답한다.

When to use

"마켓컬리에서 우유 얼마야?"

"컬리에서 딸기 검색해줘"

"이 상품 품절인지 보고 링크도 줘"

"지금 컬리 가격만 빠르게 보고 싶어"

When not to use

주문/장바구니/결제까지 자동화해야 하는 경우

주소 기반 배송 가능 여부나 회원 전용 가격을 확정해야 하는 경우

로그인 세션이 필요한 개인화 추천/찜 정보를 조회해야 하는 경우

Prerequisites

인터넷 연결

node 18+

이 저장소의 market-kurly-search package 또는 동일 로직

Required inputs

1. Ask for a product keyword if it is missing

상품명 또는 검색어가 없으면 먼저 물어본다.

권장 질문: 찾을 마켓컬리 상품명이나 검색어를 알려주세요. 예: 우유, 딸기, 닭가슴살

너무 넓으면: 검색어가 너무 넓어요. 브랜드나 용량까지 같이 알려주시면 가격 후보를 더 정확히 추릴 수 있어요.

2. Confirm which candidate they want when the query is ambiguous

검색 결과가 여러 개면 상위 2~3개만 보여주고 다시 확인받는다.

권장 질문: 후보가 여러 개예요. 아래 상품 중 어떤 상품 가격을 볼까요?

응답에는 상품명 + 현재 가격 + 품절 여부 + 링크를 같이 붙인다.

Official Market Kurly surfaces

search list: https://api.kurly.com/search/v4/sites/market/normal-search?keyword=<keyword>&page=1

search count: https://api.kurly.com/search/v3/sites/market/normal-search/count?keyword=<keyword>&filters=&allow_replace=true

product detail page: https://www.kurly.com/goods/<productNo>

Workflow

1. Search by keyword first

const { searchProducts } = require("market-kurly-search")

const result = await searchProducts("우유")
console.log(result.items.slice(0, 3))

검색 결과에서는 아래 필드를 우선 본다.

상품명

현재 가격 (discountedPrice 우선, 없으면 salesPrice)

할인율

품절 여부

배송 타입

상품 링크

2. Use the count endpoint when the result set is broad

const { countProducts } = require("market-kurly-search")

const count = await countProducts("우유")
console.log(count)

후보가 너무 많으면 count 를 먼저 보여 주고 검색어를 좁히라고 안내한다.

3. Use the goods page detail as a fallback or follow-up lookup

const { getProductDetail } = require("market-kurly-search")

const detail = await getProductDetail(5063110)
console.log(detail)

goods/<productNo> HTML 안의 __NEXT_DATA__ 에서 상품명, 가격, 품절 여부, 배송 타입을 추출한다.

4. Respond conservatively

응답은 짧고 보수적으로 정리한다.

상품명

현재 가격

필요하면 원가/할인가 여부

품절 여부 또는 판매 가능 여부

상품 링크

가격/품절/노출 정보는 시점에 따라 달라질 수 있으니 조회 시각 기준 참고값이라고 분명히 말한다.

Done when

상품 키워드를 확인했다.

검색 결과에서 후보와 현재 가격을 최소 1개 이상 반환했다.

필요하면 상품 상세 페이지로 보조 확인했다.

주문/장바구니 같은 범위 밖 액션은 하지 않았다.

Failure modes

검색어가 너무 넓으면 후보가 과도하게 많아질 수 있다.

가격/품절/배송 문구는 시점에 따라 달라질 수 있다.

현재 확인한 표면은 공식 개발자 Open API가 아니라 웹이 쓰는 공개 표면 이므로 스키마가 바뀌면 깨질 수 있다.

회원 전용/주소 전용 정보는 비로그인 조회만으로 확정할 수 없다.

Notes

조회형 스킬이다.

비로그인 공개 표면 우선 원칙을 유지한다.

주문/장바구니/로그인 요구 기능은 시도하지 않는다.