hmmhmmhm · Oct 21, 2026 · Oct 21, 2026 · Oct 21, 2026
@@ -2,7 +2,15 @@
 <summary>AI 에이전트 사용 안내</summary>
 
 > [!IMPORTANT]
-> **AI 에이전트의 무설치 MCP 사용:** 공개 원격 서버 `https://mcp.aka.page`에 Streamable HTTP로 연결하면 **로컬 설치·빌드·API 키 준비 없이 바로 사용할 수 있습니다.** 무설치 요청에는 npm 설치나 전체 스키마 탐색을 하지 말고, [짧은 시작 안내](https://mcp.aka.page/llms.txt)를 읽은 뒤 필요한 도구를 호출하세요.
+> **로컬 설치·빌드·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으로 전환하세요.
+>
+> **실행 근거:** 실제 데이터·도구·오류만 보고하고 실행하지 않은 요청의 성공·실패를 만들지 마세요. REST GET 성공은 MCP 연결 성공과 구분합니다.
+>
+> **상품 이미지:** 해당 응답의 `imageUrl`만 사용하세요. 없거나 표시되지 않으면 생략하고 웹 검색 이미지·다른 상품·다른 국가의 이미지로 대체하지 마세요.
 >
 > **MCP 도구는 10개 고정:** `service`와 `operation`으로 지원 서비스를 선택합니다. 새 연동은 [통합 도구 10개](docs/mcp-tools.md)만 사용하세요. 기존 서비스별 도구는 deprecated 호출 별칭으로 유지하지만 목록에는 표시하지 않습니다.
 >

@@ -96,7 +96,7 @@ claude mcp add daiso-mcp https://mcp.aka.page --transport http
 ```
 
 새 대화에서 `다이소 MCP로 수납박스 검색해줘`를 요청하세요.
-에이전트가 `daiso_search_products`에 `{"query":"수납박스"}`를 전달하고 상품 목록과 가격을 반환하면 연결이 완료된 것입니다.
+에이전트가 `search_products`에 `{"service":"daiso","query":"수납박스"}`를 전달하고 상품 목록과 가격을 반환하면 연결이 완료된 것입니다.
 
 <br>
 
@@ -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 또는 HTTP POST를 우선 사용합니다. `npx`나 Skill 설치, 전체 스키마 탐색은 필요하지 않습니다.
+- 사용자가 무설치 조회를 요청하면 연결된 MCP 도구를 사용하고, 없으면 웹 읽기의 HTML GET을 우선 사용합니다. 셸이 있어도 이 순서를 유지하며, 두 수단이 없을 때만 외부 통신 가능한 셸의 POST를 사용합니다. `npx`나 Skill 설치, 전체 스키마 탐색은 필요하지 않습니다.
 - CLI를 사용하기로 선택했고 쉘 실행이 가능한 환경에서만 `npx daiso`를 사용합니다. AI 앱 연결에는 MCP 서버 URL `https://mcp.aka.page`를 사용합니다.
 - 구조화 결과가 필요하면 스킬은 `npx daiso ... --json` 형태를 선택합니다.
 - 상황별 레시피는 `콜라 어디가 싸?`, `강남역 근처 카페`, `다이소 핫식스 재고`, `오늘 강남 CGV 시간표`처럼 실제 사용자 문장 기준으로 정리되어 있습니다.

@@ -29,7 +29,7 @@ Actions는 JSON 응답을 직접 소비합니다. 웹 검색/웹 읽기로 REST
 
 재고 0, 미확인 수량, 원본 차단, 자체 한도, 인증 오류를 구분합니다. 실패를 정상 품절이나 결과 없음으로 바꾸지 않습니다. 실제 호출 결과에 없는 수량·영업시간·가격·좌표·상품 코드를 만들지 않습니다. 실패 시 한 번만 조건을 좁혀 재시도하고 계속 실패하면 원인과 확인하지 못한 범위를 알립니다. 캐시 응답은 실시간 원본을 검증한 것처럼 설명하지 않습니다.
 
-결과는 사용자에게 필요한 상품명·가격·매장명·주소·재고·상영 시각·남은 좌석 중심으로 정리합니다. 이미지 URL과 출처/상품 링크가 있으면 함께 제공합니다. 데이터가 없으면 없음과 미확인을 구분합니다.
+결과는 사용자에게 필요한 상품명·가격·매장명·주소·재고·상영 시각·남은 좌석 중심으로 정리합니다. 이미지는 해당 조회 응답의 imageUrl만 사용하고 전체 URL을 유지합니다. 없거나 표시되지 않으면 생략하며 웹 검색 이미지·다른 상품·다른 국가 이미지로 대체하지 않습니다. 출처/상품 링크가 있으면 함께 제공합니다. 데이터가 없으면 없음과 미확인을 구분합니다.
 
 사용자가 개발자 전달을 명시적으로 요청한 경우에만 submitDeveloperRequest를 사용합니다. 제목과 설명을 확인하고 비밀번호·인증 코드·토큰·쿠키·개인정보를 포함하지 않습니다. 테스트나 일반 조회 과정에서 요청을 임의로 제출하지 않습니다.
 

@@ -7,17 +7,23 @@ README 하단에 있던 기능, REST API, 개발, 아키텍처 설명을 분리
 공개 원격 MCP는 `https://mcp.aka.page`이며 Streamable HTTP 방식이고 인증·API 키가 필요 없습니다.
 에이전트용 짧은 안내는 [빠른 시작](https://mcp.aka.page/llms.txt)에 있습니다. 첫 조회에는 이 상세 레퍼런스나 전체 도구 목록을 먼저 읽을 필요가 없습니다.
 
-HTTP POST를 실행할 수 있다면 아래 한 요청으로 실제 MCP 상품 조회를 완료합니다. 루트 POST가 지원하는 서버 전용 단축 경로여서 initialize나 로컬 패키지 설치가 필요 없습니다.
+연결된 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 실패가 아니며 실제 실행하지 않은 요청을 실패했다고 보고하지 않습니다.
+
+위 두 수단이 없고 외부 통신 가능한 셸만 있다면 아래 한 요청으로 실제 MCP 상품 조회를 완료합니다. 루트 POST가 지원하는 서버 전용 단축 경로여서 initialize나 로컬 패키지 설치가 필요 없습니다.
 
 ```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":"daiso_search_products","arguments":{"query":"수납박스","pageSize":3}}}'
+  --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_products","arguments":{"service":"daiso","query":"수납박스","pageSize":3}}}'
 ```
 
 SSE `data:`의 JSON에 `error`가 없고 `result.isError`가 true가 아닌지 확인한 뒤 `result.structuredContent.products`에서 실제 상품을 읽습니다. 검색에 성공하면 결과부터 보여주고 추가 진단은 생략합니다.
-범용 MCP 클라이언트는 표준 initialize 흐름을 사용하며 `/mcp`는 초기화가 필요합니다. GET만 가능한 환경의 REST 대안은 위 빠른 시작 안내를 확인하세요.
+범용 MCP 클라이언트는 표준 initialize 흐름을 사용하며 `/mcp`는 초기화가 필요합니다. 웹 읽기가 가능하면 위 HTML GET을 우선 사용하세요.
+
+### 구형 도구 레퍼런스의 범위
+
+아래 서비스별 MCP 이름은 하위호환용 **deprecated 별칭** 레퍼런스입니다. 새 연동의 호출 예제로 사용하지 마세요. 현재 공개 MCP 도구는 정확히 10개이며 [통합 도구와 구형 매핑](mcp-tools.md)을 사용합니다. REST와 CLI 계약은 유지합니다.
 
 ### MCP 표준 응답 모델
 

@@ -0,0 +1,10 @@
+# 무설치 경로 안내 구현 계획
+
+**Goal:** 웹 도구가 있는 Chat 에이전트가 셸 DNS 실패에 멈추지 않고 HTML GET으로 첫 조회를 완료하도록 안내를 일치시킨다.
+**Architecture:** 기존 agentStart 공통 문구를 첫 화면과 prompt에서 재사용한다. README와 문서는 동일한 순서를 명시한다. 서버 조회 계약은 유지한다.
+**Tech Stack:** TypeScript, Markdown, Vitest, Cloudflare Workers.
+
+- [x] agentStart/discovery/prompt/README/AI 문서의 경로 우선순위와 이미지 출처·실행 근거 검사를 추가하고 기존 문구에서 실패함을 확인한다.
+- [x] 공통 시작 안내, 첫 화면, 문서의 구형 예제 및 이미지 출처 지침을 수정한다. 상세 구형 레퍼런스는 deprecated임을 명시한다.
+- [ ] check, coverage 100%, build, 정적 발견 자산 생성, 독립 리뷰와 GitHub 검사를 수행한다.
+- [ ] PR 병합·배포 후 첫 화면/llms/prompt/HTML 실제 검색·후속 조회·MCP 10개 유지를 확인하고 운영 기록을 남긴다.
@@ -0,0 +1,7 @@
+# 무설치 에이전트 경로 선택 개선
+
+사용자가 승인한 개선은 연결된 MCP 도구, 웹 읽기의 HTML GET, 두 수단이 없는 환경의 셸 순서로 첫 조회를 선택하는 것이다. 셸 DNS 실패를 웹 GET 실패로 확대하지 않고 실행하지 않은 요청의 성공·실패를 보고하지 않는다.
+
+README 접힘 안내, 첫 화면, llms.txt, prompt, AI 지침과 클라이언트 안내를 맞춘다. 새 MCP 호출 예제는 공개 10개 도구를 사용하고 기존 별칭은 하위호환 레퍼런스로 구분한다. 상품 이미지는 해당 응답의 imageUrl만 쓰며 없거나 읽을 수 없으면 다른 상품·국가·웹 검색 이미지로 대체하지 않는다.
+
+런타임 도구·REST JSON·하위호환은 변경하지 않는다. 실제 에이전트 판단을 문서만으로 강제할 수는 없으므로
CD1D
 안내 회귀 검사와 배포 응답 확인 후 별도 새 Chat 재현으로 평가한다.
@@ -1,6 +1,6 @@
 # 웹에서 다이소 MCP 발견하기
 
-[공개 첫 화면](https://mcp.aka.page/)은 설치 없는 사용 방법과 첫 실제 조회 링크를 HTML로 제공합니다. 웹 읽기 기능만으로 MCP 도구가 자동 등록되는 것은 아닙니다. 원격 MCP 클라이언트, HTTP POST 또는 공개 REST GET 중 에이전트가 실행할 수 있는 방식을 선택합니다.
+[공개 첫 화면](https://mcp.aka.page/)은 설치 없는 사용 방법과 첫 실제 조회 링크를 HTML로 제공합니다. 웹 읽기 기능만으로 MCP 도구가 자동 등록되는 것은 아닙니다. 연결된 MCP 도구를 먼저 사용하고, 없으면 셸 유무와 무관하게 웹 읽기의 HTML GET을 바로 실행합니다. 두 수단이 없을 때만 외부 통신 가능한 셸의 POST를 사용합니다.
 
 - `/`: HTML 안내. `Accept: application/json`이면 기존 서버 정보 JSON.
 - `/root.json`: 현재 서비스·도구 목록 JSON. API 클라이언트는 이 명시적 주소를 권장합니다.
@@ -46,3 +46,7 @@ HTML은 원래 응답의 성공·오류와 HTTP 상태를 보존합니다. 상
 `llms.txt`와 `robots.txt`는 정적 Assets에서도 `text/plain; charset=utf-8`을 명시합니다. UTF-8 본문을 다른 인코딩으로 추측하는 클라이언트에서 한글이 깨지는 것을 방지합니다.
 
 **웹 읽기 전용 에이전트는 모든 `/api/*` GET 조회 URL에 `format=html`을 반드시 붙이세요.** 검색·상세·매장·재고·후속 조회 모두 적용합니다. `/prompt`의 GET URL 예시도 모두 이 형식으로 제공합니다. JSON 스키마 예시는 필드 설명이고 웹 읽기용 URL 안내가 아닙니다. 일반 JSON API와 MCP 클라이언트의 계약은 유지합니다.
+
+## 실행과 이미지 출처
+
+셸 DNS 실패를 웹 GET 실패로 확대하지 않습니다. 실제 URL을 open/WebFetch로 연 결과와 웹 검색을 구분하고 실행하지 않은 요청의 성공·실패나 확인하지 않은 HTTP 상태를 만들지 않습니다. 상품 사진은 해당 응답의 imageUrl만 사용하며 없거나 표시되지 않으면 웹 검색 이미지·다른 상품·다른 국가 이미지로 대체하지 않고 생략합니다.