diff --git a/README.md b/README.md
index 0a831064..e4629bac 100644
--- a/README.md
+++ b/README.md
@@ -2,25 +2,27 @@
AI 에이전트 사용 안내
> [!IMPORTANT]
-> **안내 버전: 2026-10-21.2 · 갱신일: 2026-10-21**
+> **최신 안내:** [현재 버전](https://mcp.aka.page/guide/2026-10-21.3) · [항상 최신 버전으로 이동](https://mcp.aka.page/guide/latest)
>
-> **ChatGPT 웹 읽기:** 연결된 MCP 도구가 없으면 [HTML GET으로 바로 조회](https://mcp.aka.page/api/daiso/products?q=%EC%88%98%EB%82%A9%EB%B0%95%EC%8A%A4&pageSize=3&format=html)하세요. 설치·API 키·MCP 연결 설정은 필요 없습니다.
+> **안내 버전: 2026-10-21.3 · 갱신일: 2026-10-21**
+>
+> **ChatGPT 웹 읽기:** 연결된 MCP 도구가 없으면 [HTML GET으로 바로 조회](https://mcp.aka.page/api/daiso/products?q=%EC%88%98%EB%82%A9%EB%B0%95%EC%8A%A4&pageSize=3&format=html&guide=2026-10-21.3)하세요. 설치·API 키·MCP 연결 설정은 필요 없습니다.
>
> **로컬 설치·빌드·API 키 준비 없이 실제 조회부터 실행하세요.** 패키지 설치나 전체 스키마 탐색은 필요 없습니다.
>
> 1. 연결된 MCP 도구가 있으면 `search_products`에 `{"service":"daiso","query":"수납박스","pageSize":3}`를 전달합니다.
-> 2. 웹 읽기(open/WebFetch)가 가능하면 [첫 HTML 조회](https://mcp.aka.page/api/daiso/products?q=%EC%88%98%EB%82%A9%EB%B0%95%EC%8A%A4&pageSize=3&format=html)를 바로 엽니다. **셸이 있어도 연결된 MCP 도구가 없으면 HTML GET이 우선입니다.** 검색어 `q`를 사용자 요청으로 바꾸세요. 웹 검색은 URL 열기를 대신하지 않습니다.
-> 3. 위 두 수단이 없을 때만 외부 통신 가능한 셸의 POST를 사용합니다. 셸 DNS 실패를 웹 GET 실패나 서비스 장애로 단정하지 말고, 웹 읽기가 가능하면 HTML GET으로 전환하세요.
+> 2. 웹 읽기(open/WebFetch)가 가능하면 [첫 HTML 조회](https://mcp.aka.page/api/daiso/products?q=%EC%88%98%EB%82%A9%EB%B0%95%EC%8A%A4&pageSize=3&format=html&guide=2026-10-21.3)를 바로 엽니다. **셸이 있어도 연결된 MCP 도구가 없으면 HTML GET이 우선입니다.** 검색어 `q`를 사용자 요청으로 바꾸세요. 웹 검색은 URL 열기를 대신하지 않습니다.
+> 3. 위 두 수단이 없을 때만 사용 가능한 조회 도구가 없음을 알립니다. 터미널·셸 호출로 우회하지 마세요. 셸 DNS 실패를 웹 GET 실패로 확대하거나 실행하지 않은 요청의 실패를 만들지 마세요.
>
> **실행 근거:** 실제 데이터·도구·오류만 보고하고 실행하지 않은 요청의 성공·실패를 만들지 마세요. REST GET 성공은 MCP 연결 성공과 구분합니다.
>
-> **상품 이미지:** 해당 응답의 `imageUrl`만 사용하세요. 없거나 표시되지 않으면 생략하고 웹 검색 이미지·다른 상품·다른 국가의 이미지로 대체하지 마세요.
+> **상품 이미지:** 해당 응답의 `imageUrl`과 카드에 제공된 원본 이미지 Markdown만 사용하세요. `image_query`·이미지 검색·검색 캐러셀은 사용하지 마세요. 원본 표시가 불가능하면 링크나 텍스트만 제공합니다. 없거나 표시되지 않으면 생략하고 웹 검색 이미지·다른 상품·다른 국가의 이미지로 대체하지 마세요.
>
> **MCP 도구는 10개 고정:** `service`와 `operation`으로 지원 서비스를 선택합니다. 새 연동은 [통합 도구 10개](docs/mcp-tools.md)만 사용하세요. 기존 서비스별 도구는 deprecated 호출 별칭으로 유지하지만 목록에는 표시하지 않습니다.
>
> **웹 읽기 전용 에이전트의 `format=html` 사용 필수:** MCP 연결 없이 GET으로 조회할 때는 **모든 `/api/*` 조회 URL에 `format=html`을 반드시 붙이세요.** 상품 검색·상세·매장·재고·후속 조회 모두 적용하며, JSON을 읽을 수 있다고 가정해 생략하지 마세요.
>
-> [첫 HTML 조회](https://mcp.aka.page/api/daiso/products?q=%EC%88%EB%82%A9%EB%B0%95%EC%8A%A4&pageSize=3&format=html) · [REST 사용법](https://mcp.aka.page/prompt) · [원격 MCP 연결](#원격-mcp로-바로-시작하기)
+> [첫 HTML 조회](https://mcp.aka.page/api/daiso/products?q=%EC%88%EB%82%A9%EB%B0%95%EC%8A%A4&pageSize=3&format=html&guide=2026-10-21.3) · [REST 사용법](https://mcp.aka.page/prompt?guide=2026-10-21.3) · [원격 MCP 연결](#원격-mcp로-바로-시작하기)
@@ -123,7 +125,7 @@
2. 서버 URL을 입력하고, 전송 방식을 묻는 경우 **HTTP / Streamable HTTP**를 선택합니다.
3. 도구를 활성화하고 `다이소 MCP로 수납박스 검색해줘`라고 요청합니다.
-[앱별 연결 방법](docs/client-guide.md#원격-mcp-연결) · [HTTP POST 직접 호출](docs/service-reference.md#설치-없이-첫-조회)
+[앱별 연결 방법](docs/client-guide.md#원격-mcp-연결) · [WebFetch로 첫 조회](docs/service-reference.md?guide=2026-10-21.3#설치-없이-첫-조회)
@@ -198,15 +200,15 @@ MCP 연결 없이 웹 읽기와 GET 요청을 지원하는 에이전트는 [REST
-| 문서 | 내용 |
-| :----------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [연결·사용 가이드](docs/client-guide.md) | 앱별 MCP 연결, CLI, Skill, OpenAPI |
-| [서비스 레퍼런스](docs/service-reference.md) | 서비스별 도구·REST API·응답 모델·가격 비교 |
-| [일본 다이소](docs/daiso-jp-network-analysis.md) | 일본 상품·매장 검색과 지원 범위 |
-| [독립·예술영화관](docs/dtryx.md) | 디트릭스 지원 극장과 조회 방법 |
-| [AI 조회 가이드](docs/ai-instruction.md) | 도구 선택과 상품·매장·재고 조회 순서 |
-| [개발·직접 배포](CONTRIBUTING.md) | 개발 환경과 자체 서버 운영 |
-| [운영 가이드](scripts/ops/README.md) | 헬스 체크·요청량·[중계 한도](docs/health-check-stock-and-quota.md)·[주소 검색](docs/geocoding-resilience.md)·[웹 검색 노출](docs/web-discovery.md) |
+| 문서 | 내용 |
+| :-------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [연결·사용 가이드](docs/client-guide.md) | 앱별 MCP 연결, CLI, Skill, OpenAPI |
+| [서비스 레퍼런스](docs/service-reference.md?guide=2026-10-21.3) | 서비스별 도구·REST API·응답 모델·가격 비교 |
+| [일본 다이소](docs/daiso-jp-network-analysis.md) | 일본 상품·매장 검색과 지원 범위 |
+| [독립·예술영화관](docs/dtryx.md) | 디트릭스 지원 극장과 조회 방법 |
+| [AI 조회 가이드](docs/ai-instruction.md) | 도구 선택과 상품·매장·재고 조회 순서 |
+| [개발·직접 배포](CONTRIBUTING.md) | 개발 환경과 자체 서버 운영 |
+| [운영 가이드](scripts/ops/README.md) | 헬스 체크·요청량·[중계 한도](docs/health-check-stock-and-quota.md)·[주소 검색](docs/geocoding-resilience.md)·[웹 검색 노출](docs/web-discovery.md) |
diff --git a/docs/ai-instruction.md b/docs/ai-instruction.md
index b840c697..a5e7e5a5 100644
--- a/docs/ai-instruction.md
+++ b/docs/ai-instruction.md
@@ -2,11 +2,13 @@
## 설치 없이 첫 조회
+최신 지침은 https://mcp.aka.page/guide/latest 를 열어 현재 버전 주소로 이동합니다. 오래된 버전 경로도 최신 지침으로 연결됩니다. 첫 조회에는 지침의 guide 버전을 유지하세요.
+
1. 연결된 MCP 도구가 있으면 `search_products`에 `{"service":"daiso","query":"수납박스","pageSize":3}`를 전달합니다.
2. 웹 읽기(open/WebFetch)가 가능하면 아래 HTML GET을 바로 엽니다. 셸이 있어도 연결된 MCP 도구가 없으면 HTML GET이 우선입니다. 웹 검색(search)은 URL 열기(open)를 대신하지 않습니다.
-3. 위 두 수단이 없을 때만 외부 통신 가능한 셸을 사용합니다. [셸 전용 POST 예제](service-reference.md#설치-없이-첫-조회)를 참고하세요. 셸 DNS 오류를 웹 GET 실패나 서버 장애로 단정하지 말고 웹 읽기가 가능하면 HTML GET으로 즉시 전환합니다.
+3. 위 두 수단이 없을 때만 사용 가능한 조회 도구가 없음을 알립니다. 셸 호출로 우회하지 말고 실제 실행하지 않은 요청을 실패라고 설명하지 않습니다. 셸 DNS 오류는 웹 GET 실패가 아닙니다.
-https://mcp.aka.page/api/daiso/products?q=%EC%88%98%EB%82%A9%EB%B0%95%EC%8A%A4&pageSize=3&format=html
+https://mcp.aka.page/api/daiso/products?q=%EC%88%98%EB%82%A9%EB%B0%95%EC%8A%A4&pageSize=3&format=html&guide=2026-10-21.3
검색어 q를 사용자 요청으로 바꾸세요. 첫 조회 전에 npm·CLI·스킬 설치, health/help, 전체 도구 목록이나 OpenAPI 탐색을 하지 않습니다. 연결 설정을 요구하기 전에 현재 웹 도구로 실제 조회부터 실행합니다.
@@ -14,7 +16,7 @@ https://mcp.aka.page/api/daiso/products?q=%EC%88%98%EB%82%A9%EB%B0%95%EC%8A%A4&p
**실행 근거:** 실제로 실행한 도구·전체 URL·반환 데이터·오류만 보고합니다. 실행하지 않은 웹 GET을 실패했다고 설명하지 않습니다. 웹 도구가 HTTP 상태를 제공하지 않으면 HTTP 200이라고 추정하지 않습니다.
-**상품 이미지:** 해당 조회 응답의 `imageUrl`만 사용하고 전체 URL과 query string을 유지합니다. 없거나 표시되지 않으면 생략하며 웹 검색 이미지·다른 상품·다른 국가 이미지로 대체하지 않습니다.
+**상품 이미지:** 해당 조회 응답의 `imageUrl`만 사용하고 전체 URL과 query string을 유지합니다. 없거나 표시되지 않으면 생략하며 image_query·이미지 검색·검색 캐러셀을 사용하거나 웹 검색 이미지·다른 상품·다른 국가 이미지로 대체하지 않습니다.
공개 원격 MCP 주소는 https://mcp.aka.page 이며 Streamable HTTP, 인증 없음입니다. MCP 클라이언트 연결은 표준 initialize 절차를 따릅니다. 공개 도구는 정확히 10개로 고정하며 늘리지 않습니다. 기존 서비스별 이름은 deprecated 호출 별칭이며 새 호출에 사용하지 않습니다. 전체 계약은 [통합 도구 안내](mcp-tools.md)를 참고하세요.
diff --git a/docs/client-guide.md b/docs/client-guide.md
index 2a17d4d8..8d5f858d 100644
--- a/docs/client-guide.md
+++ b/docs/client-guide.md
@@ -233,7 +233,7 @@ npx daiso products 수납박스 --json
- 공개 페이지: `https://clawhub.ai/hmmhmmhm/daiso-cli`
- 스킬 파일: [skills/daiso-cli/SKILL.md](../skills/daiso-cli/SKILL.md)
- 명령 맵: [CLI 명령 맵](../skills/daiso-cli/references/cli-command-map.md)
-- 사용자가 무설치 조회를 요청하면 연결된 MCP 도구를 사용하고, 없으면 웹 읽기의 HTML GET을 우선 사용합니다. 셸이 있어도 이 순서를 유지하며, 두 수단이 없을 때만 외부 통신 가능한 셸의 POST를 사용합니다. `npx`나 Skill 설치, 전체 스키마 탐색은 필요하지 않습니다.
+- 사용자가 무설치 조회를 요청하면 연결된 MCP 도구를 사용하고, 없으면 웹 읽기의 HTML GET을 우선 사용합니다. 셸이 있어도 이 순서를 유지하며, 두 수단이 없으면 실제 도구 제약을 알리고 셸 호출로 우회하지 않습니다. WebFetch 또는 open으로 HTML 링크를 직접 여세요. `npx`나 Skill 설치, 전체 스키마 탐색은 필요하지 않습니다.
- CLI를 사용하기로 선택했고 쉘 실행이 가능한 환경에서만 `npx daiso`를 사용합니다. AI 앱 연결에는 MCP 서버 URL `https://mcp.aka.page`를 사용합니다.
- 구조화 결과가 필요하면 스킬은 `npx daiso ... --json` 형태를 선택합니다.
- 상황별 레시피는 `콜라 어디가 싸?`, `강남역 근처 카페`, `다이소 핫식스 재고`, `오늘 강남 CGV 시간표`처럼 실제 사용자 문장 기준으로 정리되어 있습니다.
diff --git a/docs/gpts-maintenance.md b/docs/gpts-maintenance.md
index 7045fcc8..4d427be9 100644
--- a/docs/gpts-maintenance.md
+++ b/docs/gpts-maintenance.md
@@ -29,7 +29,7 @@ Actions는 JSON 응답을 직접 소비합니다. 웹 검색/웹 읽기로 REST
재고 0, 미확인 수량, 원본 차단, 자체 한도, 인증 오류를 구분합니다. 실패를 정상 품절이나 결과 없음으로 바꾸지 않습니다. 실제 호출 결과에 없는 수량·영업시간·가격·좌표·상품 코드를 만들지 않습니다. 실패 시 한 번만 조건을 좁혀 재시도하고 계속 실패하면 원인과 확인하지 못한 범위를 알립니다. 캐시 응답은 실시간 원본을 검증한 것처럼 설명하지 않습니다.
-결과는 사용자에게 필요한 상품명·가격·매장명·주소·재고·상영 시각·남은 좌석 중심으로 정리합니다. 이미지는 해당 조회 응답의 imageUrl만 사용하고 전체 URL을 유지합니다. 없거나 표시되지 않으면 생략하며 웹 검색 이미지·다른 상품·다른 국가 이미지로 대체하지 않습니다. 출처/상품 링크가 있으면 함께 제공합니다. 데이터가 없으면 없음과 미확인을 구분합니다.
+결과는 사용자에게 필요한 상품명·가격·매장명·주소·재고·상영 시각·남은 좌석 중심으로 정리합니다. 이미지는 해당 조회 응답의 imageUrl만 사용하고 전체 URL을 유지합니다. 없거나 표시되지 않으면 생략하며 image_query·이미지 검색·검색 캐러셀을 사용하거나 웹 검색 이미지·다른 상품·다른 국가 이미지로 대체하지 않습니다. 출처/상품 링크가 있으면 함께 제공합니다. 데이터가 없으면 없음과 미확인을 구분합니다.
사용자가 개발자 전달을 명시적으로 요청한 경우에만 submitDeveloperRequest를 사용합니다. 제목과 설명을 확인하고 비밀번호·인증 코드·토큰·쿠키·개인정보를 포함하지 않습니다. 테스트나 일반 조회 과정에서 요청을 임의로 제출하지 않습니다.
diff --git a/docs/service-reference.md b/docs/service-reference.md
index 86625625..bcb7777e 100644
--- a/docs/service-reference.md
+++ b/docs/service-reference.md
@@ -4,22 +4,15 @@ README 하단에 있던 기능, REST API, 개발, 아키텍처 설명을 분리
## 설치 없이 첫 조회
-공개 원격 MCP는 `https://mcp.aka.page`이며 Streamable HTTP 방식이고 인증·API 키가 필요 없습니다.
-에이전트용 짧은 안내는 [빠른 시작](https://mcp.aka.page/llms.txt)에 있습니다. 첫 조회에는 이 상세 레퍼런스나 전체 도구 목록을 먼저 읽을 필요가 없습니다.
+**ChatGPT 및 웹 읽기 에이전트는 터미널을 실행하지 말고 WebFetch 또는 URL 열기(open) 도구로 아래 링크를 직접 여세요.** 설치·API 키·MCP 연결 설정 없이 상품 검색 결과를 읽을 수 있습니다. 검색 도구(search)는 URL 열기를 대신하지 않습니다.
-연결된 MCP 도구가 있으면 `search_products`에 `service=daiso`를 전달합니다. 없으면 셸이 있어도 웹 읽기의 [첫 HTML GET](https://mcp.aka.page/api/daiso/products?q=%EC%88%98%EB%82%A9%EB%B0%95%EC%8A%A4&pageSize=3&format=html)을 먼저 엽니다. 모든 후속 웹 GET에도 `format=html`을 붙입니다. 셸 DNS 실패는 웹 GET 실패가 아니며 실제 실행하지 않은 요청을 실패했다고 보고하지 않습니다.
+[WebFetch로 다이소 수납박스 3개 조회](https://mcp.aka.page/api/daiso/products?q=%EC%88%98%EB%82%A9%EB%B0%95%EC%8A%A4&pageSize=3&format=html&guide=2026-10-21.3)
-위 두 수단이 없고 외부 통신 가능한 셸만 있다면 아래 한 요청으로 실제 MCP 상품 조회를 완료합니다. 루트 POST가 지원하는 서버 전용 단축 경로여서 initialize나 로컬 패키지 설치가 필요 없습니다.
+모든 후속 웹 GET에도 `format=html&guide=2026-10-21.3`을 유지하세요. 상품 검색 결과의 실제 ID로 재고를 조회하고 검색 성공만으로 매장 재고를 단정하지 않습니다. 이미지는 응답 imageUrl과 카드의 원본 Markdown만 사용하고 이미지 검색으로 대체하지 않습니다.
-```bash
-curl -sS -N --max-time 20 'https://mcp.aka.page/' \
- -H 'Content-Type: application/json' \
- -H 'Accept: application/json, text/event-stream' \
- --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_products","arguments":{"service":"daiso","query":"수납박스","pageSize":3}}}'
-```
+현재 안내는 [버전 안내](https://mcp.aka.page/guide/2026-10-21.3), 다음 버전도 따라가려면 [항상 최신 안내](https://mcp.aka.page/guide/latest)를 여세요. 이 상세 레퍼런스를 끝까지 읽기 전에 첫 조회를 실행하세요.
-SSE `data:`의 JSON에 `error`가 없고 `result.isError`가 true가 아닌지 확인한 뒤 `result.structuredContent.products`에서 실제 상품을 읽습니다. 검색에 성공하면 결과부터 보여주고 추가 진단은 생략합니다.
-범용 MCP 클라이언트는 표준 initialize 흐름을 사용하며 `/mcp`는 초기화가 필요합니다. 웹 읽기가 가능하면 위 HTML GET을 우선 사용하세요.
+이미 연결된 MCP 도구가 있는 환경만 `search_products`에 `service=daiso`, `query=수납박스`를 전달합니다. 서버는 https://mcp.aka.page 이며 Streamable HTTP, 인증 없음입니다. 실제로 실행한 도구·URL·오류만 보고하고 실행하지 않은 요청의 성공·실패를 만들지 않습니다.
### 구형 도구 레퍼런스의 범위
diff --git a/docs/superpowers/plans/2026-10-21-latest-guide.md b/docs/superpowers/plans/2026-10-21-latest-guide.md
new file mode 100644
index 00000000..95e1b46d
--- /dev/null
+++ b/docs/superpowers/plans/2026-10-21-latest-guide.md
@@ -0,0 +1,11 @@
+# 최신 안내 발견 경로와 원본 이미지 표시
+
+사용자 승인 범위: 최신 버전 안내의 자연스러운 발견과 원본 상품 이미지만 사용하도록 개선한다.
+
+- /guide/latest는 현재 버전의 /guide/버전으로 임시 리다이렉트하며 캐시하지 않는다. 이전 버전 경로도 현재 버전으로 연결한다. 기존 llms/prompt/JSON/MCP 호환은 유지한다.
+- README·첫화면·메타·robots·sitemap·공통프롬프트에서 현재 버전 안내를 연결한다. 첫 HTML 조회와 후속 상세 링크에 guide 버전을 전달하고 오래된 안내/결과를 최신으로 단정하지 않는다.
+- 상품 카드에 동일 응답 imageUrl로 만든 복사 가능한 Markdown과 원본 링크를 함께 제공한다. 이미지 검색/image_query/검색 캐러셀로 대체하지 않으며, 원본 표시 불가시 링크나 텍스트만 제공한다.
+- 안내/HTML은 새 캐시 저장을 막고 JSON과 원본 API 캐시는 유지한다. 외부 검색 캐시의 강제 삭제나 에이전트 판단을 보장하지 않는다.
+- 회귀 red/green, 전체 check/coverage100/build/발견자산, 독립리뷰, GitHub검사·병합배포 후 실제 최신 안내·상품·후속 링크와 MCP10개를 검증한다.
+
+추가 사용자 요청: 에이전트가 찾는 service-reference와 README/시작 안내/스킬의 터미널 호출 예제를 제거하고 WebFetch·URL 열기만 안내한다. 셸 우회 예제를 다시 노출하지 않는 회귀 검사를 유지한다. 서버의 MCP 전송 계약은 유지한다.
diff --git a/docs/web-discovery.md b/docs/web-discovery.md
index ead60dd0..0d00ab4f 100644
--- a/docs/web-discovery.md
+++ b/docs/web-discovery.md
@@ -1,6 +1,6 @@
# 웹에서 다이소 MCP 발견하기
-[공개 첫 화면](https://mcp.aka.page/)은 설치 없는 사용 방법과 첫 실제 조회 링크를 HTML로 제공합니다. 웹 읽기 기능만으로 MCP 도구가 자동 등록되는 것은 아닙니다. 연결된 MCP 도구를 먼저 사용하고, 없으면 셸 유무와 무관하게 웹 읽기의 HTML GET을 바로 실행합니다. 두 수단이 없을 때만 외부 통신 가능한 셸의 POST를 사용합니다.
+[공개 첫 화면](https://mcp.aka.page/)은 설치 없는 사용 방법과 첫 실제 조회 링크를 HTML로 제공합니다. 웹 읽기 기능만으로 MCP 도구가 자동 등록되는 것은 아닙니다. 연결된 MCP 도구를 먼저 사용하고, 없으면 셸 유무와 무관하게 웹 읽기의 HTML GET을 바로 실행합니다. 두 수단이 없으면 실제 조회 도구 제약을 알리며 셸 호출로 우회하지 않습니다. WebFetch 또는 open으로 HTML 링크를 직접 엽니다.
- `/`: HTML 안내. `Accept: application/json`이면 기존 서버 정보 JSON.
- `/root.json`: 현재 서비스·도구 목록 JSON. API 클라이언트는 이 명시적 주소를 권장합니다.
@@ -53,6 +53,13 @@ HTML은 원래 응답의 성공·오류와 HTTP 상태를 보존합니다. 상
## 안내 버전과 상품 이미지 카드
-현재 안내 버전은 `2026-10-21.2`, 갱신일은 `2026-10-21`입니다. README의 AI 안내, 첫 화면, llms.txt, prompt와 HTML 조회 결과에 표시합니다. 버전이 없거나 다르면 예전 검색 사본일 수 있으므로 실제 읽은 URL과 문구를 확인하고 최신 버전을 읽었다고 추정하지 않습니다. 검색 엔진의 재수집·캐시 반영 시각은 이 배포로 보장하지 않습니다.
+현재 안내 버전은 `2026-10-21.3`, 갱신일은 `2026-10-21`입니다. README의 AI 안내, 첫 화면, llms.txt, prompt와 HTML 조회 결과에 표시합니다. 버전이 없거나 다르면 예전 검색 사본일 수 있으므로 실제 읽은 URL과 문구를 확인하고 최신 버전을 읽었다고 추정하지 않습니다. 검색 엔진의 재수집·캐시 반영 시각은 이 배포로 보장하지 않습니다.
상품 HTML은 이름·ID·원본 필드와 응답 imageUrl의 이미지를 같은 카드에 표시합니다. 이미지 링크는 원본 URL의 쿼리까지 유지하며 HTTPS이고 인증정보가 없는 주소만 사용합니다. imageUrl이 없거나 안전한 이미지 주소가 아니면 이미지 없음으로 표시합니다. 검색 이미지로 채우지 않습니다. JSON API 필드와 오류 상태는 유지합니다.
+
+
+## 최신 안내의 연결 계약
+
+`/guide/latest` 및 이전 `/guide/버전`은 307과 Cache-Control: no-store로 현재 `/guide/2026-10-21.3`에 연결합니다. 새 버전 배포 시 공통 상수와 README·스킬 안내를 함께 갱신합니다. 첫 화면·robots·sitemap도 같은 상수의 현재 경로를 안내합니다. 외부 캐시가 과거 응답이나 리다이렉트를 재사용하는 것까지 강제할 수는 없습니다.
+
+첫 HTML 조회와 상품 상세 링크는 format=html 및 guide 버전을 포함합니다. 프롬프트의 REST 예제도 같은 버전을 사용합니다. 안내와 HTML 결과는 no-store를 보내며 기존 JSON/API 원본 캐시 정책은 유지합니다. 이미지 카드에는 원본 imageUrl로 생성한 Markdown을 제공하고 이미지 검색/image_query/캐러셀 대체를 금지합니다. 표시가 불가능하면 원본 링크와 텍스트만 제공합니다.
diff --git a/skills/daiso-cli/SKILL.md b/skills/daiso-cli/SKILL.md
index effa646e..60b31437 100644
--- a/skills/daiso-cli/SKILL.md
+++ b/skills/daiso-cli/SKILL.md
@@ -1,7 +1,7 @@
---
name: daiso-cli
description: Use this when a user wants to search Daiso/다이소, compare product price candidates, nearby restaurants/cafes/음식점/카페, convenience stores/편의점, marts, Olive Young/올리브영, Megabox/메가박스, Lotte Cinema/롯데시네마, or CGV data through the Daiso project. Honor explicit no-install requests with connected MCP tools first, then HTML GET via web reading even when a shell is available; otherwise prefer the daiso CLI for direct execution, use the MCP endpoint when the host app supports remote MCP, and choose commands for products, stores, inventory/재고, compare, places, movies, showtimes, seats, health checks, and raw JSON output.
-version: 1.0.7
+version: 1.0.8
metadata:
openclaw:
requires:
@@ -21,27 +21,20 @@ Use this skill to operate the Daiso MCP project through `npx daiso` and the publ
## 설치 없이 첫 조회
+최신 지침은 https://mcp.aka.page/guide/latest 를 열어 현재 버전 주소로 이동합니다. 오래된 버전 경로도 최신 지침으로 연결됩니다. 첫 조회에는 지침의 guide 버전을 유지하세요.
+
1. 연결된 MCP 도구가 있으면 `search_products`에 `{"service":"daiso","query":"수납박스","pageSize":3}`를 전달합니다.
2. 웹 읽기(open/WebFetch)가 가능하면 아래 HTML GET을 바로 엽니다. 셸이 있어도 연결된 MCP 도구가 없으면 이 경로가 우선입니다. 검색(search)은 URL 열기(open)를 대신하지 않습니다.
-3. 위 두 수단이 없을 때만 외부 통신 가능한 셸에서 루트 POST를 사용합니다. 셸 DNS 실패를 웹 GET 실패나 서버 장애로 확대하지 말고 웹 읽기가 가능하면 HTML GET으로 전환합니다.
+3. 위 두 수단이 없을 때만 사용 가능한 조회 도구가 없음을 알립니다. 셸 호출로 우회하지 않으며, 셸 DNS 오류를 웹 GET 실패로 확대하지 않습니다. 실제로 실행하지 않은 요청의 성공·실패를 만들지 않습니다.
-https://mcp.aka.page/api/daiso/products?q=%EC%88%98%EB%82%A9%EB%B0%95%EC%8A%A4&pageSize=3&format=html
+https://mcp.aka.page/api/daiso/products?q=%EC%88%98%EB%82%A9%EB%B0%95%EC%8A%A4&pageSize=3&format=html&guide=2026-10-21.3
검색어 q를 사용자 요청으로 바꾸고 상세·매장·재고를 포함한 모든 후속 웹 GET에도 `format=html`을 반드시 붙이세요. 첫 조회 전에 npx·패키지·스킬 설치, health/help, 전체 도구 목록이나 OpenAPI 탐색을 요구하지 않습니다. REST GET 성공과 MCP 도구 호출 성공은 구분합니다.
-상품 이미지는 해당 조회 응답의 imageUrl만 사용합니다. 전체 URL과 query string을 유지하고, 없거나 표시되지 않으면 생략하며 웹 검색 이미지·다른 상품·다른 국가 이미지로 대체하지 않습니다. 실제 도구·URL·반환 데이터·오류만 보고하고 실행하지 않은 요청의 성공·실패를 만들지 않습니다.
+상품 이미지는 해당 조회 응답의 imageUrl만 사용합니다. 전체 URL과 query string을 유지하고, 없거나 표시되지 않으면 생략하며 image_query·이미지 검색·검색 캐러셀을 사용하거나 웹 검색 이미지·다른 상품·다른 국가 이미지로 대체하지 않습니다. 실제 도구·URL·반환 데이터·오류만 보고하고 실행하지 않은 요청의 성공·실패를 만들지 않습니다.
공개 MCP는 https://mcp.aka.page, Streamable HTTP, 인증 없음입니다. 연결은 표준 initialize 절차를 사용합니다. 공개 도구 10개는 늘리지 않습니다. 기존 서비스별 이름은 deprecated 별칭이며 새 호출에 쓰지 않습니다.
-셸 전용 대안은 다음과 같습니다. SSE의 error/result.isError를 확인하고 result.structuredContent.products 또는 content[].text에서 실제 결과를 읽으세요.
-
-```bash
-curl -fsS -N --max-time 20 'https://mcp.aka.page/' \
- -H 'Content-Type: application/json' \
- -H 'Accept: application/json, text/event-stream' \
- --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_products","arguments":{"service":"daiso","query":"수납박스","pageSize":3}}}'
-```
-
## Core Rule
무설치 요청이 아니고 CLI 사용이 허용된 환경에서는 CLI를 우선 사용한다. The CLI is the preferred path when you can run shell commands and package execution is allowed. Use the MCP endpoint when the user is configuring an AI app or explicitly asks for MCP connection details.
diff --git a/src/index.ts b/src/index.ts
index 3c2c5be7..9db5a26c 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -39,7 +39,7 @@ import { createPlacesService } from './services/places/index.js';
import { createOpinetService } from './services/opinet/index.js';
import { createCompareService } from './services/compare/index.js';
import { createFeedbackService } from './services/feedback/index.js';
-import { createAgentStartResponse } from './pages/agentStart.js';
+import { createAgentStartResponse, createVersionedGuideResponse } from './pages/agentStart.js';
import { createPromptResponse } from './pages/prompt.js';
import { buildDiscoveryAssets } from './pages/discovery.js';
import {
@@ -200,7 +200,7 @@ function createRootInfoResponse(request: Request): Response {
status: 200,
headers: { ...ROOT_INFO_HEADERS,
'Content-Type': json ? 'application/json; charset=utf-8' : 'text/html; charset=utf-8',
- 'Content-Length': String(body.byteLength), Vary: 'Accept' },
+ 'Content-Length': String(body.byteLength), 'Cache-Control': json ? ROOT_INFO_HEADERS['Cache-Control'] : 'no-store', Vary: 'Accept' },
});
}
/**
@@ -364,13 +364,11 @@ registerRateLimitStatsRoutes(app);
registerServiceRoutes(app);
// 설치 없는 첫 조회 안내
+app.get('/guide/:version', (c) => createVersionedGuideResponse(new URL(c.req.url).origin, c.req.param('version')));
app.get('/llms.txt', (c) => createAgentStartResponse(new URL(c.req.url).origin));
// 프롬프트 페이지 (MCP 미지원 에이전트용)
-app.get('/prompt', (c) => {
- const baseUrl = new URL(c.req.url).origin;
- return createPromptResponse(baseUrl);
-});
+app.get('/prompt', (c) => createPromptResponse(new URL(c.req.url).origin));
// OpenAPI 스펙 엔드포인트 (ChatGPT GPTs 등록용)
app.get('/openapi.json', (c) => {
diff --git a/src/pages/agentStart.ts b/src/pages/agentStart.ts
index bb410931..af98ca6a 100644
--- a/src/pages/agentStart.ts
+++ b/src/pages/agentStart.ts
@@ -1,7 +1,9 @@
/** 검색·읽기 사본의 안내 세대를 구분하는 고정 버전 */
-export const AGENT_GUIDE_VERSION = '2026-10-21.2';
+export const AGENT_GUIDE_VERSION = '2026-10-21.3';
export const AGENT_GUIDE_UPDATED = '2026-10-21';
export const AGENT_GUIDE_STAMP = `안내 버전: ${AGENT_GUIDE_VERSION} · 갱신일: ${AGENT_GUIDE_UPDATED}`;
+export const AGENT_GUIDE_PATH = `/guide/${AGENT_GUIDE_VERSION}`;
+export const HTML_GUIDE_QUERY = `&guide=${AGENT_GUIDE_VERSION}`;
export const WEB_SEARCH_DESCRIPTION = 'ChatGPT 웹 읽기로 설치·API 키·MCP 연결 설정 없이 바로 상품을 조회하세요. URL 열기로 /api/daiso/products?q=검색어&format=html을 사용합니다. 다이소·편의점 재고와 영화·생활 정보도 지원합니다.';
/** 웹 읽기 환경에서 조회 형식을 선택하는 공통 규칙 */
@@ -10,10 +12,10 @@ export const WEB_READ_RULE = '웹 읽기 전용 에이전트: 모든 /api/* GET
/** 셸 존재를 네트워크 접근 가능 여부로 오해하지 않는 실행 순서 */
export const ROUTE_SELECTION_TEXT = `1. 연결된 MCP 도구가 있으면 search_products {"service":"daiso","query":"수납박스","pageSize":3}를 호출합니다.
2. 웹 읽기(open/WebFetch)가 가능하면 HTML GET 주소를 바로 엽니다. 셸이 있어도 연결된 MCP 도구가 없으면 이 경로가 우선입니다. 웹 검색(search)은 URL 열기(open)를 대신하지 않습니다.
-3. 위 두 수단이 없을 때만 외부 통신 가능한 셸에서 아래 POST를 사용합니다. 셸 DNS 오류는 그 실행 환경의 실패이며 웹 GET 실패나 서버 장애의 근거가 아닙니다. 웹 읽기가 가능하면 HTML GET으로 즉시 전환합니다.`;
+3. 위 두 수단이 없을 때만 사용 가능한 조회 도구가 없음을 알립니다. 터미널·셸 호출로 우회하지 않습니다. 셸 DNS 오류를 웹 GET 실패나 서버 장애로 확대하지 말고 실제로 실행하지 않은 요청의 실패를 만들지 마세요.`;
/** 유사 상품의 웹 검색 이미지를 실제 상품 사진으로 오인하지 않도록 제한합니다. */
-export const IMAGE_SOURCE_RULE = '상품 이미지는 해당 조회 응답의 imageUrl만 사용하세요. 전체 URL과 query string을 유지합니다. imageUrl이 없거나 표시되지 않으면 이미지를 생략하고 웹 검색 이미지·다른 상품·다른 국가의 이미지로 대체하지 마세요.';
+export const IMAGE_SOURCE_RULE = '상품 이미지는 해당 조회 응답의 imageUrl만 사용하세요. image_query·이미지 검색·검색 이미지 캐러셀은 사용하지 마세요. 카드의 원본 이미지 Markdown을 그대로 쓰고, 표시할 수 없으면 원본 링크와 텍스트만 제공하세요. 전체 URL과 query string을 유지합니다. imageUrl이 없거나 표시되지 않으면 이미지를 생략하고 웹 검색 이미지·다른 상품·다른 국가의 이미지로 대체하지 마세요.';
/** 실행 기록 없이 성공·실패나 HTTP 상태를 단정하지 않도록 안내합니다. */
export const EXECUTION_EVIDENCE_RULE = '실제로 실행한 도구·요청 URL·반환 데이터와 확인된 오류만 보고하세요. 실행하지 않은 웹 GET을 실패했다고 말하거나 검색 결과·문서 예제를 실제 조회 결과로 제시하지 마세요. 도구가 HTTP 상태를 제공하지 않으면 HTTP 200이라고 추정하지 마세요. REST GET 성공과 MCP 도구 호출 성공은 구분합니다.';
@@ -22,6 +24,7 @@ export const EXECUTION_EVIDENCE_RULE = '실제로 실행한 도구·요청 URL·
export function buildAgentStartText(baseUrl: string): string {
return `# DAISO MCP: 설치 없이 시작하기
${AGENT_GUIDE_STAMP}
+최신 안내: ${baseUrl}${AGENT_GUIDE_PATH} (이전 버전은 /guide/latest에서 갱신). 버전 없는 검색 사본을 최신이라고 추정하지 마세요.
**${WEB_READ_RULE}**
@@ -32,22 +35,15 @@ ${AGENT_GUIDE_STAMP}
${ROUTE_SELECTION_TEXT}
웹 읽기용 첫 조회 (사용자 검색어로 q를 바꾸세요):
-${baseUrl}/api/daiso/products?q=%EC%88%98%EB%82%A9%EB%B0%95%EC%8A%A4&pageSize=3&format=html
-이것은 공개 REST GET이며 MCP 프로토콜 호출이 아닙니다. 상품 결과의 실제 id로 상세·재고를 조회하고 모든 후속 URL에도 format=html을 붙이세요. 상품 검색만으로 매장 재고를 단정하지 마세요.
+${baseUrl}/api/daiso/products?q=%EC%88%98%EB%82%A9%EB%B0%95%EC%8A%A4&pageSize=3&format=html${HTML_GUIDE_QUERY}
+이것은 공개 REST GET이며 MCP 프로토콜 호출이 아닙니다. 상품 결과의 실제 id로 상세·재고를 조회하고 모든 후속 URL에도 format=html과 guide=${AGENT_GUIDE_VERSION}을 유지하세요. 상품 검색만으로 매장 재고를 단정하지 마세요.
${IMAGE_SOURCE_RULE}
${EXECUTION_EVIDENCE_RULE}
-셸 전용 대안: 루트 POST의 stateless 호출은 이 서버가 지원하는 단축 경로입니다. /mcp 및 범용 클라이언트 연결은 initialize → notifications/initialized 후 mcp-session-id를 전달합니다.
-\`\`\`bash
-curl --max-time 20 -sS -N ${baseUrl}/ \\
- -H 'Content-Type: application/json' \\
- -H 'Accept: application/json, text/event-stream' \\
- --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_products","arguments":{"service":"daiso","query":"수납박스","pageSize":3}}}'
-\`\`\`
-응답은 SSE의 data: JSON-RPC 메시지입니다. result.isError=true이거나 error 응답이면 실패입니다. 상품은 result.structuredContent.products 또는 content[].text의 JSON에서 읽으세요. 오류·미확인을 재고 0으로 해석하지 마세요.
+연결된 MCP 클라이언트는 initialize 절차를 처리합니다. MCP 결과의 isError=true/error를 확인하고 structuredContent 또는 content[].text에서 실제 상품을 읽습니다. 웹 읽기는 WebFetch·open 도구에서 위 HTML GET 링크를 그대로 여세요.
기존 서비스별 MCP 이름은 deprecated 호출 별칭입니다. 새 연동은 공개 도구 10개만 사용하며 도구를 늘리지 않습니다.
-상세 API와 서비스 안내: ${baseUrl}/prompt
+상세 API와 서비스 안내: ${baseUrl}/prompt?guide=${AGENT_GUIDE_VERSION}
---
@@ -59,7 +55,13 @@ export function createAgentStartResponse(baseUrl: string): Response {
return new Response(buildAgentStartText(baseUrl), {
headers: {
'Content-Type': 'text/plain; charset=utf-8',
- 'Cache-Control': 'public, max-age=3600',
+ 'Cache-Control': 'no-store',
},
});
}
+
+/** 오래된 버전 주소도 현재 안내로 연결하며 영구 리다이렉트 캐시를 만들지 않습니다. */
+export function createVersionedGuideResponse(baseUrl: string, version: string): Response {
+ if (version === AGENT_GUIDE_VERSION) return createAgentStartResponse(baseUrl);
+ return new Response(null, { status: 307, headers: { Location: AGENT_GUIDE_PATH, 'Cache-Control': 'no-store' } });
+}
diff --git a/src/pages/apiResult.ts b/src/pages/apiResult.ts
index 45754609..0a832605 100644
--- a/src/pages/apiResult.ts
+++ b/src/pages/apiResult.ts
@@ -1,5 +1,5 @@
/** 웹 읽기 에이전트용 공개 GET 결과 표시 */
-import { WEB_READ_RULE, IMAGE_SOURCE_RULE, EXECUTION_EVIDENCE_RULE, AGENT_GUIDE_STAMP } from './agentStart.js';
+import { WEB_READ_RULE, IMAGE_SOURCE_RULE, EXECUTION_EVIDENCE_RULE, AGENT_GUIDE_STAMP, AGENT_GUIDE_PATH, AGENT_GUIDE_VERSION, HTML_GUIDE_QUERY } from './agentStart.js';
import type { MiddlewareHandler } from 'hono';
import type { AppBindings } from '../api/response.js';
@@ -15,7 +15,9 @@ function productImage(value: unknown, name: string): string {
const url = new URL(value);
if (url.protocol === 'https:' && !url.username && !url.password) {
const source = escapeHtml(value);
- return `원본 상품 이미지`;
+ const label = name.replace(/[\\[\]]/g, '\\$&').replace(/[\r\n]/g, ' ');
+ const markdown = `}>)`;
+ return `원본 상품 이미지
복사할 원본 이미지 Markdown: ${escapeHtml(markdown)}
이 상품에는 이 원본 주소만 사용하세요. 이미지 검색·캐러셀로 대체하지 마세요.
`;
}
} catch { /* 잘못된 원본 URL은 아래 이미지 없음으로 표시합니다. */ }
}
@@ -31,7 +33,7 @@ function renderValue(value: unknown, productLinks: string | null, product = fals
const fields = `
`;
const record = value as Record;
@@ -55,19 +57,21 @@ export const apiResultHtml: MiddlewareHandler<{ Bindings: AppBindings }> = async
const inventoryGuide = japan ? '일본 매장 재고 미지원. 온라인 판매 가능 여부를 매장 재고로 해석하지 마세요.' : '매장 재고는 상품 ID와 매장명 또는 사용자 위치를 확인한 뒤 별도로 조회하세요.';
const html = `${title}: DAISO MCP
@@ -198,15 +200,15 @@ MCP 연결 없이 웹 읽기와 GET 요청을 지원하는 에이전트는 [REST
diff --git a/docs/ai-instruction.md b/docs/ai-instruction.md
index b840c697..a5e7e5a5 100644
--- a/docs/ai-instruction.md
+++ b/docs/ai-instruction.md
@@ -2,11 +2,13 @@
## 설치 없이 첫 조회
+최신 지침은 https://mcp.aka.page/guide/latest 를 열어 현재 버전 주소로 이동합니다. 오래된 버전 경로도 최신 지침으로 연결됩니다. 첫 조회에는 지침의 guide 버전을 유지하세요.
+
1. 연결된 MCP 도구가 있으면 `search_products`에 `{"service":"daiso","query":"수납박스","pageSize":3}`를 전달합니다.
2. 웹 읽기(open/WebFetch)가 가능하면 아래 HTML GET을 바로 엽니다. 셸이 있어도 연결된 MCP 도구가 없으면 HTML GET이 우선입니다. 웹 검색(search)은 URL 열기(open)를 대신하지 않습니다.
-3. 위 두 수단이 없을 때만 외부 통신 가능한 셸을 사용합니다. [셸 전용 POST 예제](service-reference.md#설치-없이-첫-조회)를 참고하세요. 셸 DNS 오류를 웹 GET 실패나 서버 장애로 단정하지 말고 웹 읽기가 가능하면 HTML GET으로 즉시 전환합니다.
+3. 위 두 수단이 없을 때만 사용 가능한 조회 도구가 없음을 알립니다. 셸 호출로 우회하지 말고 실제 실행하지 않은 요청을 실패라고 설명하지 않습니다. 셸 DNS 오류는 웹 GET 실패가 아닙니다.
-https://mcp.aka.page/api/daiso/products?q=%EC%88%98%EB%82%A9%EB%B0%95%EC%8A%A4&pageSize=3&format=html
+https://mcp.aka.page/api/daiso/products?q=%EC%88%98%EB%82%A9%EB%B0%95%EC%8A%A4&pageSize=3&format=html&guide=2026-10-21.3
검색어 q를 사용자 요청으로 바꾸세요. 첫 조회 전에 npm·CLI·스킬 설치, health/help, 전체 도구 목록이나 OpenAPI 탐색을 하지 않습니다. 연결 설정을 요구하기 전에 현재 웹 도구로 실제 조회부터 실행합니다.
@@ -14,7 +16,7 @@ https://mcp.aka.page/api/daiso/products?q=%EC%88%98%EB%82%A9%EB%B0%95%EC%8A%A4&p
**실행 근거:** 실제로 실행한 도구·전체 URL·반환 데이터·오류만 보고합니다. 실행하지 않은 웹 GET을 실패했다고 설명하지 않습니다. 웹 도구가 HTTP 상태를 제공하지 않으면 HTTP 200이라고 추정하지 않습니다.
-**상품 이미지:** 해당 조회 응답의 `imageUrl`만 사용하고 전체 URL과 query string을 유지합니다. 없거나 표시되지 않으면 생략하며 웹 검색 이미지·다른 상품·다른 국가 이미지로 대체하지 않습니다.
+**상품 이미지:** 해당 조회 응답의 `imageUrl`만 사용하고 전체 URL과 query string을 유지합니다. 없거나 표시되지 않으면 생략하며 image_query·이미지 검색·검색 캐러셀을 사용하거나 웹 검색 이미지·다른 상품·다른 국가 이미지로 대체하지 않습니다.
공개 원격 MCP 주소는 https://mcp.aka.page 이며 Streamable HTTP, 인증 없음입니다. MCP 클라이언트 연결은 표준 initialize 절차를 따릅니다. 공개 도구는 정확히 10개로 고정하며 늘리지 않습니다. 기존 서비스별 이름은 deprecated 호출 별칭이며 새 호출에 사용하지 않습니다. 전체 계약은 [통합 도구 안내](mcp-tools.md)를 참고하세요.
diff --git a/docs/client-guide.md b/docs/client-guide.md
index 2a17d4d8..8d5f858d 100644
--- a/docs/client-guide.md
+++ b/docs/client-guide.md
@@ -233,7 +233,7 @@ npx daiso products 수납박스 --json
- 공개 페이지: `https://clawhub.ai/hmmhmmhm/daiso-cli`
- 스킬 파일: [skills/daiso-cli/SKILL.md](../skills/daiso-cli/SKILL.md)
- 명령 맵: [CLI 명령 맵](../skills/daiso-cli/references/cli-command-map.md)
-- 사용자가 무설치 조회를 요청하면 연결된 MCP 도구를 사용하고, 없으면 웹 읽기의 HTML GET을 우선 사용합니다. 셸이 있어도 이 순서를 유지하며, 두 수단이 없을 때만 외부 통신 가능한 셸의 POST를 사용합니다. `npx`나 Skill 설치, 전체 스키마 탐색은 필요하지 않습니다.
+- 사용자가 무설치 조회를 요청하면 연결된 MCP 도구를 사용하고, 없으면 웹 읽기의 HTML GET을 우선 사용합니다. 셸이 있어도 이 순서를 유지하며, 두 수단이 없으면 실제 도구 제약을 알리고 셸 호출로 우회하지 않습니다. WebFetch 또는 open으로 HTML 링크를 직접 여세요. `npx`나 Skill 설치, 전체 스키마 탐색은 필요하지 않습니다.
- CLI를 사용하기로 선택했고 쉘 실행이 가능한 환경에서만 `npx daiso`를 사용합니다. AI 앱 연결에는 MCP 서버 URL `https://mcp.aka.page`를 사용합니다.
- 구조화 결과가 필요하면 스킬은 `npx daiso ... --json` 형태를 선택합니다.
- 상황별 레시피는 `콜라 어디가 싸?`, `강남역 근처 카페`, `다이소 핫식스 재고`, `오늘 강남 CGV 시간표`처럼 실제 사용자 문장 기준으로 정리되어 있습니다.
diff --git a/docs/gpts-maintenance.md b/docs/gpts-maintenance.md
index 7045fcc8..4d427be9 100644
--- a/docs/gpts-maintenance.md
+++ b/docs/gpts-maintenance.md
@@ -29,7 +29,7 @@ Actions는 JSON 응답을 직접 소비합니다. 웹 검색/웹 읽기로 REST
재고 0, 미확인 수량, 원본 차단, 자체 한도, 인증 오류를 구분합니다. 실패를 정상 품절이나 결과 없음으로 바꾸지 않습니다. 실제 호출 결과에 없는 수량·영업시간·가격·좌표·상품 코드를 만들지 않습니다. 실패 시 한 번만 조건을 좁혀 재시도하고 계속 실패하면 원인과 확인하지 못한 범위를 알립니다. 캐시 응답은 실시간 원본을 검증한 것처럼 설명하지 않습니다.
-결과는 사용자에게 필요한 상품명·가격·매장명·주소·재고·상영 시각·남은 좌석 중심으로 정리합니다. 이미지는 해당 조회 응답의 imageUrl만 사용하고 전체 URL을 유지합니다. 없거나 표시되지 않으면 생략하며 웹 검색 이미지·다른 상품·다른 국가 이미지로 대체하지 않습니다. 출처/상품 링크가 있으면 함께 제공합니다. 데이터가 없으면 없음과 미확인을 구분합니다.
+결과는 사용자에게 필요한 상품명·가격·매장명·주소·재고·상영 시각·남은 좌석 중심으로 정리합니다. 이미지는 해당 조회 응답의 imageUrl만 사용하고 전체 URL을 유지합니다. 없거나 표시되지 않으면 생략하며 image_query·이미지 검색·검색 캐러셀을 사용하거나 웹 검색 이미지·다른 상품·다른 국가 이미지로 대체하지 않습니다. 출처/상품 링크가 있으면 함께 제공합니다. 데이터가 없으면 없음과 미확인을 구분합니다.
사용자가 개발자 전달을 명시적으로 요청한 경우에만 submitDeveloperRequest를 사용합니다. 제목과 설명을 확인하고 비밀번호·인증 코드·토큰·쿠키·개인정보를 포함하지 않습니다. 테스트나 일반 조회 과정에서 요청을 임의로 제출하지 않습니다.
diff --git a/docs/service-reference.md b/docs/service-reference.md
index 86625625..bcb7777e 100644
--- a/docs/service-reference.md
+++ b/docs/service-reference.md
@@ -4,22 +4,15 @@ README 하단에 있던 기능, REST API, 개발, 아키텍처 설명을 분리
## 설치 없이 첫 조회
-공개 원격 MCP는 `https://mcp.aka.page`이며 Streamable HTTP 방식이고 인증·API 키가 필요 없습니다.
-에이전트용 짧은 안내는 [빠른 시작](https://mcp.aka.page/llms.txt)에 있습니다. 첫 조회에는 이 상세 레퍼런스나 전체 도구 목록을 먼저 읽을 필요가 없습니다.
+**ChatGPT 및 웹 읽기 에이전트는 터미널을 실행하지 말고 WebFetch 또는 URL 열기(open) 도구로 아래 링크를 직접 여세요.** 설치·API 키·MCP 연결 설정 없이 상품 검색 결과를 읽을 수 있습니다. 검색 도구(search)는 URL 열기를 대신하지 않습니다.
-연결된 MCP 도구가 있으면 `search_products`에 `service=daiso`를 전달합니다. 없으면 셸이 있어도 웹 읽기의 [첫 HTML GET](https://mcp.aka.page/api/daiso/products?q=%EC%88%98%EB%82%A9%EB%B0%95%EC%8A%A4&pageSize=3&format=html)을 먼저 엽니다. 모든 후속 웹 GET에도 `format=html`을 붙입니다. 셸 DNS 실패는 웹 GET 실패가 아니며 실제 실행하지 않은 요청을 실패했다고 보고하지 않습니다.
+[WebFetch로 다이소 수납박스 3개 조회](https://mcp.aka.page/api/daiso/products?q=%EC%88%98%EB%82%A9%EB%B0%95%EC%8A%A4&pageSize=3&format=html&guide=2026-10-21.3)
-위 두 수단이 없고 외부 통신 가능한 셸만 있다면 아래 한 요청으로 실제 MCP 상품 조회를 완료합니다. 루트 POST가 지원하는 서버 전용 단축 경로여서 initialize나 로컬 패키지 설치가 필요 없습니다.
+모든 후속 웹 GET에도 `format=html&guide=2026-10-21.3`을 유지하세요. 상품 검색 결과의 실제 ID로 재고를 조회하고 검색 성공만으로 매장 재고를 단정하지 않습니다. 이미지는 응답 imageUrl과 카드의 원본 Markdown만 사용하고 이미지 검색으로 대체하지 않습니다.
-```bash
-curl -sS -N --max-time 20 'https://mcp.aka.page/' \
- -H 'Content-Type: application/json' \
- -H 'Accept: application/json, text/event-stream' \
- --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_products","arguments":{"service":"daiso","query":"수납박스","pageSize":3}}}'
-```
+현재 안내는 [버전 안내](https://mcp.aka.page/guide/2026-10-21.3), 다음 버전도 따라가려면 [항상 최신 안내](https://mcp.aka.page/guide/latest)를 여세요. 이 상세 레퍼런스를 끝까지 읽기 전에 첫 조회를 실행하세요.
-SSE `data:`의 JSON에 `error`가 없고 `result.isError`가 true가 아닌지 확인한 뒤 `result.structuredContent.products`에서 실제 상품을 읽습니다. 검색에 성공하면 결과부터 보여주고 추가 진단은 생략합니다.
-범용 MCP 클라이언트는 표준 initialize 흐름을 사용하며 `/mcp`는 초기화가 필요합니다. 웹 읽기가 가능하면 위 HTML GET을 우선 사용하세요.
+이미 연결된 MCP 도구가 있는 환경만 `search_products`에 `service=daiso`, `query=수납박스`를 전달합니다. 서버는 https://mcp.aka.page 이며 Streamable HTTP, 인증 없음입니다. 실제로 실행한 도구·URL·오류만 보고하고 실행하지 않은 요청의 성공·실패를 만들지 않습니다.
### 구형 도구 레퍼런스의 범위
diff --git a/docs/superpowers/plans/2026-10-21-latest-guide.md b/docs/superpowers/plans/2026-10-21-latest-guide.md
new file mode 100644
index 00000000..95e1b46d
--- /dev/null
+++ b/docs/superpowers/plans/2026-10-21-latest-guide.md
@@ -0,0 +1,11 @@
+# 최신 안내 발견 경로와 원본 이미지 표시
+
+사용자 승인 범위: 최신 버전 안내의 자연스러운 발견과 원본 상품 이미지만 사용하도록 개선한다.
+
+- /guide/latest는 현재 버전의 /guide/버전으로 임시 리다이렉트하며 캐시하지 않는다. 이전 버전 경로도 현재 버전으로 연결한다. 기존 llms/prompt/JSON/MCP 호환은 유지한다.
+- README·첫화면·메타·robots·sitemap·공통프롬프트에서 현재 버전 안내를 연결한다. 첫 HTML 조회와 후속 상세 링크에 guide 버전을 전달하고 오래된 안내/결과를 최신으로 단정하지 않는다.
+- 상품 카드에 동일 응답 imageUrl로 만든 복사 가능한 Markdown과 원본 링크를 함께 제공한다. 이미지 검색/image_query/검색 캐러셀로 대체하지 않으며, 원본 표시 불가시 링크나 텍스트만 제공한다.
+- 안내/HTML은 새 캐시 저장을 막고 JSON과 원본 API 캐시는 유지한다. 외부 검색 캐시의 강제 삭제나 에이전트 판단을 보장하지 않는다.
+- 회귀 red/green, 전체 check/coverage100/build/발견자산, 독립리뷰, GitHub검사·병합배포 후 실제 최신 안내·상품·후속 링크와 MCP10개를 검증한다.
+
+추가 사용자 요청: 에이전트가 찾는 service-reference와 README/시작 안내/스킬의 터미널 호출 예제를 제거하고 WebFetch·URL 열기만 안내한다. 셸 우회 예제를 다시 노출하지 않는 회귀 검사를 유지한다. 서버의 MCP 전송 계약은 유지한다.
diff --git a/docs/web-discovery.md b/docs/web-discovery.md
index ead60dd0..0d00ab4f 100644
--- a/docs/web-discovery.md
+++ b/docs/web-discovery.md
@@ -1,6 +1,6 @@
# 웹에서 다이소 MCP 발견하기
-[공개 첫 화면](https://mcp.aka.page/)은 설치 없는 사용 방법과 첫 실제 조회 링크를 HTML로 제공합니다. 웹 읽기 기능만으로 MCP 도구가 자동 등록되는 것은 아닙니다. 연결된 MCP 도구를 먼저 사용하고, 없으면 셸 유무와 무관하게 웹 읽기의 HTML GET을 바로 실행합니다. 두 수단이 없을 때만 외부 통신 가능한 셸의 POST를 사용합니다.
+[공개 첫 화면](https://mcp.aka.page/)은 설치 없는 사용 방법과 첫 실제 조회 링크를 HTML로 제공합니다. 웹 읽기 기능만으로 MCP 도구가 자동 등록되는 것은 아닙니다. 연결된 MCP 도구를 먼저 사용하고, 없으면 셸 유무와 무관하게 웹 읽기의 HTML GET을 바로 실행합니다. 두 수단이 없으면 실제 조회 도구 제약을 알리며 셸 호출로 우회하지 않습니다. WebFetch 또는 open으로 HTML 링크를 직접 엽니다.
- `/`: HTML 안내. `Accept: application/json`이면 기존 서버 정보 JSON.
- `/root.json`: 현재 서비스·도구 목록 JSON. API 클라이언트는 이 명시적 주소를 권장합니다.
@@ -53,6 +53,13 @@ HTML은 원래 응답의 성공·오류와 HTTP 상태를 보존합니다. 상
## 안내 버전과 상품 이미지 카드
-현재 안내 버전은 `2026-10-21.2`, 갱신일은 `2026-10-21`입니다. README의 AI 안내, 첫 화면, llms.txt, prompt와 HTML 조회 결과에 표시합니다. 버전이 없거나 다르면 예전 검색 사본일 수 있으므로 실제 읽은 URL과 문구를 확인하고 최신 버전을 읽었다고 추정하지 않습니다. 검색 엔진의 재수집·캐시 반영 시각은 이 배포로 보장하지 않습니다.
+현재 안내 버전은 `2026-10-21.3`, 갱신일은 `2026-10-21`입니다. README의 AI 안내, 첫 화면, llms.txt, prompt와 HTML 조회 결과에 표시합니다. 버전이 없거나 다르면 예전 검색 사본일 수 있으므로 실제 읽은 URL과 문구를 확인하고 최신 버전을 읽었다고 추정하지 않습니다. 검색 엔진의 재수집·캐시 반영 시각은 이 배포로 보장하지 않습니다.
상품 HTML은 이름·ID·원본 필드와 응답 imageUrl의 이미지를 같은 카드에 표시합니다. 이미지 링크는 원본 URL의 쿼리까지 유지하며 HTTPS이고 인증정보가 없는 주소만 사용합니다. imageUrl이 없거나 안전한 이미지 주소가 아니면 이미지 없음으로 표시합니다. 검색 이미지로 채우지 않습니다. JSON API 필드와 오류 상태는 유지합니다.
+
+
+## 최신 안내의 연결 계약
+
+`/guide/latest` 및 이전 `/guide/버전`은 307과 Cache-Control: no-store로 현재 `/guide/2026-10-21.3`에 연결합니다. 새 버전 배포 시 공통 상수와 README·스킬 안내를 함께 갱신합니다. 첫 화면·robots·sitemap도 같은 상수의 현재 경로를 안내합니다. 외부 캐시가 과거 응답이나 리다이렉트를 재사용하는 것까지 강제할 수는 없습니다.
+
+첫 HTML 조회와 상품 상세 링크는 format=html 및 guide 버전을 포함합니다. 프롬프트의 REST 예제도 같은 버전을 사용합니다. 안내와 HTML 결과는 no-store를 보내며 기존 JSON/API 원본 캐시 정책은 유지합니다. 이미지 카드에는 원본 imageUrl로 생성한 Markdown을 제공하고 이미지 검색/image_query/캐러셀 대체를 금지합니다. 표시가 불가능하면 원본 링크와 텍스트만 제공합니다.
diff --git a/skills/daiso-cli/SKILL.md b/skills/daiso-cli/SKILL.md
index effa646e..60b31437 100644
--- a/skills/daiso-cli/SKILL.md
+++ b/skills/daiso-cli/SKILL.md
@@ -1,7 +1,7 @@
---
name: daiso-cli
description: Use this when a user wants to search Daiso/다이소, compare product price candidates, nearby restaurants/cafes/음식점/카페, convenience stores/편의점, marts, Olive Young/올리브영, Megabox/메가박스, Lotte Cinema/롯데시네마, or CGV data through the Daiso project. Honor explicit no-install requests with connected MCP tools first, then HTML GET via web reading even when a shell is available; otherwise prefer the daiso CLI for direct execution, use the MCP endpoint when the host app supports remote MCP, and choose commands for products, stores, inventory/재고, compare, places, movies, showtimes, seats, health checks, and raw JSON output.
-version: 1.0.7
+version: 1.0.8
metadata:
openclaw:
requires:
@@ -21,27 +21,20 @@ Use this skill to operate the Daiso MCP project through `npx daiso` and the publ
## 설치 없이 첫 조회
+최신 지침은 https://mcp.aka.page/guide/latest 를 열어 현재 버전 주소로 이동합니다. 오래된 버전 경로도 최신 지침으로 연결됩니다. 첫 조회에는 지침의 guide 버전을 유지하세요.
+
1. 연결된 MCP 도구가 있으면 `search_products`에 `{"service":"daiso","query":"수납박스","pageSize":3}`를 전달합니다.
2. 웹 읽기(open/WebFetch)가 가능하면 아래 HTML GET을 바로 엽니다. 셸이 있어도 연결된 MCP 도구가 없으면 이 경로가 우선입니다. 검색(search)은 URL 열기(open)를 대신하지 않습니다.
-3. 위 두 수단이 없을 때만 외부 통신 가능한 셸에서 루트 POST를 사용합니다. 셸 DNS 실패를 웹 GET 실패나 서버 장애로 확대하지 말고 웹 읽기가 가능하면 HTML GET으로 전환합니다.
+3. 위 두 수단이 없을 때만 사용 가능한 조회 도구가 없음을 알립니다. 셸 호출로 우회하지 않으며, 셸 DNS 오류를 웹 GET 실패로 확대하지 않습니다. 실제로 실행하지 않은 요청의 성공·실패를 만들지 않습니다.
-https://mcp.aka.page/api/daiso/products?q=%EC%88%98%EB%82%A9%EB%B0%95%EC%8A%A4&pageSize=3&format=html
+https://mcp.aka.page/api/daiso/products?q=%EC%88%98%EB%82%A9%EB%B0%95%EC%8A%A4&pageSize=3&format=html&guide=2026-10-21.3
검색어 q를 사용자 요청으로 바꾸고 상세·매장·재고를 포함한 모든 후속 웹 GET에도 `format=html`을 반드시 붙이세요. 첫 조회 전에 npx·패키지·스킬 설치, health/help, 전체 도구 목록이나 OpenAPI 탐색을 요구하지 않습니다. REST GET 성공과 MCP 도구 호출 성공은 구분합니다.
-상품 이미지는 해당 조회 응답의 imageUrl만 사용합니다. 전체 URL과 query string을 유지하고, 없거나 표시되지 않으면 생략하며 웹 검색 이미지·다른 상품·다른 국가 이미지로 대체하지 않습니다. 실제 도구·URL·반환 데이터·오류만 보고하고 실행하지 않은 요청의 성공·실패를 만들지 않습니다.
+상품 이미지는 해당 조회 응답의 imageUrl만 사용합니다. 전체 URL과 query string을 유지하고, 없거나 표시되지 않으면 생략하며 image_query·이미지 검색·검색 캐러셀을 사용하거나 웹 검색 이미지·다른 상품·다른 국가 이미지로 대체하지 않습니다. 실제 도구·URL·반환 데이터·오류만 보고하고 실행하지 않은 요청의 성공·실패를 만들지 않습니다.
공개 MCP는 https://mcp.aka.page, Streamable HTTP, 인증 없음입니다. 연결은 표준 initialize 절차를 사용합니다. 공개 도구 10개는 늘리지 않습니다. 기존 서비스별 이름은 deprecated 별칭이며 새 호출에 쓰지 않습니다.
-셸 전용 대안은 다음과 같습니다. SSE의 error/result.isError를 확인하고 result.structuredContent.products 또는 content[].text에서 실제 결과를 읽으세요.
-
-```bash
-curl -fsS -N --max-time 20 'https://mcp.aka.page/' \
- -H 'Content-Type: application/json' \
- -H 'Accept: application/json, text/event-stream' \
- --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_products","arguments":{"service":"daiso","query":"수납박스","pageSize":3}}}'
-```
-
## Core Rule
무설치 요청이 아니고 CLI 사용이 허용된 환경에서는 CLI를 우선 사용한다. The CLI is the preferred path when you can run shell commands and package execution is allowed. Use the MCP endpoint when the user is configuring an AI app or explicitly asks for MCP connection details.
diff --git a/src/index.ts b/src/index.ts
index 3c2c5be7..9db5a26c 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -39,7 +39,7 @@ import { createPlacesService } from './services/places/index.js';
import { createOpinetService } from './services/opinet/index.js';
import { createCompareService } from './services/compare/index.js';
import { createFeedbackService } from './services/feedback/index.js';
-import { createAgentStartResponse } from './pages/agentStart.js';
+import { createAgentStartResponse, createVersionedGuideResponse } from './pages/agentStart.js';
import { createPromptResponse } from './pages/prompt.js';
import { buildDiscoveryAssets } from './pages/discovery.js';
import {
@@ -200,7 +200,7 @@ function createRootInfoResponse(request: Request): Response {
status: 200,
headers: { ...ROOT_INFO_HEADERS,
'Content-Type': json ? 'application/json; charset=utf-8' : 'text/html; charset=utf-8',
- 'Content-Length': String(body.byteLength), Vary: 'Accept' },
+ 'Content-Length': String(body.byteLength), 'Cache-Control': json ? ROOT_INFO_HEADERS['Cache-Control'] : 'no-store', Vary: 'Accept' },
});
}
/**
@@ -364,13 +364,11 @@ registerRateLimitStatsRoutes(app);
registerServiceRoutes(app);
// 설치 없는 첫 조회 안내
+app.get('/guide/:version', (c) => createVersionedGuideResponse(new URL(c.req.url).origin, c.req.param('version')));
app.get('/llms.txt', (c) => createAgentStartResponse(new URL(c.req.url).origin));
// 프롬프트 페이지 (MCP 미지원 에이전트용)
-app.get('/prompt', (c) => {
- const baseUrl = new URL(c.req.url).origin;
- return createPromptResponse(baseUrl);
-});
+app.get('/prompt', (c) => createPromptResponse(new URL(c.req.url).origin));
// OpenAPI 스펙 엔드포인트 (ChatGPT GPTs 등록용)
app.get('/openapi.json', (c) => {
diff --git a/src/pages/agentStart.ts b/src/pages/agentStart.ts
index bb410931..af98ca6a 100644
--- a/src/pages/agentStart.ts
+++ b/src/pages/agentStart.ts
@@ -1,7 +1,9 @@
/** 검색·읽기 사본의 안내 세대를 구분하는 고정 버전 */
-export const AGENT_GUIDE_VERSION = '2026-10-21.2';
+export const AGENT_GUIDE_VERSION = '2026-10-21.3';
export const AGENT_GUIDE_UPDATED = '2026-10-21';
export const AGENT_GUIDE_STAMP = `안내 버전: ${AGENT_GUIDE_VERSION} · 갱신일: ${AGENT_GUIDE_UPDATED}`;
+export const AGENT_GUIDE_PATH = `/guide/${AGENT_GUIDE_VERSION}`;
+export const HTML_GUIDE_QUERY = `&guide=${AGENT_GUIDE_VERSION}`;
export const WEB_SEARCH_DESCRIPTION = 'ChatGPT 웹 읽기로 설치·API 키·MCP 연결 설정 없이 바로 상품을 조회하세요. URL 열기로 /api/daiso/products?q=검색어&format=html을 사용합니다. 다이소·편의점 재고와 영화·생활 정보도 지원합니다.';
/** 웹 읽기 환경에서 조회 형식을 선택하는 공통 규칙 */
@@ -10,10 +12,10 @@ export const WEB_READ_RULE = '웹 읽기 전용 에이전트: 모든 /api/* GET
/** 셸 존재를 네트워크 접근 가능 여부로 오해하지 않는 실행 순서 */
export const ROUTE_SELECTION_TEXT = `1. 연결된 MCP 도구가 있으면 search_products {"service":"daiso","query":"수납박스","pageSize":3}를 호출합니다.
2. 웹 읽기(open/WebFetch)가 가능하면 HTML GET 주소를 바로 엽니다. 셸이 있어도 연결된 MCP 도구가 없으면 이 경로가 우선입니다. 웹 검색(search)은 URL 열기(open)를 대신하지 않습니다.
-3. 위 두 수단이 없을 때만 외부 통신 가능한 셸에서 아래 POST를 사용합니다. 셸 DNS 오류는 그 실행 환경의 실패이며 웹 GET 실패나 서버 장애의 근거가 아닙니다. 웹 읽기가 가능하면 HTML GET으로 즉시 전환합니다.`;
+3. 위 두 수단이 없을 때만 사용 가능한 조회 도구가 없음을 알립니다. 터미널·셸 호출로 우회하지 않습니다. 셸 DNS 오류를 웹 GET 실패나 서버 장애로 확대하지 말고 실제로 실행하지 않은 요청의 실패를 만들지 마세요.`;
/** 유사 상품의 웹 검색 이미지를 실제 상품 사진으로 오인하지 않도록 제한합니다. */
-export const IMAGE_SOURCE_RULE = '상품 이미지는 해당 조회 응답의 imageUrl만 사용하세요. 전체 URL과 query string을 유지합니다. imageUrl이 없거나 표시되지 않으면 이미지를 생략하고 웹 검색 이미지·다른 상품·다른 국가의 이미지로 대체하지 마세요.';
+export const IMAGE_SOURCE_RULE = '상품 이미지는 해당 조회 응답의 imageUrl만 사용하세요. image_query·이미지 검색·검색 이미지 캐러셀은 사용하지 마세요. 카드의 원본 이미지 Markdown을 그대로 쓰고, 표시할 수 없으면 원본 링크와 텍스트만 제공하세요. 전체 URL과 query string을 유지합니다. imageUrl이 없거나 표시되지 않으면 이미지를 생략하고 웹 검색 이미지·다른 상품·다른 국가의 이미지로 대체하지 마세요.';
/** 실행 기록 없이 성공·실패나 HTTP 상태를 단정하지 않도록 안내합니다. */
export const EXECUTION_EVIDENCE_RULE = '실제로 실행한 도구·요청 URL·반환 데이터와 확인된 오류만 보고하세요. 실행하지 않은 웹 GET을 실패했다고 말하거나 검색 결과·문서 예제를 실제 조회 결과로 제시하지 마세요. 도구가 HTTP 상태를 제공하지 않으면 HTTP 200이라고 추정하지 마세요. REST GET 성공과 MCP 도구 호출 성공은 구분합니다.';
@@ -22,6 +24,7 @@ export const EXECUTION_EVIDENCE_RULE = '실제로 실행한 도구·요청 URL·
export function buildAgentStartText(baseUrl: string): string {
return `# DAISO MCP: 설치 없이 시작하기
${AGENT_GUIDE_STAMP}
+최신 안내: ${baseUrl}${AGENT_GUIDE_PATH} (이전 버전은 /guide/latest에서 갱신). 버전 없는 검색 사본을 최신이라고 추정하지 마세요.
**${WEB_READ_RULE}**
@@ -32,22 +35,15 @@ ${AGENT_GUIDE_STAMP}
${ROUTE_SELECTION_TEXT}
웹 읽기용 첫 조회 (사용자 검색어로 q를 바꾸세요):
-${baseUrl}/api/daiso/products?q=%EC%88%98%EB%82%A9%EB%B0%95%EC%8A%A4&pageSize=3&format=html
-이것은 공개 REST GET이며 MCP 프로토콜 호출이 아닙니다. 상품 결과의 실제 id로 상세·재고를 조회하고 모든 후속 URL에도 format=html을 붙이세요. 상품 검색만으로 매장 재고를 단정하지 마세요.
+${baseUrl}/api/daiso/products?q=%EC%88%98%EB%82%A9%EB%B0%95%EC%8A%A4&pageSize=3&format=html${HTML_GUIDE_QUERY}
+이것은 공개 REST GET이며 MCP 프로토콜 호출이 아닙니다. 상품 결과의 실제 id로 상세·재고를 조회하고 모든 후속 URL에도 format=html과 guide=${AGENT_GUIDE_VERSION}을 유지하세요. 상품 검색만으로 매장 재고를 단정하지 마세요.
${IMAGE_SOURCE_RULE}
${EXECUTION_EVIDENCE_RULE}
-셸 전용 대안: 루트 POST의 stateless 호출은 이 서버가 지원하는 단축 경로입니다. /mcp 및 범용 클라이언트 연결은 initialize → notifications/initialized 후 mcp-session-id를 전달합니다.
-\`\`\`bash
-curl --max-time 20 -sS -N ${baseUrl}/ \\
- -H 'Content-Type: application/json' \\
- -H 'Accept: application/json, text/event-stream' \\
- --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_products","arguments":{"service":"daiso","query":"수납박스","pageSize":3}}}'
-\`\`\`
-응답은 SSE의 data: JSON-RPC 메시지입니다. result.isError=true이거나 error 응답이면 실패입니다. 상품은 result.structuredContent.products 또는 content[].text의 JSON에서 읽으세요. 오류·미확인을 재고 0으로 해석하지 마세요.
+연결된 MCP 클라이언트는 initialize 절차를 처리합니다. MCP 결과의 isError=true/error를 확인하고 structuredContent 또는 content[].text에서 실제 상품을 읽습니다. 웹 읽기는 WebFetch·open 도구에서 위 HTML GET 링크를 그대로 여세요.
기존 서비스별 MCP 이름은 deprecated 호출 별칭입니다. 새 연동은 공개 도구 10개만 사용하며 도구를 늘리지 않습니다.
-상세 API와 서비스 안내: ${baseUrl}/prompt
+상세 API와 서비스 안내: ${baseUrl}/prompt?guide=${AGENT_GUIDE_VERSION}
---
@@ -59,7 +55,13 @@ export function createAgentStartResponse(baseUrl: string): Response {
return new Response(buildAgentStartText(baseUrl), {
headers: {
'Content-Type': 'text/plain; charset=utf-8',
- 'Cache-Control': 'public, max-age=3600',
+ 'Cache-Control': 'no-store',
},
});
}
+
+/** 오래된 버전 주소도 현재 안내로 연결하며 영구 리다이렉트 캐시를 만들지 않습니다. */
+export function createVersionedGuideResponse(baseUrl: string, version: string): Response {
+ if (version === AGENT_GUIDE_VERSION) return createAgentStartResponse(baseUrl);
+ return new Response(null, { status: 307, headers: { Location: AGENT_GUIDE_PATH, 'Cache-Control': 'no-store' } });
+}
diff --git a/src/pages/apiResult.ts b/src/pages/apiResult.ts
index 45754609..0a832605 100644
--- a/src/pages/apiResult.ts
+++ b/src/pages/apiResult.ts
@@ -1,5 +1,5 @@
/** 웹 읽기 에이전트용 공개 GET 결과 표시 */
-import { WEB_READ_RULE, IMAGE_SOURCE_RULE, EXECUTION_EVIDENCE_RULE, AGENT_GUIDE_STAMP } from './agentStart.js';
+import { WEB_READ_RULE, IMAGE_SOURCE_RULE, EXECUTION_EVIDENCE_RULE, AGENT_GUIDE_STAMP, AGENT_GUIDE_PATH, AGENT_GUIDE_VERSION, HTML_GUIDE_QUERY } from './agentStart.js';
import type { MiddlewareHandler } from 'hono';
import type { AppBindings } from '../api/response.js';
@@ -15,7 +15,9 @@ function productImage(value: unknown, name: string): string {
const url = new URL(value);
if (url.protocol === 'https:' && !url.username && !url.password) {
const source = escapeHtml(value);
- return `