mcp-app-studio 0.3.2

package/dist/core/index.d.ts

@@ -0,0 +1,445 @@
+/**
+ * Color theme of the host application.
+ * Use `useTheme()` hook to get the current theme and adapt your UI accordingly.
+ *
+ * @example
+ * ```tsx
+ * const theme = useTheme();
+ * return <div className={theme === 'dark' ? 'bg-gray-900' : 'bg-white'}>...</div>
+ * ```
+ */
+type Theme = "light" | "dark";
+/**
+ * Platform your app is running on.
+ * - `"chatgpt"` - Running inside ChatGPT (window.openai API available)
+ * - `"mcp"` - Running inside an MCP host like Claude Desktop
+ * - `"unknown"` - Platform not detected (development mode or unsupported host)
+ *
+ * Use `usePlatform()` hook or `detectPlatform()` to check at runtime.
+ *
+ * @example
+ * ```tsx
+ * const platform = usePlatform();
+ * if (platform === 'chatgpt') {
+ *   // Use ChatGPT-specific features like widgetState
+ * }
+ * ```
+ */
+type Platform = "chatgpt" | "mcp" | "unknown";
+/**
+ * Display mode for the widget.
+ * - `"inline"` - Widget embedded in conversation flow (default)
+ * - `"fullscreen"` - Widget takes full screen
+ * - `"pip"` - Picture-in-picture floating window (ChatGPT only)
+ *
+ * Use `useDisplayMode()` to get current mode and request changes.
+ *
+ * @example
+ * ```tsx
+ * const [mode, setMode] = useDisplayMode();
+ * <button onClick={() => setMode('fullscreen')}>Expand</button>
+ * ```
+ */
+type DisplayMode = "inline" | "fullscreen" | "pip";
+/**
+ * Annotations for content blocks that provide hints to the host.
+ */
+interface ContentBlockAnnotations {
+    /** Who should see this content: user, assistant, or both */
+    audience?: Array<"user" | "assistant">;
+    /** ISO timestamp of last modification */
+    lastModified?: string;
+    /** Priority hint for content ordering (higher = more important) */
+    priority?: number;
+}
+interface ContentBlockBase {
+    /** Arbitrary metadata passed through to the host */
+    _meta?: Record<string, unknown>;
+    /** Annotations providing hints about the content */
+    annotations?: ContentBlockAnnotations;
+}
+/**
+ * Icon definition for resource links.
+ */
+interface ContentBlockIcon {
+    /** URL or data URI of the icon */
+    src: string;
+    /** MIME type of the icon (e.g., "image/png") */
+    mimeType?: string;
+    /** Available sizes (e.g., ["16x16", "32x32"]) */
+    sizes?: string[];
+    /** Which theme this icon is for */
+    theme?: "light" | "dark";
+}
+/**
+ * Text content block for plain text responses.
+ *
+ * @example
+ * ```ts
+ * const block: TextContentBlock = { type: "text", text: "Hello, world!" };
+ * // Or use the helper:
+ * const block = textBlock("Hello, world!");
+ * ```
+ */
+interface TextContentBlock extends ContentBlockBase {
+    type: "text";
+    /** The text content */
+    text: string;
+}
+/**
+ * Image content block for inline images.
+ *
+ * @example
+ * ```ts
+ * const block = imageBlock(base64Data, "image/png");
+ * ```
+ */
+interface ImageContentBlock extends ContentBlockBase {
+    type: "image";
+    /** Base64-encoded image data */
+    data: string;
+    /** MIME type (e.g., "image/png", "image/jpeg") */
+    mimeType: string;
+}
+/**
+ * Audio content block for inline audio.
+ */
+interface AudioContentBlock extends ContentBlockBase {
+    type: "audio";
+    /** Base64-encoded audio data */
+    data: string;
+    /** MIME type (e.g., "audio/mp3", "audio/wav") */
+    mimeType: string;
+}
+/**
+ * Resource link content block for clickable links to external resources.
+ */
+interface ResourceLinkContentBlock extends ContentBlockBase {
+    type: "resource_link";
+    /** URI of the resource */
+    uri: string;
+    /** Display name */
+    name: string;
+    /** Optional title for tooltip */
+    title?: string;
+    /** Optional description text */
+    description?: string;
+    /** MIME type of the linked resource */
+    mimeType?: string;
+    /** Icons to display with the link */
+    icons?: ContentBlockIcon[];
+}
+/**
+ * Embedded resource content block.
+ */
+interface ResourceContentBlock extends ContentBlockBase {
+    type: "resource";
+    resource: {
+        /** URI identifying the resource */
+        uri: string;
+        /** MIME type of the resource */
+        mimeType?: string;
+    } & ({
+        text: string;
+        blob?: never;
+    } | {
+        blob: string;
+        text?: never;
+    });
+}
+/**
+ * Union type for all content block types.
+ * Used in tool results and chat messages.
+ */
+type ContentBlock = TextContentBlock | ImageContentBlock | AudioContentBlock | ResourceLinkContentBlock | ResourceContentBlock;
+/**
+ * Creates a text content block.
+ *
+ * @param text - The text content
+ * @param annotations - Optional annotations
+ * @returns A TextContentBlock object
+ *
+ * @example
+ * ```ts
+ * const result: ToolResult = {
+ *   content: [textBlock("Operation completed successfully")]
+ * };
+ * ```
+ */
+declare function textBlock(text: string, annotations?: ContentBlockAnnotations): TextContentBlock;
+/**
+ * Creates an image content block.
+ *
+ * @param data - Base64-encoded image data
+ * @param mimeType - MIME type (e.g., "image/png")
+ * @param annotations - Optional annotations
+ * @returns An ImageContentBlock object
+ *
+ * @example
+ * ```ts
+ * const screenshot = await captureScreen();
+ * const result: ToolResult = {
+ *   content: [imageBlock(screenshot, "image/png")]
+ * };
+ * ```
+ */
+declare function imageBlock(data: string, mimeType: string, annotations?: ContentBlockAnnotations): ImageContentBlock;
+/**
+ * Result returned from a tool call.
+ * Use with `useCallTool()` hook to call tools and handle responses.
+ *
+ * @example
+ * ```tsx
+ * const callTool = useCallTool();
+ * const result = await callTool('search', { query: 'restaurants' });
+ * if (result.isError) {
+ *   console.error('Tool failed:', result.content);
+ * }
+ * ```
+ */
+interface ToolResult {
+    /** Content blocks with the result (text, images, etc.) */
+    content?: ContentBlock[];
+    /** Structured JSON data for programmatic access */
+    structuredContent?: Record<string, unknown>;
+    /** Whether the tool call resulted in an error */
+    isError?: boolean;
+    /** Arbitrary metadata from the tool */
+    _meta?: Record<string, unknown>;
+}
+/**
+ * Container dimensions provided by the host.
+ */
+interface ContainerDimensions {
+    /** Current height in pixels */
+    height?: number;
+    /** Maximum allowed height */
+    maxHeight?: number;
+    /** Current width in pixels */
+    width?: number;
+    /** Maximum allowed width */
+    maxWidth?: number;
+}
+/**
+ * CSS styling hints from the host.
+ */
+interface HostStyles {
+    /** CSS custom properties (variables) from the host */
+    variables?: Record<string, string>;
+    css?: {
+        /** Font CSS to inject for consistent typography */
+        fonts?: string;
+    };
+}
+/**
+ * Context information about the host environment.
+ * Access via `useHostContext()` hook.
+ *
+ * @example
+ * ```tsx
+ * const context = useHostContext();
+ * console.log('Theme:', context?.theme);
+ * console.log('Locale:', context?.locale);
+ * console.log('Display mode:', context?.displayMode);
+ * ```
+ */
+interface HostContext {
+    /** Current color theme ("light" or "dark") */
+    theme?: Theme;
+    /** User's locale (e.g., "en-US", "ja-JP") */
+    locale?: string;
+    /** User's timezone (e.g., "America/New_York") */
+    timeZone?: string;
+    /** Current display mode */
+    displayMode?: DisplayMode;
+    /** Display modes the host supports */
+    availableDisplayModes?: DisplayMode[];
+    /** Container size constraints */
+    containerDimensions?: ContainerDimensions;
+    /** Host-provided styling hints */
+    styles?: HostStyles;
+    /** Platform type (web, desktop, mobile) */
+    platform?: "web" | "desktop" | "mobile";
+    /** Device input capabilities */
+    deviceCapabilities?: {
+        /** Device has touch input */
+        touch?: boolean;
+        /** Device has hover capability (mouse) */
+        hover?: boolean;
+    };
+    /** Safe area insets for notched devices */
+    safeAreaInsets?: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    /** User agent string */
+    userAgent?: string;
+    /** Information about the tool that invoked this widget */
+    toolInfo?: {
+        /** Unique identifier for this tool call */
+        id?: string | number;
+        tool: {
+            /** Name of the tool */
+            name: string;
+            /** Tool description */
+            description?: string;
+            /** JSON Schema for tool input */
+            inputSchema?: Record<string, unknown>;
+        };
+    };
+}
+/**
+ * Chat message to send to the conversation.
+ * Used with `useSendMessage()` hook.
+ */
+interface ChatMessage {
+    /** Message role (currently only "user" supported) */
+    role: "user";
+    /** Message content blocks */
+    content: ContentBlock[];
+}
+
+/**
+ * Feature keys that can be checked with `useFeature()` hook.
+ * These correspond to boolean capabilities in `HostCapabilities`.
+ */
+type FeatureKey = "callTool" | "openLink" | "sizeReporting" | "closeWidget" | "sendMessage" | "modal" | "fileUpload" | "fileDownload" | "widgetState" | "modelContext" | "logging" | "partialToolInput" | "toolCancellation" | "teardown";
+/**
+ * Capabilities supported by the host platform.
+ * Use `useCapabilities()` hook to access these at runtime.
+ *
+ * @example
+ * ```tsx
+ * const capabilities = useCapabilities();
+ * if (capabilities?.widgetState) {
+ *   // ChatGPT-specific feature
+ * }
+ * ```
+ */
+interface HostCapabilities {
+    /** The platform this capability set is for */
+    platform: Platform;
+    /** Can call tools registered with the host */
+    callTool: boolean;
+    /** Can open external links */
+    openLink: boolean;
+    /** Supported display modes */
+    displayModes: DisplayMode[];
+    /** Can report widget size to host */
+    sizeReporting: boolean;
+    /** Can request widget close */
+    closeWidget: boolean;
+    /** Can send messages to conversation */
+    sendMessage: boolean;
+    /** Can request modal dialogs */
+    modal: boolean;
+    /** Can upload files (ChatGPT only) */
+    fileUpload: boolean;
+    /** Can download files (ChatGPT only) */
+    fileDownload: boolean;
+    /** Can persist widget state (ChatGPT only) */
+    widgetState: boolean;
+    /** Can update model context (MCP only) */
+    modelContext: boolean;
+    /** Structured logging support (MCP only) */
+    logging: boolean;
+    /** Partial/streaming tool input (MCP only) */
+    partialToolInput: boolean;
+    /** Tool cancellation support (MCP only) */
+    toolCancellation: boolean;
+    /** Teardown notification support (MCP only) */
+    teardown: boolean;
+}
+/**
+ * Capabilities available on ChatGPT.
+ *
+ * Notable features:
+ * - `widgetState`: Persistent state across refreshes
+ * - `fileUpload`/`fileDownload`: File handling
+ * - `modal`: Modal dialog support
+ * - `pip`: Picture-in-picture display mode
+ */
+declare const CHATGPT_CAPABILITIES: HostCapabilities;
+/**
+ * Capabilities available on MCP hosts (e.g., Claude Desktop).
+ *
+ * Notable features:
+ * - `modelContext`: Update model context dynamically
+ * - `logging`: Structured logging to host
+ * - `partialToolInput`: Streaming input support
+ * - `toolCancellation`: Handle cancelled tool calls
+ * - `teardown`: Cleanup notification
+ */
+declare const MCP_CAPABILITIES: HostCapabilities;
+/**
+ * Check if a specific feature is available.
+ *
+ * @param capabilities - The host capabilities object
+ * @param feature - The feature key to check
+ * @returns Whether the feature is available
+ *
+ * @example
+ * ```ts
+ * if (hasFeature(capabilities, 'widgetState')) {
+ *   // Safe to use widget state
+ * }
+ * ```
+ */
+declare function hasFeature(capabilities: HostCapabilities | null, feature: FeatureKey): boolean;
+
+type ToolInputCallback = (args: Record<string, unknown>) => void;
+type ToolInputPartialCallback = (args: Record<string, unknown>) => void;
+type ToolResultCallback = (result: ToolResult) => void;
+type ToolCancelledCallback = (reason: string) => void;
+type HostContextChangedCallback = (ctx: Partial<HostContext>) => void;
+type TeardownCallback = () => Promise<void> | void;
+interface HostBridge {
+    readonly platform: "chatgpt" | "mcp";
+    readonly capabilities: HostCapabilities;
+    connect(): Promise<void>;
+    getHostContext(): HostContext | null;
+    onToolInput(callback: ToolInputCallback): () => void;
+    onToolResult(callback: ToolResultCallback): () => void;
+    onHostContextChanged(callback: HostContextChangedCallback): () => void;
+    callTool(name: string, args: Record<string, unknown>): Promise<ToolResult>;
+    openLink(url: string): Promise<void>;
+    requestDisplayMode(mode: DisplayMode): Promise<DisplayMode>;
+    sendSizeChanged(size: {
+        width?: number;
+        height?: number;
+    }): void;
+}
+interface ExtendedBridge extends HostBridge {
+    onToolInputPartial?(callback: ToolInputPartialCallback): () => void;
+    onToolCancelled?(callback: ToolCancelledCallback): () => void;
+    onTeardown?(callback: TeardownCallback): () => void;
+    sendMessage?(message: ChatMessage): Promise<void>;
+    updateModelContext?(ctx: {
+        content?: ContentBlock[];
+        structuredContent?: Record<string, unknown>;
+    }): Promise<void>;
+    setWidgetState?(state: Record<string, unknown> | null): void;
+    getWidgetState?(): Record<string, unknown> | null;
+    uploadFile?(file: File): Promise<{
+        fileId: string;
+    }>;
+    getFileDownloadUrl?(fileId: string): Promise<{
+        downloadUrl: string;
+    }>;
+    requestClose?(): void;
+    requestModal?(options: {
+        title?: string;
+        params?: Record<string, unknown>;
+        anchor?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    }): Promise<void>;
+    sendLog?(level: "debug" | "info" | "warning" | "error", data: string): void;
+}
+
+export { type AudioContentBlock, CHATGPT_CAPABILITIES, type ChatMessage, type ContainerDimensions, type ContentBlock, type ContentBlockAnnotations, type ContentBlockIcon, type DisplayMode, type ExtendedBridge, type FeatureKey, type HostBridge, type HostCapabilities, type HostContext, type HostContextChangedCallback, type HostStyles, type ImageContentBlock, MCP_CAPABILITIES, type Platform, type ResourceContentBlock, type ResourceLinkContentBlock, type TeardownCallback, type TextContentBlock, type Theme, type ToolCancelledCallback, type ToolInputCallback, type ToolInputPartialCallback, type ToolResult, type ToolResultCallback, hasFeature, imageBlock, textBlock };

package/dist/core/index.js

@@ -0,0 +1,16 @@
+import {
+  imageBlock,
+  textBlock
+} from "../chunk-KRCGOYZ5.js";
+import {
+  CHATGPT_CAPABILITIES,
+  MCP_CAPABILITIES,
+  hasFeature
+} from "../chunk-4LAH4JH6.js";
+export {
+  CHATGPT_CAPABILITIES,
+  MCP_CAPABILITIES,
+  hasFeature,
+  imageBlock,
+  textBlock
+};