# 다이소 MCP API 다이소 제품 검색, 매장 찾기, 재고 확인을 위한 API입니다. 모든 요청은 GET 방식이며, 결과는 JSON으로 반환됩니다. Base URL: https://mcp.aka.page --- ## 사용 가능한 기능 ### 1. 제품 검색 **설명**: 키워드로 다이소 제품을 검색합니다. **URL**: https://mcp.aka.page/api/daiso/products?q={검색어} **필수 파라미터**: - q: 검색 키워드 (예: 수납박스, 펜, 정리함) **선택 파라미터**: - page: 페이지 번호 (기본값: 1) - pageSize: 페이지당 결과 수 (기본값: 30, 최대: 100) **예시**: - https://mcp.aka.page/api/daiso/products?q=수납박스 - https://mcp.aka.page/api/daiso/products?q=펜&page=2&pageSize=10 **응답 예시**: ```json { "success": true, "data": { "products": [ { "id": "1234567890", "name": "PP 수납박스 대형", "price": 5000, "imageUrl": "https://cdn.daisomall.co.kr/...", "soldOut": false, "isNew": false, "pickupAvailable": true } ] }, "meta": { "total": 150, "page": 1, "pageSize": 30 } } ``` --- ### 2. 제품 상세 정보 **설명**: 제품 ID로 상세 정보를 조회합니다. **URL**: https://mcp.aka.page/api/daiso/products/{제품ID} **예시**: - https://mcp.aka.page/api/daiso/products/1234567890 **응답 예시**: ```json { "success": true, "data": { "id": "1234567890", "name": "PP 수납박스 대형", "price": 5000, "currency": "KRW", "imageUrl": "https://cdn.daisomall.co.kr/...", "brand": "다이소", "soldOut": false, "isNew": false } } ``` --- ### 3. 매장 찾기 **설명**: 키워드 또는 지역으로 다이소 매장을 검색합니다. **URL**: https://mcp.aka.page/api/daiso/stores?keyword={키워드} **필수 파라미터** (둘 중 하나 필수): - keyword: 매장명 또는 주소 키워드 (예: 강남, 홍대, 안산) - sido: 시/도 (예: 서울, 경기, 부산) **선택 파라미터**: - gugun: 구/군 (예: 강남구, 마포구) - dong: 동 (예: 역삼동, 합정동) - limit: 최대 결과 수 (기본값: 50) **예시**: - https://mcp.aka.page/api/daiso/stores?keyword=강남 - https://mcp.aka.page/api/daiso/stores?sido=서울&gugun=마포구 - https://mcp.aka.page/api/daiso/stores?keyword=홍대&limit=10 **응답 예시**: ```json { "success": true, "data": { "stores": [ { "name": "다이소 강남역점", "phone": "02-1234-5678", "address": "서울특별시 강남구 강남대로 123", "lat": 37.4979, "lng": 127.0276, "openTime": "10:00", "closeTime": "22:00", "options": { "parking": true, "pickup": true, "taxFree": false } } ] }, "meta": { "total": 5 } } ``` --- ### 4. 재고 확인 **설명**: 특정 제품의 매장별 재고와 온라인 재고를 확인합니다. **URL**: https://mcp.aka.page/api/daiso/inventory?productId={제품ID} **필수 파라미터**: - productId: 제품 ID (제품 검색 API에서 조회한 id 값) **선택 파라미터**: - lat: 위도 (기본값: 37.5665, 서울 시청) - lng: 경도 (기본값: 126.978, 서울 시청) - keyword: 매장 검색어 (예: 안산, 강남) - page: 페이지 번호 (기본값: 1) - pageSize: 페이지당 결과 수 (기본값: 30) **주의**: - 다이소 재고 조회는 storeCode가 필요하지 않습니다. - storeCode는 재고 응답의 storeInventory.stores[].storeCode에서 확인한 뒤 진열 위치 조회에 사용합니다. - 안산 중앙역 같은 역명 키워드가 비면 안산중앙역, 안산중앙, 고잔처럼 붙여쓴 변형으로 재시도하세요. **예시**: - https://mcp.aka.page/api/daiso/inventory?productId=1234567890 - https://mcp.aka.page/api/daiso/inventory?productId=1234567890&lat=37.3219&lng=126.8309 - https://mcp.aka.page/api/daiso/inventory?productId=1234567890&keyword=안산 **응답 예시**: ```json { "success": true, "data": { "productId": "1234567890", "product": { "id": "1234567890", "name": "PP 수납박스 대형", "imageUrl": "https://cdn.daisomall.co.kr/...", "brand": "다이소", "soldOut": false, "isNew": false }, "location": { "latitude": 37.5665, "longitude": 126.978 }, "onlineStock": 150, "storeInventory": { "totalStores": 25, "inStockCount": 18, "stores": [ { "storeCode": "ST001", "storeName": "다이소 강남역점", "address": "서울특별시 강남구...", "distance": "0.5km", "quantity": 12, "options": { "parking": true, "pickup": true } } ] } }, "meta": { "total": 25, "page": 1, "pageSize": 30 } } ``` --- ### 4-1. 진열 위치 조회 **설명**: 특정 상품이 특정 매장 내 어디에 진열되어 있는지(구역/층) 조회합니다. **URL**: https://mcp.aka.page/api/daiso/display-location?productId={제품ID}&storeCode={매장코드} **필수 파라미터**: - productId: 제품 ID (제품 검색 API에서 조회한 id 값) - storeCode: 매장 코드 (재고 확인 API 결과의 storeCode 값) **예시**: - https://mcp.aka.page/api/daiso/display-location?productId=1234567890&storeCode=04515 --- ### 5. 올리브영 매장 찾기 **설명**: 위치 기반으로 주변 올리브영 매장을 검색합니다. **URL**: https://mcp.aka.page/api/oliveyoung/stores?keyword={키워드} **선택 파라미터**: - keyword: 매장명/지역 키워드 (예: 명동, 강남) - lat: 위도 (기본값: 37.5665) - lng: 경도 (기본값: 126.978) - pageIdx: 페이지 번호 (기본값: 1) - limit: 최대 결과 수 (기본값: 20) **예시**: - https://mcp.aka.page/api/oliveyoung/stores?keyword=명동 - https://mcp.aka.page/api/oliveyoung/stores?lat=37.498&lng=127.027&limit=5 --- ### 6. 올리브영 상품 검색 **설명**: 키워드로 올리브영 상품 목록을 조회합니다. 사용자가 "올리브영 마스크팩 어떤 거 있나요", "립밤 종류 보여줘"처럼 상품 후보나 종류를 묻는 경우에는 이 API를 먼저 사용하세요. **표시 규칙**: - 응답의 `products[].imageUrl`이 있으면 각 상품 이미지를 반드시 마크다운 이미지로 함께 렌더링합니다. - 여러 상품이 나오면 첫 상품만 대표로 보여주지 말고, 이미지가 있는 상품은 전부 표시합니다. **URL**: https://mcp.aka.page/api/oliveyoung/products?keyword={검색어} **필수 파라미터**: - keyword: 상품 검색어 (예: 마스크팩, 선크림, 립밤) **선택 파라미터**: - page: 상품 검색 페이지 (기본값: 1) - size: 페이지당 상품 수 (기본값: 20) - sort: 정렬 코드 (기본값: 01) - includeSoldOut: 품절 포함 여부 (기본값: false) **예시**: - https://mcp.aka.page/api/oliveyoung/products?keyword=마스크팩 - https://mcp.aka.page/api/oliveyoung/products?keyword=립밤&size=10 --- ### 7. 올리브영 재고 확인 **설명**: 상품 키워드 기준 올리브영 재고를 조회하고 주변 매장 목록을 함께 반환합니다. 상위 상품에는 storeInventory가 포함되며 매장별 재고 3개, 재고 9개 이상, 품절, 미판매 같은 상태를 제공합니다. **URL**: https://mcp.aka.page/api/oliveyoung/inventory?keyword={검색어} **필수 파라미터**: - keyword: 상품 검색어 (예: 선크림, 립밤) **선택 파라미터**: - lat: 위도 (기본값: 37.5665) - lng: 경도 (기본값: 126.978) - storeKeyword: 매장 필터 키워드 - page: 상품 검색 페이지 (기본값: 1) - size: 페이지당 결과 수 (기본값: 20) - includeSoldOut: 품절 포함 여부 (기본값: false) **예시**: - https://mcp.aka.page/api/oliveyoung/inventory?keyword=선크림 - https://mcp.aka.page/api/oliveyoung/inventory?keyword=립밤&storeKeyword=명동 --- ### 6-0. 키 없는 통합 상품 가격 후보 비교 **설명**: 새 외부 API 키 없이 기존 다이소, GS25, 세븐일레븐, 이마트24 상품 검색을 묶어 가격 후보를 비교합니다. 실제 매장 재고와 행사가까지 확정하는 기능이 아니라 "어디가 싸 보이는지"를 빠르게 고르는 1차 검색입니다. **URL**: - https://mcp.aka.page/api/compare/products?keyword={검색어} **선택 파라미터**: - services: daiso,gs25,seveneleven,emart24 중 쉼표 구분 목록 - limit: 서비스별 최대 결과 수 (기본값: 5) **예시**: - https://mcp.aka.page/api/compare/products?keyword=콜라&limit=3 - https://mcp.aka.page/api/compare/products?keyword=컵라면&services=seveneleven,emart24 --- ### 6-1. 주변 음식점/카페 검색 **설명**: 네이버 지역 검색으로 특정 지역의 음식점, 카페, 디저트 가게 등 주변 장소를 조회합니다. 좌표 반경 검색이 아니라 `강남역 카페` 같은 키워드 기반 검색입니다. **URL**: - https://mcp.aka.page/api/places/search?location={지역}&category={카테고리} - https://mcp.aka.page/api/places/search?location={지역}&keyword={검색어} **선택 파라미터**: - location: 지역/역/주소 키워드 (예: 강남역, 성수동) - category: restaurant, cafe, food, dessert, all - keyword: 직접 검색어 (예: 라멘, 브런치, 조용한 카페) - limit: 최대 결과 수 (기본값: 5, 네이버 지역 검색 최대 5) - sort: random 또는 comment **예시**: - https://mcp.aka.page/api/places/search?location=강남역&category=cafe&limit=5 - https://mcp.aka.page/api/places/search?location=성수동&keyword=브런치&limit=5 --- ### 6-2. 롯데마트 매장/상품 조회 **설명**: 롯데마트 계열 매장 검색과 특정 매장 기준 상품 가격/재고 조회를 제공합니다. **URL**: - https://mcp.aka.page/api/lottemart/stores?keyword={키워드} - https://mcp.aka.page/api/lottemart/products?keyword={검색어}&storeName={매장명} **선택 파라미터**: - area: 지역 (예: 서울, 경기, 제주) - brandVariant: lottemart, toysrus, max, bottlebunker, mealguru, grandgrocery - lat: 위도 (선택) - lng: 경도 (선택) - limit: 최대 결과 수 (기본값: 20) - storeCode 또는 storeName: 상품 검색 대상 매장 - pageLimit: 추가 조회할 최대 페이지 수 (기본값: 3) - source: 상품 검색 경로 (auto, legacy, zetta). 빠른 검색이나 헬스체크에는 zetta 권장 **예시**: - https://mcp.aka.page/api/lottemart/stores?keyword=잠실&area=서울&limit=10 - https://mcp.aka.page/api/lottemart/stores?area=경기&brandVariant=lottemart&limit=10 - https://mcp.aka.page/api/lottemart/products?keyword=콜라&storeName=강변점&area=서울 - https://mcp.aka.page/api/lottemart/products?keyword=우유&storeCode=2301&pageLimit=2&source=zetta --- ### 6-3. GS25 매장/상품/재고 조회 **설명**: GS25 매장 탐색, 상품 키워드 검색, 재고 조회를 제공합니다. **URL**: - https://mcp.aka.page/api/gs25/stores?keyword={키워드} - https://mcp.aka.page/api/gs25/products?keyword={검색어} - https://mcp.aka.page/api/gs25/inventory?keyword={검색어} - https://mcp.aka.page/api/gs25/inventory?itemCode={상품코드} **선택 파라미터(공통)**: - lat: 위도 (선택) - lng: 경도 (선택) - limit / storeLimit: 최대 결과 수 - serviceCode: 서비스 코드 (기본값: 01) **예시**: - https://mcp.aka.page/api/gs25/stores?keyword=강남&limit=10 - https://mcp.aka.page/api/gs25/products?keyword=오감자&limit=20 - https://mcp.aka.page/api/gs25/inventory?keyword=오감자&storeKeyword=강남&storeLimit=10 - https://mcp.aka.page/api/gs25/inventory?itemCode=8801056038861&storeKeyword=안산%20중앙역&storeLimit=10 --- ### 6-4. 세븐일레븐 상품/매장/재고/인기검색어/카탈로그 조회 **설명**: 세븐일레븐 상품 검색, 매장 검색, 재고 수량 조회, 인기 검색어, 카탈로그 스냅샷을 제공합니다. **URL**: - https://mcp.aka.page/api/seveneleven/products?query={검색어} - https://mcp.aka.page/api/seveneleven/stores?keyword={매장키워드} - https://mcp.aka.page/api/seveneleven/inventory?keyword={검색어} - https://mcp.aka.page/api/seveneleven/popwords?label={라벨} - https://mcp.aka.page/api/seveneleven/catalog?includeIssues={true|false}&includeExhibition={true|false}&limit={개수} **선택 파라미터**: - page: 페이지 번호 (기본값: 1) - size: 페이지당 결과 수 (기본값: 20) - sort: 정렬 기준 (기본값: recommend) - storeKeyword: 매장명/지역 키워드 - storeLimit: 최대 매장 수 (기본값: 20) - timeoutMs: 요청 제한 시간 (기본값: 20000) - label: 인기 검색어 라벨 (기본값: home) **예시**: - https://mcp.aka.page/api/seveneleven/products?query=삼각김밥&size=20 - https://mcp.aka.page/api/seveneleven/stores?keyword=안산%20중앙역&limit=10 - https://mcp.aka.page/api/seveneleven/inventory?keyword=핫식스&storeKeyword=안산%20중앙역&storeLimit=10 - https://mcp.aka.page/api/seveneleven/popwords?label=home - https://mcp.aka.page/api/seveneleven/catalog?includeIssues=true&includeExhibition=true&limit=10 --- ### 7. 메가박스 주변 지점 찾기 **설명**: 사용자 좌표 또는 위치 키워드 기준으로 메가박스 지점을 거리순으로 조회합니다. **URL**: https://mcp.aka.page/api/megabox/theaters?lat={위도}&lng={경도} **선택 파라미터**: - keyword: 위치 키워드 (예: 안산 중앙역, 강남역) - lat: 위도 (기본값: 37.5665) - lng: 경도 (기본값: 126.978) - playDate: 조회 날짜 (YYYYMMDD, 기본값: 오늘) - areaCode: 지역 코드 (기본값: 11, 서울) - limit: 최대 결과 수 (기본값: 10) **예시**: - https://mcp.aka.page/api/megabox/theaters?keyword=안산%20중앙역&limit=5 - https://mcp.aka.page/api/megabox/theaters?lat=37.4982&lng=127.0264 - https://mcp.aka.page/api/megabox/theaters?areaCode=11&limit=5 --- ### 8. 메가박스 영화/회차 목록 **설명**: 날짜/지점 조건으로 메가박스 영화와 상영 회차를 조회합니다. theaterId가 없고 위치 키워드/좌표가 있으면 가장 가까운 지점을 먼저 선택합니다. **URL**: https://mcp.aka.page/api/megabox/movies?playDate={YYYYMMDD} **선택 파라미터**: - playDate: 조회 날짜 (YYYYMMDD, 기본값: 오늘) - theaterId: 지점 ID (예: 1372) - movieId: 영화 ID (예: 25104500) - keyword: 위치 키워드 (예: 안산 중앙역, 강남역) - lat: 위도 - lng: 경도 - areaCode: 지역 코드 (기본값: 11) **예시**: - https://mcp.aka.page/api/megabox/movies?playDate=20260315&keyword=안산%20중앙역 - https://mcp.aka.page/api/megabox/movies?playDate=20260304&theaterId=1372 - https://mcp.aka.page/api/megabox/movies?playDate=20260304&movieId=25104500 --- ### 9. 메가박스 잔여 좌석 조회 **설명**: 영화/지점/날짜 기준으로 회차별 잔여 좌석 수를 조회합니다. theaterId가 없고 위치 키워드/좌표가 있으면 가장 가까운 지점을 먼저 선택합니다. **URL**: https://mcp.aka.page/api/megabox/seats?playDate={YYYYMMDD} **선택 파라미터**: - playDate: 조회 날짜 (YYYYMMDD, 기본값: 오늘) - theaterId: 지점 ID - movieId: 영화 ID - keyword: 위치 키워드 (예: 안산 중앙역, 강남역) - lat: 위도 - lng: 경도 - areaCode: 지역 코드 (기본값: 11) - limit: 최대 결과 수 (기본값: 50) **예시**: - https://mcp.aka.page/api/megabox/seats?playDate=20260315&keyword=안산%20중앙역 - https://mcp.aka.page/api/megabox/seats?playDate=20260304&theaterId=1372 - https://mcp.aka.page/api/megabox/seats?playDate=20260304&movieId=25104500&limit=20 --- ### 10. CGV 극장 검색 **설명**: 지역 코드 또는 위치 키워드 기준으로 CGV 극장 목록을 조회합니다. **URL**: https://mcp.aka.page/api/cgv/theaters?playDate={YYYYMMDD} **선택 파라미터**: - playDate: 조회 날짜 (YYYYMMDD, 기본값: 오늘) - regionCode: 지역 코드 (예: 01) - keyword: 위치 키워드 (예: 안산 중앙역, 강남역) - lat: 위도 - lng: 경도 - limit: 최대 결과 수 (기본값: 30) **예시**: - https://mcp.aka.page/api/cgv/theaters?playDate=20260304®ionCode=01 - https://mcp.aka.page/api/cgv/theaters?playDate=20260315&keyword=안산%20중앙역 - https://mcp.aka.page/api/cgv/theaters?playDate=20260304&limit=10 --- ### 11. CGV 영화 검색 **설명**: 날짜/극장 조건으로 CGV 영화 목록을 조회합니다. theaterCode가 없으면 keyword 또는 lat,lng 기준으로 가장 가까운 극장을 먼저 선택합니다. **URL**: https://mcp.aka.page/api/cgv/movies?playDate={YYYYMMDD} **선택 파라미터**: - playDate: 조회 날짜 (YYYYMMDD, 기본값: 오늘) - theaterCode: 극장 코드 (예: 0056) - keyword: 위치 키워드 (예: 안산 중앙역, 강남역) - lat: 위도 - lng: 경도 **예시**: - https://mcp.aka.page/api/cgv/movies?playDate=20260304&theaterCode=0056 - https://mcp.aka.page/api/cgv/movies?playDate=20260315&keyword=안산%20중앙역 --- ### 12. CGV 시간표 조회 **설명**: 날짜/극장/영화 조건으로 CGV 상영 시간표를 조회합니다. theaterCode가 없으면 keyword 또는 lat,lng 기준으로 가장 가까운 극장을 먼저 선택합니다. 잔여 좌석은 각 회차의 `remainingSeats` 필드로 함께 내려옵니다. **URL**: https://mcp.aka.page/api/cgv/timetable?playDate={YYYYMMDD} **선택 파라미터**: - playDate: 조회 날짜 (YYYYMMDD, 기본값: 오늘) - theaterCode: 극장 코드 (예: 0056) - movieCode: 영화 코드 - keyword: 위치 키워드 (예: 안산 중앙역, 강남역) - lat: 위도 - lng: 경도 - limit: 최대 결과 수 (기본값: 50) **예시**: - https://mcp.aka.page/api/cgv/timetable?playDate=20260304&theaterCode=0056 - https://mcp.aka.page/api/cgv/timetable?playDate=20260315&keyword=안산%20중앙역 - https://mcp.aka.page/api/cgv/timetable?playDate=20260304&movieCode=200001 --- ### 13. 롯데시네마 주변 지점 찾기 **설명**: 위치 키워드 또는 사용자 좌표 기준으로 롯데시네마 지점을 거리순으로 조회합니다. **URL**: https://mcp.aka.page/api/lottecinema/theaters?keyword={위치키워드} **선택 파라미터**: - keyword: 위치 키워드 (예: 안산 중앙역, 잠실역) - lat: 위도 (keyword가 없을 때 기본값: 37.5665) - lng: 경도 (keyword가 없을 때 기본값: 126.978) - playDate: 조회 날짜 (YYYYMMDD, 기본값: 오늘) - limit: 최대 결과 수 (기본값: 10) **예시**: - https://mcp.aka.page/api/lottecinema/theaters?keyword=안산%20중앙역 - https://mcp.aka.page/api/lottecinema/theaters?lat=37.5133&lng=127.1042 --- ### 14. 롯데시네마 영화/회차 목록 **설명**: 날짜/지점/영화 조건으로 롯데시네마 영화와 상영 회차를 조회합니다. theaterId가 없으면 위치 키워드 기준 최근접 지점을 선택할 수 있습니다. **URL**: https://mcp.aka.page/api/lottecinema/movies?playDate={YYYYMMDD} **선택 파라미터**: - playDate: 조회 날짜 (YYYYMMDD, 기본값: 오늘) - theaterId: 지점 ID (예: 1016) - movieId: 대표 영화 코드 (예: 23816) - keyword: 위치 키워드 (예: 안산 중앙역) - lat: 위도 (theaterId가 없을 때 사용) - lng: 경도 (theaterId가 없을 때 사용) **예시**: - https://mcp.aka.page/api/lottecinema/movies?playDate=20260315&keyword=안산%20중앙역 - https://mcp.aka.page/api/lottecinema/movies?playDate=20260310&theaterId=1016 - https://mcp.aka.page/api/lottecinema/movies?playDate=20260310&theaterId=1016&movieId=23816 --- ### 15. 롯데시네마 잔여 좌석 조회 **설명**: 영화/지점/날짜 기준으로 회차별 잔여 좌석 수를 조회합니다. theaterId가 없으면 위치 키워드 기준 최근접 지점을 선택할 수 있습니다. **URL**: https://mcp.aka.page/api/lottecinema/seats?playDate={YYYYMMDD} **선택 파라미터**: - playDate: 조회 날짜 (YYYYMMDD, 기본값: 오늘) - theaterId: 지점 ID - movieId: 대표 영화 코드 - keyword: 위치 키워드 (예: 안산 중앙역) - lat: 위도 (theaterId가 없을 때 사용) - lng: 경도 (theaterId가 없을 때 사용) - limit: 최대 결과 수 (기본값: 50) **예시**: - https://mcp.aka.page/api/lottecinema/seats?playDate=20260315&keyword=안산%20중앙역 - https://mcp.aka.page/api/lottecinema/seats?playDate=20260310&theaterId=1016&movieId=23816 --- ## 응답 형식 ### 성공 응답 ```json { "success": true, "data": { ... }, "meta": { "total": 100, "page": 1, "pageSize": 30 } } ``` ### 에러 응답 ```json { "success": false, "error": { "code": "ERROR_CODE", "message": "에러 메시지" } } ``` ### 에러 코드 | 코드 | 설명 | |------|------| | MISSING_QUERY | 검색어가 누락됨 | | MISSING_PARAMS | 필수 파라미터 누락 | | MISSING_PRODUCT_ID | 제품 ID 누락 | | MISSING_STORE_CODE | 매장 코드 누락 | | NOT_FOUND | 결과를 찾을 수 없음 | | SEARCH_FAILED | 검색 실패 | | FETCH_FAILED | 데이터 조회 실패 | | DISPLAY_LOCATION_FAILED | 진열 위치 조회 실패 | | OLIVEYOUNG_STORE_SEARCH_FAILED | 올리브영 매장 조회 실패 | | OLIVEYOUNG_PRODUCT_SEARCH_FAILED | 올리브영 상품 조회 실패 | | OLIVEYOUNG_INVENTORY_CHECK_FAILED | 올리브영 재고 조회 실패 | | MEGABOX_THEATER_SEARCH_FAILED | 메가박스 지점 조회 실패 | | MEGABOX_MOVIE_LIST_FAILED | 메가박스 영화 목록 조회 실패 | | MEGABOX_SEAT_LIST_FAILED | 메가박스 좌석 조회 실패 | | LOTTECINEMA_THEATER_SEARCH_FAILED | 롯데시네마 지점 조회 실패 | | LOTTECINEMA_MOVIE_LIST_FAILED | 롯데시네마 영화 목록 조회 실패 | | LOTTECINEMA_SEAT_LIST_FAILED | 롯데시네마 좌석 조회 실패 | | CGV_THEATER_SEARCH_FAILED | CGV 극장 조회 실패 | | CGV_MOVIE_SEARCH_FAILED | CGV 영화 목록 조회 실패 | | CGV_TIMETABLE_FETCH_FAILED | CGV 시간표 조회 실패 | | GS25_STORE_SEARCH_FAILED | GS25 매장 조회 실패 | | GS25_PRODUCT_SEARCH_FAILED | GS25 상품 조회 실패 | | GS25_INVENTORY_CHECK_FAILED | GS25 재고 조회 실패 | | LOTTEMART_STORE_SEARCH_FAILED | 롯데마트 매장 조회 실패 | | LOTTEMART_PRODUCT_SEARCH_FAILED | 롯데마트 상품 조회 실패 | | SEVENELEVEN_INVENTORY_CHECK_FAILED | 세븐일레븐 재고 조회 실패 | | PLACES_SEARCH_FAILED | 주변 장소 검색 실패 | | DEVELOPER_REQUEST_SUBMIT_FAILED | 개발자 요청 저장 실패 | --- ## 에이전트 실행 레시피 - "콜라 어디가 싸?", "컵라면 가격 비교해줘": 먼저 `compare_products` 또는 /api/compare/products를 호출합니다. 실제 재고와 매장 행사가가 필요하면 최저가 후보의 서비스별 재고/상품 도구로 한 번 더 확인합니다. - "강남역 근처 카페", "성수동 브런치 음식점": 브랜드를 되묻지 말고 `places_search_nearby` 또는 /api/places/search를 호출합니다. 이 검색은 키워드 기반이므로 좌표 반경 결과처럼 단정하지 않습니다. - "다이소 핫식스 재고", "올리브영 두바이초콜릿 있어?": 상품이 브랜드와 어색해 보여도 브랜드를 바꾸지 말고 먼저 다이소로 검색하거나 명시된 서비스로 검색합니다. 결과가 없을 때만 다른 서비스 대안을 제안합니다. - "GS25 강남 오감자 재고": 상품명과 위치를 분리해 상품 후보를 먼저 찾고, 선택한 itemCode나 keyword와 storeKeyword로 재고를 확인합니다. - "오늘 강남 CGV 시간표": 오늘 날짜는 KST 기준 YYYYMMDD로 계산하고, theaterCode가 없으면 극장 검색 후 시간표를 조회합니다. - MCP 기능이 제대로 동작하지 않거나 개선/신규 기능 요청이 있으면 `submit_developer_request` 또는 /api/feedback/requests를 사용해 개발자에게 전달합니다. 제목과 설명은 필수입니다. - 도구 호출이 실패하면 같은 도구를 한 번 더 좁은 조건으로 재시도합니다. 두 번 실패하면 실패한 서비스와 요청 조건을 밝히고 추측으로 결과를 만들지 않습니다. - 결과에 imageUrl이 있으면 각 항목 이미지 표시를 우선합니다. 쿼리 문자열이 있는 이미지 URL도 그대로 사용합니다. --- ## 사용 팁 1. **한글 검색어**: URL 인코딩이 자동으로 처리됩니다 2. **페이지네이션**: 결과가 많을 경우 page 파라미터 사용 3. **브랜드 고정**: 사용자가 "다이소에서", "GS25에서"처럼 브랜드를 명시하면 품목상 어색해 보여도 먼저 그 브랜드에서 실제 검색/조회하고, 결과가 없을 때만 다른 브랜드 대안을 짧게 제안합니다. - 금지: "핫식스는 다이소가 아니라 편의점 상품이라서 조회할 수 없습니다"처럼 사전 판단으로 검색을 거부 - 원칙: 브랜드가 명시되면 일단 해당 브랜드에서 실제 조회 후, 결과가 없을 때만 다른 브랜드 제안 - 확장 해석: "안산 중앙역 주변 다이소 찾아주시고 핫식스 재고 찾아주세요"처럼 브랜드가 앞부분에만 나와도 뒤 요청 전체를 다이소 기준으로 처리 4. **이미지 적극 표시**: - **규칙 1**: MCP/REST 응답에 `imageUrl`이 있으면 반드시 마크다운 이미지로 렌더링하세요. - **규칙 2**: 사용자가 따로 요청하기 전까지 이미지를 임의로 생략하지 마세요. - **규칙 3**: 이미지가 여러 개이면 첫 번째만 대표로 보여주지 말고 각 항목의 이미지를 전부 표시하세요. - **규칙 4**: "길어서 일부만 표시", "대표 이미지만 표시", "나머지는 생략" 같은 동작을 하지 마세요. - **규칙 5**: 텍스트 요약보다 이미지 표시 의무가 우선이며, 이미지가 있으면 답변 길이 때문에라도 빼지 마세요. - **규칙 6**: `imageUrl`에 query string이 있으면 `?l=ko` 같은 쿼리를 절대 삭제하거나 정규화하지 말고, 마크다운 이미지 src에 전체 URL을 그대로 사용하세요. - **규칙 7**: 이미지 src를 비교하거나 캐시 키를 판단할 때도 hostname + pathname만 쓰지 말고 query string까지 포함한 전체 URL을 기준으로 취급하세요. 5. **재고 확인 워크플로우**: - 먼저 /api/daiso/products로 제품 검색 - 결과에서 원하는 제품의 id 확인 - /api/daiso/inventory에 해당 id로 재고 조회 - 진열 위치가 필요하면 재고 응답의 storeCode를 확인한 뒤 /api/daiso/display-location에 productId + storeCode로 조회 - 다이소 재고 조회는 storeCode가 필요하지 않습니다. 6. **최소 정보 요청 처리**: - 사용자가 상품명만 주면 먼저 상품 검색 도구로 후보를 찾고, 응답의 productId/itemCode/pluCd를 다음 단계에 전달합니다. - 사용자가 위치를 대강 말하면 keyword/storeKeyword에 그대로 넣어 먼저 조회하고, 결과가 없을 때만 공백 제거, 역/점 접미어 제거 같은 변형을 시도합니다. - 도구가 productId, itemCode, storeCode 같은 내부 ID를 요구하면 사용자에게 바로 ID를 요구하지 말고, 검색/재고 응답에서 먼저 확인합니다. - "근처", "주변"처럼 위치가 없는 표현만 있으면 기본 좌표 결과를 단정하지 말고 사용자의 지역/역명/좌표를 물어봅니다. 7. **상품명 단계 검색**: - 재고 검색은 어떤 서비스이든 검색어 전체를 먼저 그대로 조회하고, 실패할 때만 공백/브랜드어 제거, 표기 변형, 더 짧은 핵심어 순으로 단계적으로 넓혀서 다시 시도합니다. - 너무 넓은 축약어로만 매칭된 경우에는 확정 상품처럼 단정하지 말고, 추정 매칭임을 짧게 밝힌 뒤 재고를 안내합니다. - 위치/브랜드/상품명은 한 인자에 섞지 말고 가능한 한 분리해서 도구에 전달합니다. 8. **위치 기반 재고**: lat, lng 파라미터로 가까운 매장 우선 조회 9. **롯데마트 상품 조회**: /api/lottemart/products는 keyword와 함께 storeCode 또는 storeName이 필요합니다. 10. **세븐일레븐 재고 조회**: /api/seveneleven/inventory에 keyword + storeKeyword를 함께 주면 매장별 수량을 바로 확인할 수 있습니다. 11. **이마트24 재고 조회**: /api/emart24/inventory는 pluCd + storeKeyword 조합도 지원하므로, 상품 선택 뒤 매장 코드를 다시 모으지 않아도 됩니다. 12. **올리브영 재고 해석**: inventory.products[].storeInventory.stores[]가 있으면 그 매장별 stockLabel과 remainQuantity를 우선 사용하고, inStock는 그 주변 매장 기준 결과로 해석합니다. 13. **올리브영 상품 이미지 표시**: /api/oliveyoung/products 또는 oliveyoung_search_products 결과에 imageUrl이 있으면 목록형 답변에서도 각 상품 이미지를 생략하지 말고 모두 렌더링합니다. 특히 `?l=ko` 같은 query string을 삭제하지 말고 전체 URL 그대로 마크다운 이미지 src에 넣습니다. 14. **통합 가격 후보 비교**: 사용자가 브랜드를 특정하지 않고 "어디가 싸?", "비교해줘"처럼 물으면 `compare_products` 또는 /api/compare/products를 먼저 사용합니다. 새 외부 키 없이 기존 상품 검색을 묶은 1차 가격 후보이므로 실제 재고/행사가는 각 서비스 상세 조회로 확인해야 합니다. 15. **주변 음식점/카페 검색**: 음식점이나 카페만 물으면 `places_search_nearby` 또는 /api/places/search를 먼저 사용합니다. 이 기능은 네이버 지역 검색 기반 키워드 검색이므로 좌표 반경 검색처럼 단정하지 말고, `searchMode: "keyword"`임을 필요할 때 짧게 밝혀주세요. --- ## MCP 지원 서비스 MCP를 지원하는 AI 에이전트(Claude 등)는 더 풍부한 기능을 사용할 수 있습니다. MCP 연결 정보: https://mcp.aka.page/mcp 지원 도구: - daiso_search_products: 제품 검색 - daiso_find_stores: 매장 검색 - daiso_check_inventory: 재고 확인 - daiso_get_price_info: 가격 정보 조회 - daiso_get_display_location: 진열 위치 조회 - lottemart_find_nearby_stores: 롯데마트 주변 매장 탐색 - lottemart_search_products: 롯데마트 상품 검색 - gs25_find_nearby_stores: GS25 주변 매장 탐색 - gs25_search_products: GS25 상품 검색 - gs25_check_inventory: GS25 재고 조회 - seveneleven_search_products: 세븐일레븐 상품 검색 - seveneleven_search_stores: 세븐일레븐 매장 검색 - seveneleven_check_inventory: 세븐일레븐 재고 조회 - seveneleven_get_search_popwords: 세븐일레븐 인기 검색어 조회 - seveneleven_get_catalog_snapshot: 세븐일레븐 카탈로그 조회 - compare_products: 키 없는 통합 상품 가격 후보 비교 - submit_developer_request: MCP 오류, 개선 요청, 신규 기능 요청을 개발자에게 전달 - places_search_nearby: 음식점/카페 등 주변 장소 검색 - oliveyoung_search_products: 올리브영 상품 검색 - oliveyoung_find_nearby_stores: 올리브영 주변 매장 탐색 - oliveyoung_check_inventory: 올리브영 재고 파악 - megabox_find_nearby_theaters: 메가박스 주변 지점 탐색 - megabox_list_now_showing: 메가박스 영화 목록 조회 - megabox_get_remaining_seats: 메가박스 잔여 좌석 조회 - lottecinema_find_nearby_theaters: 롯데시네마 주변 지점 탐색 - lottecinema_list_now_showing: 롯데시네마 영화 목록 조회 - lottecinema_get_remaining_seats: 롯데시네마 잔여 좌석 조회 - cgv_find_theaters: CGV 극장 검색 - cgv_search_movies: CGV 영화 검색 - cgv_get_timetable: CGV 시간표 조회