겜팩샵 — WebMCP + MCP 데모

닌텐도 스위치 게임팩 쇼핑몰. AI 에이전트가 웹 애플리케이션을 조작하는 두 가지 방식을 한 프로젝트에서 나란히 구현해 비교합니다.

• WebMCP — 페이지가 document.modelContext 와 HTML 속성으로 툴을 노출. 브라우저 내장 에이전트, 같은 트리의 동일 출처 문서, exposedTo 로 허용한 iframe 에이전트가 호출

• MCP — 서버가 /mcp 엔드포인트로 툴을 노출. 외부 클라이언트(Claude Code 등)가 호출

두 경로와 사람의 UI 조작이 같은 서버 상태를 공유하므로, 어느 쪽에서 바꿔도 열려 있는 모든 브라우저가 즉시 따라옵니다.

빌드 단계 없음. 프레임워크 없음. 의존성은 MCP SDK 와 zod 둘.

빠른 시작

npm install
npm start        # http://localhost:4173
npm test         # 로직 + 서버 상태 검증

브라우저에서 바로 쇼핑할 수 있습니다 — 검색, 발매일 범위 필터, 5가지 정렬, 장바구니, 데모 결제.

외부 MCP 클라이언트 연결

claude mcp add --transport http gempack-shop http://localhost:4173/mcp

연결하면 에이전트가 상품을 검색하고 장바구니를 조작할 수 있습니다. 그때마다 열려 있는 브라우저 화면의 해당 영역이 빨간 테두리로 표시되고 토스트가 뜹니다.

페이지 내 WebMCP 활성화

WebMCP 는 아직 Chrome 플래그 뒤에 있습니다.

1. Chrome 149+ 에서 chrome://flags/#enable-webmcp-testing → Enabled → 재시작

2. http://localhost:4173 접속 (localhost 는 SecureContext 로 인정되어 https 불필요)

3. 우측 상단 배지가 WebMCP 연결됨 이면 준비 완료

미지원 브라우저에서도 쇼핑몰과 서버측 MCP 는 정상 동작합니다. 선언형 HTML 속성은 그냥 무시됩니다.

Related MCP server: MCP E-Commerce Agent

아키텍처

        사람이 UI 조작 ─────┐
                            │
  WebMCP 폼 제출 ───────────┼──▶  state.js  ──SSE──▶  열려 있는 모든 브라우저
  (브라우저 내장 에이전트)   │   (서버 단일 상태)
                            │
  MCP tools/call ───────────┘
  (외부 에이전트, /mcp)

state.js 의 apply(action, args, by) 가 유일한 변경 진입점입니다. by 가 출처를 구분합니다.

브라우저는 필터·정렬을 직접 계산하지 않습니다. 서버가 완성된 스냅샷을 SSE 로 밀어주고 화면은 그것을 렌더링만 합니다.

하이라이트

AI 가 건드린 자리를 눈에 보이게 하는 것이 이 데모의 핵심입니다. 두 경로가 서로 다른 수단을 씁니다.

WebMCP 는 브라우저가 상태를 CSS 의사클래스로 노출하므로 스타일만 덮어씁니다.

