@mcp-b/global 1.0.15 → 1.1.1

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
@@ -103,7 +129,7 @@ interface ModelContextInput {
    * Array of tool descriptors
    * Supports both JSON Schema and Zod schema formats
    */
-  tools: ToolDescriptor<any, any>[];
+  tools: ToolDescriptor[];
 }
 /**
  * Tool call event
@@ -141,6 +167,16 @@ interface ModelContext {
   registerTool<TInputSchema extends ZodSchemaObject = Record<string, never>, TOutputSchema extends ZodSchemaObject = Record<string, never>>(tool: ToolDescriptor<TInputSchema, TOutputSchema>): {
     unregister: () => void;
   };
+  /**
+   * Unregister a tool by name
+   * Available in Chromium's native implementation
+   */
+  unregisterTool(name: string): void;
+  /**
+   * Clear all registered tools (both buckets)
+   * Available in Chromium's native implementation
+   */
+  clearContext(): void;
   /**
    * Add event listener for tool calls
    */
@@ -180,11 +216,97 @@ interface InternalModelContext extends ModelContext {
  * Internal MCP Bridge state
  */
 interface MCPBridge {
-  server: Server;
+  tabServer: Server;
+  iframeServer?: Server;
   tools: Map<string, ValidatedToolDescriptor>;
   modelContext: InternalModelContext;
+  modelContextTesting?: ModelContextTesting;
   isInitialized: boolean;
 }
+/**
+ * Tool info returned by listTools() in testing API
+ * Note: inputSchema is a JSON string, not an object (matches Chromium implementation)
+ */
+interface ToolInfo {
+  name: string;
+  description: string;
+  inputSchema: string;
+}
+/**
+ * Testing API for Model Context
+ *
+ * **Native Support**: This API is available natively in Chromium-based browsers
+ * when the experimental "Model Context Testing" feature flag is enabled.
+ *
+ * **How to enable in Chromium**:
+ * - Navigate to `chrome://flags`
+ * - Search for "experimental web platform features" or "model context"
+ * - Enable the feature and restart the browser
+ * - Or launch with: `--enable-experimental-web-platform-features`
+ *
+ * **Polyfill**: If the native API is not available, this polyfill provides
+ * a compatible implementation for testing purposes.
+ */
+interface ModelContextTesting {
+  /**
+   * Execute a tool directly with JSON string input (Chromium native API)
+   * @param toolName - Name of the tool to execute
+   * @param inputArgsJson - JSON string of input arguments
+   * @returns Promise resolving to the tool's result
+   */
+  executeTool(toolName: string, inputArgsJson: string): Promise<unknown>;
+  /**
+   * List all registered tools (Chromium native API)
+   * Returns tools with inputSchema as JSON string
+   */
+  listTools(): ToolInfo[];
+  /**
+   * Register a callback that fires when the tools list changes (Chromium native API)
+   * Callback will fire on: registerTool, unregisterTool, provideContext, clearContext
+   */
+  registerToolsChangedCallback(callback: () => void): void;
+  /**
+   * Get all tool calls that have been made (for testing/debugging)
+   * Polyfill-specific extension
+   */
+  getToolCalls(): Array<{
+    toolName: string;
+    arguments: Record<string, unknown>;
+    timestamp: number;
+  }>;
+  /**
+   * Clear the history of tool calls
+   * Polyfill-specific extension
+   */
+  clearToolCalls(): void;
+  /**
+   * Set a mock response for a specific tool (for testing)
+   * When set, the tool's execute function will be bypassed and the mock response returned
+   * Polyfill-specific extension
+   */
+  setMockToolResponse(toolName: string, response: ToolResponse): void;
+  /**
+   * Clear mock response for a specific tool
+   * Polyfill-specific extension
+   */
+  clearMockToolResponse(toolName: string): void;
+  /**
+   * Clear all mock tool responses
+   * Polyfill-specific extension
+   */
+  clearAllMockToolResponses(): void;
+  /**
+   * Get the current tools registered in the system
+   * (same as modelContext.listTools but explicitly for testing)
+   * Polyfill-specific extension
+   */
+  getRegisteredTools(): ReturnType<ModelContext['listTools']>;
+  /**
+   * Reset the entire testing state (clears tool calls and mock responses)
+   * Polyfill-specific extension
+   */
+  reset(): void;
+}
 declare global {
   interface Navigator {
     /**
@@ -192,6 +314,18 @@ declare global {
      * Provides tools and context to AI agents
      */
     modelContext: ModelContext;
+    /**
+     * Model Context Testing API
+     *
+     * **IMPORTANT**: This API is only available in Chromium-based browsers
+     * with the experimental feature flag enabled:
+     * - `chrome://flags` → "Experimental Web Platform Features"
+     * - Or launch with: `--enable-experimental-web-platform-features`
+     *
+     * If not available natively, the @mcp-b/global polyfill provides
+     * a compatible implementation.
+     */
+    modelContextTesting?: ModelContextTesting;
   }
   interface Window {
     /**
@@ -202,5 +336,46 @@ 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;
+  }
+}
+/**
+ * Initializes the Web Model Context API on window.navigator.
+ * Creates and exposes navigator.modelContext and navigator.modelContextTesting.
+ * Automatically detects and uses native Chromium implementation if available.
+ *
+ * @param {WebModelContextInitOptions} [options] - Configuration options
+ * @throws {Error} If initialization fails
+ * @example
+ * ```typescript
+ * import { initializeWebModelContext } from '@mcp-b/global';
+ *
+ * initializeWebModelContext({
+ *   transport: {
+ *     tabServer: {
+ *       allowedOrigins: ['https://example.com']
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare function initializeWebModelContext(options?: WebModelContextInitOptions): void;
+/**
+ * Cleans up the Web Model Context API.
+ * Closes all MCP servers and removes API from window.navigator.
+ * Useful for testing and hot module replacement.
+ *
+ * @example
+ * ```typescript
+ * import { cleanupWebModelContext } from '@mcp-b/global';
+ *
+ * cleanupWebModelContext();
+ * ```
+ */
+declare function cleanupWebModelContext(): void;
+//#endregion
+export { type CallToolResult, InputSchema, InternalModelContext, MCPBridge, ModelContext, ModelContextInput, ModelContextTesting, type ToolAnnotations, ToolCallEvent, ToolDescriptor, ToolInfo, 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":"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"}