mcp-ui-ext-apps-openai 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,225 @@
+import { App, McpUiAppCapabilities } from '@modelcontextprotocol/ext-apps';
+
+/**
+ * @file Unified App Utility - Works with both OpenAI ChatGPT Apps and MCP Apps
+ *
+ * This utility provides a unified interface that abstracts away the differences
+ * between OpenAI's window.openai API and MCP Apps SDK.
+ */
+
+type Platform = "openai" | "mcp" | "unknown";
+interface UnifiedToolResult {
+    content: Array<{
+        type: string;
+        text?: string;
+        [key: string]: unknown;
+    }>;
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+}
+interface UnifiedMessage {
+    role: "user" | "assistant";
+    content: Array<{
+        type: string;
+        text?: string;
+        [key: string]: unknown;
+    }>;
+}
+interface UnifiedHostContext {
+    theme?: "light" | "dark";
+    displayMode?: "inline" | "pip" | "fullscreen";
+    locale?: string;
+    safeAreaInsets?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
+    maxWidth?: number;
+    maxHeight?: number;
+}
+interface UnifiedAppOptions {
+    appInfo: {
+        name: string;
+        version: string;
+    };
+    capabilities?: McpUiAppCapabilities;
+    onToolInput?: (input: unknown) => void | Promise<void>;
+    onToolResult?: (result: UnifiedToolResult) => void | Promise<void>;
+    onHostContextChanged?: (context: UnifiedHostContext) => void;
+    onTeardown?: () => void | Promise<void>;
+    onError?: (error: Error) => void;
+}
+interface UnifiedApp {
+    /** The underlying platform */
+    platform: Platform;
+    /** Call a server tool by name with arguments */
+    callServerTool: (params: {
+        name: string;
+        arguments: Record<string, unknown>;
+    }) => Promise<UnifiedToolResult>;
+    /** Send a message to the host/conversation */
+    sendMessage: (message: UnifiedMessage, options?: {
+        signal?: AbortSignal;
+    }) => Promise<{
+        isError: boolean;
+    }>;
+    /** Send a log message to the host */
+    sendLog: (params: {
+        level: "info" | "warning" | "error" | "debug";
+        data: string;
+    }) => Promise<void>;
+    /** Open an external link */
+    openLink: (params: {
+        url: string;
+    }) => Promise<{
+        isError: boolean;
+    }>;
+    /** Get the current host context */
+    getHostContext: () => UnifiedHostContext;
+    /** Get tool input (initial arguments passed to the tool) */
+    getToolInput: () => Record<string, unknown>;
+    /** Get tool output (result from server) */
+    getToolOutput: () => unknown;
+    /** Get tool response metadata (OpenAI only, returns {} on MCP) */
+    getToolResponseMetadata: () => Record<string, unknown>;
+    /** Get widget state (OpenAI only, returns null on MCP) */
+    getWidgetState: <T = unknown>() => T | null;
+    /** Get widget props (OpenAI only, returns {} on MCP) */
+    getWidgetProps: <T = Record<string, unknown>>() => T;
+    /** Set widget state - persists across renders (OpenAI only, no-op on MCP) */
+    setWidgetState: <T = unknown>(state: T) => void;
+    /** Update widget state - partial update (OpenAI only, no-op on MCP) */
+    updateWidgetState: <T = unknown>(state: Partial<T>) => void;
+    /** Request a specific display mode (OpenAI only, no-op on MCP) */
+    requestDisplayMode: (mode: "inline" | "pip" | "fullscreen") => Promise<void>;
+    /** Request to close the widget (OpenAI only, no-op on MCP) */
+    requestClose: () => void;
+    /** Notify intrinsic height for dynamic sizing (OpenAI only, no-op on MCP) */
+    notifyIntrinsicHeight: (height: number) => void;
+    /** Upload a file (OpenAI only, throws on MCP) */
+    uploadFile: (file: File) => Promise<{
+        fileId: string;
+    }>;
+    /** Get file download URL (OpenAI only, throws on MCP) */
+    getFileDownloadUrl: (params: {
+        fileId: string;
+    }) => Promise<string>;
+    /** Set URL for "Open in App" button (OpenAI only, no-op on MCP) */
+    setOpenInAppUrl: (params: {
+        href: string;
+    }) => void;
+    /** Share content (OpenAI only, throws on MCP) */
+    share: (params: unknown) => Promise<void>;
+    /** Call AI completion (OpenAI only, throws on MCP) */
+    callCompletion: (params: unknown) => Promise<unknown>;
+    /** Stream AI completion (OpenAI only, throws on MCP) */
+    streamCompletion: (params: unknown) => AsyncIterable<unknown>;
+    /** The raw underlying app instance */
+    _raw: App | OpenAIGlobal | null;
+}
+interface OpenAIGlobal {
+    callTool: (name: string, args: Record<string, unknown>) => Promise<unknown>;
+    sendFollowUpMessage: (params: {
+        prompt: string;
+    }) => Promise<void>;
+    openExternal: (params: {
+        href: string;
+    }) => Promise<void>;
+    setOpenInAppUrl: (params: {
+        href: string;
+    }) => void;
+    requestDisplayMode: (mode: string) => Promise<void>;
+    requestModal: (params: unknown) => Promise<void>;
+    requestClose: () => void;
+    notifyIntrinsicHeight: (height: number) => void;
+    uploadFile: (file: File) => Promise<{
+        fileId: string;
+    }>;
+    getFileDownloadUrl: (params: {
+        fileId: string;
+    }) => Promise<string>;
+    getFileMetadata: (params: {
+        fileId: string;
+    }) => Promise<unknown>;
+    setWidgetState: (state: unknown) => void;
+    updateWidgetState: (state: unknown) => void;
+    share: (params: unknown) => Promise<void>;
+    streamCompletion: (params: unknown) => AsyncIterable<unknown>;
+    callCompletion: (params: unknown) => Promise<unknown>;
+    toolInput: Record<string, unknown>;
+    toolOutput: unknown;
+    toolResponseMetadata: Record<string, unknown>;
+    widgetState: unknown;
+    theme: "light" | "dark";
+    displayMode: "inline" | "pip" | "fullscreen";
+    locale: string;
+    maxWidth?: number;
+    maxHeight?: number;
+    safeArea: {
+        insets: {
+            top: number;
+            right: number;
+            bottom: number;
+            left: number;
+        };
+    };
+    userAgent: {
+        device: unknown;
+        capabilities: unknown;
+    };
+    view: {
+        params: unknown;
+        mode: string;
+    };
+    widget: {
+        state: unknown;
+        props: unknown;
+        setState: (state: unknown) => void;
+    };
+    subjectId: string;
+}
+/** Widget props from OpenAI (passed to widget via widget.props) */
+interface OpenAIWidgetProps {
+    [key: string]: unknown;
+}
+declare global {
+    interface Window {
+        openai?: OpenAIGlobal;
+    }
+}
+/**
+ * Detect which platform the app is running on
+ */
+declare function detectPlatform(): Platform;
+/**
+ * Check if running in OpenAI ChatGPT environment
+ */
+declare function isOpenAI(): boolean;
+/**
+ * Check if running in MCP Apps environment
+ */
+declare function isMCP(): boolean;
+/**
+ * Create a UnifiedApp from OpenAI's window.openai
+ */
+declare function createOpenAIAdapter(options: UnifiedAppOptions): UnifiedApp;
+/**
+ * Create a UnifiedApp from MCP App instance
+ */
+declare function createMCPAdapter(app: App, _options: UnifiedAppOptions): UnifiedApp;
+interface CreateUnifiedAppResult {
+    app: UnifiedApp | null;
+    isConnected: boolean;
+    error: Error | null;
+    platform: Platform;
+}
+/**
+ * Create a unified app - automatically detects platform and creates appropriate adapter
+ *
+ * For OpenAI: Returns immediately with the adapter
+ * For MCP: Returns null app (use the React hook instead for MCP)
+ */
+declare function createUnifiedApp(options: UnifiedAppOptions): CreateUnifiedAppResult;
+
+export { type CreateUnifiedAppResult, type OpenAIGlobal, type OpenAIWidgetProps, type Platform, type UnifiedApp, type UnifiedAppOptions, type UnifiedHostContext, type UnifiedMessage, type UnifiedToolResult, createMCPAdapter, createOpenAIAdapter, createUnifiedApp, detectPlatform, isMCP, isOpenAI };

