webmcp-gen: TypeScript로부터 Chrome WebMCP 도구 정의 생성하기

Chrome 149에는 웹 페이지가 navigator.modelContext를 통해 AI 에이전트에게 구조화된 도구를 노출할 수 있게 해주는 브라우저 네이티브 API인 WebMCP가 탑재되었습니다. 생태계가 빠르게 형성되고 있습니다: webmcp-core는 라이브 사이트를 크롤링하여 도구 정의를 자동 생성하며, @webmcp-registry/kit은 Zod 기반의 defineTool()을 포함한 런타임 SDK를 제공합니다.

현재 부족한 점은 **기존 TypeScript로부터의 빌드 타임 코드 생성 (codegen)**입니다. 이미 API를 위한 타입 인터페이스 (typed interfaces)를 가지고 있다면, 이를 Zod 스키마로 다시 작성하거나 크롤러가 이를 발견할 때까지 기다릴 필요가 없어야 합니다.

webmcp-gen이 그 간극을 메워줍니다. API를 TypeScript 인터페이스로 작성하고 명령어를 한 번 실행하면, 사양을 준수하는 WebMCP 도구 정의와 보안 모범 사례가 내장된 핸들러 스텁 (handler stubs)을 얻을 수 있습니다.

활용 위치

도구	접근 방식	사용 시점
webmcp-core	라이브 URL 크롤링	사이트가 있고, 도구가 자동으로 발견되기를 원할 때
...
이들은 상호 보완적이며, 서로 다른 워크플로우를 위한 서로 다른 계층을 담당합니다.

빠른 예시

// api.ts

/** 키워드로 제품 검색. */
...

npx webmcp-gen --api api.ts

출력 결과: .webmcp.json 정의 + navigator.modelContext.registerTool()이 연결되어 즉시 구현 가능한 .handler.ts 스텁.

주요 기능

• ts-morph를 통한 TypeScript 인터페이스 및 타입 별칭 (type aliases) 파싱
• TS 타입을 JSON Schema (문자열, 숫자, 열거형 (enums), 배열, 중첩된 객체, 선택적 속성 (optionals))로 매핑
• JSDoc 주석에서 설명 (descriptions) 추출
• WebMCP 사양에 따른 출력 검증
• Google의 보안 가이드라인이 내장된 핸들러 스텁 생성:
  • 상태를 변경하는 도구를 위한 requestUserInteraction() 알림
  • 자유 형식의 문자열 입력에 대한 입력값 정화 (Input sanitisation) 경고
  • 조회 전용 도구를 위한 readOnlyHint 어노테이션

기본 보안 설정

WebMCP는 AI 에이전트가 실제 웹 애플리케이션에 영향을 미치는 도구(tools)를 실행할 수 있도록 허용합니다. Google은 인간 참여형(human-in-the-loop) 훅을 사용하고 간접 프롬프트 주입(indirect prompt injection)에 대비할 것을 권고합니다. webmcp-gen은 생성된 모든 핸들러 스텁(handler stub)에 이를 내장하고 있습니다. 즉, 상태를 변경하는 도구에는 requestUserInteraction() 알림이 추가되고, 자유 형식의 입력(freeform inputs)에는 정화(sanitisation) 경고가 포함됩니다. 사후 고려 사항이 아닌, 안전한 기본 설정(Safe defaults)을 제공합니다.

설치 (Install)

npm install -g webmcp-gen

시작을 돕기 위해 4가지 스타터 템플릿(CRUD, 검색, 폼 핸들러, 데이터 변환기)이 포함되어 있습니다:

webmcp-gen --template crud-api
webmcp-gen --api crud-api.ts

MIT 라이선스입니다. 기여(Contributions)를 환영합니다.

v1.2.0 — 보안 강화 릴리스 (security-hardened release)

현재 npm 버전(v1.2.0)은 라인별 디프 스캐닝(line-by-line diff scanning), 파일 간 추적(cross-file tracing), 제거된 동작 분석(removed-behavior analysis) 및 전담 보안 검토를 포함하는 4개 에이전트 보안 감사(security audit)를 거쳤습니다. 생성된 코드의 주입 방어(injection hardening), 경로 탐색(path traversal) 보호, Chrome 150 호환성(오리진 트라이얼 API가 navigator.modelContext에서 document.modelContext로 이동)을 포함하여 10개의 발견 사항이 공개 발표 전에 수정되었습니다. 전체 변경 로그는 README에서 확인할 수 있습니다.

GitHub: oliuntangled/webmcp-gen
npm: webmcp-gen

Google 또는 W3C와 제휴하거나 승인받지 않았습니다. AI의 도움을 받아 제작되었습니다.