@mcp-b

Polyfill and MCP bridge for the Web Model Context API (document.modelContext)

---

The Web Standard

The Web Model Context API is a W3C Community Group draft spec. It makes every browser tab a tool source — web pages register tools that AI agents can discover and call:

document.modelContext
├── .registerTool(tool, { signal })  Register a tool for AI agents
└── .getTools()                      Discover registered tools

Chrome preview extension
└── .executeTool(tool, inputJson)    Execute a discovered tool

MCP-b polyfills that API for all browsers today, and bridges it to the full Model Context Protocol — turning that tool source into a complete MCP server with prompts, resources, and browser transports.

Built by MCP-b. Not an official W3C or MCP project.

Getting Started

1. Use the web standard directly

If you're running Chrome with --enable-experimental-web-platform-features, document.modelContext is already there. Just use it:

Add @mcp-b/webmcp-types (pnpm add -D @mcp-b/webmcp-types) for input schema inference:

await document.modelContext.registerTool({
  name: 'add_todo',
  description: 'Add a new todo item',
  inputSchema: {
    type: 'object',
    properties: { title: { type: 'string' }, done: { type: 'boolean' } },
    required: ['title'],
  } as const, // ← args inferred: { title: string; done?: boolean }
  execute: async (args) => ({ id: Date.now(), title: args.title }),
});

2. Polyfill it

Want it to work in any browser without the Chrome flag? Add the polyfill — same API, same code:

import { initializeWebMCPPolyfill } from '@mcp-b/webmcp-polyfill'; // pnpm add @mcp-b/webmcp-polyfill

initializeWebMCPPolyfill(); // no-op if native support exists

await document.modelContext.registerTool({
  name: 'get_page_title',
  description: 'Returns the current page title',
  inputSchema: { type: 'object', properties: {} },
  execute: async () => ({
    content: [{ type: 'text', text: document.title }],
  }),
});

Or with React: pnpm add usewebmcp

import { useWebMCP } from 'usewebmcp';

function PageTitle() {
  useWebMCP({
    name: 'get_page_title',
    description: 'Returns the current page title',
    execute: async () => ({ title: document.title }),
  });
  // ...
}

3. Full MCP server

Need the full Model Context Protocol — prompts, resources, transports, and interop with Claude Desktop, Cursor, or another MCP client? Use @mcp-b/global:

import '@mcp-b/global'; // pnpm add @mcp-b/global

// Same registerTool API — now backed by a full MCP server
await document.modelContext.registerTool({
  name: 'add_todo',
  description: 'Add a new todo item',
  inputSchema: {
    type: 'object',
    properties: {
      title: { type: 'string', description: 'Todo title' },
    },
    required: ['title'],
  },
  execute: async (args) => {
    const todo = { id: Date.now(), ...args };
    return { content: [{ type: 'text', text: JSON.stringify(todo) }] };
  },
});

Or as a script tag (zero build step):

<script src="https://unpkg.com/@mcp-b/global/dist/index.iife.js"></script>
<script type="module">
  await document.modelContext.registerTool({
    /* ... */
  });
</script>

Or with React: pnpm add @mcp-b/global @mcp-b/react-webmcp

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

function TodoApp({ todos, addTodo }) {
  useWebMCP({
    name: 'add_todo',
    description: 'Add a new todo item',
    inputSchema: {
      type: 'object',
      properties: {
        title: { type: 'string', description: 'Todo title' },
      },
      required: ['title'],
    } as const,
    execute: async ({ title }) => {
      addTodo(title);
      return { success: true };
    },
  });

  return (
    <ul>
      {todos.map((t) => (
        <li key={t.id}>{t.title}</li>
      ))}
    </ul>
  );
}

Call Those Tools

Three ways for AI agents to discover and call your tools:

┌─────────────────────────────────────────────────────────┐
│  Your website                                           │
│  document.modelContext.registerTool({ ... })             │
└────────┬────────────────────┬───────────────────┬───────┘
         │                    │                   │
    ┌────▼─────┐    ┌────────▼────────┐   ┌─────▼──────┐
    │  MCP-B   │    │  Chrome Native  │   │   Local    │
    │Extension │    │  (experimental) │   │   Relay    │
    └────┬─────┘    └────────┬────────┘   └─────┬──────┘
         │                   │                   │
         ▼                   ▼                   ▼
    AI agent in         Browser's            Claude Desktop
    browser             built-in agent       Cursor, VS Code

MCP-B Extension — Install it from the Chrome Web Store. It discovers tools exposed by pages and connects them to extension-side agent experiences.

Chrome Native — Enable at chrome://flags → Experimental Web Platform features, or:

google-chrome --enable-experimental-web-platform-features

See Chromium flags reference for macOS / Windows / Linux commands.

Local Relay — Add to your MCP client config (Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "webmcp-local-relay": {
      "command": "npx",
      "args": ["-y", "@mcp-b/webmcp-local-relay@latest"]
    }
  }
}

Any website running @mcp-b/global becomes callable from your desktop AI agent. See the relay README for details.

Which Package?

I want to…	Package
Add tools to my site (simplest)	@mcp-b/global
Just the polyfill, no MCP bridge	@mcp-b/webmcp-polyfill
Register tools from React	@mcp-b/react-webmcp
Add WebMCP from an extension	@mcp-b/webmcp-extension
Forward tools to local AI agents	@mcp-b/webmcp-local-relay
Control Chrome from an AI agent	chrome-devtools-mcp
Just the TypeScript types	@mcp-b/webmcp-types

