@mcp-b/webmcp-ts-sdk weekly downloads statistics

@mcp-b/webmcp-ts-sdk

A thin WebMCP adapter over the official MCP TypeScript SDK v2.

BrowserMcpServer composes and exposes the official v2 McpServer. Use this package when you need direct control over the browser adapter. Most applications should use @mcp-b/global.

Installation

pnpm add @mcp-b/webmcp-ts-sdk @mcp-b/transports

Example

import { TabServerTransport } from '@mcp-b/transports';
import { BrowserMcpServer } from '@mcp-b/webmcp-ts-sdk';

const server = new BrowserMcpServer({ name: 'catalog-app', version: '1.0.0' });

await server.connect(
  new TabServerTransport({
    allowedOrigins: ['https://shop.example'],
  })
);

const controller = new AbortController();

await server.registerTool(
  {
    name: 'echo',
    description: 'Echo a message',
    inputSchema: {
      type: 'object',
      properties: { message: { type: 'string' } },
      required: ['message'],
    },
    async execute({ message }) {
      return { content: [{ type: 'text', text: `Echo: ${String(message)}` }] };
    },
  },
  { signal: controller.signal }
);

controller.abort();

An AbortSignal owns each WebMCP tool registration. Aborting it removes the local MCP registration and its native mirror.

What the adapter owns

• WebMCP registerTool(), getTools(), ontoolchange, ontoolactivated, ontoolcancel, and descriptor-based executeTool()
• Native document.modelContext registration mirroring and tool reconciliation
• MCP-B registerPrompt(), registerResource(), and listTools() extensions
• MCP transport lifecycle through connect() and close()

The official McpServer owns MCP registration, validation, and protocol behavior. Access it through server.mcpServer for official SDK APIs. Register multi-round tools directly on server.mcpServer; WebMCP descriptor callbacks are single-round when exposed over MCP.

Prompt and resource discovery also belongs to MCP. Use a connected MCP client instead of adapter-side list, read, or get methods.

Native integration

The constructor uses document.modelContext, installing the bundled @mcp-b/webmcp-polyfill (about 28 KB minified) when needed, and delegates browser discovery, execution, and access checks to that context. Without a WebMCP context (no document, or an insecure page), the server serves MCP only. The document property keeps exposing the underlying context; @mcp-b/global installs the extended API and connects its default transport.

To select a context explicitly, pass it as native, then reconcile its current tools:

const native = document.modelContext;
if (!native) throw new Error('Install a WebMCP runtime first');
const server = new BrowserMcpServer({ name: 'catalog-app', version: '1.0.0' }, { native });

await server.syncNativeTools();

syncNativeTools() resolves after reconciliation, and later native toolchange events reconcile again. The package reference covers frame scope, native result conversion, lifecycle events, and the MCP-only mode.

Schema boundary

BrowserMcpServer accepts JSON Schema and Standard JSON Schema input metadata. The official MCP server validates input and outputSchema on MCP client calls only; direct executeTool() calls and native mirrors invoke the browser callback without that validation, so validate in the callback when both paths can call a tool. The @mcp-b/react-webmcp hook already does this.

MCP requires an object-root tool input schema. An array-root WebMCP tool remains available through WebMCP but is omitted from MCP discovery. Direct registrations on server.mcpServer use the official SDK's schema APIs; Zod 4.2 or newer is supported, and Zod 3 is unsupported. See the package reference for the contracts and schemas and structured output for examples.

Exports

• BrowserMcpServer, BrowserMcpServerOptions, isBrowserMcpServer
• PromptDescriptor, ResourceDescriptor, RegistrationHandle
• ModelContext, ModelContextWithExtensions, RegisteredTool, ToolDescriptor, ToolDescriptorFromSchema, ToolListItem, InputSchema, and the other MCP-B descriptor and inference types
• CallToolResult, ContentBlock, TextContent, JsonObject, JsonValue, re-exported from @modelcontextprotocol/server
• WebMCP, the upstream namespace re-exported through @mcp-b/webmcp-polyfill, which also brings the polyfill's SubmitEvent and ModelContext declarations into scope
• @mcp-b/webmcp-ts-sdk/schema: normalizeInputSchema(), normalizeToolResponse(), isMcpStandardSchema(), ToolInputSchema, NormalizedInputSchema

Import MCP clients, servers, schemas, transports, and validators from the official @modelcontextprotocol/* packages.

Related documentation

• Package reference
• MCP TypeScript SDK v2
• WebMCP specification
• Chrome Model Context Tool Inspector

License

MIT. See LICENSE.