open-mcp-app 0.1.3 → 0.1.4

package/dist/core/index.d.ts

@@ -217,33 +217,72 @@ interface WebSocketClient<TSend = unknown, TReceive = unknown> {
 interface UnifiedHostClientEvents extends BaseHostClientEvents, McpAppsHostClientEvents {
 }
 /**
- * Unified host client interface.
+ * Experimental host APIs that are not part of the MCP Apps spec.
  *
- * This is the primary interface returned by `createHost()`.
- * It combines the base interface with host-specific extensions,
- * providing a consistent API across all platforms.
+ * These APIs may change or be removed in future versions. They provide
+ * access to Creature-specific features and other non-standard extensions.
+ *
+ * Similar to Vercel AI SDK's `experimental_*` pattern, these APIs are
+ * grouped under a separate namespace to clearly indicate their status.
  */
-interface UnifiedHostClient {
-    /** Get current state */
-    getState(): HostClientState;
-    /** Subscribe to state changes. Returns unsubscribe function. */
-    subscribe(listener: StateListener): () => void;
-    /** Call a tool on the MCP server */
-    callTool<T = Record<string, unknown>>(toolName: string, args: Record<string, unknown>): Promise<ToolResult<T>>;
+interface ExperimentalHostApi {
     /**
-     * Send a notification to the host.
+     * Send a raw notification to the host.
+     *
+     * This is a low-level API for sending custom notifications. Most apps
+     * should use higher-level methods like `setWidgetState` or `setTitle`.
      *
      * MCP Apps only - no-op on ChatGPT.
+     *
+     * @param method - The notification method name (e.g., "ui/notifications/...")
+     * @param params - The notification parameters
      */
     sendNotification(method: string, params: unknown): void;
-    /** Set widget state */
+    /**
+     * Set widget state and notify the host.
+     *
+     * Widget state is synchronized with the host for persistence across
+     * sessions and visibility to the AI model.
+     *
+     * **Non-spec extension:** On MCP Apps hosts, this sends a
+     * `ui/notifications/widget-state-changed` notification (Creature extension).
+     * On ChatGPT, this uses the native `window.openai.setWidgetState` bridge.
+     *
+     * @param state - New widget state (or null to clear)
+     */
     setWidgetState(state: WidgetState | null): void;
     /**
      * Set the pip/widget title displayed in the host UI.
      *
-     * Creature extension - no-op on ChatGPT and generic MCP Apps hosts.
+     * **Creature-only extension:** This sends a `ui/notifications/title-changed`
+     * notification. No-op on ChatGPT and generic MCP Apps hosts.
+     *
+     * @param title - The new title to display
      */
     setTitle(title: string): void;
+    /**
+     * Get Creature-specific CSS style variables.
+     *
+     * **Creature-only extension:** Returns custom CSS variables provided by the
+     * Creature host via `hostContext.creatureStyles`. Returns null when not
+     * running in Creature or styles are not available.
+     */
+    getCreatureStyles(): Record<string, string | undefined> | null;
+}
+/**
+ * Unified host client interface.
+ *
+ * This is the primary interface returned by `createHost()`.
+ * It combines the base interface with host-specific extensions,
+ * providing a consistent API across all platforms.
+ */
+interface UnifiedHostClient {
+    /** Get current state */
+    getState(): HostClientState;
+    /** Subscribe to state changes. Returns unsubscribe function. */
+    subscribe(listener: StateListener): () => void;
+    /** Call a tool on the MCP server */
+    callTool<T = Record<string, unknown>>(toolName: string, args: Record<string, unknown>): Promise<ToolResult<T>>;
     /**
      * Request a display mode change from the host.
      */
@@ -282,6 +321,24 @@ interface UnifiedHostClient {
      * Returns null before connection is established.
      */
     getHostContext(): HostContext | null;
+    /**
+     * Experimental APIs that are not part of the MCP Apps spec.
+     *
+     * These APIs provide access to Creature-specific features and other
+     * non-standard extensions. They may change or be removed in future versions.
+     *
+     * @example
+     * ```typescript
+     * // Set widget state (non-spec extension)
+     * client.experimental.setWidgetState({ count: 42 });
+     *
+     * // Set title (Creature-only)
+     * if (client.isCreature) {
+     *   client.experimental.setTitle("My Widget");
+     * }
+     * ```
+     */
+    readonly experimental: ExperimentalHostApi;
 }
 /**
  * The kind of adapter in use.
@@ -680,6 +737,11 @@ declare class McpAppsAdapter implements HostAdapter {
      * Base MCP Apps adapter returns false - CreatureAdapter overrides this.
      */
     get isCreature(): boolean;
+    /**
+     * Experimental APIs for non-spec extensions.
+     * Base MCP Apps adapter provides minimal implementations - CreatureAdapter overrides.
+     */
+    get experimental(): ExperimentalHostApi;
     /**
      * Get the host context received from the host.
      * Useful for checking host-specific capabilities.
@@ -688,13 +750,6 @@ declare class McpAppsAdapter implements HostAdapter {
     getState(): HostClientState;
     subscribe(listener: StateListener): () => void;
     callTool<T = Record<string, unknown>>(toolName: string, args: Record<string, unknown>): Promise<ToolResult<T>>;
-    sendNotification(method: string, params: unknown): void;
-    setWidgetState(state: WidgetState | null): void;
-    /**
-     * Set pip/widget title.
-     * Sends a notification - hosts that support it will update the title.
-     */
-    setTitle(title: string): void;
     requestDisplayMode(params: {
         mode: DisplayMode;
     }): Promise<{
@@ -776,21 +831,14 @@ declare class UpgradingMcpAppsClient implements HostAdapter {
     get isCreature(): boolean;
     get environment(): Environment;
     /**
-     * Get Creature-specific styles if available.
-     * Returns null when not running in Creature.
+     * Experimental APIs with dynamic Creature support.
+     * Methods like setTitle will only work when isCreature is true.
      */
-    getCreatureStyles(): Record<string, string | undefined> | null;
+    get experimental(): ExperimentalHostApi;
     getHostContext(): HostContext | null;
     getState(): HostClientState;
     subscribe(listener: StateListener): () => void;
     callTool<T = Record<string, unknown>>(toolName: string, args: Record<string, unknown>): Promise<ToolResult<T>>;
-    sendNotification(method: string, params: unknown): void;
-    setWidgetState(state: WidgetState | null): void;
-    /**
-     * Set pip/widget title.
-     * Sends a notification - hosts that support it will update the title.
-     */
-    setTitle(title: string): void;
     requestDisplayMode(params: {
         mode: DisplayMode;
     }): Promise<{
@@ -874,10 +922,9 @@ declare class CreatureAdapter extends McpAppsAdapter {
      */
     get isCreature(): boolean;
     /**
-     * Get Creature-specific styles if available.
-     * Returns null when not running in Creature.
+     * Experimental APIs with Creature-specific implementations.
      */
-    getCreatureStyles(): Record<string, string | undefined> | null;
+    get experimental(): ExperimentalHostApi;
 }
 
 /**
@@ -907,6 +954,11 @@ declare class ChatGptAdapter implements HostAdapter {
     static detect(): boolean;
     get environment(): Environment;
     get isCreature(): boolean;
+    /**
+     * Experimental APIs for ChatGPT.
+     * Most are no-ops since ChatGPT doesn't support MCP Apps extensions.
+     */
+    get experimental(): ExperimentalHostApi;
     /**
      * Get host context - returns null for ChatGPT as it doesn't use MCP Apps protocol.
      */
@@ -914,15 +966,6 @@ declare class ChatGptAdapter implements HostAdapter {
     getState(): HostClientState;
     subscribe(listener: StateListener): () => void;
     callTool<T = Record<string, unknown>>(toolName: string, args: Record<string, unknown>): Promise<ToolResult<T>>;
-    /**
-     * Send notification - not supported on ChatGPT.
-     */
-    sendNotification(_method: string, _params: unknown): void;
-    setWidgetState(state: WidgetState | null): void;
-    /**
-     * Set pip/widget title - not supported on ChatGPT.
-     */
-    setTitle(_title: string): void;
     requestDisplayMode(params: {
         mode: DisplayMode;
     }): Promise<{
@@ -962,6 +1005,11 @@ declare class StandaloneAdapter implements HostAdapter {
     static detect(): boolean;
     get environment(): Environment;
     get isCreature(): boolean;
+    /**
+     * Experimental APIs for standalone mode.
+     * All methods are logged for development/debugging purposes.
+     */
+    get experimental(): ExperimentalHostApi;
     /**
      * Get host context - returns null for standalone mode.
      */
@@ -969,15 +1017,6 @@ declare class StandaloneAdapter implements HostAdapter {
     getState(): HostClientState;
     subscribe(listener: StateListener): () => void;
     callTool<T = Record<string, unknown>>(toolName: string, args: Record<string, unknown>): Promise<ToolResult<T>>;
-    /**
-     * Send notification - logged in standalone mode.
-     */
-    sendNotification(method: string, params: unknown): void;
-    setWidgetState(state: WidgetState | null): void;
-    /**
-     * Set pip/widget title - logged in standalone mode.
-     */
-    setTitle(title: string): void;
     requestDisplayMode(params: {
         mode: DisplayMode;
     }): Promise<{
@@ -1168,4 +1207,4 @@ declare function createHost(config: HostClientConfig): UnifiedHostClient;
  */
 declare function createHostAsync(config: HostClientConfig): Promise<UnifiedHostClient>;
 
-export { type AdapterKind, type BaseHostClient, type BaseHostClientEvents, CHATGPT_DARK_DEFAULTS, CHATGPT_LIGHT_DEFAULTS, CHATGPT_SHARED_DEFAULTS, ChatGptAdapter, ChatGptBaseHostClient, CreatureAdapter, type DisplayMode, type Environment, type HostAdapter, type HostClientConfig, type HostClientState, type HostContext, type HostIdentity, type InitStylesOptions, KNOWN_HOSTS, type LogLevel, MCP_APPS_DARK_DEFAULTS, MCP_APPS_LIGHT_DEFAULTS, MCP_APPS_SHARED_DEFAULTS, McpAppsAdapter, McpAppsBaseHostClient, type McpAppsHostClientEvents, StandaloneAdapter, StandaloneBaseHostClient, type StateListener, type StructuredWidgetState, type Theme, type ToolResult, type UnifiedHostClient, type UnifiedHostClientEvents, UpgradingMcpAppsClient, type WebSocketClient, type WebSocketClientConfig, type WebSocketStatus, type WidgetState, applyStyles, createHost, createHostAsync, createWebSocket, detectEnvironment, detectTheme, getChatGptDefaultStyles, getHostIdentity, getMcpAppDefaultStyles, initStyles, isHost, parseHostUserAgent };
+export { type AdapterKind, type BaseHostClient, type BaseHostClientEvents, CHATGPT_DARK_DEFAULTS, CHATGPT_LIGHT_DEFAULTS, CHATGPT_SHARED_DEFAULTS, ChatGptAdapter, ChatGptBaseHostClient, CreatureAdapter, type DisplayMode, type Environment, type ExperimentalHostApi, type HostAdapter, type HostClientConfig, type HostClientState, type HostContext, type HostIdentity, type InitStylesOptions, KNOWN_HOSTS, type LogLevel, MCP_APPS_DARK_DEFAULTS, MCP_APPS_LIGHT_DEFAULTS, MCP_APPS_SHARED_DEFAULTS, McpAppsAdapter, McpAppsBaseHostClient, type McpAppsHostClientEvents, StandaloneAdapter, StandaloneBaseHostClient, type StateListener, type StructuredWidgetState, type Theme, type ToolResult, type UnifiedHostClient, type UnifiedHostClientEvents, UpgradingMcpAppsClient, type WebSocketClient, type WebSocketClientConfig, type WebSocketStatus, type WidgetState, applyStyles, createHost, createHostAsync, createWebSocket, detectEnvironment, detectTheme, getChatGptDefaultStyles, getHostIdentity, getMcpAppDefaultStyles, initStyles, isHost, parseHostUserAgent };

package/dist/core/index.js

@@ -275,6 +275,24 @@ var ChatGptAdapter = class _ChatGptAdapter {
   get isCreature() {
     return false;
   }
+  /**
+   * Experimental APIs for ChatGPT.
+   * Most are no-ops since ChatGPT doesn't support MCP Apps extensions.
+   */
+  get experimental() {
+    return {
+      sendNotification: (_method, _params) => {
+      },
+      setWidgetState: (state) => {
+        this.base.setWidgetState(state);
+      },
+      setTitle: (_title) => {
+      },
+      getCreatureStyles: () => {
+        return null;
+      }
+    };
+  }
   /**
    * Get host context - returns null for ChatGPT as it doesn't use MCP Apps protocol.
    */
@@ -290,19 +308,6 @@ var ChatGptAdapter = class _ChatGptAdapter {
   async callTool(toolName, args) {
     return this.base.callTool(toolName, args);
   }
-  /**
-   * Send notification - not supported on ChatGPT.
-   */
-  sendNotification(_method, _params) {
-  }
-  setWidgetState(state) {
-    this.base.setWidgetState(state);
-  }
-  /**
-   * Set pip/widget title - not supported on ChatGPT.
-   */
-  setTitle(_title) {
-  }
   async requestDisplayMode(params) {
     return this.base.requestDisplayMode(params);
   }
@@ -457,6 +462,26 @@ var StandaloneAdapter = class _StandaloneAdapter {
   get isCreature() {
     return false;
   }
+  /**
+   * Experimental APIs for standalone mode.
+   * All methods are logged for development/debugging purposes.
+   */
+  get experimental() {
+    return {
+      sendNotification: (method, params) => {
+        console.debug(`[Standalone] experimental.sendNotification("${method}")`, params);
+      },
+      setWidgetState: (state) => {
+        this.base.setWidgetState(state);
+      },
+      setTitle: (title) => {
+        console.debug(`[Standalone] experimental.setTitle("${title}")`);
+      },
+      getCreatureStyles: () => {
+        return null;
+      }
+    };
+  }
   /**
    * Get host context - returns null for standalone mode.
    */
@@ -472,21 +497,6 @@ var StandaloneAdapter = class _StandaloneAdapter {
   async callTool(toolName, args) {
     return this.base.callTool(toolName, args);
   }
-  /**
-   * Send notification - logged in standalone mode.
-   */
-  sendNotification(method, params) {
-    console.debug(`[Standalone] sendNotification("${method}")`, params);
-  }
-  setWidgetState(state) {
-    this.base.setWidgetState(state);
-  }
-  /**
-   * Set pip/widget title - logged in standalone mode.
-   */
-  setTitle(title) {
-    console.debug(`[Standalone] setTitle("${title}")`);
-  }
   async requestDisplayMode(params) {
     return this.base.requestDisplayMode(params);
   }
@@ -10153,14 +10163,29 @@ var UpgradingMcpAppsClient = class _UpgradingMcpAppsClient {
     return this.base.getState().environment;
   }
   // ============================================================================
-  // Creature-Specific Extensions (gracefully no-op when not in Creature)
+  // Experimental APIs
   // ============================================================================
   /**
-   * Get Creature-specific styles if available.
-   * Returns null when not running in Creature.
+   * Experimental APIs with dynamic Creature support.
+   * Methods like setTitle will only work when isCreature is true.
    */
-  getCreatureStyles() {
-    return this.base.getCreatureStyles();
+  get experimental() {
+    return {
+      sendNotification: (method, params) => {
+        this.base.sendNotification(method, params);
+      },
+      setWidgetState: (state) => {
+        this.base.setWidgetState(state);
+      },
+      setTitle: (title) => {
+        if (this.isCreature) {
+          this.base.sendNotification("ui/notifications/title-changed", { title });
+        }
+      },
+      getCreatureStyles: () => {
+        return this.base.getCreatureStyles();
+      }
+    };
   }
   // ============================================================================
   // UnifiedHostClient Implementation
@@ -10177,19 +10202,6 @@ var UpgradingMcpAppsClient = class _UpgradingMcpAppsClient {
   async callTool(toolName, args) {
     return this.base.callTool(toolName, args);
   }
-  sendNotification(method, params) {
-    this.base.sendNotification(method, params);
-  }
-  setWidgetState(state) {
-    this.base.setWidgetState(state);
-  }
-  /**
-   * Set pip/widget title.
-   * Sends a notification - hosts that support it will update the title.
-   */
-  setTitle(title) {
-    this.base.sendNotification("ui/notifications/title-changed", { title });
-  }
   async requestDisplayMode(params) {
     return this.base.requestDisplayMode(params);
   }
@@ -10259,6 +10271,25 @@ var McpAppsAdapter = class _McpAppsAdapter {
   get isCreature() {
     return false;
   }
+  /**
+   * Experimental APIs for non-spec extensions.
+   * Base MCP Apps adapter provides minimal implementations - CreatureAdapter overrides.
+   */
+  get experimental() {
+    return {
+      sendNotification: (method, params) => {
+        this.base.sendNotification(method, params);
+      },
+      setWidgetState: (state) => {
+        this.base.setWidgetState(state);
+      },
+      setTitle: (_title) => {
+      },
+      getCreatureStyles: () => {
+        return null;
+      }
+    };
+  }
   /**
    * Get the host context received from the host.
    * Useful for checking host-specific capabilities.
@@ -10275,19 +10306,6 @@ var McpAppsAdapter = class _McpAppsAdapter {
   async callTool(toolName, args) {
     return this.base.callTool(toolName, args);
   }
-  sendNotification(method, params) {
-    this.base.sendNotification(method, params);
-  }
-  setWidgetState(state) {
-    this.base.setWidgetState(state);
-  }
-  /**
-   * Set pip/widget title.
-   * Sends a notification - hosts that support it will update the title.
-   */
-  setTitle(title) {
-    this.base.sendNotification("ui/notifications/title-changed", { title });
-  }
   async requestDisplayMode(params) {
     return this.base.requestDisplayMode(params);
   }
@@ -10385,11 +10403,25 @@ var CreatureAdapter = class _CreatureAdapter extends McpAppsAdapter {
     return this.base.isCreatureHost();
   }
   /**
-   * Get Creature-specific styles if available.
-   * Returns null when not running in Creature.
+   * Experimental APIs with Creature-specific implementations.
    */
-  getCreatureStyles() {
-    return this.base.getCreatureStyles();
+  get experimental() {
+    return {
+      sendNotification: (method, params) => {
+        this.base.sendNotification(method, params);
+      },
+      setWidgetState: (state) => {
+        this.base.setWidgetState(state);
+      },
+      setTitle: (title) => {
+        if (this.isCreature) {
+          this.base.sendNotification("ui/notifications/title-changed", { title });
+        }
+      },
+      getCreatureStyles: () => {
+        return this.base.getCreatureStyles();
+      }
+    };
   }
 };