# Webmcp Sdk > OpenTiny NEXT-SDKs is a front-end AI and browser automation toolkit. It implements WebMCP + WebSkills to build AI-native apps, and leverages webmcp-cli to enable LLM agents to remote-control any webpage without source code modifications. OpenTiny NEXT-SDKs 是一套前端 AI 与浏览器自动化工具包。它通过 WebMCP + WebSkills 协议构建 AI 原生应用，并利用 webmcp-cli 实现了无需修改源码即可让大模型代理自动控制任 - **Type:** MCP server - **Install:** `agentstack add mcp-opentiny-webmcp-sdk` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [opentiny](https://agentstack.voostack.com/s/opentiny) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [opentiny](https://github.com/opentiny) - **Source:** https://github.com/opentiny/webmcp-sdk - **Website:** https://docs.opentiny.design/next-sdk/guide ## Install ```sh agentstack add mcp-opentiny-webmcp-sdk ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # OpenTiny NEXT-SDKs: Built-in WebMCP & Polyfill + WebSkills + WebAgent English | [简体中文](README.zh-CN.md) [](https://deepwiki.com/opentiny/webmcp-sdk) A front-end intelligent application development and browser automation toolkit. It turns existing apps intelligent via WebMCP + WebSkills, and provides webmcp-cli to perceive and control any webpage with zero refactoring. 📖 Docs | 🚀 Quick Start | 🌐 WebMCP & Polyfill | 💡 Scenarios > [!IMPORTANT] > **Next-Gen AI Protocol**: OpenTiny NEXT-SDKs is built on the **WebMCP (Model Context Protocol for Web)**. It is fully compatible with the native `navigator.modelContext` API (currently in experimental stage in browsers like Chrome), allowing your web apps to be controlled by AI via a standardized protocol. > [!TIP] > **✨ Command-line Automation & AI Skills**: > We now offer **`webmcp-cli`** (browser control & polyfill auto-injection CLI) and **`webmcp-skill`** (standard instructions and sub-skills like Excalidraw drawing for AI agents). Together, they enable AI agents to perform complex, fine-grained tasks and "remote-drive" any webpage out of the box. --- **OpenTiny NEXT-SDKs** is a front-end intelligent application development and browser automation toolkit. Beyond enabling the "WebMCP + WebSkills" model to expose page operations as standardized tools in just a few lines of code, it features **`webmcp-cli`** to connect, perceive, and control any webpage with zero source code modifications, instantly bringing out-of-the-box AI-Native capability to any web app. ## 📑 Table of Contents - [✨ Main Features](#-main-features) - [🌐 WebMCP & Polyfill](#-webmcp--polyfill) - [🚀 Quick Start](#-quick-start) - [📦 Core Packages Description](#-core-packages-description) - [💻 WebMCP CLI & Agent Skills](#-webmcp-cli--agent-skills) - [💡 Core Concepts](#-core-concepts) - [📖 Scenarios](#-scenarios) - [🛠️ Contributing](#️-contributing) - [📄 License](#-license) ## ✨ Main Features - 🔌 **Standard WebMCP Implementation**: Fully implements the browser version of MCP, making front-ends "AI-Callable" via a unified protocol. - 📡 **Remote AI Control**: Seamlessly connect your front-end to a **WebAgent service**, allowing AI to remotely orchestrate and control your application via a stable sessionId. - 🛠️ **Built-in Polyfill Support**: Provides `navigator.modelContext` polyfill for current browsers, ensuring your code works today and is ready for tomorrow's native browser support. - 🎯 **Zero-Refactor Intelligence**: Expose existing business logic and UI operations as tools without changing your app's core architecture. - 🧩 **WebSkills Abstraction**: Organizes tools into "Business Skills" for progressive disclosure to AI. - 🤖 **AI Chat Components**: Ready-to-use `@opentiny/next-remoter` for instant AI remote control. ## 🌐 WebMCP & Polyfill ### What is WebMCP? WebMCP is an extension of the Model Context Protocol specifically for web browsers. It defines how a web page provides "Tools" and "Resources" to AI agents. In the near future, browsers will provide a native `navigator.modelContext` object to manage these capabilities. ### Why Polyfill? Since the native API is still in its experimental phase, **OpenTiny NEXT-SDKs provides a robust Polyfill**. By calling `initializeBuiltinWebMCP()`, the SDK: 1. **Injects `navigator.modelContext`**: Provides a standard-compliant API for tool registration. 2. **Automatic Routing & Bridge**: Automatically handles page navigation and message synchronization across different routes/iframes. This means you can write standard WebMCP code today, and it will automatically switch to the native engine when the browser supports it. ### 📡 Remote Control via WebAgent One of the most powerful features of NEXT-SDKs is the ability to connect your local page tools to a remote **WebAgent**. By using the `WebMcpClient`, you can: - **Obtain a Session ID**: Establish a persistent connection to the cloud-based AI orchestrator. - **Remote Orchestration**: Allow the AI to call your page's tools even when you are not actively interacting with the chat UI. - **Cross-Device Control**: Once connected, your application can be controlled from any authorized MCP client using its `sessionId`. #### Connection Example ```typescript import { WebMcpClient } from '@opentiny/next-sdk' const client = new WebMcpClient() // Connect to the remote WebAgent service const { sessionId } = await client.connect({ agent: true, builtin: true, // Enable the built-in WebMCP proxy url: 'https://agent.opentiny.design/api/v1/webmcp-trial/mcp' }) console.log('Connected! Session ID:', sessionId) // Now your app can be controlled remotely via this sessionId ``` > [!TIP] > The URL above is a public test server provided by OpenTiny for testing purposes. For production use, you should deploy your own WebAgent instance. > Source code: [https://github.com/opentiny/web-agent](https://github.com/opentiny/web-agent) ## 🚀 Quick Start Turn your front-end application into an AI-Native one in just a few lines. ### Step 1: Install Dependencies ```bash npm install @opentiny/next-sdk ``` ### Step 2: Initialize WebMCP Polyfill (Recommended) Add this at your application's entry point (e.g., `main.ts` or `app.js`). ```typescript import { initializeBuiltinWebMCP } from '@opentiny/next-sdk' // Initialize Polyfill and Bridge initializeBuiltinWebMCP() ``` ### Step 3: Register Tools via Standard API Now you can use the standard `navigator.modelContext` to register tools anywhere in your app: ```typescript // Register a tool that AI can call navigator.modelContext.registerTool({ name: 'get_user_info', description: 'Get current user profile', inputSchema: { type: 'object', properties: { userId: { type: 'string' } } }, execute: async (args) => { // Your business logic here return { content: [{ type: 'text', text: `Info for user ${args.userId}` }] } } }) ``` ✅ **Done!** Your app is now an MCP Server. You can connect it to any MCP-compatible client or use our [TinyRemoter](#-remote-control-via-webagent) to start chatting with your app. --- ## 📦 Core Packages Description ### @opentiny/next-sdk (Current Package) Core SDK package, providing: - **Built-in WebMCP Polyfill**: Injects `navigator.modelContext` and sets up the bridge for seamless AI-to-Page communication. - **WebMcpServer**: Managed MCP server for full control over lifecycle and transports. - **WebMcpClient**: MCP client for connecting to WebAgents and other services. - **WebAgent**: High-level agent orchestration logic. - **Transport Layer**: Support for MessageChannel, SSE, HTTP, and Chrome Extension messaging. ### @opentiny/next-remoter Vue3 AI chat component based on TinyRobot, offering: - Integrated AI assistant UI. - MCP Plugin marketplace. - Dynamic WebSkills discovery and execution. ### @opentiny/webmcp-cli A CLI tool that launches or connects to Chrome via Chrome DevTools Protocol (CDP), allowing AI agents to perceive and control pages: - **Browser Orchestration**: Configures a dedicated Chrome profile or connects to a running debug instance. - **Auto-Injection**: Intercepts navigations to auto-inject the WebMCP polyfill and `page-agent-tool`. - **JSON RPC API**: Exposes standard MCP tools like state inspection and page actions. ### webmcp-skill Guidelines and domain-specific tools package for AI agents: - **Agent Optimization**: Pre-written system prompts and instructions guiding LLM agents to call CLI commands correctly. - **Domain Specialization**: Specific sub-skills (e.g., Excalidraw drawing tools) for advanced interaction tasks. --- ## 💻 WebMCP CLI & Agent Skills With the WebMCP CLI, you can expose browser control directly to AI agents. It runs a local Puppeteer instance under the hood and maps page actions to standard MCP tools. ### 🚀 Getting Started #### 1. Installation You can install it globally from NPM: ```bash npm install -g @opentiny/webmcp-cli ``` Or run it locally within this monorepo: ```bash cd packages/webmcp-cli pnpm build npm install -g . ``` #### 2. Open a Page Launch a headless/headful browser and navigate to a URL: ```bash webmcp-cli tabs open https://excalidraw.com ``` #### 3. Inspect Browser State Get current URL, title, open tabs, and **available WebMCP tools**, along with an indexed representation of the DOM tree: ```bash webmcp-cli state ``` Output includes interactive element IDs (e.g., `[18]Search`) and tool lists. #### 4. Run an MCP Tool Directly trigger actions using standard MCP calls: ```bash # Click a button at DOM index 18 webmcp-cli run page-agent-tool '{"action": "click", "index": 18}' # Fill an input field at DOM index 13 webmcp-cli run page-agent-tool '{"action": "fill", "index": 13, "text": "Model Context Protocol"}' ``` ### 🧠 Agent Skill Guidelines Under `packages/webmcp-skill`, we define a set of **Agent Skills** (System instructions and reference templates). When an AI agent connects to a webpage, it reads `SKILL.md` to learn how to interact with the page. For complex pages, it also loads domain-specific sub-skills: - **Excalidraw (`domains/excalidraw.md`)**: Instructs the agent on how to call canvas drawing commands (`excalidraw_execute_command`) to draw flowcharts and shapes. - **Baidu Search**: Executes search actions and parses results automatically. This makes NEXT-SDKs not just an API for your app, but a complete playground for autonomous AI agents. --- ## 💡 Core Concepts ### The WebMCP Bridge Architecture Unlike traditional backend MCP, WebMCP focuses on the **Browser Context**. ```text ┌─────────────────────────────────────────────────────────────┐ │ Web Browser │ │ ┌──────────────────┐ ┌───────────────────┐ │ │ │ Front-end App │◄── Bridge ──►│ AI Assistant │ │ │ │ (WebMCP Server) │ │ (MCP Client) │ │ │ └──────────────────┘ └───────────────────┘ │ │ ▲ │ │ └───────────┼──────────────────────────────────┼──────────────┘ │ (Standard Protocol) │ └──────────────────────────────────┘ ``` 1. **Registering**: Use `navigator.modelContext.registerTool` to declare what your app can do. 2. **Bridging**: Our Bridge automatically routes AI requests to the correct page/iframe, even if the user has navigated away. 3. **Executing**: Tools run in the context of your page, allowing direct access to DOM, State, and APIs. ### WebMcpServer WebMcpServer is the MCP server implementation used to declare front-end application functions as MCP tools. ```typescript import { WebMcpServer } from '@opentiny/next-sdk' const server = new WebMcpServer({ name: 'my-app', version: '1.0.0' }) // Register tool server.registerTool( 'tool-name', { title: 'Tool Title', description: 'Tool Description', inputSchema: { /* Zod schema */ } }, async (params) => { // Tool logic return { content: [{ type: 'text', text: 'Result' }] } } ) ``` ### WebMcpClient WebMcpClient is the MCP client implementation used to connect to WebAgent services and other MCP services. ```typescript import { WebMcpClient } from '@opentiny/next-sdk' const client = new WebMcpClient({ name: 'my-client', version: '1.0.0' }) // Connect to WebAgent const { sessionId } = await client.connect({ agent: true, url: 'https://agent.opentiny.design/api/v1/webmcp-trial/mcp' }) ``` ### Transport Layer NEXT-SDKs supports multiple communication methods: - **MessageChannel**: Cross-window communication within the browser. - **SSE**: Server-Sent Events. - **HTTP**: Standard HTTP requests. ```typescript import { createMessageChannelPairTransport } from '@opentiny/next-sdk' // Create MessageChannel transport pair const [serverTransport, clientTransport] = createMessageChannelPairTransport() ``` ## 📖 Scenarios - **🤝 Smart Customer Service**: Quickly build an AI customer service system that supports tool calls. - **📚 Doc Assistant**: Add intelligent Q&A functionality to documentation websites. - **🛠️ Dev Tools**: Build developer auxiliary tools that support code generation and analysis. - **🌐 Browser Extensions**: Develop browser plugins with AI capabilities. - **🏢 Enterprise Apps**: Add intelligent capabilities to enterprise applications. - **📊 Data Analysis**: Build intelligent data analysis and visualization applications. - **✍️ Content Creation**: Develop AI-assisted content creation tools. ## 🛠️ Contributing We welcome all forms of contribution! Whether it's reporting bugs, suggesting new features, improving documentation, or submitting code, we appreciate it. ### Prerequisites Before you start developing, please make sure your environment meets the following requirements: - **Node.js** >= 18.0.0 - **pnpm** >= 8.0.0 - **Git** Latest version ### Get the Code ```bash # Clone the repository git clone https://github.com/opentiny/next-sdk.git cd next-sdk # Install dependencies pnpm install ``` ### Project Structure ```text next-sdk/ ├── packages/ │ ├── next-sdk/ # Core SDK package │ │ ├── agent/ # WebAgent implementation │ │ ├── client/ # WebMCP client │ │ ├── server/ # WebMCP server │ │ ├── transport/ # Transport layer implementation │ │ ├── McpSdk.ts # MCP SDK encapsulation │ │ ├── index.ts # Main entry │ │ ├── package.json │ │ └── README.md │ ├── next-remoter/ # Vue3 AI Chat Component │ │ ├── src/ │ │ │ ├── components/ # Component implementation │ │ │ └── composable/ # Composables │ │ ├── package.json │ │ └── README.md │ ├── webmcp-cli/ # CLI tool for browser control via WebMCP │ │ ├── src/ # CLI main implementation │ │ ├── webmcp-tools/ # Injected page tools (e.g. Excalidraw, Baidu) │ │ ├── package.json │ │ └── README.md │ ├── webmcp-skill/ # Guidelines and domain-specific skills for AI agents │ │ ├── SKILL.md # Master instruction file for agents │ │ └── domains/ # Domain-specific instructions (e.g., Excalidraw) │ └── doc-ai/ # Doc AI example app ├── docs/ # Project docs ├── pnpm-workspace.yaml # pnpm workspace config ├── package.json └── README.md ``` ### Development Flow #### 1. Develop Core SDK ```bash # Enter next-sdk package directory cd packages/next-sdk # Dev mode (supports hot reloading) pnpm dev # Run tests pnpm test # Build project pnpm build ``` #### 2. Develop Remoter Component ```bash # Enter next-remoter package directory cd packages/next-remoter # Start dev server pnpm dev # Browser access http://localhost:5173 ``` #### 3. Debug Example App ```bash # Enter doc-ai example directory cd packages/doc-ai # Start dev server pnpm dev ``` ### Build Script Description The core SDK provides multiple build scripts: ```bash # Build all versions (production + dev) pnpm build:all # Build production version only pnpm build:cdn # Build dev version (includes source maps) pnpm build:cdn:dev # Build specific module pnpm build:webAgent # WebAgent module pnpm build:webMcp # WebMCP module pnpm build:mcpSdk # MCP SDK module pnpm build:zod # Zod validation module pnpm build:webMcpFull # WebMCP full version ``` ### Code Convention Before submitting code, please ensure it complies with the following conventions: - **TypeScript**: Write type-safe code using TypeScript. - **Code Style**: Follow the project's ESLint configuration. - **Naming Convention**: - Filenames: use kebab-case (e.g., `web-mcp-client.ts`). - Class names: use PascalCase (e.g., `WebMcpClient`). - Function names: use camelCase (e.g., `registerTool`). - Constants: use UPPER_SNAKE_CASE (e.g., `MAX_RETRY_COUNT`). - **Comments**: Add clear … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [opentiny](https://github.com/opentiny) - **Source:** [opentiny/webmcp-sdk](https://github.com/opentiny/webmcp-sdk) - **License:** MIT - **Homepage:** https://docs.opentiny.design/next-sdk/guide Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-opentiny-webmcp-sdk - Seller: https://agentstack.voostack.com/s/opentiny - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.