@mcp-b/global weekly downloads statistics

@mcp-b/global

WebMCP runtime - Let Claude, ChatGPT, Gemini, and other AI agents interact with your website

Reference | First Tool Tutorial | Add Tools to an App

@mcp-b/global implements the WebMCP API (document.modelContext) specification, allowing AI agents like Claude, ChatGPT, Gemini, Cursor, and Copilot to discover and call functions on your website.

Why Use @mcp-b/global?

| Feature | Benefit |

| W3C Standard | Implements the emerging WebMCP API specification | | Drop-in IIFE | Add AI capabilities with a single tag - no build step | | Native Chromium Support | Auto-detects and uses native browser implementation when available | | Dual Transport | Works with both same-window clients AND parent pages (iframe support) | | Spec-Aware Compatibility | Tracks the current WebMCP draft (document.modelContext, registerTool(tool, { signal }), and getTools()) and object-input executeTool(...). | | Works with Any AI | Claude, ChatGPT, Gemini, Cursor, Copilot, and any MCP client |

Package Selection

• Use upstream webmcp-types for standard browser contracts and @mcp-b/webmcp-ts-sdk for MCP-B extensions. • Use @mcp-b/webmcp-polyfill when you only need strict WebMCP runtime polyfill behavior. • Use @mcp-b/global when you want MCPB integration features (bridge transport, prompts/resources, extension APIs).

Upstream runtime

When no context is installed, @mcp-b/global calls installWebMCP() from @mcp-b/webmcp-polyfill. That package bundles the upstream WebMCP polyfill at revision 6bf6c57bbaf3d1173d7737cfb79572632d9b7871. It depends on the upstream webmcp-types declarations. Consumers do not install or build a Git dependency.

@mcp-b/webmcp-polyfill retains the declarative API and its SubmitEvent extensions until upstream supports them. @mcp-b/global adds MCP-B transports, prompts, resources, MCP outputSchema metadata, and structured MCP responses. Existing native contexts take precedence and receive the MCP-B adapter when wrapped, including when the upstream polyfill was installed before @mcp-b/global. cleanupWebModelContext() removes the MCP-B adapter; the polyfill context and declarative layer remain installed for the document lifetime. Existing native SubmitEvent hooks are preserved.

executeTool(tool, inputObject) follows the current draft and returns JSON.

Quick Start

Via IIFE Script Tag (No Build Required)

• Self-contained - All dependencies bundled • Auto-initializes - document.modelContext ready immediately • No build step - Just drop it in your HTML

Via ES Module

The ESM entry keeps @mcp-b/transports, @mcp-b/webmcp-polyfill, and @mcp-b/webmcp-ts-sdk external; only the IIFE bundles them.

Via NPM

API Reference

Functions

initializeWebModelContext(options?)

Initializes the global adapter. Replaces document.modelContext with a BrowserMcpServer instance that bridges WebMCP tools to the MCP protocol layer.

Behavior:

• Only operates in browser environments • Returns nothing; use document.modelContext after initialization • Idempotent - repeated and cross-bundle calls are no-ops • Wraps the native context when present; otherwise installs and wraps the polyfill • Cleanup restores the captured native or polyfilled context • Auto-called on import unless window.__webModelContextOptions.autoInitialize is false

cleanupWebModelContext()

Tears down the adapter and restores document.modelContext to the captured native or polyfilled context. Closing the adapter aborts every registration made through document.modelContext while it was installed; re-initializing does not restore them. Tools registered directly on the underlying context, including declarative tools, survive.

document.modelContext Methods

After initialization, document.modelContext exposes these methods:

registerTool(tool, options?)

Registers a single tool. The tool name must be unique. Duplicate and invalid registrations reject the returned promise. The recommended unregistration path is options.signal (AbortSignal):

registerTool resolves undefined, matching current Chromium and the WebMCP spec. Use AbortSignal cleanup for dynamic tools.

getTools()

Returns WebMCP tool descriptors for all registered tools.

executeTool(tool, inputObject)

Execute a discovered descriptor with an input object. The result is serialized JSON.

listTools()

This MCP-B helper exposes MCP metadata. In-page WebMCP consumers should use getTools() and executeTool(tool, inputObject).

Prompt, resource, and lower-level MCP helpers are MCP-B extensions. Narrow document.modelContext with isBrowserMcpServer() from @mcp-b/webmcp-ts-sdk before using them. Install that package directly when importing the guard; do not add extensions to the standard global type.

BrowserMcpServer Tool Descriptor

The MCP-B runtime consumes outputSchema when a separately typed descriptor is passed to document.modelContext.registerTool(). Native and strict polyfill runtimes ignore the extra field.

| Property | Type | Required | Description |

| name | string | Yes | Unique identifier for the tool | | description | string | Yes | Natural language description of what the tool does | | inputSchema | InputSchema | No | JSON Schema describing accepted input. Defaults to { type: 'object', properties: {} } | | outputSchema | InputSchema | No | MCP-B helper metadata for output typing and structured MCP responses | | annotations | ToolAnnotations | No | Hints about tool behavior for LLM planners | | execute | (args) => unknown \| Promise | Yes | Function implementing the tool logic |

Tool Response Format

Tools may return an MCP CallToolResult object:

Configuration

WebModelContextInitOptions

| Option | Default | Description |

| transport | Auto-detect | Transport layer configuration (tab server and/or iframe) | | autoInitialize | true | Whether to auto-initialize on import |

Transport Configuration

The transport is auto-selected based on context:…

Description from the npm listing.