@mcp-b/global 3.0.0 → 4.0.0-beta.20260702175639

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +95 -64
  2. package/dist/index.d.ts.map +1 -1
  3. package/dist/index.iife.js +13 -6
  4. package/dist/index.js +4 -3
  5. package/dist/index.js.map +1 -1
  6. package/package.json +10 -9
package/README.md CHANGED
@@ -6,22 +6,22 @@
6
6
  [![npm downloads](https://img.shields.io/npm/dm/@mcp-b/global?style=flat-square)](https://www.npmjs.com/package/@mcp-b/global)
7
7
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
8
8
  [![Bundle Size](https://img.shields.io/badge/IIFE-285KB-blue?style=flat-square)](https://bundlephobia.com/package/@mcp-b/global)
9
- [![W3C](https://img.shields.io/badge/W3C-Web_Model_Context-005A9C?style=flat-square)](https://github.com/nicolo-ribaudo/model-context-protocol-api)
9
+ [![W3C](https://img.shields.io/badge/W3C-Web_Model_Context-005A9C?style=flat-square)](https://webmachinelearning.github.io/webmcp/)
10
10
 
11
- **[Full Documentation](https://docs.mcp-b.ai/packages/global)** | **[Quick Start](https://docs.mcp-b.ai/quickstart)** | **[Tool Registration](https://docs.mcp-b.ai/concepts/tool-registration)**
11
+ **[Reference](https://docs.mcp-b.ai/packages/global/reference)** | **[First Tool Tutorial](https://docs.mcp-b.ai/tutorials/first-tool)** | **[Add Tools to an App](https://docs.mcp-b.ai/how-to/add-tools-to-an-existing-app)**
12
12
 
13
- **@mcp-b/global** implements the [W3C Web Model Context API](https://github.com/nicolo-ribaudo/model-context-protocol-api) (`navigator.modelContext`) specification, allowing AI agents like Claude, ChatGPT, Gemini, Cursor, and Copilot to discover and call functions on your website.
13
+ **@mcp-b/global** implements the [W3C Web Model Context API](https://webmachinelearning.github.io/webmcp/) (`document.modelContext`) specification, allowing AI agents like Claude, ChatGPT, Gemini, Cursor, and Copilot to discover and call functions on your website.
14
14
 
15
15
  ## Why Use @mcp-b/global?
16
16
 
17
- | Feature | Benefit |
18
- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
19
- | **W3C Standard** | Implements the emerging Web Model Context API specification |
20
- | **Drop-in IIFE** | Add AI capabilities with a single `<script>` tag - no build step |
21
- | **Native Chromium Support** | Auto-detects and uses native browser implementation when available |
22
- | **Dual Transport** | Works with both same-window clients AND parent pages (iframe support) |
23
- | **Spec-Aware Compatibility** | Tracks the current WebMCP draft (`document.modelContext`, `registerTool(tool, { signal })`, `getTools()`, and `executeTool(...)`). Deprecated `unregisterTool(name)` and the `{ unregister }` return handle remain for existing MCP-B integrations and will be removed in the next major version. |
24
- | **Works with Any AI** | Claude, ChatGPT, Gemini, Cursor, Copilot, and any MCP client |
17
+ | Feature | Benefit |
18
+ | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
19
+ | **W3C Standard** | Implements the emerging Web Model Context API specification |
20
+ | **Drop-in IIFE** | Add AI capabilities with a single `<script>` tag - no build step |
21
+ | **Native Chromium Support** | Auto-detects and uses native browser implementation when available |
22
+ | **Dual Transport** | Works with both same-window clients AND parent pages (iframe support) |
23
+ | **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. |
24
+ | **Works with Any AI** | Claude, ChatGPT, Gemini, Cursor, Copilot, and any MCP client |
25
25
 
26
26
  ## Package Selection
27
27
 
@@ -43,7 +43,7 @@
43
43
  <h1>My AI-Powered App</h1>
44
44
 
45
45
  <script>
46
- navigator.modelContext.registerTool({
46
+ document.modelContext.registerTool({
47
47
  name: 'get-page-title',
48
48
  description: 'Get the current page title',
49
49
  inputSchema: { type: 'object', properties: {} },
@@ -59,7 +59,7 @@
59
59
  ```
60
60
 
61
61
  - **Self-contained** - All dependencies bundled (285KB minified)
62
- - **Auto-initializes** - `navigator.modelContext` ready immediately
62
+ - **Auto-initializes** - `document.modelContext` ready immediately
63
63
  - **No build step** - Just drop it in your HTML
64
64
 
65
65
  ### Via ES Module
@@ -67,7 +67,7 @@
67
67
  ```html
68
68
  <script type="module">
69
69
  import '@mcp-b/global';
70
- navigator.modelContext.registerTool({
70
+ document.modelContext.registerTool({
71
71
  /* your tool */
72
72
  });
73
73
  </script>
@@ -84,7 +84,7 @@ npm install @mcp-b/global
84
84
  ```javascript
85
85
  import '@mcp-b/global';
86
86
 
87
- navigator.modelContext.registerTool({
87
+ document.modelContext.registerTool({
88
88
  /* your tool */
89
89
  });
90
90
  ```
@@ -95,7 +95,7 @@ navigator.modelContext.registerTool({
95
95
 
96
96
  #### `initializeWebModelContext(options?)`
97
97
 
98
- Initializes the global adapter. Replaces `navigator.modelContext` with a `BrowserMcpServer` instance that bridges WebMCP tools to the MCP protocol layer.
98
+ Initializes the global adapter. Replaces `document.modelContext` with a `BrowserMcpServer` instance that bridges WebMCP tools to the MCP protocol layer.
99
99
 
100
100
  ```typescript
101
101
  import { initializeWebModelContext } from '@mcp-b/global';
@@ -112,12 +112,12 @@ initializeWebModelContext({
112
112
 
113
113
  - Only operates in browser environments
114
114
  - Idempotent - calling multiple times is a no-op after first initialization
115
- - Preserves native `navigator.modelContext` by default (configurable)
115
+ - Preserves native `document.modelContext` by default (configurable)
116
116
  - Auto-called on import unless `window.__webModelContextOptions.autoInitialize` is `false`
117
117
 
118
118
  #### `cleanupWebModelContext()`
119
119
 
120
- Tears down the adapter and restores `navigator.modelContext` to its original state. Allows re-initialization.
120
+ Tears down the adapter and restores `document.modelContext` to its original state. Allows re-initialization.
121
121
 
122
122
  ```typescript
123
123
  import { cleanupWebModelContext, initializeWebModelContext } from '@mcp-b/global';
@@ -130,9 +130,9 @@ cleanupWebModelContext();
130
130
  initializeWebModelContext();
131
131
  ```
132
132
 
133
- ### `navigator.modelContext` Methods
133
+ ### `document.modelContext` Methods
134
134
 
135
- After initialization, `navigator.modelContext` exposes these methods:
135
+ After initialization, `document.modelContext` exposes these methods:
136
136
 
137
137
  #### `registerTool(tool, options?)`
138
138
 
@@ -140,7 +140,7 @@ Registers a single tool. The tool name must be unique, otherwise throws if a too
140
140
 
141
141
  ```typescript
142
142
  const ac = new AbortController();
143
- navigator.modelContext.registerTool(
143
+ document.modelContext.registerTool(
144
144
  {
145
145
  name: 'add-to-cart',
146
146
  description: 'Add a product to the shopping cart',
@@ -166,37 +166,46 @@ navigator.modelContext.registerTool(
166
166
  ac.abort();
167
167
  ```
168
168
 
169
- For backwards compatibility, `@mcp-b/global` also returns a deprecated `{ unregister }` handle so existing MCP-B integrations do not break, even though current Chromium and the WebMCP spec return `undefined`. The handle will be removed in the next major version.
169
+ `registerTool` resolves `undefined`, matching current Chromium and the WebMCP spec. Use `AbortSignal` cleanup for dynamic tools.
170
170
 
171
171
  #### `unregisterTool(nameOrTool)` (deprecated)
172
172
 
173
173
  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.
174
174
 
175
175
  ```typescript
176
- navigator.modelContext.unregisterTool('add-to-cart');
176
+ document.modelContext.unregisterTool('add-to-cart');
177
177
  ```
178
178
 
179
- #### `listTools()`
179
+ #### `getTools()`
180
180
 
181
- Returns metadata for all registered tools (without execute functions).
181
+ Returns WebMCP tool descriptors for all registered tools.
182
182
 
183
183
  ```typescript
184
- const tools = navigator.modelContext.listTools();
185
- // [{ name: 'search-products', description: '...', inputSchema: {...} }, ...]
184
+ const tools = await document.modelContext.getTools();
185
+ // [{ name: 'search-products', inputSchema: '{"type":"object",...}', ... }, ...]
186
186
  ```
187
187
 
188
- #### `callTool(params)`
188
+ #### `executeTool(tool, inputArgsJson)`
189
189
 
190
- Executes a registered tool by name.
190
+ Executes a tool descriptor returned from `getTools()`.
191
191
 
192
192
  ```typescript
193
- const result = await navigator.modelContext.callTool({
194
- name: 'search-products',
195
- arguments: { query: 'laptop', limit: 5 },
196
- });
193
+ const tools = await document.modelContext.getTools();
194
+ const searchTool = tools.find((tool) => tool.name === 'search-products');
195
+ if (!searchTool) throw new Error('search-products is not available');
196
+
197
+ const resultJson = await document.modelContext.executeTool(
198
+ searchTool,
199
+ JSON.stringify({ query: 'laptop', limit: 5 })
200
+ );
201
+ const result = resultJson === null ? null : JSON.parse(resultJson);
197
202
  // { content: [{ type: 'text', text: '...' }] }
198
203
  ```
199
204
 
205
+ #### `listTools()` and `callTool(params)` (deprecated)
206
+
207
+ These MCP-B compatibility helpers remain available for older integrations. Prefer `getTools()` and `executeTool(tool, inputArgsJson)` for in-page WebMCP consumers.
208
+
200
209
  ### Tool Descriptor
201
210
 
202
211
  | Property | Type | Required | Description |
@@ -325,7 +334,7 @@ const result = await navigator.modelContextTesting?.executeTool(
325
334
 
326
335
  ```javascript
327
336
  if ('modelContext' in navigator) {
328
- navigator.modelContext.registerTool({
337
+ document.modelContext.registerTool({
329
338
  /* your tool */
330
339
  });
331
340
  }
@@ -338,7 +347,7 @@ if ('modelContext' in navigator) {
338
347
  ```typescript
339
348
  import '@mcp-b/global';
340
349
 
341
- navigator.modelContext.registerTool({
350
+ document.modelContext.registerTool({
342
351
  name: 'search-products',
343
352
  description: 'Search products by keyword, category, or price range',
344
353
  inputSchema: {
@@ -358,7 +367,7 @@ navigator.modelContext.registerTool({
358
367
  },
359
368
  });
360
369
 
361
- navigator.modelContext.registerTool({
370
+ document.modelContext.registerTool({
362
371
  name: 'add-to-cart',
363
372
  description: 'Add a product to the shopping cart',
364
373
  inputSchema: {
@@ -385,35 +394,57 @@ navigator.modelContext.registerTool({
385
394
  import '@mcp-b/global';
386
395
 
387
396
  // Start with base tools
388
- navigator.modelContext.registerTool({
389
- name: 'get-user',
390
- description: 'Get current user info',
391
- inputSchema: { type: 'object', properties: {} },
392
- async execute() {
393
- return { content: [{ type: 'text', text: JSON.stringify(currentUser) }] };
397
+ const userToolController = new AbortController();
398
+ document.modelContext.registerTool(
399
+ {
400
+ name: 'get-user',
401
+ description: 'Get current user info',
402
+ inputSchema: { type: 'object', properties: {} },
403
+ async execute() {
404
+ return { content: [{ type: 'text', text: JSON.stringify(currentUser) }] };
405
+ },
394
406
  },
395
- });
407
+ { signal: userToolController.signal }
408
+ );
409
+
410
+ let adminToolController: AbortController | undefined;
411
+
412
+ function registerAdminTool() {
413
+ adminToolController?.abort();
414
+ adminToolController = new AbortController();
415
+
416
+ document.modelContext.registerTool(
417
+ {
418
+ name: 'delete-user',
419
+ description: 'Delete a user account (admin only)',
420
+ inputSchema: {
421
+ type: 'object',
422
+ properties: { userId: { type: 'string' } },
423
+ required: ['userId'],
424
+ },
425
+ async execute(args) {
426
+ await fetch(`/api/users/${args.userId}`, { method: 'DELETE' });
427
+ return { content: [{ type: 'text', text: 'User deleted' }] };
428
+ },
429
+ },
430
+ { signal: adminToolController.signal }
431
+ );
432
+ }
433
+
434
+ function unregisterAdminTool() {
435
+ adminToolController?.abort();
436
+ adminToolController = undefined;
437
+ }
396
438
 
397
439
  // Add tools dynamically based on user role
398
440
  if (currentUser.isAdmin) {
399
- navigator.modelContext.registerTool({
400
- name: 'delete-user',
401
- description: 'Delete a user account (admin only)',
402
- inputSchema: {
403
- type: 'object',
404
- properties: { userId: { type: 'string' } },
405
- required: ['userId'],
406
- },
407
- async execute(args) {
408
- await fetch(`/api/users/${args.userId}`, { method: 'DELETE' });
409
- return { content: [{ type: 'text', text: 'User deleted' }] };
410
- },
411
- });
441
+ registerAdminTool();
412
442
  }
413
443
 
414
444
  // Remove tools when permissions change
415
445
  function onLogout() {
416
- navigator.modelContext.unregisterTool('get-user');
446
+ userToolController.abort();
447
+ unregisterAdminTool();
417
448
  }
418
449
  ```
419
450
 
@@ -422,7 +453,7 @@ function onLogout() {
422
453
  ```typescript
423
454
  import '@mcp-b/global';
424
455
 
425
- navigator.modelContext.registerTool({
456
+ document.modelContext.registerTool({
426
457
  name: 'fill-contact-form',
427
458
  description: 'Fill the contact form with provided details',
428
459
  inputSchema: {
@@ -442,7 +473,7 @@ navigator.modelContext.registerTool({
442
473
  },
443
474
  });
444
475
 
445
- navigator.modelContext.registerTool({
476
+ document.modelContext.registerTool({
446
477
  name: 'submit-form',
447
478
  description: 'Submit the contact form',
448
479
  inputSchema: { type: 'object', properties: {} },
@@ -493,15 +524,15 @@ import type {
493
524
 
494
525
  ## Related Packages
495
526
 
496
- - [`@mcp-b/transports`](https://docs.mcp-b.ai/packages/transports) - MCP transport implementations
497
- - [`@mcp-b/react-webmcp`](https://docs.mcp-b.ai/packages/react-webmcp) - React hooks for MCP
498
- - [`@mcp-b/extension-tools`](https://docs.mcp-b.ai/packages/extension-tools) - Chrome Extension API tools
499
- - [`@mcp-b/chrome-devtools-mcp`](https://docs.mcp-b.ai/packages/chrome-devtools-mcp) - Connect desktop AI agents to browser tools
527
+ - [`@mcp-b/transports`](https://docs.mcp-b.ai/packages/transports/reference) - MCP transport implementations
528
+ - [`@mcp-b/react-webmcp`](https://docs.mcp-b.ai/packages/react-webmcp/reference) - React hooks for MCP
529
+ - [`@mcp-b/extension-tools`](https://docs.mcp-b.ai/packages/extension-tools/reference) - Chrome Extension API tools
530
+ - [`@mcp-b/chrome-devtools-mcp`](https://docs.mcp-b.ai/packages/chrome-devtools-mcp/reference) - Connect desktop AI agents to browser tools
500
531
 
501
532
  ## Resources
502
533
 
503
534
  - [WebMCP Documentation](https://docs.mcp-b.ai)
504
- - [Web Model Context API Explainer](https://github.com/nicolo-ribaudo/model-context-protocol-api)
535
+ - [Web Model Context API Explainer](https://webmachinelearning.github.io/webmcp/)
505
536
  - [Model Context Protocol Spec](https://modelcontextprotocol.io/)
506
537
 
507
538
  ## License
package/dist/index.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/global.ts"],"mappings":";;;UAEiB,sBAAA;EACf,SAAA,GAAY,OAAA,CAAQ,yBAAA;EACpB,YAAA,GAAe,OAAA,CAAQ,2BAAA;AAAA;AAAA,KAGb,0BAAA;AAAA,UAEK,0BAAA;EACf,SAAA,GAAY,sBAAA;EACZ,cAAA;EAPe;;;;;;;EAef,0BAAA,GAA6B,0BAAA;EAfN;;;AAGzB;;;EAmBE,kBAAA;AAAA;AAAA,QAGM,MAAA;EAAA,UACI,MAAA;IACR,wBAAA,GAA2B,0BAAA;EAAA;AAAA;;;iBC2Mf,yBAAA,CAA0B,OAAA,GAAU,0BAAA;AAAA,iBA6DpC,sBAAA,CAAA"}
1
+ {"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/global.ts"],"mappings":";;;UAEiB,sBAAA;EACf,SAAA,GAAY,OAAA,CAAQ,yBAAA;EACpB,YAAA,GAAe,OAAA,CAAQ,2BAAA;AAAA;AAAA,KAGb,0BAAA;AAAA,UAEK,0BAAA;EACf,SAAA,GAAY,sBAAA;EACZ,cAAA;EAPe;;;;;;;EAef,0BAAA,GAA6B,0BAAA;EAfN;;;AAGzB;;;EAmBE,kBAAA;AAAA;AAAA,QAGM,MAAA;EAAA,UACI,MAAA;IACR,wBAAA,GAA2B,0BAAA;EAAA;AAAA;;;iBC4Mf,yBAAA,CAA0B,OAAA,GAAU,0BAAA;AAAA,iBA6DpC,sBAAA,CAAA"}