daiso 1.0.4 → 1.0.6

package/README.md

@@ -5,18 +5,40 @@
 <br>
 <br>
 
-# Daiso MCP Server
+# Daiso MCP 및 Skill
 
-다이소(제품/매장/재고), 올리브영(매장/재고), 메가박스(지점/영화/시간표/좌석), CGV(극장/영화/시간표) 조회 기능을 AI에 연결합니다.
+다이소(제품/매장/재고), 롯데마트(매장/상품), GS25(매장/상품/재고), 세븐일레븐(상품/매장/재고/인기검색어/카탈로그), CU(매장/재고), 이마트24(매장/상품/재고), 올리브영(매장/재고), 메가박스(지점/영화/시간표/좌석), 롯데시네마(지점/영화/좌석), CGV(극장/영화/시간표) 조회 기능을 MCP, CLI, Codex Skill로 AI에 연결합니다.
+
+<br>
+
+**MCP:** `https://mcp.aka.page` · **CLI:** `npx daiso` · **Skill:** `clawhub install daiso-cli`
+
+**ClawHub:** [clawhub.ai/hmmhmmhm/daiso-cli](https://clawhub.ai/hmmhmmhm/daiso-cli)
+
+한국 로컬 리테일과 영화관 조회를 MCP, CLI, Codex Skill로 연결하는 도구입니다.
 
 <br>
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Cloudflare Workers](https://img.shields.io/badge/Cloudflare-Workers-F38020.svg)](https://workers.cloudflare.com/)
 [![MCP](https://img.shields.io/badge/MCP-Protocol-8B5CF6.svg)](https://modelcontextprotocol.io/)
+[![Code Coverage](https://img.shields.io/badge/Code%20Coverage-100%25-brightgreen.svg)](https://github.com/hmmhmmhm/daiso-mcp/actions/workflows/coverage.yml)
 [![Coverage](https://github.com/hmmhmmhm/daiso-mcp/actions/workflows/coverage.yml/badge.svg?branch=main)](https://github.com/hmmhmmhm/daiso-mcp/actions/workflows/coverage.yml)
+[![Better Stack Badge](https://uptime.betterstack.com/status-badges/v2/monitor/2mmhx.svg)](https://aka-page.betteruptime.com/)
+
+**[실시간 서비스 상태 보기](https://aka-page.betteruptime.com/)**
+
+<!-- WORKERS_INVOCATIONS_CHART:START -->
+<h3>Cloudflare Workers 호출량 (2026-03-01 ~ 2026-05-19, 80일)</h3>
+
+<img src="./assets/analytics/workers-invocations.png?v=2026-05-19T16:35:34.414Z" alt="Cloudflare Workers 호출량 그래프 (2026-03-01 ~ 2026-05-19)" width="100%">
+
+<sub>기준 워커: <code>daiso-mcp</code> · 마지막 갱신: 2026-05-20 01:35 KST</sub>
+
+<!-- WORKERS_INVOCATIONS_CHART:END -->
 
 <br>
+
 <br>
 
 <img src="https://i.imgur.com/mPwS4Kv.png" width="400">&nbsp;&nbsp;<img src="https://i.imgur.com/MrndJ3g.png" width="400">
@@ -31,31 +53,8 @@
 
 ## AI 앱에서 MCP 연결하기
 
-MCP 서버 URL:
-
-```
-https://mcp.aka.page
-```
-
-CLI (npx):
-
-```bash
-npx daiso help
-npx daiso help products
-npx daiso url
-npx daiso health
-npx daiso claude
-
-# AI 없이 직접 조회
-npx daiso products 수납박스
-npx daiso product 1034604
-npx daiso stores 강남역
-npx daiso inventory 1034604 --keyword 강남역
-npx daiso get /api/cgv/movies --playDate 20260307 --theaterCode 0056
-
-# 원본 JSON 필요 시
-npx daiso products 수납박스 --json
-```
+ChatGPT, Claude, Grok 같은 AI 앱에서 바로 연결해 사용할 수 있습니다.
+아래 앱별 가이드에서 먼저 연동한 뒤 검색/재고/영화 조회를 요청하세요.
 
 <br>
 
@@ -71,7 +70,17 @@ npx daiso products 수납박스 --json
 ```
 다이소 mcp로 수납박스 검색해줘
 올리브영 mcp로 명동 근처 매장 찾아줘
+이마트24 mcp로 강남 근처 매장과 두바이 재고 알려줘
+롯데마트 mcp로 잠실 근처 매장 찾아줘
+롯데마트 mcp로 강변점에서 콜라 재고 알려줘
+GS25 mcp로 강남 근처 매장과 오감자 재고 알려줘
+세븐일레븐 mcp로 삼각김밥 검색해줘
+세븐일레븐 mcp로 안산 중앙역 근처 매장 찾아줘
+세븐일레븐 mcp로 안산 중앙역 근처 세븐일레븐에서 핫식스 재고 알려줘
+세븐일레븐 mcp로 인기 검색어와 카탈로그 요약 알려줘
 메가박스 mcp로 강남점 영화와 잔여 좌석 알려줘
+롯데시네마 mcp로 월드타워 근처 지점과 상영 영화 알려줘
+롯데시네마 mcp로 월드타워 잔여 좌석 알려줘
 CGV mcp로 강남 상영 영화와 시간표 알려줘
 ```
 
@@ -94,8 +103,15 @@ CGV mcp로 강남 상영 영화와 시간표 알려줘
 다이소 mcp를 사용해서 강남역 근처 매장 찾아줘
 올리브영 mcp를 사용해서 명동 근처 매장 찾아줘
 올리브영 mcp를 사용해서 선크림 재고 확인해줘
+이마트24 mcp를 사용해서 강남 매장 찾고 두바이 재고 확인해줘
+롯데마트 mcp를 사용해서 잠실 근처 매장 찾아줘
+롯데마트 mcp를 사용해서 강변점에서 콜라 검색해줘
+GS25 mcp를 사용해서 강남 매장 찾고 오감자 재고 확인해줘
+세븐일레븐 mcp를 사용해서 안산 중앙역 근처 매장 찾고 핫식스 재고 확인해줘
 메가박스 mcp를 사용해서 강남역 근처 지점 찾아줘
 메가박스 mcp를 사용해서 강남점 영화 목록이랑 잔여 좌석 확인해줘
+롯데시네마 mcp를 사용해서 잠실 근처 지점 찾아줘
+롯데시네마 mcp를 사용해서 월드타워 영화 목록이랑 잔여 좌석 확인해줘
 CGV mcp를 사용해서 서울 지역 극장 목록 찾아줘
 CGV mcp를 사용해서 강남 CGV 영화랑 시간표 확인해줘
 ```
@@ -109,7 +125,7 @@ CGV mcp를 사용해서 강남 CGV 영화랑 시간표 확인해줘
 > Claude Code CLI에서 MCP 서버 추가
 
 ```bash
-claude mcp add daiso-mcp https://mcp.aka.page --transport sse
+claude mcp add daiso-mcp https://mcp.aka.page --transport http
 ```
 
 <br>
@@ -138,423 +154,206 @@ AI: (페이지를 읽고 API 사용법 이해)
 사용자: 수납박스 검색해줘
 AI: (https://mcp.aka.page/api/daiso/products?q=수납박스 호출 후 결과 제공)
 
-사용자: 강남역 근처 메가박스 지점 찾아줘
-AI: (https://mcp.aka.page/api/megabox/theaters?lat=37.4982&lng=127.0264 호출 후 결과 제공)
+사용자: 안산 중앙역 근처 메가박스 지점 찾아줘
+AI: (https://mcp.aka.page/api/megabox/theaters?keyword=안산%20중앙역 호출 후 결과 제공)
+
+사용자: 잠실 근처 롯데시네마 지점 찾아줘
+AI: (https://mcp.aka.page/api/lottecinema/theaters?keyword=%EC%9E%A0%EC%8B%A4 호출 후 결과 제공)
 
 사용자: 강남 CGV 시간표 알려줘
 AI: (https://mcp.aka.page/api/cgv/timetable?playDate=20260304&theaterCode=0056 호출 후 결과 제공)
-```
-
-<br>
-
-### 미지원 서비스
-
-| 서비스                                                                                                | 상태      |
-| :---------------------------------------------------------------------------------------------------- | :-------- |
-| ![Gemini](https://img.shields.io/badge/Gemini-8E75B2?logo=googlegemini&logoColor=white) Google Gemini | ❌ 미지원 |
-| ![Copilot](https://img.shields.io/badge/Copilot-000000?logo=github&logoColor=white) GitHub Copilot    | ❌ 미지원 |
-
-<br>
-
----
-
-<br>
-
-## 기능
-
-### daiso_search_products
-
-다이소 제품을 검색합니다.
-
-| 파라미터   | 필수 | 설명                          |
-| :--------- | :--: | :---------------------------- |
-| `query`    |  O   | 검색할 제품명 또는 키워드     |
-| `page`     |      | 페이지 번호 (기본값: 1)       |
-| `pageSize` |      | 페이지당 결과 수 (기본값: 30) |
-
-<br>
-
-### daiso_find_stores
-
-다이소 매장을 검색합니다.
-
-| 파라미터  | 필수 | 설명                      |
-| :-------- | :--: | :------------------------ |
-| `keyword` |      | 매장명 또는 주소 키워드   |
-| `sido`    |      | 시/도 (예: 서울, 경기)    |
-| `gugun`   |      | 구/군 (예: 강남구)        |
-| `dong`    |      | 동 (예: 역삼동)           |
-| `limit`   |      | 최대 매장 수 (기본값: 50) |
-
-<br>
-
-### daiso_check_inventory
-
-특정 제품의 매장별 재고를 확인합니다.
-
-| 파라미터     | 필수 | 설명                          |
-| :----------- | :--: | :---------------------------- |
-| `productId`  |  O   | 제품 ID                       |
-| `storeQuery` |      | 매장 검색어 (예: 안산 중앙역) |
-| `latitude`   |      | 위도 (기본값: 서울 시청)      |
-| `longitude`  |      | 경도 (기본값: 서울 시청)      |
-| `page`       |      | 페이지 번호 (기본값: 1)       |
-| `pageSize`   |      | 페이지당 결과 수 (기본값: 30) |
-
-<br>
-
-### daiso_get_price_info
-
-제품의 가격 정보를 조회합니다.
-
-| 파라미터      | 필수 | 설명                                |
-| :------------ | :--: | :---------------------------------- |
-| `productId`   |      | 제품 ID                             |
-| `productName` |      | 제품명 (productId가 없을 경우 사용) |
-
-<br>
-
-### oliveyoung_find_nearby_stores
-
-Zyte API 기반으로 내 주변 올리브영 매장을 조회합니다.
-
-| 파라미터    | 필수 | 설명                                |
-| :---------- | :--: | :---------------------------------- |
-| `latitude`  |      | 위도 (기본값: 서울 시청)            |
-| `longitude` |      | 경도 (기본값: 서울 시청)            |
-| `keyword`   |      | 매장명/지역 키워드 (예: 명동, 강남) |
-| `pageIdx`   |      | 페이지 번호 (기본값: 1)             |
-| `limit`     |      | 최대 결과 수 (기본값: 20)           |
-
-<br>
-
-### oliveyoung_check_inventory
-
-Zyte API 기반으로 올리브영 상품 재고를 조회하고 주변 매장 정보를 함께 반환합니다.
-
-| 파라미터         | 필수 | 설명                           |
-| :--------------- | :--: | :----------------------------- |
-| `keyword`        |  O   | 재고를 확인할 상품 키워드      |
-| `latitude`       |      | 위도 (기본값: 서울 시청)       |
-| `longitude`      |      | 경도 (기본값: 서울 시청)       |
-| `storeKeyword`   |      | 주변 매장 검색 키워드          |
-| `page`           |      | 페이지 번호 (기본값: 1)        |
-| `size`           |      | 페이지당 상품 수 (기본값: 20)  |
-| `includeSoldOut` |      | 품절 포함 여부 (기본값: false) |
-
-<br>
-
-### megabox_find_nearby_theaters
-
-사용자 좌표 기준으로 메가박스 주변 지점을 거리순으로 조회합니다.
-
-| 파라미터    | 필수 | 설명                               |
-| :---------- | :--: | :--------------------------------- |
-| `latitude`  |      | 위도 (기본값: 서울 시청)           |
-| `longitude` |      | 경도 (기본값: 서울 시청)           |
-| `playDate`  |      | 조회 날짜 (YYYYMMDD, 기본값: 오늘) |
-| `areaCode`  |      | 지역 코드 (기본값: 11, 서울)       |
-| `limit`     |      | 최대 결과 수 (기본값: 10)          |
-
-<br>
-
-### megabox_list_now_showing
-
-날짜/지점 조건으로 메가박스 영화 및 상영 회차 목록을 조회합니다.
-
-| 파라미터    | 필수 | 설명                               |
-| :---------- | :--: | :--------------------------------- |
-| `playDate`  |      | 조회 날짜 (YYYYMMDD, 기본값: 오늘) |
-| `theaterId` |      | 지점 ID (예: 1372)                 |
-| `movieId`   |      | 영화 ID (예: 25104500)             |
-| `areaCode`  |      | 지역 코드 (기본값: 11, 서울)       |
-
-<br>
-
-### megabox_get_remaining_seats
-
-영화/지점/날짜 조건으로 회차별 남은 좌석 수를 조회합니다.
-
-| 파라미터    | 필수 | 설명                               |
-| :---------- | :--: | :--------------------------------- |
-| `playDate`  |      | 조회 날짜 (YYYYMMDD, 기본값: 오늘) |
-| `theaterId` |      | 지점 ID                            |
-| `movieId`   |      | 영화 ID                            |
-| `areaCode`  |      | 지역 코드 (기본값: 11, 서울)       |
-| `limit`     |      | 최대 결과 수 (기본값: 50)          |
-
-<br>
-
-### cgv_find_theaters
-
-지역 코드 기준으로 CGV 극장 목록을 조회합니다.
-
-| 파라미터     | 필수 | 설명                               |
-| :----------- | :--: | :--------------------------------- |
-| `playDate`   |      | 조회 날짜 (YYYYMMDD, 기본값: 오늘) |
-| `regionCode` |      | 지역 코드 (예: 01 서울)            |
-| `limit`      |      | 최대 결과 수 (기본값: 30)          |
-| `timeoutMs`  |      | 요청 제한 시간(ms, 기본값: 15000)  |
-
-<br>
-
-### cgv_search_movies
-
-날짜/극장 조건으로 CGV 영화 목록을 조회합니다.
-
-| 파라미터      | 필수 | 설명                               |
-| :------------ | :--: | :--------------------------------- |
-| `playDate`    |      | 조회 날짜 (YYYYMMDD, 기본값: 오늘) |
-| `theaterCode` |      | CGV 극장 코드 (예: 0056)           |
-| `timeoutMs`   |      | 요청 제한 시간(ms, 기본값: 15000)  |
-
-<br>
-
-### cgv_get_timetable
-
-날짜/극장/영화 조건으로 CGV 상영 시간표를 조회합니다.
 
-| 파라미터      | 필수 | 설명                               |
-| :------------ | :--: | :--------------------------------- |
-| `playDate`    |      | 조회 날짜 (YYYYMMDD, 기본값: 오늘) |
-| `theaterCode` |      | CGV 극장 코드 (예: 0056)           |
-| `movieCode`   |      | CGV 영화 코드                      |
-| `limit`       |      | 최대 결과 수 (기본값: 50)          |
-| `timeoutMs`   |      | 요청 제한 시간(ms, 기본값: 15000)  |
-
-<br>
-
-### 올리브영 REST 캐싱 정책
-
-Cloudflare Edge Cache API(`caches.default`)를 사용해 올리브영 REST 응답을 캐싱합니다.
-
-- `GET /api/oliveyoung/stores`: 24시간 TTL
-- `GET /api/oliveyoung/inventory`: 10분 TTL
-- 공통: `stale-while-revalidate` 적용, 오류 응답(4xx/5xx)은 캐시하지 않음
+사용자: 안산 중앙역 근처 CGV 찾아서 오늘 영화랑 시간표 알려줘
+AI: (https://mcp.aka.page/api/cgv/theaters?playDate=20260315&keyword=안산%20중앙역 호출 후 결과 제공)
+AI: (https://mcp.aka.page/api/cgv/movies?playDate=20260315&keyword=안산%20중앙역 호출 후 결과 제공)
+AI: (https://mcp.aka.page/api/cgv/timetable?playDate=20260315&keyword=안산%20중앙역 호출 후 결과 제공)
+```
 
 <br>
 
-### 메가박스 REST 캐싱 정책
-
-Cloudflare Edge Cache API(`caches.default`)를 사용해 메가박스 REST 응답을 캐싱합니다.
+### MCP 서버 URL / CLI (고급)
 
-- `GET /api/megabox/theaters`: 24시간 TTL
-- `GET /api/megabox/movies`: 10분 TTL
-- `GET /api/megabox/seats`: 3분 TTL
-- 공통: `stale-while-revalidate` 적용, 오류 응답(4xx/5xx)은 캐시하지 않음
+AI 앱 대신 직접 연결하거나 스크립트에서 사용할 때만 참고하세요.
 
-<br>
+MCP 서버 URL:
 
-### CGV REST 캐싱 정책
+```
+https://mcp.aka.page
+```
 
-Cloudflare Edge Cache API(`caches.default`)를 사용해 CGV REST 응답을 캐싱합니다.
+CLI (npx):
 
-- `GET /api/cgv/theaters`: 24시간 TTL
-- `GET /api/cgv/movies`: 10분 TTL
-- `GET /api/cgv/timetable`: 3분 TTL
-- 공통: `stale-while-revalidate` 적용, 오류 응답(4xx/5xx)은 캐시하지 않음
+```bash
+# 인터랙티브 모드 (추천)
+npx daiso
 
-<br>
+# 인터랙티브 비활성화 (CI/스크립트)
+npx daiso --non-interactive
 
-### 다이소 REST 캐싱 정책
+# 명령형 모드
+npx daiso help
+npx daiso help products
+npx daiso url
+npx daiso health
+npx daiso claude
 
-Cloudflare Edge Cache API(`caches.default`)를 사용해 다이소 REST 응답을 캐싱합니다.
+# AI 없이 직접 조회
+npx daiso products 수납박스
+npx daiso product 1034604
+npx daiso stores 강남역
+npx daiso inventory 1034604 --keyword 강남역
+npx daiso display-location 1034604 04515
+npx daiso cu-stores 강남
+npx daiso cu-inventory 과자 --storeKeyword 강남
+npx daiso lottemart-stores 잠실 --area 서울 --limit 10
+npx daiso lottemart-products 콜라 --storeName 강변점 --area 서울
+npx daiso emart24-stores 강남 --service24h true
+npx daiso emart24-products 두바이 --pageSize 20
+npx daiso emart24-inventory 8800244010504 --bizNoArr 28339,05015
+npx daiso gs25-stores 강남 --limit 10
+npx daiso gs25-products 오감자 --limit 20
+npx daiso gs25-inventory 오감자 --storeKeyword 강남 --storeLimit 10
+npx daiso seveneleven-products 삼각김밥 --size 20
+npx daiso seveneleven-stores 안산 중앙역 --limit 10
+npx daiso get /api/seveneleven/inventory --keyword 핫식스 --storeKeyword 안산%20중앙역 --storeLimit 10
+npx daiso seveneleven-popwords --label home
+npx daiso seveneleven-catalog --includeIssues true --includeExhibition true --limit 10
+npx daiso get /api/cgv/movies --playDate 20260307 --theaterCode 0056
 
-- `GET /api/daiso/products`: 30분 TTL
-- `GET /api/daiso/products/:id`: 1시간 TTL
-- `GET /api/daiso/stores`: 24시간 TTL
-- `GET /api/daiso/inventory`: 10분 TTL
-- 공통: `stale-while-revalidate` 적용, 오류 응답(4xx/5xx)은 캐시하지 않음
+# 원본 JSON 필요 시
+npx daiso products 수납박스 --json
+```
 
-<br>
+### Codex Skill
 
----
+이 저장소는 MCP 서버뿐 아니라 에이전트가 `npx daiso` CLI를 직접 고를 수 있게 하는 Codex Skill도 제공합니다.
 
-<br>
+- ClawHub: `clawhub install daiso-cli`
+- 공개 페이지: `https://clawhub.ai/hmmhmmhm/daiso-cli`
+- 스킬 파일: `skills/daiso-cli/SKILL.md`
+- 명령 맵: `skills/daiso-cli/references/cli-command-map.md`
+- 기본 원칙: 쉘 실행이 가능한 환경에서는 CLI를 우선 사용하고, AI 앱 연결이 필요할 때는 MCP 서버 URL `https://mcp.aka.page`를 사용합니다.
+- 구조화 결과가 필요하면 스킬은 `npx daiso ... --json` 형태를 선택합니다.
 
-## REST API
+### OpenAPI 스펙
 
-MCP를 지원하지 않는 서비스를 위한 GET 기반 REST API입니다.
+- OpenAI 챗봇 등록용 축약 스펙: `https://mcp.aka.page/openapi.json`
+- OpenAI 챗봇 등록용 YAML: `https://mcp.aka.page/openapi.yaml`
+- 전체 개별 엔드포인트 스펙(JSON): `https://mcp.aka.page/openapi-full.json`
+- 전체 개별 엔드포인트 스펙(YAML): `https://mcp.aka.page/openapi-full.yaml`
 
-### 엔드포인트
+### MCP 표준 응답 모델
 
-| 엔드포인트                      | 설명                                |
-| :------------------------------ | :---------------------------------- |
-| `GET /prompt`                   | API 사용법 설명 페이지 (에이전트용) |
-| `GET /api/daiso/products`       | 제품 검색                           |
-| `GET /api/daiso/products/:id`   | 제품 상세 정보                      |
-| `GET /api/daiso/stores`         | 매장 검색                           |
-| `GET /api/daiso/inventory`      | 재고 확인                           |
-| `GET /api/oliveyoung/stores`    | 올리브영 매장 검색                  |
-| `GET /api/oliveyoung/inventory` | 올리브영 재고 확인                  |
-| `GET /api/megabox/theaters`     | 메가박스 주변 지점 조회             |
-| `GET /api/megabox/movies`       | 메가박스 영화/회차 목록 조회        |
-| `GET /api/megabox/seats`        | 메가박스 잔여 좌석 조회             |
-| `GET /api/cgv/theaters`         | CGV 극장 목록 조회                  |
-| `GET /api/cgv/movies`           | CGV 영화 목록 조회                  |
-| `GET /api/cgv/timetable`        | CGV 상영 시간표 조회                |
+MCP 도구 응답은 각 서비스의 원본 필드를 유지하면서, 클라이언트가 공통 UI를 만들 수 있도록 `standard` 필드를 함께 제공합니다.
 
-### 제품 검색
+- `standard.products`: 상품/영화 목록을 `code`, `name`, `price`, `imageUrl`, `raw` 형태로 정규화합니다.
+- `standard.stores`: 매장 목록을 `code`, `name`, `address`, `distanceMeters`, `raw` 형태로 정규화합니다.
+- `standard.theaters`: 영화관 목록을 `code`, `name`, `address`, `distanceMeters`, `raw` 형태로 정규화합니다.
 
-```
-GET /api/daiso/products?q={검색어}&page={페이지}&pageSize={개수}
-```
+### 운영 헬스 체크
 
-| 파라미터   | 필수 | 설명                          |
-| :--------- | :--: | :---------------------------- |
-| `q`        |  O   | 검색 키워드                   |
-| `page`     |      | 페이지 번호 (기본값: 1)       |
-| `pageSize` |      | 페이지당 결과 수 (기본값: 30) |
+공개 상태 페이지: **[Daiso MCP Status](https://aka-page.betteruptime.com/)**
 
-### 매장 검색
+서비스별 API 상태를 즉시 확인할 때는 `GET /api/health/checks`를 사용합니다. 이 엔드포인트는 `HEALTH_CHECK_SECRET` 환경 변수가 설정되어 있어야 하며, 요청에는 `Authorization: Bearer <secret>` 또는 `x-health-check-key: <secret>` 헤더가 필요합니다. 내부 체크 요청의 기준 URL은 `HEALTH_CHECK_BASE_URL`로 지정할 수 있습니다.
 
+```bash
+curl -H "Authorization: Bearer $HEALTH_CHECK_SECRET" \
+  "https://mcp.aka.page/api/health/checks?mode=full&fresh=true&includeSamples=true&timeoutMs=20000&slowThresholdMs=9000"
 ```
-GET /api/daiso/stores?keyword={키워드}&sido={시도}&limit={개수}
-```
-
-| 파라미터  | 필수 | 설명                                                |
-| :-------- | :--: | :-------------------------------------------------- |
-| `keyword` |  △   | 매장명/주소 키워드 (keyword 또는 sido 중 하나 필수) |
-| `sido`    |  △   | 시/도                                               |
-| `gugun`   |      | 구/군                                               |
-| `dong`    |      | 동                                                  |
-| `limit`   |      | 최대 결과 수 (기본값: 50)                           |
 
-### 재고 확인
+주요 쿼리:
 
-```
-GET /api/daiso/inventory?productId={제품ID}&lat={위도}&lng={경도}
-```
+- `service=gs25`: 특정 서비스만 확인
+- `check=lottemart.products`: 특정 체크만 확인
+- `mode=quick|deep|full`: 체크 모드 선택
+- `fresh=true`: 60초 캐시 우회
+- `includeSamples=true`: 첫 결과 이름 샘플 포함
+- `timeoutMs=20000`: 체크별 요청 제한 시간
+- `slowThresholdMs=9000`: 지정 시간보다 느린 성공 응답을 degraded로 표시
 
-| 파라미터    | 필수 | 설명                          |
-| :---------- | :--: | :---------------------------- |
-| `productId` |  O   | 제품 ID                       |
-| `lat`       |      | 위도 (기본값: 37.5665)        |
-| `lng`       |      | 경도 (기본값: 126.978)        |
-| `keyword`   |      | 매장 검색어                   |
-| `page`      |      | 페이지 번호 (기본값: 1)       |
-| `pageSize`  |      | 페이지당 결과 수 (기본값: 30) |
+상태 기준:
 
-### 올리브영 매장 검색
-
-```
-GET /api/oliveyoung/stores?keyword={키워드}&lat={위도}&lng={경도}
-```
+- `ok`: 필수 응답 구조와 최소 결과가 정상입니다.
+- `degraded`: 기능은 살아 있지만 빈 결과, 느린 응답, 응답 구조 변화 등 확인이 필요합니다.
+- `fail`: 외부 API 오류, 타임아웃, 인증 문제처럼 실제 장애로 봐야 합니다.
 
-| 파라미터  | 필수 | 설명                                |
-| :-------- | :--: | :---------------------------------- |
-| `keyword` |      | 매장명/지역 키워드 (예: 명동, 강남) |
-| `lat`     |      | 위도 (기본값: 37.5665)              |
-| `lng`     |      | 경도 (기본값: 126.978)              |
-| `pageIdx` |      | 페이지 번호 (기본값: 1)             |
-| `limit`   |      | 최대 결과 수 (기본값: 20)           |
+Better Stack 같은 외부 모니터링에서는 `fail`을 장애 알림 기준으로 보고, `degraded`는 느린 외부 API나 응답 품질 저하를 추적하는 경고 신호로 봅니다.
 
-### 올리브영 재고 확인
+배포 전 로컬에서 CLI 모드까지 확인할 때는 아래 명령을 사용합니다.
 
-```
-GET /api/oliveyoung/inventory?keyword={검색어}&lat={위도}&lng={경도}
+```bash
+npm run cli:smoke
 ```
 
-| 파라미터         | 필수 | 설명                           |
-| :--------------- | :--: | :----------------------------- |
-| `keyword`        |  O   | 검색 키워드 (예: 선크림, 립밤) |
-| `lat`            |      | 위도 (기본값: 37.5665)         |
-| `lng`            |      | 경도 (기본값: 126.978)         |
-| `storeKeyword`   |      | 주변 매장 필터 키워드          |
-| `page`           |      | 페이지 번호 (기본값: 1)        |
-| `size`           |      | 페이지당 결과 수 (기본값: 20)  |
-| `sort`           |      | 정렬 코드 (기본값: 01)         |
-| `includeSoldOut` |      | 품절 포함 여부 (기본값: false) |
+기본 `openapi.json`은 OpenAI Actions import 제한에 맞추기 위해 `GET /api/actions/query` 단일 facade만 노출합니다.
+기존 서비스별 GET API는 유지되며, 자세한 배경은 [OpenAPI Actions Facade 문서](./docs/openapi-actions-facade.md)에 정리했습니다.
 
-### 메가박스 주변 지점 조회
+인터랙티브 예시:
 
-```
-GET /api/megabox/theaters?lat={위도}&lng={경도}&playDate={YYYYMMDD}&areaCode={지역코드}
-```
+```text
+$ npx daiso
+daiso 인터랙티브 모드
 
-| 파라미터   | 필수 | 설명                               |
-| :--------- | :--: | :--------------------------------- |
-| `lat`      |      | 위도 (기본값: 37.5665)             |
-| `lng`      |      | 경도 (기본값: 126.978)             |
-| `playDate` |      | 조회 날짜 (YYYYMMDD, 기본값: 오늘) |
-| `areaCode` |      | 지역 코드 (기본값: 11, 서울)       |
-| `limit`    |      | 최대 결과 수 (기본값: 10)          |
+[서비스 선택]
+1. 다이소
+2. 올리브영
+3. CU
+서비스 번호를 선택하세요 (0: 종료): 1
 
-### 메가박스 영화/회차 목록 조회
+매장 검색 키워드를 입력하세요: 강남
 
-```
-GET /api/megabox/movies?playDate={YYYYMMDD}&theaterId={지점ID}&movieId={영화ID}
-```
+[매장 선택]
+1. 다이소 강남점 | 서울 강남구 ...
+2. 다이소 강남역점 | 서울 강남구 ...
+입력: 번호 선택 | /키워드 필터 | all 전체보기 | 0 다시 검색
+선택: /역점
+선택: 1
 
-| 파라미터    | 필수 | 설명                               |
-| :---------- | :--: | :--------------------------------- |
-| `playDate`  |      | 조회 날짜 (YYYYMMDD, 기본값: 오늘) |
-| `theaterId` |      | 지점 ID (예: 1372)                 |
-| `movieId`   |      | 영화 ID (예: 25104500)             |
-| `areaCode`  |      | 지역 코드 (기본값: 11, 서울)       |
+[선택한 매장 정보]
+- 매장명: 다이소 강남역점
+- 주소: 서울 강남구 ...
+- 전화: 02-...
 
-### 메가박스 잔여 좌석 조회
+찾을 상품 키워드를 입력하세요: 수납박스
 
-```
-GET /api/megabox/seats?playDate={YYYYMMDD}&theaterId={지점ID}&movieId={영화ID}
-```
-
-| 파라미터    | 필수 | 설명                               |
-| :---------- | :--: | :--------------------------------- |
-| `playDate`  |      | 조회 날짜 (YYYYMMDD, 기본값: 오늘) |
-| `theaterId` |      | 지점 ID                            |
-| `movieId`   |      | 영화 ID                            |
-| `areaCode`  |      | 지역 코드 (기본값: 11, 서울)       |
-| `limit`     |      | 최대 결과 수 (기본값: 50)          |
+[상품 선택]
+1. 손잡이 수납박스 (2000원, ID: 1034604)
+2. 접이식 수납박스 (3000원, ID: 1034605)
+입력: 번호 선택 | /키워드 필터 | all 전체보기 | 0 취소
+선택: 1
 
-### CGV 극장 목록 조회
+[재고 결과]
+- 상품: 손잡이 수납박스
+- 매장: 다이소 강남역점
+- 재고 수량: 7
 
-```
-GET /api/cgv/theaters?playDate={YYYYMMDD}&regionCode={지역코드}
+[다음 동작]
+1. 같은 매장에서 다른 상품 찾기
+2. 다른 매장/서비스 다시 선택하기
+3. 종료하기
+번호를 선택하세요: 3
+인터랙티브 모드를 종료합니다.
 ```
 
-| 파라미터     | 필수 | 설명                               |
-| :----------- | :--: | :--------------------------------- |
-| `playDate`   |      | 조회 날짜 (YYYYMMDD, 기본값: 오늘) |
-| `regionCode` |      | 지역 코드 (예: 01 서울)            |
-| `limit`      |      | 최대 결과 수 (기본값: 30)          |
-| `timeoutMs`  |      | 요청 제한 시간(ms, 기본값: 15000)  |
+<br>
 
-### CGV 영화 목록 조회
+### 미지원 서비스
 
-```
-GET /api/cgv/movies?playDate={YYYYMMDD}&theaterCode={극장코드}
-```
+| 서비스                                                                                                | 상태      |
+| :---------------------------------------------------------------------------------------------------- | :-------- |
+| ![Gemini](https://img.shields.io/badge/Gemini-8E75B2?logo=googlegemini&logoColor=white) Google Gemini | ❌ 미지원 |
+| ![Copilot](https://img.shields.io/badge/Copilot-000000?logo=github&logoColor=white) GitHub Copilot    | ❌ 미지원 |
 
-| 파라미터      | 필수 | 설명                               |
-| :------------ | :--: | :--------------------------------- |
-| `playDate`    |      | 조회 날짜 (YYYYMMDD, 기본값: 오늘) |
-| `theaterCode` |      | CGV 극장 코드 (예: 0056)           |
-| `timeoutMs`   |      | 요청 제한 시간(ms, 기본값: 15000)  |
+<br>
 
-### CGV 시간표 조회
+## Special Thanks
 
-```
-GET /api/cgv/timetable?playDate={YYYYMMDD}&theaterCode={극장코드}&movieCode={영화코드}
-```
+이 프로젝트에 도움 주신 분들께 감사드립니다.
 
-| 파라미터      | 필수 | 설명                               |
-| :------------ | :--: | :--------------------------------- |
-| `playDate`    |      | 조회 날짜 (YYYYMMDD, 기본값: 오늘) |
-| `theaterCode` |      | CGV 극장 코드 (예: 0056)           |
-| `movieCode`   |      | CGV 영화 코드                      |
-| `limit`       |      | 최대 결과 수 (기본값: 50)          |
-| `timeoutMs`   |      | 요청 제한 시간(ms, 기본값: 15000)  |
-
-### 응답 형식
-
-```json
-{
-  "success": true,
-  "data": { ... },
-  "meta": { "total": 100, "page": 1, "pageSize": 30 }
-}
-```
+- [@thecats1105](https://github.com/thecats1105): 다이소 진열 위치 조회 도구(`daiso_get_display_location`) 구현 및 API/테스트 연동
+- [@betterthanhajin](https://github.com/betterthanhajin): CGV 서비스 프로바이더 구현(극장/영화/시간표 도구, 라우트·스펙·테스트 추가)
+- [@LLagoon3](https://github.com/LLagoon3): 다이소 매장 재고 조회 신규 인증 흐름 전환 및 관련 테스트 보강
+- [제로초님](https://youtube.com/shorts/ZgIqA1NCEp0?si=UW0pKsSpqmEi7lXG): 프로젝트 홍보 도움
 
 <br>
 
@@ -562,36 +361,12 @@ GET /api/cgv/timetable?playDate={YYYYMMDD}&theaterCode={극장코드}&movieCode=
 
 <br>
 
-## 사용 예시
-
-```
-사용자: 수납박스 검색해줘
-AI: daiso_search_products 도구로 제품 목록 조회
-
-사용자: 이 제품 안산 중앙역 근처 매장에 재고 있어?
-AI: daiso_check_inventory 도구로 특정 매장 재고 확인
-
-사용자: 강남역 근처 다이소 매장 찾아줘
-AI: daiso_find_stores 도구로 매장 검색
+## 상세 문서
 
-사용자: 명동 근처 올리브영 매장 찾아줘
-AI: oliveyoung_find_nearby_stores 도구로 주변 매장 검색
+`Special Thanks` 이후에 있던 상세 설명은 별도 문서로 분리했습니다.
 
-사용자: 올리브영 선크림 재고 확인해줘
-AI: oliveyoung_check_inventory 도구로 재고/매장 정보 조회
-
-사용자: 강남역 근처 메가박스 지점 찾아줘
-AI: megabox_find_nearby_theaters 도구로 주변 지점 조회
-
-사용자: 메가박스 강남점 영화 목록과 잔여 좌석 알려줘
-AI: megabox_list_now_showing / megabox_get_remaining_seats 도구로 회차/좌석 조회
-
-사용자: 서울 지역 CGV 극장 목록 알려줘
-AI: cgv_find_theaters 도구로 CGV 극장 목록 조회
-
-사용자: CGV 강남 상영 영화랑 시간표 알려줘
-AI: cgv_search_movies / cgv_get_timetable 도구로 영화/시간표 조회
-```
+- [서비스 레퍼런스](./docs/service-reference.md)
+- [CONTRIBUTING 가이드](./CONTRIBUTING.md)
 
 <br>
 
@@ -599,154 +374,95 @@ AI: cgv_search_movies / cgv_get_timetable 도구로 영화/시간표 조회
 
 <br>
 
-## 개발
+## docs 문서
 
-```bash
-# Node 버전 맞추기
-nvm use
+### 공통 가이드
 
-# 설치
-npm ci
+- [서비스 레퍼런스](./docs/service-reference.md)
+- [스크래핑 플레이북](./docs/scraping-playbook.md)
+- [mitmproxy 가이드](./docs/mitmproxy-guide.md)
+- [AI 지시문](./docs/ai-instruction.md)
 
-# 환경 변수 설정
-cp .env.example .env
-# .env 파일에 ZYTE_API_KEY 값 입력
+### 다이소
 
-# 품질 검사 (포맷/린트/타입/테스트)
-npm run check
+- [다이소 네트워크 분석 결과](./docs/daiso-network-analysis-result.md)
+- [다이소 Playwright 네트워크 분석](./docs/daiso-playwright-network-analysis.md)
+- [다이소 리플레이 세션 테스트 HTML](./docs/daiso-replay-session-test.html)
+- [다이소 테스트 리플레이 스크립트](./docs/daiso-test-replay.ts)
 
-# 로컬 개발 서버
-npm run dev
+### CU
 
-# 배포
-npm run deploy
-```
+- [CU 네트워크 분석 결과](./docs/cu-network-analysis-result.md)
+- [CU 앱 요청 캡처 가이드](./docs/cu-app-request-capture-guide.md)
+- [CU 앱 스크래핑 리플레이 가이드](./docs/cu-app-scraping-replay-guide.md)
 
-## npm 퍼블리싱
+### 이마트24
 
-```bash
-# npm 로그인
-npm login
+- [이마트24 네트워크 분석 결과](./docs/emart24-network-analysis-result.md)
+- [이마트24 앱 스크래핑 준비 가이드](./docs/emart24-app-scraping-preparation-guide.md)
+- [이마트24 앱 스크래핑 리플레이 가이드](./docs/emart24-app-scraping-replay-guide.md)
 
-# 배포 산출물/메타 검증
-npm run release:dry-run
+### 롯데마트
 
-# 퍼블리시 (공개 패키지)
-npm run publish:public
-```
+- [롯데마트 모바일 도와센터 스크래핑 리플레이 계획](./docs/lottemart-mobile-scraping-replay-plan.md)
 
-기여 가이드는 [CONTRIBUTING.md](./CONTRIBUTING.md)에서 확인할 수 있습니다.
+### 공통
 
-<br>
+- [OpenAPI Actions facade 리팩토링 배경](./docs/openapi-actions-facade.md)
 
----
+### 올리브영
 
-<br>
+- [올리브영 네트워크 분석 결과](./docs/oliveyoung-network-analysis-result.md)
+- [올리브영 Playwright MCP 온보딩](./docs/oliveyoung-playwright-mcp-onboarding.md)
+- [올리브영 Playwright 네트워크 분석](./docs/oliveyoung-playwright-network-analysis.md)
+- [올리브영 Lightpanda 검증](./docs/oliveyoung-lightpanda-validation.md)
+- [올리브영 리플레이 세션 테스트 스크립트](./docs/oliveyoung-replay-session-test.ts)
+- [올리브영 Zyte 대역폭 테스트](./docs/oliveyoung-zyte-bandwidth-test.ts)
+- [올리브영 Zyte 리플레이 테스트](./docs/oliveyoung-zyte-replay-test.ts)
 
-## 아키텍처
+### 영화관
 
-| 항목       | 기술                         |
-| :--------- | :--------------------------- |
-| 런타임     | Cloudflare Workers           |
-| 프레임워크 | Hono + TypeScript            |
-| 프로토콜   | MCP (Model Context Protocol) |
-| 전송       | SSE (Server-Sent Events)     |
+- [CGV 네트워크 분석 결과](./docs/cgv-network-analysis-result.md)
+- [메가박스 네트워크 분석 결과](./docs/megabox-network-analysis-result.md)
+- [롯데시네마 네트워크 분석 결과](./docs/lottecinema-network-analysis-result.md)
 
-<br>
+### GS25
 
----
+- [GS25 API 리플레이 방법론 (최종)](./docs/gs25-final-replay-methodology.md)
+- [GS25 네트워크 분석 결과 (아카이브)](./docs/archive/gs25-network-analysis-result.md)
+- [GS25 안드로이드 우회 캡처 가이드 (아카이브)](./docs/archive/gs25-android-bypass-capture-guide.md)
+- [GS25 앱 캡처 시도 로그 (2026-03-08, 아카이브)](./docs/archive/gs25-app-capture-attempt-log-20260308.md)
+- [GS25 앱 스크래핑 준비 가이드 (아카이브)](./docs/archive/gs25-app-scraping-preparation-guide.md)
+- [GS25 세션 인계 문서 (2026-03-09, 아카이브)](./docs/archive/gs25-session-handoff-20260309.md)
 
 <br>
 
-## 프로젝트 구조
+---
 
-```
-daiso-mcp/
-├── src/
-│   ├── index.ts              # MCP 서버 진입점
-│   ├── core/                 # 핵심 모듈
-│   │   ├── types.ts          # 공통 타입
-│   │   ├── interfaces.ts     # ServiceProvider 인터페이스
-│   │   └── registry.ts       # ServiceRegistry
-│   ├── services/             # 서비스 프로바이더
-│   │   ├── daiso/            # 다이소 서비스
-│   │   ├── oliveyoung/       # 올리브영 서비스 (Zyte API)
-│   │   ├── megabox/          # 메가박스 서비스
-│   │   └── cgv/              # CGV 서비스
-│   ├── api/                  # REST API (MCP 미지원 서비스용)
-│   │   ├── handlers.ts       # 다이소/올리브영 API 핸들러
-│   │   ├── megaboxHandlers.ts # 메가박스 API 핸들러
-│   │   ├── cgvHandlers.ts    # CGV API 핸들러
-│   │   └── routes/           # 서비스별 API 라우트
-│   ├── pages/                # 정적 페이지
-│   │   └── prompt.ts         # 에이전트용 프롬프트 페이지
-│   └── utils/                # 유틸리티
-├── wrangler.toml             # Cloudflare Workers 설정
-└── package.json
-```
+<div align="center">
 
 <br>
 
----
+MIT License
 
 <br>
 
-## 확장 가능한 아키텍처
-
-이 프로젝트는 **플러그인 기반 아키텍처**로 설계되어 새로운 서비스를 쉽게 추가할 수 있습니다.
-
-### 핵심 컴포넌트
-
-| 컴포넌트           | 역할                                   |
-| :----------------- | :------------------------------------- |
-| `ServiceProvider`  | 모든 서비스가 구현해야 하는 인터페이스 |
-| `ServiceRegistry`  | 서비스 등록 및 MCP 서버 연결 관리      |
-| `ToolRegistration` | 도구 메타데이터와 핸들러 정의          |
-
-### 새 서비스 추가 방법
-
-예: CU 편의점 서비스 추가
-
-```typescript
-// 1. src/services/cu/index.ts 생성
-import type { ServiceProvider } from '../../core/interfaces.js';
-
-class CuService implements ServiceProvider {
-  readonly metadata = {
-    id: 'cu',
-    name: 'CU 편의점',
-    version: '1.0.0',
-  };
-
-  getTools() {
-    return [
-      /* cu_search_products, cu_find_stores 등 */
-    ];
-  }
-}
-
-export function createCuService(): ServiceProvider {
-  return new CuService();
-}
-```
-
-```typescript
-// 2. src/index.ts에 한 줄 추가
-import { createCuService } from './services/cu/index.js';
-
-registry.registerAll([createDaisoService, createCuService]);
-```
-
-<br>
+</div>
 
 ---
 
-<div align="center">
+## 신규 MCP 기능 추가 시 유의사항
 
-<br>
+새로운 서비스나 도구를 추가할 때는 구현만 끝내지 말고 아래 반영 범위를 함께 확인해야 합니다.
 
-MIT License
+- `MCP`: `src/index.ts` 서비스 등록, 루트 서비스/도구 목록, 관련 테스트 반영
+- `HTTPS`: GET API 핸들러/라우트, 프롬프트 페이지(`src/pages/prompt.ts`), 앱 통합 테스트 반영
+- `CLI`: `src/cli.ts`, `src/cliHelp.ts`, CLI 테스트 반영
+- `AI instruction`: [ai-instruction.md](./docs/ai-instruction.md) 사용 규칙/워크플로우 반영
+- `README`: 지원 서비스 설명, 예시, 문서 링크 반영
+- `OpenAPI`: 기본 `/openapi.json` facade 스펙, `/openapi-full.json` 전체 스펙, 관련 테스트 반영
 
-<br>
+기능 추가 후 최소 검증 기준:
 
-</div>
+- `npm run typecheck`
+- `npm test`