package/dist/index.d.ts

@@ -0,0 +1,225 @@
+import { App, McpUiAppCapabilities } from '@modelcontextprotocol/ext-apps';
+
+/**
+ * @file Unified App Utility - Works with both OpenAI ChatGPT Apps and MCP Apps
+ *
+ * This utility provides a unified interface that abstracts away the differences
+ * between OpenAI's window.openai API and MCP Apps SDK.
+ */
+
+type Platform = "openai" | "mcp" | "unknown";
+interface UnifiedToolResult {
+    content: Array<{
+        type: string;
+        text?: string;
+        [key: string]: unknown;
+    }>;
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+}
+interface UnifiedMessage {
+    role: "user" | "assistant";
+    content: Array<{
+        type: string;
+        text?: string;
+        [key: string]: unknown;
+    }>;
+}
+interface UnifiedHostContext {
+    theme?: "light" | "dark";
+    displayMode?: "inline" | "pip" | "fullscreen";
+    locale?: string;
+    safeAreaInsets?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
+    maxWidth?: number;
+    maxHeight?: number;
+}
+interface UnifiedAppOptions {
+    appInfo: {
+        name: string;
+        version: string;
+    };
+    capabilities?: McpUiAppCapabilities;
+    onToolInput?: (input: unknown) => void | Promise<void>;
+    onToolResult?: (result: UnifiedToolResult) => void | Promise<void>;
+    onHostContextChanged?: (context: UnifiedHostContext) => void;
+    onTeardown?: () => void | Promise<void>;
+    onError?: (error: Error) => void;
+}
+interface UnifiedApp {
+    /** The underlying platform */
+    platform: Platform;
+    /** Call a server tool by name with arguments */
+    callServerTool: (params: {
+        name: string;
+        arguments: Record<string, unknown>;
+    }) => Promise<UnifiedToolResult>;
+    /** Send a message to the host/conversation */
+    sendMessage: (message: UnifiedMessage, options?: {
+        signal?: AbortSignal;
+    }) => Promise<{
+        isError: boolean;
+    }>;
+    /** Send a log message to the host */
+    sendLog: (params: {
+        level: "info" | "warning" | "error" | "debug";
+        data: string;
+    }) => Promise<void>;
+    /** Open an external link */
+    openLink: (params: {
+        url: string;
+    }) => Promise<{
+        isError: boolean;
+    }>;
+    /** Get the current host context */
+    getHostContext: () => UnifiedHostContext;
+    /** Get tool input (initial arguments passed to the tool) */
+    getToolInput: () => Record<string, unknown>;
+    /** Get tool output (result from server) */
+    getToolOutput: () => unknown;
+    /** Get tool response metadata (OpenAI only, returns {} on MCP) */
+    getToolResponseMetadata: () => Record<string, unknown>;
+    /** Get widget state (OpenAI only, returns null on MCP) */
+    getWidgetState: <T = unknown>() => T | null;
+    /** Get widget props (OpenAI only, returns {} on MCP) */
+    getWidgetProps: <T = Record<string, unknown>>() => T;
+    /** Set widget state - persists across renders (OpenAI only, no-op on MCP) */
+    setWidgetState: <T = unknown>(state: T) => void;
+    /** Update widget state - partial update (OpenAI only, no-op on MCP) */
+    updateWidgetState: <T = unknown>(state: Partial<T>) => void;
+    /** Request a specific display mode (OpenAI only, no-op on MCP) */
+    requestDisplayMode: (mode: "inline" | "pip" | "fullscreen") => Promise<void>;
+    /** Request to close the widget (OpenAI only, no-op on MCP) */
+    requestClose: () => void;
+    /** Notify intrinsic height for dynamic sizing (OpenAI only, no-op on MCP) */
+    notifyIntrinsicHeight: (height: number) => void;
+    /** Upload a file (OpenAI only, throws on MCP) */
+    uploadFile: (file: File) => Promise<{
+        fileId: string;
+    }>;
+    /** Get file download URL (OpenAI only, throws on MCP) */
+    getFileDownloadUrl: (params: {
+        fileId: string;
+    }) => Promise<string>;
+    /** Set URL for "Open in App" button (OpenAI only, no-op on MCP) */
+    setOpenInAppUrl: (params: {
+        href: string;
+    }) => void;
+    /** Share content (OpenAI only, throws on MCP) */
+    share: (params: unknown) => Promise<void>;
+    /** Call AI completion (OpenAI only, throws on MCP) */
+    callCompletion: (params: unknown) => Promise<unknown>;
+    /** Stream AI completion (OpenAI only, throws on MCP) */
+    streamCompletion: (params: unknown) => AsyncIterable<unknown>;
+    /** The raw underlying app instance */
+    _raw: App | OpenAIGlobal | null;
+}
+interface OpenAIGlobal {
+    callTool: (name: string, args: Record<string, unknown>) => Promise<unknown>;
+    sendFollowUpMessage: (params: {
+        prompt: string;
+    }) => Promise<void>;
+    openExternal: (params: {
+        href: string;
+    }) => Promise<void>;
+    setOpenInAppUrl: (params: {
+        href: string;
+    }) => void;
+    requestDisplayMode: (mode: string) => Promise<void>;
+    requestModal: (params: unknown) => Promise<void>;
+    requestClose: () => void;
+    notifyIntrinsicHeight: (height: number) => void;
+    uploadFile: (file: File) => Promise<{
+        fileId: string;
+    }>;
+    getFileDownloadUrl: (params: {
+        fileId: string;
+    }) => Promise<string>;
+    getFileMetadata: (params: {
+        fileId: string;
+    }) => Promise<unknown>;
+    setWidgetState: (state: unknown) => void;
+    updateWidgetState: (state: unknown) => void;
+    share: (params: unknown) => Promise<void>;
+    streamCompletion: (params: unknown) => AsyncIterable<unknown>;
+    callCompletion: (params: unknown) => Promise<unknown>;
+    toolInput: Record<string, unknown>;
+    toolOutput: unknown;
+    toolResponseMetadata: Record<string, unknown>;
+    widgetState: unknown;
+    theme: "light" | "dark";
+    displayMode: "inline" | "pip" | "fullscreen";
+    locale: string;
+    maxWidth?: number;
+    maxHeight?: number;
+    safeArea: {
+        insets: {
+            top: number;
+            right: number;
+            bottom: number;
+            left: number;
+        };
+    };
+    userAgent: {
+        device: unknown;
+        capabilities: unknown;
+    };
+    view: {
+        params: unknown;
+        mode: string;
+    };
+    widget: {
+        state: unknown;
+        props: unknown;
+        setState: (state: unknown) => void;
+    };
+    subjectId: string;
+}
+/** Widget props from OpenAI (passed to widget via widget.props) */
+interface OpenAIWidgetProps {
+    [key: string]: unknown;
+}
+declare global {
+    interface Window {
+        openai?: OpenAIGlobal;
+    }
+}
+/**
+ * Detect which platform the app is running on
+ */
+declare function detectPlatform(): Platform;
+/**
+ * Check if running in OpenAI ChatGPT environment
+ */
+declare function isOpenAI(): boolean;
+/**
+ * Check if running in MCP Apps environment
+ */
+declare function isMCP(): boolean;
+/**
+ * Create a UnifiedApp from OpenAI's window.openai
+ */
+declare function createOpenAIAdapter(options: UnifiedAppOptions): UnifiedApp;
+/**
+ * Create a UnifiedApp from MCP App instance
+ */
+declare function createMCPAdapter(app: App, _options: UnifiedAppOptions): UnifiedApp;
+interface CreateUnifiedAppResult {
+    app: UnifiedApp | null;
+    isConnected: boolean;
+    error: Error | null;
+    platform: Platform;
+}
+/**
+ * Create a unified app - automatically detects platform and creates appropriate adapter
+ *
+ * For OpenAI: Returns immediately with the adapter
+ * For MCP: Returns null app (use the React hook instead for MCP)
+ */
+declare function createUnifiedApp(options: UnifiedAppOptions): CreateUnifiedAppResult;
+
+export { type CreateUnifiedAppResult, type OpenAIGlobal, type OpenAIWidgetProps, type Platform, type UnifiedApp, type UnifiedAppOptions, type UnifiedHostContext, type UnifiedMessage, type UnifiedToolResult, createMCPAdapter, createOpenAIAdapter, createUnifiedApp, detectPlatform, isMCP, isOpenAI };