@mcp-b/global 1.0.15 → 1.1.1

package/README.md

@@ -103,6 +103,263 @@ window.navigator.modelContext.provideContext({
 });
 ```
 
+## ⚙️ Configuration
+
+The polyfill exposes `initializeWebModelContext(options?: WebModelContextInitOptions)` to let you control transport behaviour. When you import `@mcp-b/global` as a module it auto-initializes by default, but you can customise or defer initialization:
+
+- **Disable auto init**: Set `window.__webModelContextOptions = { autoInitialize: false }` before importing, then call `initializeWebModelContext()` manually.
+- **Configure via script tag**: When using the IIFE build, pass options through data attributes:
+  ```html
+  <script
+    src="https://unpkg.com/@mcp-b/global@latest/dist/index.iife.js"
+    data-webmcp-auto-initialize="false"
+    data-webmcp-allowed-origins="https://example.com,https://docs.example.com"
+  ></script>
+  <!-- Later in the page -->
+  <script>
+    window.navigator.modelContext.provideContext({ tools: [] });
+  </script>
+  ```
+  Use `data-webmcp-options='{"transport":{"tabServer":{"allowedOrigins":["https://example.com"]}}}'` for advanced JSON configuration.
+- **Supported data attributes**
+  - `data-webmcp-auto-initialize="false"`: Skip automatic setup.
+  - `data-webmcp-allowed-origins="https://a.com,https://b.com"`: Override `tabServer.allowedOrigins`.
+  - `data-webmcp-channel-id="custom-channel"`: Set the Tab transport channel.
+
+### Dual-Server Mode (Tab + Iframe)
+
+By default, the global package runs **two MCP servers** that share the same tool registry:
+
+1. **Tab Server** (`TabServerTransport`) - For same-window communication
+2. **Iframe Server** (`IframeChildTransport`) - Auto-enabled when running in an iframe (when `window.parent !== window`)
+
+Both servers expose the same tools (Bucket A + Bucket B), allowing your tools to be accessed from:
+- Same-window clients (e.g., browser extension content scripts)
+- Parent page (when running in an iframe)
+
+**Example: Running in an Iframe**
+
+When your app runs in an iframe, both servers are automatically enabled:
+
+```ts
+// In iframe: Auto-initializes with both servers
+import '@mcp-b/global';
+
+// Register tools - they're automatically available to:
+// 1. Same-window clients (via TabServerTransport)
+// 2. Parent page (via IframeChildTransport)
+window.navigator.modelContext.provideContext({
+  tools: [
+    {
+      name: "iframe-action",
+      description: "Action from iframe",
+      inputSchema: { type: "object", properties: {} },
+      async execute() {
+        return {
+          content: [{ type: "text", text: "Hello from iframe!" }]
+        };
+      }
+    }
+  ]
+});
+```
+
+**Configure Iframe Server**
+
+You can customize or disable the iframe server:
+
+```ts
+import { initializeWebModelContext } from '@mcp-b/global';
+
+// Customize iframe server
+initializeWebModelContext({
+  transport: {
+    iframeServer: {
+      allowedOrigins: ['https://parent-app.com'], // Only allow specific parent
+      channelId: 'custom-iframe-channel',
+    },
+  },
+});
+
+// Disable iframe server (only Tab server runs)
+initializeWebModelContext({
+  transport: {
+    iframeServer: false, // Disable iframe server
+  },
+});
+
+// Disable tab server (only Iframe server runs)
+initializeWebModelContext({
+  transport: {
+    tabServer: false, // Disable tab server
+    iframeServer: {
+      allowedOrigins: ['https://parent-app.com'],
+    },
+  },
+});
+```
+
+**Custom Transport Factory**
+
+Provide `transport.create` to supply any MCP `Transport` implementation instead of the built-in dual-server mode:
+
+```ts
+import { initializeWebModelContext } from '@mcp-b/global';
+import { CustomTransport } from './my-transport';
+
+initializeWebModelContext({
+  transport: {
+    create: () => new CustomTransport(),
+  },
+});
+```
+
+## 🔄 Native Chromium API Support
+
+This package **automatically detects and integrates** with Chromium's native Web Model Context API when available. No configuration needed - it just works!
+
+### Automatic Detection & Integration
+
+When you call `initializeWebModelContext()` (or when auto-initialization runs):
+
+1. **Native API detected** (both `navigator.modelContext` and `navigator.modelContextTesting` present):
+   - Uses native Chromium implementation
+   - Creates MCP bridge and syncs tools automatically
+   - Registers callback to listen for native tool changes
+   - MCP clients stay synchronized with native tool registry
+
+2. **No native API detected**:
+   - Installs full polyfill implementation
+   - Provides identical API surface
+
+**Zero configuration required** - the package automatically adapts to your environment!
+
+### Native API Features
+
+When the native Chromium API is available, you get:
+
+- ✅ **Automatic tool synchronization** - Tools registered in native API are synced to MCP bridge via `registerToolsChangedCallback()`
+- ✅ **Iframe tool collection** - Native API automatically collects tools from embedded iframes (no manual transport setup needed)
+- ✅ **MCP compatibility** - Your MCP clients (extensions, apps) continue to work seamlessly
+- ✅ **Tool change notifications** - MCP servers receive `tools/list_changed` notifications automatically
+- ✅ **Consistent API** - Same code works with both native and polyfill implementations
+
+### How Tool Synchronization Works
+
+The polyfill automatically registers a callback with the native API:
+
+```typescript
+// Happens automatically when native API is detected
+navigator.modelContextTesting.registerToolsChangedCallback(() => {
+  // Syncs native tools → MCP bridge
+  // MCP clients receive tools/list_changed notification
+});
+```
+
+This callback fires when:
+- `navigator.modelContext.registerTool()` is called
+- `navigator.modelContext.unregisterTool()` is called
+- `navigator.modelContext.provideContext()` is called
+- `navigator.modelContext.clearContext()` is called
+- Tools are added from embedded iframes (native feature)
+
+### Enabling Native API in Chromium
+
+```bash
+# Method 1: Launch with flag
+chromium --enable-experimental-web-platform-features
+
+# Method 2: Enable in chrome://flags
+# Search for: "Experimental Web Platform Features"
+# Set to: Enabled
+# Restart browser
+```
+
+### Example: Using Native API
+
+```typescript
+import '@mcp-b/global';
+
+// If native API is present, this delegates to navigator.modelContext:
+window.navigator.modelContext.registerTool({
+  name: 'myTool',
+  description: 'My tool',
+  inputSchema: { type: 'object', properties: {} },
+  async execute() {
+    return { content: [{ type: 'text', text: 'Hello!' }] };
+  }
+});
+
+// Behind the scenes:
+// 1. Tool registered in native Chromium registry
+// 2. Callback fires (registerToolsChangedCallback)
+// 3. Tool synced to MCP bridge
+// 4. MCP clients notified (tools/list_changed)
+```
+
+### Iframe Tool Collection (Native Only)
+
+When the native API is active, tools from embedded iframes are **automatically collected**:
+
+```html
+<!-- parent.html -->
+<script type="module">
+  import '@mcp-b/global';
+
+  // Native API will collect tools from this page AND all iframes
+  navigator.modelContext.registerTool({
+    name: 'parent-tool',
+    description: 'Tool from parent page',
+    inputSchema: { type: 'object', properties: {} },
+    async execute() {
+      return { content: [{ type: 'text', text: 'Parent tool' }] };
+    }
+  });
+</script>
+
+<iframe src="child.html"></iframe>
+```
+
+```html
+<!-- child.html -->
+<script type="module">
+  import '@mcp-b/global';
+
+  // This tool is automatically visible in parent's registry (native feature)
+  navigator.modelContext.registerTool({
+    name: 'child-tool',
+    description: 'Tool from iframe',
+    inputSchema: { type: 'object', properties: {} },
+    async execute() {
+      return { content: [{ type: 'text', text: 'Child tool' }] };
+    }
+  });
+</script>
+```
+
+With native API, `navigator.modelContextTesting.listTools()` in the parent will show **both** tools! The MCP bridge stays in sync automatically.
+
+### Detection in Console
+
+When you initialize the package, check the console logs:
+
+```
+✅ [Web Model Context] Native Chromium API detected
+   Using native implementation with MCP bridge synchronization
+   Native API will automatically collect tools from embedded iframes
+✅ [Web Model Context] MCP bridge synced with native API
+   MCP clients will receive automatic tool updates from native registry
+```
+
+Or if polyfill is used:
+
+```
+[Web Model Context] Native API not detected, installing polyfill
+✅ [Web Model Context] window.navigator.modelContext initialized successfully
+[Model Context Testing] Installing polyfill
+✅ [Model Context Testing] Polyfill installed at window.navigator.modelContextTesting
+```
+
 ## 📖 API Reference
 
 ### Two-Bucket Tool Management System
@@ -577,9 +834,238 @@ if (window.__mcpBridge) {
 }
 ```
 
