Webmcp Sdk

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

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

🚀 Quick Start

Turn your front-end application into an AI-Native one in just a few lines.

Step 1: Install Dependencies

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).

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:

// 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:

npm install -g @opentiny/webmcp-cli

Or run it locally within this monorepo:

cd packages/webmcp-cli
pnpm build
npm install -g .

2. Open a Page

Launch a headless/headful browser and navigate to a URL:

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:

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:

# 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.

┌─────────────────────────────────────────────────────────────┐
│                       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.

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.

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.

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

# Clone the repository
git clone https://github.com/opentiny/next-sdk.git
cd next-sdk

# Install dependencies
pnpm install

Project Structure

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

# 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

# Enter next-remoter package directory
cd packages/next-remoter

# Start dev server
pnpm dev

# Browser access http://localhost:5173

3. Debug Example App

# Enter doc-ai example directory
cd packages/doc-ai

# Start dev server
pnpm dev

Build Script Description

The core SDK provides multiple build scripts:

# 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 UPPERSNAKECASE (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
• Source: opentiny/webmcp-sdk
• License: MIT
• Homepage: https://docs.opentiny.design/next-sdk/guide

Install and usage instructions live in the source repository linked above.