OpenTiny NEXT-SDKs: 내장 WebMCP & Polyfill + WebSkills + WebAgent
<p align="center">
<a href="https://opentiny.design" target="_blank" rel="noopener noreferrer">
<img alt="OpenTiny Logo" src="https://raw.githubusercontent.com/opentiny/webmcp-sdk/HEAD/logo.svg" height="100" style="max-width:100%;">
</a>
</p>
English | 简体中文
Ask DeepWiki
<p align="center">
<strong>프론트엔드 지능형 애플리케이션 개발 및 브라우저 자동화 툴킷입니다. WebMCP + WebSkills을 통해 기존 앱을 지능적으로 변환하며, webmcp-cli를 제공하여 리팩토링 없이 모든 웹페이지를 인식하고 제어할 수 있게 함으로써 즉시 AI Native 기능을 부여합니다.</strong>
</p>
<p align="center">
<a href="https://docs.opentiny.design/next-sdk/">📖 Docs</a> |
<a href="#-quick-start">🚀 Quick Start</a> |
<a href="#-webmcp--polyfill">🌐 WebMCP & Polyfill</a> |
<a href="#-scenarios">💡 Scenarios</a>
</p>
차세대 AI 프로토콜: OpenTiny NEXT-SDKs는 **WebMCP (Model Context Protocol for Web)**를 기반으로 구축되었습니다. 이는 네이티브 document.modelContext API(현재 Chrome과 같은 브라우저에서 실험 단계)와 완벽하게 호환되어, 웹 앱을 표준화된 프로토콜을 통해 AI가 제어할 수 있도록 합니다.
[!TIP]
✨ 명령어 라인 자동화 및 AI 스킬:
이제 webmcp-cli (브라우저 제어 및 Polyfill 자동 주입 CLI)와 webmcp-skill (AI 에이전트를 위한 Excalidraw 드로잉과 같은 표준 지침 및 하위 스킬)을 제공합니다. 이 둘은 AI 에이전트가 복잡하고 세밀한 작업을 수행하고 모든 웹페이지를 즉시 "원격 구동(remote-drive)"할 수 있도록 합니다.
OpenTiny NEXT-SDKs는 프론트엔드 지능형 애플리케이션 개발 및 브라우저 자동화 툴킷입니다. 이 툴킷은 "WebMCP + WebSkills" 모델이 몇 줄의 코드로 페이지 작업을 표준화된 도구로 노출하도록 지원할 뿐만 아니라, webmcp-cli (브라우저 인식 및 제어)와 webmcp-skill (에이전트 스킬 라이브러리) 기능을 갖추고 있습니다. 당사의 Polyfill과 결합하면, 오늘날의 브라우저에서도 미래 지향적인 AI 네이티브(AI-Native) 앱을 구축할 수 있을 뿐만 아니라, 소스 코드 수정 없이도 AI 에이전트가 모든 웹페이지를 자동으로 인식하고 제어하도록 할 수 있습니다.
📑 목차
✨ 주요 기능
- 🔌 표준 WebMCP 구현: MCP 프로토콜의 브라우저 버전을 완벽하게 구현하여, 통합 표준을 통해 프론트엔드를 "AI 호출 가능(AI-Callable)"하게 만듭니다.
- 📡 원격 AI 제어: WebAgent 서비스에 원활하게 연결되어, AI가 프론트엔드 도구를 쉽고 안정적으로 원격 호출할 수 있도록 합니다.
- 🛠️ 내장 Polyfill 지원: 현재 브라우저를 위한
document.modelContext / document.modelContext 패치를 제공하여, 오늘날의 코드가 원활하게 작동하고 미래에 네이티브 지원으로 전환되도록 보장합니다.
- 🎯 제로 리팩토링 지능: 앱의 핵심 아키텍처를 변경하지 않고도 비즈니스 로직 및 UI 작업을 도구로 노출할 수 있습니다.
- 🧩 WebSkills 추상화: 점진적 공개(progressive disclosure)를 위해 도구를 "비즈니스 스킬"로 구성합니다.
- 🤖 AI 채팅 컴포넌트: 즉각적인 AI 원격 컨트롤러인
@opentiny/next-remoter를 제공합니다.
🌐 WebMCP 및 Polyfill
WebMCP란 무엇인가요?
WebMCP는 웹 브라우저 전용으로 모델 컨텍스트 프로토콜(Model Context Protocol)을 확장한 것입니다. 이는 웹 페이지가 AI 에이전트에게 "도구(Tools)"와 "리소스(Resources)"를 제공하는 방법을 정의합니다. 가까운 미래에, 브라우저는 이러한 기능을 관리하기 위해 네이티브 document.modelContext 객체를 제공할 것입니다.
왜 폴리필(Polyfill)을 사용해야 하는가?
네이티브 API는 아직 실험 단계이기 때문에, OpenTiny NEXT-SDKs는 강력한 폴리필을 제공합니다. initializeBuiltinWebMCP()를 호출함으로써 SDK는 다음 작업을 수행합니다:
document.modelContext 주입: 도구 등록을 위한 표준 준수 API를 제공합니다. 기본적으로 크로미움(Chromium)의 실험적인 네이티브 구현보다 JS 폴리필(forcePolyfill: true)을 강제 적용하며, 이는 getTools() 실행 시 렌더러 충돌을 일으킬 수 있습니다. 네이티브 WebMCP가 안정적임이 확인된 경우에만 { forcePolyfill: false }를 전달하십시오.- 자동 라우팅 및 브리징(Bridging): 서로 다른 페이지 경로와 iframe 전반에 걸쳐 메시지 동기화 및 도구 호출을 자동으로 처리합니다.
도구를 등록하거나 Agent에게 document.modelContext를 넘겨주기 전에, 페이지 진입 시점(또는 registerPageAgentTool()을 통해)에 이를 호출해야 합니다.
📡 크로스 페이지 및 원격 제어
OpenTiny NEXT-SDKs의 핵심 기능 중 하나는 페이지의 "크로스 환경 제어 가능성(cross-environment controllability)"을 지원한다는 것입니다. 내장 WebMCP 폴리필과 @opentiny/next-remoter를 활용하여 다음을 달성할 수 있습니다:
- 자동 브리징(Automated Bridging): 기반 계층이 서로 다른 페이지 경로와 iframe 전반에 걸쳐 메시지 동기화 및 도구 호출을 자동으로 처리합니다.
- 영속적인 세션 ID(Persistent Session ID): 클라우드 AI 오케스트레이터와 장기 연결을 설정할 수 있습니다.
- 시간 간 크로스 협업(Cross-time Collaboration): 사용자가 활발하게 상호 작용하지 않더라도, 비즈니스 시스템이 전송한 지침에 따라 AI가 원격으로 페이지 도구를 트리거할 수 있습니다.
- 고수준 비즈니스 자동화(High-level Business Automation): 프론트엔드 DOM 작업과 비즈니스 컴포넌트 API를 자동화된 흐름 내의 실행 단위로 변환하여, 앱 수준의 "원격 구동(remote driving)"을 달성합니다.
연결 예시
WebMcpClient를 통해 클라우드 기반 웹 에이전트를 거쳐 브라우저의 내장 WebMCP 도구를 원격으로 호출하고 제어할 수 있습니다:
import { WebMcpClient } from '@opentiny/next-sdk'
const client = new WebMcpClient()
...
[!TIP]
위의 URL은 OpenTiny가 테스트 목적으로 제공하는 공개 테스트 서버입니다. 프로덕션 환경에서는 자체 WebAgent 인스턴스를 배포해야 합니다.
소스 코드: https://github.com/opentiny/web-agent
🚀 빠른 시작 (Quick Start)
몇 줄의 코드로 프론트엔드 애플리케이션을 AI 기능을 갖춘 애플리케이션으로 전환할 수 있습니다.
단계 1: 종속성 설치 (Install Dependencies)
npm install @opentiny/next-sdk
단계 2: WebMCP 폴리필 초기화 (권장)
애플리케이션의 진입점(예: main.ts 또는 app.js)에 다음을 추가합니다:
import { initializeBuiltinWebMCP } from '@opentiny/next-sdk'
...
이제 앱의 어느 곳에서든 표준 document.modelContext를 사용하여 도구를 등록할 수 있습니다:
const abortController = new AbortController()
...
✅ 완료! 이제 앱은 MCP 서버입니다.
이를 모든 MCP 호환 클라이언트에 연결하거나, TinyRemoter를 사용하여 앱과 직접 채팅할 수 있습니다.
📦 핵심 패키지 (Core Packages)
@opentiny/next-sdk (현재 패키지)
다음 기능을 제공하는 핵심 SDK 패키지입니다:
- 내장 WebMCP 폴리필 (Built-in WebMCP Polyfill):
document.modelContext를 주입하고 원활한 AI-to-page 통신을 위한 브릿징 메커니즘을 설정합니다.
- WebMcpServer: 라이프사이클 및 전송 계층에 대한 완전한 제어를 제공하는 관리형 MCP 서버입니다.
- WebMcpClient: WebAgent 또는 기타 원격 서비스에 연결하기 위한 MCP 클라이언트입니다.
- WebAgent: 고수준의 지능형 에이전트 오케스트레이션 로직입니다.
- 전송 계층 (Transport Layer): MessageChannel, SSE, HTTP 및 Chrome Extension 메시징을 지원합니다.
@opentiny/next-remoter
TinyRobot 기반의 Vue3 AI 채팅 컴포넌트로, 다음을 제공합니다:
- 통합된 AI 어시스턴트 UI.
- MCP 플러그인 마켓플레이스.
- 동적 웹 스킬(WebSkills) 검색 및 실행.
@opentiny/webmcp-cli
Chrome 브라우저를 제어하고 WebMCP 인터페이스를 노출하는 데 사용되는 puppeteer-core 기반의 CLI 도구:
- 브라우저 장악(Browser Takeover): Chrome DevTools Protocol (CDP)을 통해 디버깅 포트를 가진 로컬 Chrome을 자동으로 시작하거나 연결합니다.
- 자동 주입(Auto-Injection): 브라우저 탭이 열릴 때, WebMCP 폴리필과 페이지 조작 도구(
page-agent-tool)를 감지하여 자동으로 주입합니다.
- 통합 도구 프로토콜(Unified Tool Protocol): 페이지 작업을 표준 MCP 인터페이스에 매핑하여 AI 에이전트가 이를 직접 호출할 수 있도록 합니다.
webmcp-skill
웹 페이지와 상호 작용하는 서드파티(third-party) AI 에이전트를 위한 가이드라인 및 도메인별 스킬:
- 프롬프트 최적화(Prompt Optimization): 외부 LLM 에이전트가 페이지를 제어하기 위해 CLI를 정확하게 사용하는 것을 돕는 내장 종합 시스템 프롬프트 및 사용 사양을 제공합니다.
- 도메인별 스킬(Domain-Specific Skills): 고난이도의 세밀한 웹 작업을 위한 Excalidraw 캔버스 명령어(
excalidraw_execute_command)와 같은 하위 스킬을 제공합니다.
💻 WebMCP CLI & Agent Skills
WebMCP CLI를 사용하면 브라우저를 MCP 서버로 취급하여 페이지 조작 인터페이스를 AI 에이전트에 직접 노출할 수 있습니다. 백그라운드에서 Puppeteer를 실행하여 실제 Chrome 브라우저를 구동하며, 전통적인 페이지 상호 작용(클릭, 입력, 스크롤 등)을 표준 MCP 도구 호출로 매핑합니다.
🚀 시작하기 (Getting Started)
1. 설치 (Installation)
NPM을 통해 전역으로 설치할 수 있습니다:
npm install -g @opentiny/webmcp-cli
또는 현재 모노레포(Monorepo) 내에서 로컬 디버깅을 위해:
cd packages/webmcp-cli
pnpm build
npm install -g .
2. 웹 페이지 열기 (Open a Webpage)
Chrome에서 특정 URL로 이동하고 환경을 준비합니다:
webmcp-cli tabs open https://excalidraw.com
3. 브라우저 상태 가져오기 (Get Browser State)
현재 페이지 상태(URL, 제목, 열린 탭 및 자동 주입된 네이티브 MCP 도구 목록)를 확인합니다. 또한 인덱싱된 DOM 트리도 반환합니다:
출력에는 인덱스와 해당 MCP 인터페이스 이름이 포함된 [18]<button>Search</button>과 같은 요소가 포함됩니다.
페이지에서 등록된 MCP 도구를 직접 실행하려면 JSON 형식의 인수를 사용합니다:
webmcp-cli run page-agent-tool '{"action": "click", "index": 18}'
...
🧠 에이전트 스킬 가이드라인 (Agent Skill Guidelines)
packages/webmcp-skill 디렉터리에는 표준 에이전트 스킬(Agent Skills) 세트가 정의되어 있습니다. LLM(Claude 또는 Gemini와 같은)이 에이전트로 웹페이지에 연결할 때, 적절하게 CLI 명령을 내리는 방법을 학습하기 위해 SKILL.md 파일을 읽습니다.
복잡한 페이지의 경우, 도메인별 하위 스킬을 함께 사용합니다:
- Excalidraw 캔버스 도구 (
domains/excalidraw.md): URL에 excalidraw.com이 포함된 경우 에이전트가 도형과 다이어그램을 그리기 위해 excalidraw_execute_command를 사용하도록 지시합니다.
- Baidu 검색 도구: 에이전트가 자동으로 검색을 수행하고 페이지 결과를 가져오도록 안내합니다.
이를 통해 NEXT-SDKs는 외부 AI가 모든 웹페이지를 자율적으로 "원격 구동(remote drive)"할 수 있게 하는 완전한 생태계를 갖추게 됩니다.
💡 핵심 개념 (Core Concepts)
WebMCP 브릿지 아키텍처 (WebMCP Bridge Architecture)
기존의 백엔드 MCP와 달리, WebMCP는 **브라우저 컨텍스트(Browser Context)**에 중점을 둡니다.
┌─────────────────────────────────────────────────────────────┐
│ 웹 브라우저 (Web Browser) │
│ ┌──────────────────┐ ┌───────────────────┐ │
...
- 도구 등록 (Register Tools):
document.modelContext.registerTool을 사용하여 앱의 기능을 선언하며, AbortSignal을 통한 자동 등록 해제 지원이 가능합니다.
- 브릿지 동기화 (Bridge Synchronization): 사용자가 페이지를 전환했더라도, 당사의 브릿징 메커니즘은 AI 요청을 올바른 페이지 또는 iframe으로 자동으로 라우팅합니다.
- 직접 실행 (Direct Execution): 도구는 페이지 환경에서 직접 실행되어 DOM, 컴포넌트 상태 및 로컬 API에 접근할 수 있게 합니다.
기반 전송 및 엔진 계층 (Underlying Transport and Engine Layer)
일상적인 개발에는 단순히 document.modelContext.registerTool을 사용할 수 있지만, NEXT-SDKs는 고급 스케줄링을 위해 전체 핵심 MCP 프로토콜 구현을 내부적으로 유지합니다:
- WebMcpServer / WebMcpClient: 기본 JSON-RPC 메시지 처리, 스키마 유효성 검사(Schema validation), 채널 핸드셰이크를 담당합니다. 인프라 확장을 고려할 때만 이해하는 것이 권장되며, 일반 비즈니스 애플리케이션에서는 직접 호출하는 것을 피해야 합니다.
📖 시나리오 (Scenarios)
- 🤝 스마트 고객 서비스(Smart Customer Service): 도구 호출(tool calls)을 지원하는 AI 고객 서비스 시스템을 빠르게 구축합니다.
- 📚 문서 어시스턴트(Doc Assistant): 문서 웹사이트에 지능형 Q&A 기능을 추가합니다.
- 🛠️ 개발자 도구(Dev Tools): 코드 생성 및 분석을 지원하는 개발자 보조 도구를 구축합니다.
- 🌐 브라우저 확장 프로그램(Browser Extensions): AI 기능을 갖춘 브라우저 플러그인을 개발합니다.
- 🏢 엔터프라이즈 앱(Enterprise Apps): 기업 애플리케이션에 지능형 기능을 추가합니다.
- 📊 데이터 분석(Data Analysis): 지능형 데이터 분석 및 시각화 애플리케이션을 구축합니다.
- ✍️ 콘텐츠 생성(Content Creation): AI 지원 콘텐츠 생성 도구를 개발합니다.
🛠️ 기여 (Contributing)
