@mcp-b/global 4.0.0 → 5.0.0

package/README.md

@@ -14,14 +14,14 @@
 
 ## Why Use @mcp-b/global?
 
-| Feature                      | Benefit                                                                                                                                                                                                                                                     |
-| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **W3C Standard**             | Implements the emerging WebMCP API specification                                                                                                                                                                                                            |
-| **Drop-in IIFE**             | Add AI capabilities with a single `<script>` 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 })`, `getTools()`, and `executeTool(...)`). Deprecated `unregisterTool(name)` remains for existing MCP-B integrations and will be removed in the next major version. |
-| **Works with Any AI**        | Claude, ChatGPT, Gemini, Cursor, Copilot, and any MCP client                                                                                                                                                                                                |
+| Feature                      | Benefit                                                                                                                                                              |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **W3C Standard**             | Implements the emerging WebMCP API specification                                                                                                                     |
+| **Drop-in IIFE**             | Add AI capabilities with a single `<script>` 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()`) plus Chromium's optional `executeTool(...)` extension. |
+| **Works with Any AI**        | Claude, ChatGPT, Gemini, Cursor, Copilot, and any MCP client                                                                                                         |
 
 ## Package Selection
 
@@ -43,16 +43,18 @@
     <h1>My AI-Powered App</h1>
 
     <script>
-      document.modelContext.registerTool({
-        name: 'get-page-title',
-        description: 'Get the current page title',
-        inputSchema: { type: 'object', properties: {} },
-        async execute() {
-          return {
-            content: [{ type: 'text', text: document.title }],
-          };
-        },
-      });
+      void document.modelContext
+        .registerTool({
+          name: 'get-page-title',
+          description: 'Get the current page title',
+          inputSchema: { type: 'object', properties: {} },
+          async execute() {
+            return {
+              content: [{ type: 'text', text: document.title }],
+            };
+          },
+        })
+        .catch(console.error);
     </script>
   </body>
 </html>
@@ -67,7 +69,7 @@
 ```html
 <script type="module">
   import '@mcp-b/global';
-  document.modelContext.registerTool({
+  await document.modelContext.registerTool({
     /* your tool */
   });
 </script>
@@ -84,7 +86,7 @@ npm install @mcp-b/global
 ```javascript
 import '@mcp-b/global';
 