form:tool-form-active { outline: 3px solid #e60012; }   /* 에이전트가 채운 폼 */
:tool-submit-active   { animation: aiPulse … }          /* 그 폼의 제출 버튼 */

toolautosubmit 을 의도적으로 쓰지 않습니다. 그래서 에이전트가 툴을 호출하면 폼이 채워진 채 하이라이트되고 멈추며, 사람이 제출 버튼을 눌러야 실행됩니다. 그 시점에 SubmitEvent.respondWith() 가 결과를 에이전트에게 돌려줍니다. 결제를 AI 가 단독으로 완료할 수 없는 것이 설계 의도입니다.

MCP 는 의사클래스가 없으므로 서버가 변경 영역 이름(filters, list, cart, order, game-<id>)을 스냅샷에 담아 보내고, 브라우저가 3.4초간 클래스를 붙입니다.

코드를 수정할 때 주의할 점

WebMCP 선언형 API 의 세 가지 제약이 이 코드의 구조를 결정했습니다.

1. 스키마는 폼이 DOM 에 삽입되는 순간 합성됩니다. <select> 를 JS 로 채우므로, HTML 에 toolname 을 두면 빈 select 로 합성되어 enum 이 비어버립니다. 그래서 data-toolname 으로 두고 옵션과 리스너를 모두 붙인 뒤 마지막에 toolname 을 답니다.

2. respondWith() 는 이벤트 디스패치 중 동기적으로 호출해야 합니다. await 뒤로 밀리면 invocation 이 실패합니다. 인자로 프로미스를 받으므로 핸들러는 동기로 두고 프로미스를 넘깁니다.

3. form.reset() 은 실행 중인 invocation 을 취소합니다. 성공 메시지를 넘긴 뒤 폼을 정리하려 reset() 을 부르면 에이전트는 결과 대신 취소를 받습니다. 그래서 어느 핸들러도 reset() 을 부르지 않습니다.

추가로 <option disabled> 은 쓰지 않습니다. HTML 스펙상 "선택됐지만 disabled 인 option" 은 FormData 에서 제외되므로, 품절 상품을 그렇게 막으면 파라미터가 undefined 로 도착합니다. 품절은 제출을 받고 애플리케이션 로직이 이유를 돌려주는 방식으로 처리합니다.

툴

서버측 MCP (/mcp)

입력은 zod 로 검증합니다. gameId 는 18개 id 의 enum 이고, 잘못된 값은 JSON-RPC -32602 로 막힙니다. 재고 초과나 빈 장바구니 같은 비즈니스 오류는 isError: true 로 돌려주므로 에이전트가 이유를 읽고 재시도할 수 있습니다.

페이지 내 WebMCP

선언형 툴의 JSON Schema 는 브라우저가 HTML 에서 합성합니다. toolparamdescription 이 설명이 되고, type="date" 는 format: "date" 로, <select> 옵션은 enum 으로, min/max/step 은 minimum/maximum/multipleOf 로, required 는 required 배열로 변환됩니다.

프로젝트 구조

shop.js       게임팩 18종 + 순수 로직 (필터·정렬·장바구니·결제 계산)
state.js      서버 단일 상태 + 액션 + 구독. 모든 변경이 여기를 지난다
mcp.js        MCP SDK 툴 정의, Streamable HTTP 트랜스포트
server.js     정적 파일 + /events(SSE) + /action + /mcp
index.html    UI 전체 + WebMCP 툴 등록 (Bootstrap 5 · Bootstrap Icons, CDN)
covers/       게임팩 패키지 이미지 18장
test.js       node test.js

shop.js 는 순수 함수라 서버와 테스트가 함께 씁니다. 브라우저는 렌더링에 필요한 만큼만 가져다 씁니다.

보안

MCP Streamable HTTP 스펙의 요구사항을 구현했습니다.

• Origin 헤더 검증 — DNS 리바인딩 공격 차단. 허용 목록 외 Origin 은 403

• 루프백 바인딩 — 127.0.0.1 만 LISTEN. 모든 인터페이스에 노출하지 않음 (HOST 환경변수로 변경 가능)

• 입력 검증 — zod 스키마

• 레이트 리밋 — 툴 호출 60회 / 10초

정적 파일 서빙은 경로 탈출을 차단하고, 요청 본문은 1MB 로 제한합니다. 결제는 데모이므로 카드번호 입력 필드를 아예 만들지 않았습니다.

테스트

npm test

필터·정렬 경계, 재고 초과 거절 시 장바구니 불변성, 결제 검증, by 별 하이라이트 규칙, 커버 이미지 존재 여부를 확인합니다.

에이전트 없이 WebMCP 툴을 직접 실행해보려면 DevTools → Application → WebMCP 패널을 쓰면 됩니다. 툴 목록과 합성된 스키마를 보고, 파라미터를 입력해 Run tool 로 실행하고, 호출 로그를 확인할 수 있습니다.

제약

이 프로젝트는 프로토콜 비교를 위한 데모입니다.

• 결제는 가짜입니다. PG 연동 없음, 실제 청구 없음, 가짜 주문번호만 발급

• 재고가 차감되지 않습니다. GAMES 는 상수이고 결제가 재고를 건드리지 않습니다

• 상태는 프로세스 메모리에 전역 1개. 서버를 재시작하면 초기화되고, 사용자 구분이 없어 모든 탭이 같은 장바구니를 봅니다

• WebMCP 는 W3C Community Group Draft 이며 Chrome 플래그 뒤에 있습니다. API 가 바뀔 수 있습니다 (navigator.modelContext 는 Chrome 150 에서 deprecated → 이 프로젝트는 document.modelContext 사용)

왜 MCP 엔드포인트를 함께 두는가

WebMCP 툴의 기본 노출 대상은 스펙상 문서 자신, 같은 트리의 동일 출처 문서, 브라우저 내장 에이전트 세 가지입니다. exposedTo 로 작성자가 지정한 교차 출처 iframe 에도 열 수 있고, 페이지나 iframe 에 직접 박은 author-provided agent 도 툴을 발견하고 실행할 수 있습니다.

스펙이 정의하지 않는 것은 브라우저 밖 프로세스를 위한 전송 계층입니다. 불가능하다는 뜻은 아닙니다 — 확장 프로그램(페이지 툴을 로컬 MCP 서버로 중계)이나 CDP 기반 브리지로 외부 MCP 클라이언트를 연결하는 방식이 이미 널리 쓰입니다. 표준화되지 않았을 뿐입니다.

이 프로젝트가 서버측 /mcp 를 함께 두는 이유는 그 방식과의 트레이드오프 때문입니다.

두 방식은 배타적이지 않습니다. Chrome 문서의 권고도 "가장 효과적인 에이전트 애플리케이션은 MCP 와 WebMCP 를 모두 쓴다" 입니다.

이미지 출처

covers/ 의 패키지 이미지는 영문 위키백과 각 게임 문서의 박스아트입니다 (MediaWiki pageimages API, pilicense=any).

저작권은 닌텐도 및 각 퍼블리셔에 있습니다. 위키백과에서 비자유 저작물로 공정 이용되는 자료이며, 그 공정 이용 근거는 위키백과의 맥락에 한정됩니다. 이 저장소는 학습·시연 목적이며 상업적 이용이나 재배포를 의도하지 않습니다. 게임 제목과 상표 역시 각 권리자의 것입니다.