diff --git a/docs/ai-instruction.md b/docs/ai-instruction.md index a2b8a646..8ae244d9 100644 --- a/docs/ai-instruction.md +++ b/docs/ai-instruction.md @@ -167,8 +167,8 @@ GPT Actions가 이미 연결된 환경은 `queryAction(action=...)`을 사용하 - CU 재고 조회 시 `keyword`는 필수이며 필요 시 `storeKeyword`를 함께 사용 - 이마트24 재고 조회는 `pluCd` + `storeKeyword` 또는 `pluCd` + `bizNoArr` 조합을 사용 - 이마트24 매장 조회 후 `storeCode`를 모아 `bizNoArr`로 전달할 수 있고, 대화형 흐름에서는 기존 매장 키워드를 다시 넣어도 됨 -- 올리브영에서 "어떤 거 있나요", "종류 보여줘", "상품 목록" 요청은 먼저 `search_products(service=oliveyoung)` 또는 `/api/oliveyoung/products` 사용 -- `search_products(service=oliveyoung)` 또는 `/api/oliveyoung/products` 응답의 `products[].imageUrl`이 있으면 각 상품 이미지를 반드시 마크다운으로 전부 렌더링 +- 올리브영에서 "어떤 거 있나요", "종류 보여줘", "상품 목록" 요청은 먼저 `search_products(service=oliveyoung)` 또는 `/browse/oliveyoung/products/{검색어}` 사용 +- `search_products(service=oliveyoung)` 또는 `/browse/oliveyoung/products/{검색어}` 응답의 `products[].imageUrl`이 있으면 각 상품 이미지를 반드시 마크다운으로 전부 렌더링 - 올리브영 이미지 URL의 query string(`?l=ko` 등)은 마크다운 렌더링 시 절대 삭제하지 않으며, 전체 URL을 그대로 사용 - 올리브영 매장/재고 조회는 위치값(`lat`,`lng`)이 있으면 함께 사용 - 올리브영 재고 조회 결과에 `storeInventory`가 있으면 매장별 `stockLabel`, `remainQuantity`를 우선 사용 @@ -183,6 +183,6 @@ GPT Actions가 이미 연결된 환경은 `queryAction(action=...)`을 사용하 - 롯데시네마 좌석 조회는 `playDate(YYYYMMDD)` 사용, 가능하면 `theaterId`/`movieId`를 함께 사용 - CGV 극장/영화/시간표 조회는 `keyword`(예: 안산 중앙역) 또는 위치값(`lat`,`lng`)이 있으면 함께 사용 - CGV 좌석 조회는 `playDate(YYYYMMDD)` 사용, 가능하면 `theaterCode`/`movieCode`를 함께 사용 -- CGV 잔여 좌석은 별도 좌석 API가 아니라 `get_showtimes(service=cgv, operation=timetable)` 또는 `/api/cgv/timetable` 응답의 `timetable[].remainingSeats`로 확인 +- CGV 잔여 좌석은 별도 좌석 API가 아니라 `get_showtimes(service=cgv, operation=timetable)` 또는 `/browse/cgv/timetable/playDate/{YYYYMMDD}/theaterCode/{실제극장코드}` 응답의 `timetable[].remainingSeats`로 확인 - 지역명도 좌표도 없으면 사용자의 지역을 확인하고 기본 좌표 결과를 사용자 주변 결과로 단정하지 않음 - 정상 빈 결과·재고 0·미확인 수량·원본 차단·자체 한도·인증 오류를 구분하며 실패를 품절로 바꾸지 않음 diff --git a/docs/client-guide.md b/docs/client-guide.md index d6dc004f..0587b76c 100644 --- a/docs/client-guide.md +++ b/docs/client-guide.md @@ -1,6 +1,6 @@ # 앱 연결·CLI·Skill 가이드 -[무설치 원격 MCP 첫 조회](../README.md#원격-mcp로-바로-시작하기)부터 시작하세요. +연결된 MCP 도구가 있으면 [원격 MCP 안내](../README.md#원격-mcp로-바로-시작하기)를 따릅니다. 웹 읽기만 가능하면 설치·연결 설정 없이 [첫 상품 조회](https://mcp.aka.page/browse/daiso/products/%EC%88%98%EB%82%A9%EB%B0%95%EC%8A%A4/pageSize/3)를 open/WebFetch로 바로 여세요. 모든 후속 조회도 쿼리 없는 `/browse/` 경로를 사용하며 자동 HTML입니다. 원격 서버는 `https://mcp.aka.page`, 전송 방식은 Streamable HTTP, 사용자 인증은 없습니다. ## 원격 MCP 연결 diff --git a/docs/daiso-jp-network-analysis.md b/docs/daiso-jp-network-analysis.md index 15c8cb4c..89a93172 100644 --- a/docs/daiso-jp-network-analysis.md +++ b/docs/daiso-jp-network-analysis.md @@ -12,21 +12,23 @@ ## 호출 예시 -원격 MCP `https://mcp.aka.page`에서 다음 도구를 호출합니다. +이미 연결된 원격 MCP 도구가 있으면 다음 통합 도구를 호출합니다. 상세 ID는 검색 결과의 실제 코드를 사용합니다. ```json -{"name":"daiso_jp_search_products","arguments":{"query":"ボウル","page":1}} -{"name":"daiso_jp_get_product","arguments":{"id":"4550746075917"}} -{"name":"daiso_jp_find_stores","arguments":{"keyword":"東京都渋谷区","page":1}} +{"name":"search_products","arguments":{"service":"daiso_jp","query":"ボウル","page":1}} +{"name":"get_product_details","arguments":{"service":"daiso_jp","operation":"product","id":"검색한 실제 코드"}} +{"name":"find_stores","arguments":{"service":"daiso_jp","keyword":"東京都渋谷区","page":1}} ``` -웹 읽기 에이전트는 후속 요청을 포함해 반드시 `format=html`을 지정합니다. +연결된 MCP 도구가 없는 웹 읽기 에이전트는 open/WebFetch로 아래 `/browse/` 링크를 엽니다. 모든 후속 조회도 `/browse/`를 사용하며 자동 HTML이므로 쿼리 문자열이나 format 지정은 필요 없습니다. - [상품 검색](https://mcp.aka.page/browse/daiso-jp/products/%E3%83%9C%E3%82%A6%E3%83%AB) - [상품 상세](https://mcp.aka.page/browse/daiso-jp/product/4550746075917) - [매장 검색](https://mcp.aka.page/browse/daiso-jp/stores/%E6%9D%B1%E4%BA%AC%E9%83%BD%E6%B8%8B%E8%B0%B7%E5%8C%BA) -개발자용 JSON 응답은 기존처럼 format을 생략하면 됩니다. 페이지는 원본 페이지 단위이며 `hasNext`가 true인 경우에만 page를 증가시킵니다. 전체 검색을 한 번에 수집하지 않습니다. +개발자용 JSON 클라이언트는 기존 `/api/daiso-jp/` 계약을 사용합니다. 구형 HTML 쿼리 주소는 하위호환용입니다. 웹 조회에서 다음 페이지는 응답의 링크를 우선하고 `hasNext`가 true인 경우에만 `/page/2`처럼 경로의 page 값을 증가시킵니다. 전체 검색을 한 번에 수집하지 않습니다. + +아래 명령은 CLI를 선택한 환경의 예시입니다. 웹 읽기 요청에 CLI 설치나 실행을 요구하지 않습니다. ```sh npx daiso jp-products ボウル --json diff --git a/docs/mcp-tools.md b/docs/mcp-tools.md index 98e0c82d..f5383387 100644 --- a/docs/mcp-tools.md +++ b/docs/mcp-tools.md @@ -17,6 +17,8 @@ ## 호출 예시 +아래 예시는 이미 연결된 MCP 도구의 호출 계약입니다. 웹 읽기만 가능한 환경에서는 설치·연결 설정 없이 [첫 HTML 조회](https://mcp.aka.page/browse/daiso/products/%EC%88%98%EB%82%A9%EB%B0%95%EC%8A%A4/pageSize/3)를 open/WebFetch로 엽니다. 모든 후속 조회는 `/browse/` 경로이며 쿼리 문자열이나 format 지정은 필요 없습니다. + 상품 검색: `search_products {"service":"daiso","query":"수납박스","pageSize":3}` 재고: `check_inventory {"service":"gs25","keyword":"오감자","storeKeyword":"강남"}` diff --git a/docs/service-reference.md b/docs/service-reference.md index b8078425..382439e9 100644 --- a/docs/service-reference.md +++ b/docs/service-reference.md @@ -809,49 +809,20 @@ GET /api/cgv/timetable?playDate={YYYYMMDD}&theaterCode={극장코드}&movieCode= ## 사용 예시 -``` -사용자: 수납박스 검색해줘 -AI: daiso_search_products 도구로 제품 목록 조회 - -사용자: 이 제품 안산 중앙역 근처 매장에 재고 있어? -AI: daiso_check_inventory 도구로 특정 매장 재고 확인 - -사용자: 강남역 근처 다이소 매장 찾아줘 -AI: daiso_find_stores 도구로 매장 검색 - -사용자: 이 상품 이 매장 어디에 있어? -AI: daiso_get_display_location 도구로 매장 내 진열 위치 조회 - -사용자: 명동 근처 올리브영 매장 찾아줘 -AI: oliveyoung_find_nearby_stores 도구로 주변 매장 검색 - -사용자: 올리브영 선크림 재고 확인해줘 -AI: oliveyoung_check_inventory 도구로 재고/매장 정보 조회 - -사용자: 강남 근처 CU 매장 찾아줘 -AI: cu_find_nearby_stores 도구로 CU 매장 검색 - -사용자: CU 과자 재고 확인해줘 -AI: cu_check_inventory 도구로 CU 재고/매장 정보 조회 - -사용자: 강남역 근처 메가박스 지점 찾아줘 -AI: megabox_find_nearby_theaters 도구로 주변 지점 조회 - -사용자: 메가박스 강남점 영화 목록과 잔여 좌석 알려줘 -AI: megabox_list_now_showing / megabox_get_remaining_seats 도구로 회차/좌석 조회 - -사용자: 잠실 근처 롯데시네마 지점 찾아줘 -AI: lottecinema_find_nearby_theaters 도구로 주변 지점 조회 - -사용자: 롯데시네마 월드타워 영화 목록과 잔여 좌석 알려줘 -AI: lottecinema_list_now_showing / lottecinema_get_remaining_seats 도구로 회차/좌석 조회 - -사용자: 서울 지역 CGV 극장 목록 알려줘 -AI: cgv_find_theaters 도구로 CGV 극장 목록 조회 - -사용자: CGV 강남 상영 영화랑 시간표 알려줘 -AI: cgv_search_movies / cgv_get_timetable 도구로 영화/시간표 조회 -``` +웹 읽기(open/WebFetch)는 아래 경로로 실행합니다. `{...}`는 앞선 실제 응답 또는 사용자가 알려 준 조건으로 바꾸고 각 값을 한 번 URL 인코딩합니다. 모든 결과는 자동 HTML입니다. + +| 사용자 요청 | 웹 조회 경로 | +| --- | --- | +| 수납박스 검색 | `/browse/daiso/products/수납박스/pageSize/3` | +| 선택한 상품의 안산 중앙역 재고 | `/browse/daiso/inventory/{실제상품ID}/안산중앙역` | +| 강남역 다이소 매장 | `/browse/daiso/stores/강남역` | +| 선택한 매장의 진열 위치 | `/browse/daiso/display-location/{실제상품ID}/{재고응답의storeCode}` | +| 명동 올리브영 매장 | `/browse/oliveyoung/stores/명동` | +| 강남 CU 과자 재고 | `/browse/cu/inventory/과자/강남` | +| 잠실 롯데시네마 극장 | `/browse/lottecinema/theaters/잠실` | +| 선택한 CGV 극장 시간표 | `/browse/cgv/timetable/playDate/{YYYYMMDD}/theaterCode/{실제극장코드}` | + +이미 연결된 MCP 도구가 있으면 웹 GET 대신 [공개 통합 도구](mcp-tools.md)를 사용합니다. 예를 들어 상품 검색은 `search_products(service=daiso, query=수납박스)`, 실제 상품 ID로 재고 조회는 `check_inventory(service=daiso, operation=by_id, productId=실제ID, keyword=사용자지역)`입니다. 위 상세 레퍼런스의 deprecated 별칭을 새 호출 예제로 사용하지 않습니다.
diff --git a/docs/web-discovery.md b/docs/web-discovery.md index 00759a2e..5195c291 100644 --- a/docs/web-discovery.md +++ b/docs/web-discovery.md @@ -41,7 +41,7 @@ OpenAI 검색·사용자 요청·학습 봇의 역할과 공개 IP는 [공식 공개 `/browse/` GET 경로는 같은 실제 조회 결과를 항상 HTML로 제공합니다. 쿼리 문자열은 필요 없습니다. 기존 `/api/`의 JSON과 구형 HTML 주소는 하위호환으로 유지합니다. 예: `/browse/daiso/stores/%EA%B0%95%EB%82%A8`, `/browse/daiso/inventory/%EC%8B%A4%EC%A0%9C%EC%83%81%ED%92%88ID/%ED%99%95%EC%9D%B8%ED%95%9C%EB%A7%A4%EC%9E%A5%EB%AA%85/lat/%ED%99%95%EC%9D%B8%ED%95%9C%EC%9C%84%EB%8F%84/lng/%ED%99%95%EC%9D%B8%ED%95%9C%EA%B2%BD%EB%8F%84`. 상품 목록의 상세 링크도 HTML로 연결합니다. 다른 서비스의 필수 파라미터는 `/prompt`에서 확인합니다. -HTML은 원래 응답의 성공·오류와 HTTP 상태를 보존합니다. 상품 검색 결과를 매장 재고로 단정하거나 오류를 재고 0으로 해석하면 안 됩니다. POST와 MCP 응답 형식은 변경하지 않습니다. 웹 읽기 도구가 HTML 접근도 거부하는 경우에는 이 옵션만으로 도구 내부 문제를 해결하지 못합니다. +HTML은 원래 응답의 성공·오류와 HTTP 상태를 보존합니다. 상품 검색 결과를 매장 재고로 단정하거나 오류를 재고 0으로 해석하면 안 됩니다. POST와 MCP 응답 형식은 변경하지 않습니다. 웹 읽기 도구가 HTML 접근도 거부하는 경우에는 경로 전환만으로 도구 내부의 접근 제한을 해결할 수는 없습니다. `llms.txt`와 `robots.txt`는 정적 Assets에서도 `text/plain; charset=utf-8`을 명시합니다. UTF-8 본문을 다른 인코딩으로 추측하는 클라이언트에서 한글이 깨지는 것을 방지합니다.