@mcp-b/global 1.0.15 → 1.1.0

package/README.md

@@ -103,6 +103,117 @@ 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(),
+  },
+});
+```
+
 ## 📖 API Reference
 
 ### Two-Bucket Tool Management System

package/dist/index.d.ts

@@ -1,17 +1,9 @@
-import { CallToolResult, Server, ToolAnnotations } from "@mcp-b/webmcp-ts-sdk";
+import { IframeChildTransportOptions, TabServerTransportOptions } from "@mcp-b/transports";
+import { CallToolResult, Server, ToolAnnotations, Transport } from "@mcp-b/webmcp-ts-sdk";
 import { z } from "zod";
 
-//#region src/global.d.ts
-/**
- * Initialize the Web Model Context API (window.navigator.modelContext)
- */
-declare function initializeWebModelContext(): void;
-/**
- * Cleanup function (for testing/development)
- */
-declare function cleanupWebModelContext(): void;
-//#endregion
 //#region src/types.d.ts
+
 /**
  * JSON Schema definition for tool input parameters
  */
@@ -35,6 +27,40 @@ type ZodSchemaObject = Record<string, z.ZodTypeAny>;
  * This is compatible with MCP SDK's CallToolResult
  */
 type ToolResponse = CallToolResult;
+/**
+ * Transport configuration for initializing the Web Model Context polyfill.
+ */
+interface TransportConfiguration {
+  /**
+   * Provide a custom transport factory. When set, tabServer and iframeServer options are ignored.
+   */
+  create?: () => Transport;
+  /**
+   * Options passed to the built-in TabServerTransport when no custom factory is provided.
+   * Set to false to disable the tab server.
+   * Default: enabled with allowedOrigins: ['*']
+   */
+  tabServer?: Partial<TabServerTransportOptions> | false;
+  /**
+   * Options passed to the built-in IframeChildTransport when no custom factory is provided.
+   * Set to false to disable the iframe server.
+   * Default: auto-enabled when running in an iframe (window.parent !== window)
+   */
+  iframeServer?: Partial<IframeChildTransportOptions> | false;
+}
+/**
+ * Initialization options for the Web Model Context polyfill.
+ */
+interface WebModelContextInitOptions {
+  /**
+   * Configure the transport used to expose the MCP server in the browser.
+   */
+  transport?: TransportConfiguration;
+  /**
+   * When set to false, automatic initialization on module load is skipped.
+   */
+  autoInitialize?: boolean;
+}
 /**
  * Tool descriptor for Web Model Context API
  * Extended with full MCP protocol support
@@ -180,7 +206,8 @@ interface InternalModelContext extends ModelContext {
  * Internal MCP Bridge state
  */
 interface MCPBridge {
-  server: Server;
+  tabServer: Server;
+  iframeServer?: Server;
   tools: Map<string, ValidatedToolDescriptor>;
   modelContext: InternalModelContext;
   isInitialized: boolean;
@@ -202,5 +229,20 @@ declare global {
 }
 //# sourceMappingURL=types.d.ts.map
 //#endregion
-export { type CallToolResult, InputSchema, InternalModelContext, MCPBridge, ModelContext, ModelContextInput, type ToolAnnotations, ToolCallEvent, ToolDescriptor, ToolResponse, ValidatedToolDescriptor, ZodSchemaObject, cleanupWebModelContext, initializeWebModelContext };
+//#region src/global.d.ts
+declare global {
+  interface Window {
+    __webModelContextOptions?: WebModelContextInitOptions;
+  }
+}
+/**
+ * Initialize the Web Model Context API (window.navigator.modelContext)
+ */
+declare function initializeWebModelContext(options?: WebModelContextInitOptions): void;
+/**
+ * Cleanup function (for testing/development)
+ */
+declare function cleanupWebModelContext(): void;
+//#endregion
+export { type CallToolResult, InputSchema, InternalModelContext, MCPBridge, ModelContext, ModelContextInput, type ToolAnnotations, ToolCallEvent, ToolDescriptor, ToolResponse, TransportConfiguration, ValidatedToolDescriptor, WebModelContextInitOptions, ZodSchemaObject, cleanupWebModelContext, initializeWebModelContext };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/global.ts","../src/types.ts"],"sourcesContent":[],"mappings":";;;;;;;iBAifgB,yBAAA,CAAA;AAAhB;AAyCA;;iBAAgB,sBAAA,CAAA;;;;;AAzChB;AAyCgB,UCjhBC,WAAA,CDihBqB;;eC/gBvB;;IAFE,WAAW,CAAA,EAAA,MAAA;IAkBhB,CAAA,GAAA,EAAA,MAAA,CAAA,EAAe,OAAA;EAgBf,CAAA,CAAA;EAWK,QAAA,CAAA,EAAA,MAAc,EAAA;EACR,CAAA,GAAA,EAAA,MAAA,CAAA,EAAA,OAAA;;;;;;AA2BN,KAvDL,eAAA,GAAkB,MAuDb,CAAA,MAAA,EAvD4B,CAAA,CAAE,UAuD9B,CAAA;;;;AAyBjB;AAGe,KAnEH,YAAA,GAAe,cAmEZ;;;;;;;;;AAcf;AAWiB,UAjFA,cAiFc,CAAA,qBAhFR,eAgFQ,GAhFU,MAgFV,CAAA,MAAA,EAAA,KAAA,CAAA,EAAA,sBA/EP,eA+EO,GA/EW,MA+EX,CAAA,MAAA,EAAA,KAAA,CAAA,CAAA,CAAA;EASlB;;;EAT+B,IAAA,EAAA,MAAA;EAqB3B;;;EAc0B,WAAA,EAAA,MAAA;EACjB;;;;;;;EAaF,WAAA,EA7GT,WA6GS,GA7GK,YA6GL;EAQF;;;;;EAiBH,YAAA,CAAA,EA/HF,WA+HE,GA/HY,aA+HZ;EACD;;;EAQD,WAAA,CAAA,EAnID,eAmIsB;EAKA;;;;;AAMtC;EACU,OAAA,EAAA,CAAA,IAAA,EAtIA,YAsIA,SAtIqB,MAsIrB,CAAA,MAAA,EAAA,KAAA,CAAA,GArIF,MAqIE,CAAA,MAAA,EAAA,OAAA,CAAA,GApIF,CAAA,CAAE,KAoIA,CApIM,CAAA,CAAE,SAoIR,CApIkB,YAoIlB,CAAA,CAAA,EAAA,GAnIH,OAmIG,CAnIK,YAmIL,CAAA;;;;;AAIT;;AAAA,UA/HgB,uBAAA,CA8IU;EAAA,IAAA,EAAA,MAAA;EAAA,WAAA,EAAA,MAAA;eA3IZ;iBACE;gBACD;kBACE,4BAA4B,QAAQ;kBAGpC,CAAA,CAAE;oBACA,CAAA,CAAE;;;;;;UAOL,iBAAA;;;;;SAKR;;;;;UAMQ,aAAA,SAAsB;;;;;;;;aAS1B;;;;0BAKa;;;;;;UAOT,YAAA;;;;;;0BAMS;;;;;;oCAQD,kBAAkB,6CACjB,kBAAkB,6BAElC,eAAe,cAAc;;;;;;uDAUjB,yBAAyB,mCACvB;;;;0DAQF,yBAAyB,mCACvB;;;;uBAMD;;;;;eAMR;;;iBAGE;mBACE;kBACD;;;;;;;UAQD,oBAAA,SAA6B;;;;;sCAKR,0BAA0B,QAAQ;;;;;UAMvD,SAAA;UACP;SACD,YAAY;gBACL;;;;;;;;;kBAUE;;;;;;kBAOA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/global.ts"],"sourcesContent":[],"mappings":";;;;;;;;AAeA;AAkBY,UAlBK,WAAA,CAkBU;EAgBf,IAAA,EAAA,MAAA;EAKK,UAAA,CAAA,EArCF,MAqCE,CAAA,MAAsB,EAAA;IAItB,IAAA,EAAA,MAAA;IAOK,WAAA,CAAA,EAAA,MAAA;IAAR,CAAA,GAAA,EAAA,MAAA,CAAA,EAAA,OAAA;EAOW,CAAA,CAAA;EAAR,QAAA,CAAA,EAAA,MAAA,EAAA;EAAO,CAAA,GAAA,EAAA,MAAA,CAAA,EAAA,OAAA;AAMxB;AAqBA;;;;AAE0C,KApE9B,eAAA,GAAkB,MAoEY,CAAA,MAAA,EApEG,CAAA,CAAE,UAoEL,CAAA;;;;;AA2CnC,KA/FK,YAAA,GAAe,cA+FpB;;AAQP;;AAIiB,UAtGA,sBAAA,CAsGA;EACD;;;EAC8B,MAAA,CAAA,EAAA,GAAA,GApG7B,SAoG6B;EAG1B;;;AAQpB;AAWA;EASa,SAAA,CAAA,EA5HC,OA4HD,CA5HS,yBA4HT,CAAA,GAAA,KAAA;EAKa;;;AAO1B;;EAcyB,YAAA,CAAA,EA/IR,OA+IQ,CA/IA,2BA+IA,CAAA,GAAA,KAAA;;;;;AAGc,UA5ItB,0BAAA,CA4IsB;EAA7B;;;EAWc,SAAA,CAAA,EAnJV,sBAmJU;EAQF;;;EAOC,cAAA,CAAA,EAAA,OAAA;;;;;;AAmBvB;;;;;AAA0D,UApKzC,cAoKyC,CAAA,qBAnKnC,eAmKmC,GAnKjB,MAmKiB,CAAA,MAAA,EAAA,KAAA,CAAA,EAAA,sBAlKlC,eAkKkC,GAlKhB,MAkKgB,CAAA,MAAA,EAAA,KAAA,CAAA,CAAA,CAAA;EAWzC;;;EAGI,IAAA,EAAA,MAAA;EAAZ;;;EAGR,WAAA,EAAA,MAAA;EAAA;;;;;;;ECnQmB,WAAA,EDmGL,WCnGK,GDmGS,YCnGT;EAAA;;;;AAohBpB;EAwCgB,YAAA,CAAA,EDldC,WCkdqB,GDldP,aCkdO;;;;gBD7ctB;;;;;;;kBASN,qBAAqB,wBACvB,0BACA,CAAA,CAAE,MAAM,CAAA,CAAE,UAAU,mBACrB,QAAQ;;;;;;;UAQE,uBAAA;;;eAGF;iBACE;gBACD;kBACE,4BAA4B,QAAQ;kBAGpC,CAAA,CAAE;oBACA,CAAA,CAAE;;;;;;UAOL,iBAAA;;;;;SAKR;;;;;UAMQ,aAAA,SAAsB;;;;;;;;aAS1B;;;;0BAKa;;;;;;UAOT,YAAA;;;;;;0BAMS;;;;;;oCAQD,kBAAkB,6CACjB,kBAAkB,6BAElC,eAAe,cAAc;;;;;;uDAUjB,yBAAyB,mCACvB;;;;0DAQF,yBAAyB,mCACvB;;;;uBAMD;;;;;eAMR;;;iBAGE;mBACE;kBACD;;;;;;;UAQD,oBAAA,SAA6B;;;;;sCAKR,0BAA0B,QAAQ;;;;;UAMvD,SAAA;aACJ;iBACI;SACR,YAAY;gBACL;;;;;;;;;kBAUE;;;;;;kBAOA;;;;;;;;+BC7Qa;;ADX/B;AAkBA;AAgBA;AAKA;AAIiB,iBC+eD,yBAAA,CD/eC,OAAA,CAAA,EC+emC,0BD/enC,CAAA,EAAA,IAAA;;;;AAcA,iBCygBD,sBAAA,CAAA,CDzgBC,EAAA,IAAA"}