---

What This Does

WebMCP (Model Context Protocol for Browsers) enables AI assistants to interact with web applications through registered tools instead of screen automation. This repository provides production-ready examples using the modern WebMCP API.

Flow:

1. Web application registers tools using navigator.modelContext.registerTool()
2. AI assistant discovers available tools through the MCP-B browser extension
3. AI invokes tools to interact with the application
4. Application updates in real-time based on AI commands

This pattern works for any web application: e-commerce, task management, data visualization, configuration UIs, and more.

Quick Start

Run Existing Examples

# Clone the repository
git clone https://github.com/WebMCP-org/examples.git
cd examples

# Choose an example
cd vanilla  # or react, rails, angular
cd vanilla  # or react, rails, phoenix-liveview

# Install and run
pnpm install
pnpm dev

Requirements

• Node.js 18 or higher
• pnpm package manager (or npm/yarn)
• Chrome browser with MCP-B extension

Examples

Vanilla JavaScript Example

Location: /vanilla

A shopping cart application demonstrating core WebMCP functionality with vanilla TypeScript.

Features:

• Uses navigator.modelContext.registerTool() - simplified API
• JSON schema validation
• Real-time UI updates
• 5 AI-callable tools (add to cart, remove, get cart, clear, get total)

Tech: Vite, TypeScript, @mcp-b/global

→ Documentation

---

React Example

Location: /react

A task management application showcasing React integration with the useWebMCP() hook.

Features:

• Uses useWebMCP() hook from @mcp-b/react-webmcp
• Zod schema validation with type safety
• Automatic cleanup on component unmount
• 6 AI-callable tools (task CRUD operations + stats)
• Responsive UI with real-time updates

Tech: React 18, TypeScript, Vite, Zod, @mcp-b/react-webmcp, @mcp-b/global

→ Documentation

---

Rails Example

Location: /rails

A bookmarks management application demonstrating Rails 7+ integration with Stimulus controllers.

Features:

• Uses navigator.modelContext.registerTool() with Stimulus controllers
• Follows Rails conventions (app/javascript/controllers/)
• Pure business logic separated into lib/ modules
• Compatible with Vite, importmaps, or esbuild
• 6 AI-callable tools (bookmark CRUD operations + search + stats)

Tech: Rails 7+, Stimulus, TypeScript, Vite, @mcp-b/global

→ Documentation

---

Angular Example

Location: /angular

A note-taking application showcasing Angular integration with services and signals.

Features:

• Uses navigator.modelContext.registerTool() via Angular service
• Angular signals for reactive state management
• Automatic cleanup via DestroyRef
• 6 AI-callable tools (note CRUD operations + stats)

Tech: Angular 19, TypeScript, @mcp-b/global

→ Documentation

Phoenix LiveView Example

Location: /phoenix-liveview

A counter and item management app demonstrating WebMCP integration with Phoenix LiveView and server-side state.

Features:

• Uses navigator.modelContext.registerTool() via LiveView hooks
• Server-side state management with real-time sync
• Bidirectional communication: AI -> JavaScript -> LiveView -> Server
• 6 AI-callable tools (counter operations + item CRUD + state query)

Tech: Elixir, Phoenix 1.7, LiveView 1.0, @mcp-b/global

→ Documentation

---

Legacy Examples (Deprecated)

Location: /relegated

These examples use the older MCP SDK API and are kept for reference only. Do not use these as starting points for new projects. They use the legacy @modelcontextprotocol/sdk with McpServer and TabServerTransport, requiring significantly more boilerplate.

Deprecated examples:

• vanilla-ts - Original TypeScript example
• login - Authentication example
• script-tag - Legacy implementation
• mcp-b-startup - Complex React Flow workspace
• extension-connector - Chrome extension
• reactFlowVoiceAgent - Voice agent

→ Legacy Documentation

API Overview

Vanilla JavaScript API

The modern WebMCP API provides a simple way to register tools:

import '@mcp-b/global';

navigator.modelContext.registerTool({
  name: 'my_tool',
  description: 'What this tool does',
  inputSchema: {
    type: 'object',
    properties: {
      param: { type: 'string', description: 'Parameter description' }
    },
    required: ['param']
  },
  async execute(args) {
    // Your logic here
    return {
      content: [{ type: 'text', text: 'Result' }]
    };
  }
});

React Hooks API

For React applications, use the useWebMCP hook for automatic lifecycle management:

import { useWebMCP } from '@mcp-b/react-webmcp';
import { z } from 'zod';