+## 🧪 Testing API (`navigator.modelContextTesting`)
+
+This package provides a **Model Context Testing API** at `window.navigator.modelContextTesting` for debugging and testing your tools during development.
+
+### Native Support in Chromium
+
+**IMPORTANT**: The `modelContextTesting` API is available natively in Chromium-based browsers when the experimental feature flag is enabled. This polyfill will detect and use the native implementation when available.
+
+#### How to Enable Native API in Chromium:
+
+**Option 1: Chrome Flags**
+1. Navigate to `chrome://flags`
+2. Search for "Experimental Web Platform Features"
+3. Enable the flag
+4. Restart your browser
+
+**Option 2: Command Line**
+```bash
+# Launch Chrome/Edge with experimental features
+chrome --enable-experimental-web-platform-features
+```
+
+**Detection**: When the native API is detected, you'll see this console message:
+```
+✅ [Model Context Testing] Native implementation detected (Chromium experimental feature)
+   Using native window.navigator.modelContextTesting from browser
+```
+
+### Polyfill Fallback
+
+If the native API is not available, this package automatically provides a polyfill implementation with the same interface:
+
+```
+[Model Context Testing] Native implementation not found, installing polyfill
+   💡 To use the native implementation in Chromium:
+      - Navigate to chrome://flags
+      - Enable "Experimental Web Platform Features"
+      - Or launch with: --enable-experimental-web-platform-features
+✅ [Model Context Testing] Polyfill installed at window.navigator.modelContextTesting
+```
+
+### API Reference
+
+#### `getToolCalls(): Array<ToolCall>`
+
+Get a history of all tool calls made during the session.
+
+```javascript
+// Register and call some tools
+window.navigator.modelContext.provideContext({
+  tools: [{
+    name: "greet",
+    description: "Greet a user",
+    inputSchema: {
+      type: "object",
+      properties: { name: { type: "string" } },
+      required: ["name"]
+    },
+    async execute({ name }) {
+      return { content: [{ type: "text", text: `Hello, ${name}!` }] };
+    }
+  }]
+});
+
+// Simulate a tool call
+// (In practice, this would come from an AI agent)
+
+// Later, inspect the tool call history
+const calls = window.navigator.modelContextTesting.getToolCalls();
+console.log(calls);
+// [
+//   {
+//     toolName: "greet",
+//     arguments: { name: "Alice" },
+//     timestamp: 1699123456789
+//   }
+// ]
+```
+
+#### `clearToolCalls(): void`
+
+Clear the tool call history.
+
+```javascript
+window.navigator.modelContextTesting.clearToolCalls();
+console.log(window.navigator.modelContextTesting.getToolCalls()); // []
+```
+
+#### `setMockToolResponse(toolName: string, response: ToolResponse): void`
+
+Set a mock response for a specific tool. When set, the tool's `execute()` function will be bypassed and the mock response will be returned instead.
+
+```javascript
+// Mock the "greet" tool to always return a specific response
+window.navigator.modelContextTesting.setMockToolResponse("greet", {
+  content: [{
+    type: "text",
+    text: "Mocked greeting!"
+  }]
+});
+
+// Now when the tool is called, it returns the mock response
+// (The execute function is never called)
+```
+
+#### `clearMockToolResponse(toolName: string): void`
+
+Remove the mock response for a specific tool.
+
+```javascript
+window.navigator.modelContextTesting.clearMockToolResponse("greet");
+// Tool will now use its actual execute function
+```
+
+#### `clearAllMockToolResponses(): void`
+
+Remove all mock tool responses.
+
+```javascript
+window.navigator.modelContextTesting.clearAllMockToolResponses();
+```
+
+#### `getRegisteredTools(): Array<ToolDescriptor>`
+
+Get the list of all currently registered tools (same as `modelContext.listTools()`).
+
+```javascript
+const tools = window.navigator.modelContextTesting.getRegisteredTools();
+console.log(tools.map(t => t.name)); // ["greet", "add-todo", ...]
+```
+
+#### `reset(): void`
+
+Reset the entire testing state (clears tool call history and all mock responses).
+
+```javascript
+window.navigator.modelContextTesting.reset();
+```
+
+### Testing Workflow Example
+
+Here's a complete example of using the testing API:
+
+```javascript
+// 1. Register your tools
+window.navigator.modelContext.provideContext({
+  tools: [
+    {
+      name: "add-todo",
+      description: "Add a todo item",
+      inputSchema: {
+        type: "object",
+        properties: { text: { type: "string" } },
+        required: ["text"]
+      },
+      async execute({ text }) {
+        // This would normally add to your app state
+        return { content: [{ type: "text", text: `Added: ${text}` }] };
+      }
+    }
+  ]
+});
+
+// 2. Set up mocks for testing
+window.navigator.modelContextTesting.setMockToolResponse("add-todo", {
+  content: [{ type: "text", text: "Mock: Todo added successfully" }]
+});
+
+// 3. Simulate tool calls (or let AI agent call them)
+// The tool will return the mock response instead of executing
+
+// 4. Inspect tool call history
+const calls = window.navigator.modelContextTesting.getToolCalls();
+console.log(`${calls.length} tool calls made`);
+calls.forEach(call => {
+  console.log(`- ${call.toolName}`, call.arguments);
+});
+
+// 5. Clean up after testing
+window.navigator.modelContextTesting.reset();
+```
+
+### Integration Testing Example
+
+Perfect for automated testing with frameworks like Jest, Vitest, or Playwright:
+
+```javascript
+// test/model-context.test.js
+import { test, expect } from 'vitest';
+
+test('todo tool creates correct response', async () => {
+  // Arrange
+  const mockResponse = {
+    content: [{ type: "text", text: "Test todo added" }]
+  };
+
+  window.navigator.modelContextTesting.setMockToolResponse(
+    "add-todo",
+    mockResponse
+  );
+
+  // Act
+  // Trigger your AI agent or directly call the tool via MCP
+  // ...
+
+  // Assert
+  const calls = window.navigator.modelContextTesting.getToolCalls();
+  expect(calls).toHaveLength(1);
+  expect(calls[0].toolName).toBe("add-todo");
+  expect(calls[0].arguments).toEqual({ text: "Test item" });
+
+  // Cleanup
+  window.navigator.modelContextTesting.reset();
+});
+```
+
+### Browser Compatibility
+
+| Browser | Native Support | Polyfill |
+|---------|---------------|----------|
+| Chrome/Edge (with flag) | ✅ Yes | N/A |
+| Chrome/Edge (default) | ❌ No | ✅ Yes |
+| Firefox | ❌ No | ✅ Yes |
+| Safari | ❌ No | ✅ Yes |
+| Other browsers | ❌ No | ✅ Yes |
+
+The polyfill automatically detects and defers to the native implementation when available, ensuring forward compatibility as browsers adopt this standard.
+
 ## 📦 What's Included
 
 - **Web Model Context API** - Standard `window.navigator.modelContext` interface
+- **Model Context Testing API** - `window.navigator.modelContextTesting` for debugging and testing (with native Chromium support detection)
 - **Dynamic Tool Registration** - `registerTool()` with `unregister()` function
 - **MCP Bridge** - Automatic bridging to Model Context Protocol
 - **Tab Transport** - Communication layer for browser contexts