k-skill/docs/features/olive-young-search.md

올리브영 검색 가이드

이 기능으로 할 수 있는 일

원본 hmmhmmhm/daiso-mcp 와 npm package daiso 를 사용해 올리브영 매장 검색, 상품 검색, 재고 확인을 한다.

• /api/oliveyoung/stores 로 매장 검색
• /api/oliveyoung/products 로 상품 검색
• /api/oliveyoung/inventory 로 재고 확인
• npx --yes daiso health 로 endpoint health 확인

가장 중요한 규칙

이 기능은 upstream 원본을 그대로 쓴다. k-skill 안에 별도 올리브영 수집기를 추가하지 않고, MCP 서버를 Claude Code에 직접 설치하지 않고 CLI로 먼저 검증하는 경로를 기본으로 둔다. 즉, 원본 서버 코드를 이 저장소에 vendoring 하지 않고 skill/docs 가이드만 유지한다.

즉 기본 경로는 아래 둘 중 하나다.

1. npx --yes daiso ...
2. git clone https://github.com/hmmhmmhm/daiso-mcp.git && cd daiso-mcp && npm install && npm run build

먼저 필요한 것

• 인터넷 연결
• node 20 권장
• npx 또는 npm
• 필요하면 git

2026-04-05 기준 upstream package.json 의 engines.node 는 >=20 <21 이다. 로컬 Node 22 환경에서도 smoke test는 통과했지만 EBADENGINE 경고가 있었으므로, 운영 가이드는 Node 20 LTS 중심으로 적는다.

가장 빠른 시작: npx CLI

npx --yes daiso health
npx --yes daiso get /api/oliveyoung/stores --keyword 명동 --limit 5 --json
npx --yes daiso get /api/oliveyoung/products --keyword 선크림 --size 5 --json
npx --yes daiso get /api/oliveyoung/inventory --keyword 선크림 --storeKeyword 명동 --size 5 --json

반복 사용이면 전역 설치도 가능하다.

npm install -g daiso
export NODE_PATH="$(npm root -g)"
daiso health

원본 저장소 clone fallback

public endpoint 재시도, 버전 고정, 원본 확인이 필요하면 아래처럼 clone 후 build 결과물 dist/bin.js 를 node 로 직접 실행한다. clone checkout 안에서는 npx daiso ... 가 Permission denied 로 실패할 수 있으므로 이 경로를 기본으로 적는다.

git clone https://github.com/hmmhmmhm/daiso-mcp.git
cd daiso-mcp
npm install
npm run build
node dist/bin.js health
node dist/bin.js get /api/oliveyoung/stores --keyword 명동 --limit 5 --json
node dist/bin.js get /api/oliveyoung/products --keyword 선크림 --size 5 --json
node dist/bin.js get /api/oliveyoung/inventory --keyword 선크림 --storeKeyword 명동 --size 5 --json

입력값 권장 순서

1. 지역/매장 키워드
   • 예: 명동, 강남역, 성수
2. 상품 키워드
   • 예: 선크림, 립밤, 마스크팩

재고 질문인데 지역/매장 키워드가 없으면 먼저 지역을 보강한다. 상품 종류를 묻는 경우에는 먼저 /api/oliveyoung/products 로 후보를 보여주고, 재고 확인이 필요할 때 /api/oliveyoung/inventory 로 내려간다.

기본 흐름

1. health 확인

npx --yes daiso health

2. 매장 검색

npx --yes daiso get /api/oliveyoung/stores --keyword 명동 --limit 5 --json

3. 상품 검색

npx --yes daiso get /api/oliveyoung/products --keyword 선크림 --size 5 --json

응답에서는 goodsNumber, goodsName, priceToPay, imageUrl, inStock 를 먼저 본다.

4. 재고 확인

npx --yes daiso get /api/oliveyoung/inventory --keyword 선크림 --storeKeyword 명동 --size 5 --json

재고 응답에서는 inventory.products[].storeInventory.stores[] 안의 아래 필드를 우선 해석한다.

• stockLabel (재고 9개 이상, 품절, 미판매 등)
• remainQuantity
• stockStatus
• storeName

응답 정리 원칙

• 매장 후보가 많으면 상위 2~3개만 먼저 제시한다.
• 상품 후보가 많으면 가격, 이미지 URL, inStock 여부를 붙여 상위 3~5개만 요약한다.
• 재고는 재고 있음 / 품절 / 미판매 를 매장별로 분리해서 쓴다.
• imageUrl 이 있으면 query string(?l=ko)을 지우지 않는다.
• 공개 endpoint 특성상 방문 직전 재확인을 권한다.

라이브 확인 메모

2026-04-05 기준 아래 흐름을 실제로 실행해 응답을 확인했다.

• npx --yes daiso health → status: ok, endpoint https://mcp.aka.page/mcp
• local clone + build 후 node dist/bin.js get /api/oliveyoung/stores --keyword 명동 --limit 3 --json
  • 명동타임워크점, 명동2가점, 올리브영 명동 타운 등 매장 후보 확인
• local clone + build 후 node dist/bin.js get /api/oliveyoung/products --keyword 선크림 --size 3 --json
  • totalCount: 435, imageUrl, priceToPay, inStock 포함 상품 후보 확인
• local clone + build 후 node dist/bin.js get /api/oliveyoung/inventory --keyword 선크림 --storeKeyword 명동 --size 3 --json
  • stockLabel: 재고 9개 이상 / 품절 / 미판매, remainQuantity, storeName 확인

같은 날짜에 public npx --yes daiso get /api/oliveyoung/stores ... 는 한 차례 Zyte API 호출 실패: 503 Service Unavailable 를 반환했다. 그래서 문서 기본 경로는 여전히 CLI first 이지만, 재시도 또는 clone fallback 을 함께 안내한다.

제한사항

• public endpoint는 upstream 수집 인프라 상태에 따라 간헐적 5xx/503이 날 수 있다.
• 넓은 지역 키워드는 먼 지점까지 섞일 수 있다.
• 재고 수량은 실시간 100% 보장값이 아니다.
• 주문/결제 자동화는 다루지 않는다.

참고 링크

• 원본 repo: https://github.com/hmmhmmhm/daiso-mcp
• npm package: https://www.npmjs.com/package/daiso
• Olive Young stores API: https://mcp.aka.page/api/oliveyoung/stores
• Olive Young products API: https://mcp.aka.page/api/oliveyoung/products
• Olive Young inventory API: https://mcp.aka.page/api/oliveyoung/inventory