function App() {
  useWebMCP({
    name: 'my_tool',
    description: 'What this tool does',
    inputSchema: {
      param: z.string().describe('Parameter description')
    },
    handler: async ({ param }) => {
      // Your logic here with React state
      return { success: true, result: 'Done!' };
    }
  });

  return <div>Your UI</div>;
}

Installation Methods

For build-based projects (recommended):

# Vanilla JavaScript/TypeScript
pnpm add @mcp-b/global

# React
pnpm add @mcp-b/react-webmcp @mcp-b/global zod

For no-build projects:

<script src="https://unpkg.com/@mcp-b/global@latest/dist/index.iife.js"></script>

Architecture

API Comparison: New vs Legacy

Feature	Modern API	Legacy API (Deprecated)
Installation	@mcp-b/global or @mcp-b/react-webmcp	@modelcontextprotocol/sdk + @mcp-b/transports
Setup	Single import	Server + Transport + Connection
Vanilla API	navigator.modelContext.registerTool()	new McpServer() + complex setup
React API	useWebMCP() hook	Manual tool registration
Validation	JSON schema or Zod	Complex Zod with custom wrapper
Return Format	Simple objects (React) or MCP format (Vanilla)	Always MCP content format
Boilerplate	Minimal	Significant
Learning Curve	Easy	Moderate to Hard

How It Works

1. Install the MCP-B browser extension
2. Run one of the example projects (pnpm dev)
3. Open the extension to discover available tools
4. Use AI (ChatGPT, Claude, etc.) to interact with your website's tools
5. Watch the page update in real-time as AI calls your tools

WebMCP enables AI assistants to interact with websites through APIs instead of screen automation, providing more reliable and powerful integration.

Commands

# Development (per example)
cd vanilla  # or react, rails, phoenix-liveview
pnpm dev                    # Run development server
pnpm build                  # Build for production
pnpm preview                # Preview production build

Documentation

Getting Started

• AGENTS.md - Navigation hub for AI agents
• CONTRIBUTING.md - Development standards and guidelines
• CHANGELOG.md - Version history and changes

Community

• CODE_OF_CONDUCT.md - Community standards

Example Documentation

• Vanilla Example - Vanilla JavaScript implementation
• React Example - React with hooks implementation
• Rails Example - Rails with Stimulus controllers
• Angular Example - Angular with services implementation
• Phoenix LiveView Example - Elixir/Phoenix implementation
• Legacy Examples - Deprecated implementations

Tech Stack

• Package Manager: pnpm (JS), Mix (Elixir)
• Build Tool: Vite 6, esbuild
• Languages: TypeScript 5.6, Elixir 1.14+
• WebMCP Core: @mcp-b/global
• React Integration: @mcp-b/react-webmcp
• Phoenix Integration: LiveView hooks + @mcp-b/global
• Validation: JSON Schema, Zod

Contributing

Fork, experiment, report issues, submit improvements.

Before contributing:

• Read CONTRIBUTING.md for development standards and best practices
• Check CODE_OF_CONDUCT.md for community guidelines
• Review existing examples to understand patterns

For AI Agents:

• Start with AGENTS.md for quick navigation
• Follow TypeScript strict mode and modern WebMCP API patterns
• Test all changes with the MCP-B Chrome Extension

Quick contribution steps:

1. Fork the repository
2. Create a feature branch
3. Make your changes following CONTRIBUTING.md
4. Test thoroughly (typecheck, lint, build, manual testing)
5. Submit a pull request

Resources

MCP-B (WebMCP / Bidirectional Tools)

Documentation:

• MCP-B Documentation - Getting started with WebMCP
• Quick Start - Get WebMCP running in minutes
• Core Concepts - Architecture and system design
• Examples - Ready-to-use implementations

NPM Packages:

• @mcp-b/react-webmcp - React hooks for WebMCP (docs)
• @mcp-b/transports - Transport layer implementations (docs)
• @mcp-b/core - Core WebMCP functionality (docs)
• @mcp-b/global - Global WebMCP polyfill (docs)
• All Packages - Complete package repository

Live Demos & Tools:

• mcp-b.ai - Interactive examples
• MCP-B Chrome Extension - Test tools in your browser

Specification:

• WebMCP Specification - W3C Web Machine Learning Community Group
• WebMCP Explainer - Technical proposal and API details

Model Context Protocol

• MCP Documentation - Official protocol documentation
• MCP Specification - Technical specification
• MCP GitHub - Specification repository

Development Tools

• TypeScript - Type-safe JavaScript
• Vite - Next generation frontend tooling
• Zod - TypeScript-first schema validation

License

MIT

---

Built by the WebMCP community