-document.modelContext.registerTool({
+await document.modelContext.registerTool({
   /* your tool */
 });
 ```
@@ -98,26 +100,34 @@ document.modelContext.registerTool({
 Initializes the global adapter. Replaces `document.modelContext` with a `BrowserMcpServer` instance that bridges WebMCP tools to the MCP protocol layer.
 
 ```typescript
-import { initializeWebModelContext } from '@mcp-b/global';
+window.__webModelContextOptions = { autoInitialize: false };
+
+const { initializeWebModelContext } = await import('@mcp-b/global');
 
 initializeWebModelContext({
   transport: {
     tabServer: { allowedOrigins: ['https://example.com'] },
   },
-  nativeModelContextBehavior: 'preserve',
+});
+
+await document.modelContext.registerTool({
+  /* your tool */
 });
 ```
 
 **Behavior:**
 
 - Only operates in browser environments
-- Idempotent - calling multiple times is a no-op after first initialization
-- Preserves native `document.modelContext` by default (configurable)
+- 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 its original state. Allows re-initialization.
+Tears down the adapter and restores `document.modelContext` to the captured native or polyfilled
+context. Allows re-initialization.
 
 ```typescript
 import { cleanupWebModelContext, initializeWebModelContext } from '@mcp-b/global';
@@ -136,11 +146,13 @@ After initialization, `document.modelContext` exposes these methods:
 
 #### `registerTool(tool, options?)`
 
-Registers a single tool. The tool name must be unique, otherwise throws if a tool with the same name already exists. The recommended unregistration path is `options.signal` (`AbortSignal`):
+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`):
 
 ```typescript
 const ac = new AbortController();
-document.modelContext.registerTool(
+await document.modelContext.registerTool(
   {
     name: 'add-to-cart',
     description: 'Add a product to the shopping cart',
@@ -168,14 +180,6 @@ ac.abort();
 
 `registerTool` resolves `undefined`, matching current Chromium and the WebMCP spec. Use `AbortSignal` cleanup for dynamic tools.
 
-#### `unregisterTool(nameOrTool)` (deprecated)
-
-Removes a tool by name. The April 23, 2026 WebMCP draft removed `unregisterTool` from the spec in favor of `AbortSignal` on `registerTool`. `@mcp-b/global` keeps `unregisterTool` functional for compatibility with older native previews and existing MCP-B integrations, and emits a one-time deprecation warning when called. It will be removed in the next major version.
-
-```typescript
-document.modelContext.unregisterTool('add-to-cart');
-```
-
 #### `getTools()`
 
 Returns WebMCP tool descriptors for all registered tools.
@@ -187,14 +191,27 @@ const tools = await document.modelContext.getTools();
 
 #### `executeTool(tool, inputArgsJson)`
 
-Executes a tool descriptor returned from `getTools()`.
+Chromium exposes an optional descriptor-based execution method. Feature-detect it
+on the canonical document surface.
+
+```bash
+npm install --save-dev @mcp-b/webmcp-types
+```
 
 ```typescript
-const tools = await document.modelContext.getTools();
+import '@mcp-b/global';
+import type { ChromeModelContext } from '@mcp-b/webmcp-types';
+
+const modelContext = document.modelContext as ChromeModelContext;
+if (typeof modelContext.executeTool !== 'function') {
+  throw new Error('Tool execution is unavailable');
+}
+
+const tools = await modelContext.getTools();
 const searchTool = tools.find((tool) => tool.name === 'search-products');
 if (!searchTool) throw new Error('search-products is not available');
 
-const resultJson = await document.modelContext.executeTool(
+const resultJson = await modelContext.executeTool(
   searchTool,
   JSON.stringify({ query: 'laptop', limit: 5 })
 );
@@ -202,24 +219,34 @@ const result = resultJson === null ? null : JSON.parse(resultJson);
 // { content: [{ type: 'text', text: '...' }] }
 ```
 
-#### `listTools()` and `callTool(params)` (deprecated)
+#### `listTools()`
+
+This MCP-B helper exposes MCP metadata. In-page WebMCP consumers should use
+`getTools()` and feature-detect `executeTool(tool, inputArgsJson)`.
+
+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.
 
-These MCP-B compatibility helpers remain available for older integrations. Prefer `getTools()` and `executeTool(tool, inputArgsJson)` for in-page WebMCP consumers.
+### `BrowserMcpServer` Tool Descriptor
 
-### 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, client) => Promise<ToolResponse>` | Yes      | Async function implementing the tool logic                                              |
+| 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<unknown>` | Yes      | Function implementing the tool logic                                                    |
 
 ### Tool Response Format
 
-Tools return a `ToolResponse` object:
+Tools may return an MCP `CallToolResult` object:
 
 ```typescript
 // Success
@@ -242,17 +269,15 @@ Tools return a `ToolResponse` object:
 interface WebModelContextInitOptions {
   transport?: TransportConfiguration;
   autoInitialize?: boolean;
-  nativeModelContextBehavior?: 'preserve' | 'patch';
-  installTestingShim?: boolean | 'always' | 'if-missing';
+  installTestingShim?: boolean;
 }
 ```
 
-| Option                       | Default        | Description                                                                                                                         |
-| ---------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `transport`                  | Auto-detect    | Transport layer configuration (tab server and/or iframe)                                                                            |
-| `autoInitialize`             | `true`         | Whether to auto-initialize on import                                                                                                |
-| `nativeModelContextBehavior` | `'preserve'`   | `'preserve'` keeps native implementation untouched. `'patch'` replaces it with a BrowserMcpServer that mirrors to the native object |
-| `installTestingShim`         | `'if-missing'` | Controls `navigator.modelContextTesting` installation. Only installs when not already present natively                              |
+| Option               | Default     | Description                                                                     |
+| -------------------- | ----------- | ------------------------------------------------------------------------------- |
+| `transport`          | Auto-detect | Transport layer configuration (tab server and/or iframe)                        |
+| `autoInitialize`     | `true`      | Whether to auto-initialize on import                                            |
+| `installTestingShim` | `true`      | Installs `navigator.modelContextTesting` only when no implementation is present |
 
 ### Transport Configuration
 
@@ -260,8 +285,8 @@ The transport is auto-selected based on context:
 
 ```typescript
 interface TransportConfiguration {
-  tabServer?: Partial<TabServerTransportOptions> | false;
-  iframeServer?: Partial<IframeChildTransportOptions> | false;
+  tabServer?: TabServerTransportOptions | false;
+  iframeServer?: IframeChildTransportOptions | false;
 }
 ```
 
@@ -270,21 +295,18 @@ interface TransportConfiguration {
 - Set either to `false` to disable it
 
 ```typescript
-// Restrict to specific origins
-initializeWebModelContext({
-  transport: {
-    tabServer: { allowedOrigins: ['https://myapp.com'] },
-  },
-});
+window.__webModelContextOptions = { autoInitialize: false };
 
-// Disable tab transport (iframe only)
+const { initializeWebModelContext } = await import('@mcp-b/global');
 initializeWebModelContext({
   transport: {
-    tabServer: false,
+    tabServer: { allowedOrigins: ['https://myapp.com'] },
   },
 });
 ```
 
+Inside an iframe, pass `transport: { tabServer: false }` to require the iframe transport.
+
 ### Auto-Initialization
 
 The package auto-initializes on import in browser environments. To customize before initialization:
@@ -310,7 +332,7 @@ To prevent auto-initialization:
 <script src="https://unpkg.com/@mcp-b/global@latest/dist/index.iife.js"></script>
 <script>
   // Initialize manually later
-  MCPB.initializeWebModelContext();
+  WebMCP.initializeWebModelContext();
 </script>
 ```
 
@@ -333,10 +355,12 @@ const result = await navigator.modelContextTesting?.executeTool(
 ## Feature Detection
 
 ```javascript
-if ('modelContext' in navigator) {
-  document.modelContext.registerTool({
-    /* your tool */
-  });
+if ('modelContext' in document) {
+  void document.modelContext
+    .registerTool({
+      /* your tool */
+    })
+    .catch(console.error);
 }
 ```
 
@@ -347,7 +371,7 @@ if ('modelContext' in navigator) {
 ```typescript
 import '@mcp-b/global';
 
-document.modelContext.registerTool({
+await document.modelContext.registerTool({
   name: 'search-products',
   description: 'Search products by keyword, category, or price range',
   inputSchema: {
@@ -367,7 +391,7 @@ document.modelContext.registerTool({
   },
 });
 
-document.modelContext.registerTool({
+await document.modelContext.registerTool({
   name: 'add-to-cart',
   description: 'Add a product to the shopping cart',
   inputSchema: {
@@ -395,7 +419,7 @@ import '@mcp-b/global';
 
 // Start with base tools
 const userToolController = new AbortController();
-document.modelContext.registerTool(
+await document.modelContext.registerTool(
   {
     name: 'get-user',
     description: 'Get current user info',
@@ -409,11 +433,11 @@ document.modelContext.registerTool(
 
 let adminToolController: AbortController | undefined;
 
-function registerAdminTool() {
+async function registerAdminTool() {
   adminToolController?.abort();
   adminToolController = new AbortController();
 
-  document.modelContext.registerTool(
+  await document.modelContext.registerTool(
     {
       name: 'delete-user',
       description: 'Delete a user account (admin only)',
@@ -438,7 +462,7 @@ function unregisterAdminTool() {
 
 // Add tools dynamically based on user role
 if (currentUser.isAdmin) {
-  registerAdminTool();
+  await registerAdminTool();
 }
 
 // Remove tools when permissions change
@@ -453,7 +477,7 @@ function onLogout() {
 ```typescript
 import '@mcp-b/global';
 
-document.modelContext.registerTool({
+await document.modelContext.registerTool({
   name: 'fill-contact-form',
   description: 'Fill the contact form with provided details',
   inputSchema: {
@@ -473,7 +497,7 @@ document.modelContext.registerTool({
   },
 });
 
-document.modelContext.registerTool({
+await document.modelContext.registerTool({
   name: 'submit-form',
   description: 'Submit the contact form',
   inputSchema: { type: 'object', properties: {} },
@@ -493,30 +517,22 @@ document.modelContext.registerTool({
 | Firefox                 | No             | Yes      |
 | Safari                  | No             | Yes      |
 
-## Zod Version Compatibility
+## Schema Compatibility
 
-This package supports **Zod `^3.25 || ^4.0`** where Zod is used by higher-level helpers. Plain JSON Schema is also supported.
+The browser API accepts plain JSON Schema and does not require Zod. Direct MCP SDK v2
+registrations accept Standard Schema implementations that emit JSON Schema, including Zod 4.2 or
+newer. Zod 3 is unsupported.
 
-## Type Exports
+## Type exports
 
-All types are re-exported for TypeScript consumers:
+This package exports its initialization options:
 
 ```typescript
-import type {
-  CallToolResult,
-  InputSchema,
-  ModelContext,
-  ModelContextCore,
-  NativeModelContextBehavior,
-  ToolAnnotations,
-  ToolDescriptor,
-  ToolListItem,
-  ToolResponse,
-  TransportConfiguration,
-  WebModelContextInitOptions,
-} from '@mcp-b/global';
+import type { TransportConfiguration, WebModelContextInitOptions } from '@mcp-b/global';
 ```
 
+Import browser contract types from `@mcp-b/webmcp-types`.
+
 ## Tool Routing Contract
 
 - MCP `tools/list`, `tools/call`, and tool list update notifications are sourced from the `BrowserMcpServer` registry.
@@ -526,7 +542,6 @@ import type {
 
 - [`@mcp-b/transports`](https://docs.mcp-b.ai/packages/transports/reference) - MCP transport implementations
 - [`@mcp-b/react-webmcp`](https://docs.mcp-b.ai/packages/react-webmcp/reference) - React hooks for MCP
-- [`@mcp-b/extension-tools`](https://docs.mcp-b.ai/packages/extension-tools/reference) - Chrome Extension API tools
 - [`chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp) - Upstream Chrome DevTools MCP server
 
 ## Resources

package/dist/index.d.ts

@@ -1,39 +1,38 @@
+/// <reference types="@mcp-b/webmcp-types" preserve="true" />
 import { IframeChildTransportOptions, TabServerTransportOptions } from "@mcp-b/transports";
 
 //#region src/types.d.ts
 interface TransportConfiguration {
-  tabServer?: Partial<TabServerTransportOptions> | false;
-  iframeServer?: Partial<IframeChildTransportOptions> | false;
+  /**
+   * Configuring a transport means stating its origins: `allowedOrigins` is required
+   * here, so a wildcard is only ever reached by omitting the transport entirely.
+   */
+  tabServer?: TabServerTransportOptions | false;
+  iframeServer?: IframeChildTransportOptions | false;
 }
-type NativeModelContextBehavior = 'preserve' | 'patch';
 interface WebModelContextInitOptions {
   transport?: TransportConfiguration;
   autoInitialize?: boolean;
-  /**
-   * Behavior when navigator.modelContext already exists.
-   * - 'preserve' (default): wrap native with BrowserMcpServer, mirroring
-   *   core operations to the native object while extending with prompts,
-   *   resources, and other MCP capabilities.
-   * - 'patch': same wrapping behavior (kept for backward compatibility).
-   */
-  nativeModelContextBehavior?: NativeModelContextBehavior;
   /**
    * Forwarded to @mcp-b/webmcp-polyfill when polyfill installation is needed.
-   * - true or 'if-missing' (default): install modelContextTesting only when missing.
-   * - 'always': replace existing modelContextTesting.
-   * - false: do not install modelContextTesting.
+   * Existing modelContextTesting implementations are never replaced.
+   *
+   * Deliberately inverts the polyfill's own default (false): this entry point is the
+   * batteries-included one, and the e2e suites rely on the shim being present.
+   * @default true
    */
-  installTestingShim?: boolean | 'always' | 'if-missing';
+  installTestingShim?: boolean;
 }
 declare global {
   interface Window {
     __webModelContextOptions?: WebModelContextInitOptions;
   }
-} //# sourceMappingURL=types.d.ts.map
+}
 //#endregion
 //#region src/global.d.ts
+/** Installs the global bridge on `document.modelContext`. */
 declare function initializeWebModelContext(options?: WebModelContextInitOptions): void;
 declare function cleanupWebModelContext(): void;
 //#endregion
-export { type NativeModelContextBehavior, type TransportConfiguration, type WebModelContextInitOptions, cleanupWebModelContext, initializeWebModelContext };
+export { type TransportConfiguration, type WebModelContextInitOptions, cleanupWebModelContext, initializeWebModelContext };
 //# sourceMappingURL=index.d.ts.map