Chrome DevTools integration now lives entirely upstream; its WebMCP changes have all landed there.

---

Installation

# Full runtime: polyfill + MCP bridge (most users start here)
pnpm add @mcp-b/global

# Strict WebMCP core polyfill only (no MCP extensions)
pnpm add @mcp-b/webmcp-polyfill

# TypeScript definitions (dev dependency)
pnpm add -D @mcp-b/webmcp-types

# React hooks for full runtime
pnpm add @mcp-b/react-webmcp

# React hooks for strict WebMCP core only
pnpm add usewebmcp

# Transport layer (custom integrations)
pnpm add @mcp-b/transports

# Chromium extension template and content-script client
pnpm add @mcp-b/global @mcp-b/webmcp-extension

# DOM extraction for AI
pnpm add @mcp-b/smart-dom-reader

All Packages

Core

Package	Version	Description
@mcp-b/webmcp-polyfill		document.modelContext polyfill, with a deprecated navigator alias
@mcp-b/webmcp-types		TypeScript definitions for the WebMCP core API
@mcp-b/global		Full runtime — polyfill + MCP bridge (prompts, resources, transport)
@mcp-b/webmcp-ts-sdk		Browser-adapted MCP TypeScript SDK with dynamic tool registration

Transports & Composition

Package	Version	Description
@mcp-b/transports		postMessage, iframe, and Chrome extension transports
@mcp-b/webmcp-extension		MV3 template and isolated content-script client for page tools
@mcp-b/mcp-iframe		Web component for exposing iframe tools, resources, and prompts
@mcp-b/webmcp-local-relay		Localhost relay — forwards website tools to Claude Desktop, Cursor, etc.

React

Package	Version	Description
@mcp-b/react-webmcp		React hooks for full runtime (register tools + consume MCP servers)
usewebmcp		React hooks for strict WebMCP core only

Browser Tooling

Package	Version	Description
@mcp-b/smart-dom-reader		Token-efficient DOM extraction for AI agents

Deprecated packages

Package	Status	Migration
@mcp-b/mcp-react-hooks	Deprecated	Use @mcp-b/react-webmcp instead
@mcp-b/mcp-react-hook-form	Removed	Use custom useWebMCP wrappers
@mcp-b/codemode	Removed	Use Cloudflare Code Mode; browser APIs are exported from @cloudflare/codemode/browser

Architecture

┌──────────────────────────────────────────────────────────┐
│  Your web app                                            │
│  document.modelContext.registerTool({ ... })              │
├────────────── @mcp-b/global ─────────────────────────────┤
│  MCP bridge: prompts, resources, browser transports      │
├────────────── @mcp-b/webmcp-ts-sdk ──────────────────────┤
│  BrowserMcpServer — wraps native/polyfill context        │
├────────────── @mcp-b/webmcp-polyfill ────────────────────┤
│  WebMCP core + optional Chrome executeTool extension    │
├──────────────────────────────────────────────────────────┤
│  Native browser API (when available)                     │
└──────────────────────────────────────────────────────────┘
         ▲                              ▲
         │ postMessage / extension      │ WebSocket
         ▼                              ▼
   AI agent in browser            Local AI agent
   (extension, tab)          (Claude Desktop, Cursor)

Dependency Graph

webmcp-types          (canonical type definitions)
└── webmcp-polyfill   (canonical runtime polyfill)
    ├── webmcp-ts-sdk (TypeScript SDK adapter)
    │   ├── global    (full runtime; also uses transports)
    │   ├── mcp-iframe (iframe element; also uses transports)
    │   └── react-webmcp (also uses usewebmcp; pair with global at app level)
    └── usewebmcp     (React hooks for strict core)

transports            (browser transports shared by integrations)
└── webmcp-extension  (MV3 template and isolated content-script client)

Standalone packages: smart-dom-reader, webmcp-local-relay.

Development

git clone https://github.com/WebMCP-org/npm-packages.git
cd npm-packages
pnpm install
pnpm build

Command	What it does
pnpm build	Build all packages
pnpm typecheck	Type-check all packages
pnpm check	Lint + format (Oxlint + Oxfmt)
pnpm test:unit	Unit tests
pnpm test:e2e	E2E tests (Playwright)
pnpm test	All tests
pnpm --filter <pkg> build	Build a single package
pnpm --filter <pkg> test	Test a single package
pnpm changeset	Create a changeset for versioning

Prerequisites: Node.js >= 22.12 (see .nvmrc), pnpm >= 10

Documentation

Document	Purpose
CONTRIBUTING.md	How to contribute: setup, PR process, commit format
AGENTS.md	Quick reference for AI agents working in this repo
Package Philosophy	Package boundaries and layering model
Testing Philosophy	Test layers, mocking policy, coverage expectations
E2E Testing	Playwright setup, test apps, debugging
@mcp-b/global guide	Advanced usage for the full runtime
AI Contribution Manifesto	Safety rules and code quality bar
Relevant Links	Curated external best practices for contributors

Contributing

Contributions welcome — see CONTRIBUTING.md for guidelines.

License

MIT

Links

• MCP-b Documentation
• MCP-B Browser Extension
• W3C WebMCP Spec
• W3C Web Machine Learning Community Group
• Model Context Protocol Specification
• Chromium WebMCP Implementation
• npm: @mcp-b
• GitHub Repository
• Issue Tracker