mcp-use/dist/src/server/widgets/mcp-ui-adapter.d.ts

Opinionated MCP Framework for TypeScript (@modelcontextprotocol/sdk compatible) - Build MCP Agents, Clients and Servers with support for ChatGPT Apps, Code Mode, OAuth, Notifications, Sampling, Observability and more.

/**
 * MCP-UI Adapter Utilities
 *
 * Pure functions to convert mcp-use high-level UIResource definitions
 * into @mcp-ui/server compatible resource objects.
 *
 * Ref: https://mcpui.dev/guide/server/typescript/usage-examples
 * Apps SDK: https://mcpui.dev/guide/apps-sdk
 * Official Apps SDK Docs: https://developers.openai.com/apps-sdk/build/mcp-server
 */
import { type AdaptersConfig } from "@mcp-ui/server";
import type { UIResourceContent, UIResourceDefinition, UIEncoding, AppsSdkMetadata } from "../types/resource.js";
/**
 * Configuration for building widget URLs
 */
export interface UrlConfig {
    baseUrl: string;
    port: number | string;
    buildId?: string;
}
/**
 * Build the full URL for a widget including query parameters
 *
 * @param widget - Widget identifier
 * @param props - Parameters to pass as a single JSON-encoded props param
 * @param config - URL configuration (baseUrl and port)
 * @returns Complete widget URL with encoded parameters
 */
export declare function buildWidgetUrl(widget: string, props: Record<string, any> | undefined, config: UrlConfig): string;
/**
 * Create a UIResource for an external URL (iframe)
 *
 * @param uri - Resource URI (must start with ui://)
 * @param iframeUrl - URL to load in iframe
 * @param encoding - Encoding type ('text' or 'blob')
 * @param adapters - Adapter configuration (e.g., Apps SDK)
 * @param metadata - Additional metadata for the resource
 * @returns UIResourceContent object
 */
export declare function createExternalUrlResource(uri: string, iframeUrl: string, encoding?: UIEncoding, adapters?: AdaptersConfig, metadata?: AppsSdkMetadata): Promise<UIResourceContent>;
/**
 * Create a UIResource for raw HTML content
 *
 * @param uri - Resource URI (must start with ui://)
 * @param htmlString - HTML content to render
 * @param encoding - Encoding type ('text' or 'blob')
 * @param adapters - Adapter configuration (e.g., Apps SDK)
 * @param metadata - Additional metadata for the resource
 * @returns UIResourceContent object
 */
export declare function createRawHtmlResource(uri: string, htmlString: string, encoding?: UIEncoding, adapters?: AdaptersConfig, metadata?: AppsSdkMetadata): Promise<UIResourceContent>;
/**
 * Create a UIResource for Remote DOM scripting
 *
 * @param uri - Resource URI (must start with ui://)
 * @param script - JavaScript code for remote DOM manipulation
 * @param framework - Framework for remote DOM ('react' or 'webcomponents')
 * @param encoding - Encoding type ('text' or 'blob')
 * @param adapters - Adapter configuration (e.g., Apps SDK)
 * @param metadata - Additional metadata for the resource
 * @returns UIResourceContent object
 */
export declare function createRemoteDomResource(uri: string, script: string, framework?: "react" | "webcomponents", encoding?: UIEncoding, adapters?: AdaptersConfig, metadata?: AppsSdkMetadata): Promise<UIResourceContent>;
/**
 * Create a UIResource for OpenAI Apps SDK
 *
 * This creates a resource compatible with OpenAI's Apps SDK using the
 * text/html+skybridge mime type. The HTML template should contain the
 * component code with embedded JS/CSS.
 *
 * The Apps SDK pattern:
 * - Uses mime type text/html+skybridge
 * - Tool's structuredContent gets injected as window.openai.toolOutput
 * - Supports Apps SDK metadata (CSP, widget domain, description, etc.)
 *
 * @param uri - Resource URI (must start with ui://)
 * @param htmlTemplate - HTML template with embedded component code
 * @param metadata - Apps SDK metadata (CSP, description, domain, etc.)
 * @returns UIResourceContent object
 *
 * @see https://developers.openai.com/apps-sdk/build/mcp-server
 * @see https://mcpui.dev/guide/apps-sdk
 *
 * @example
 * ```typescript
 * const resource = createAppsSdkResource(
 *   'ui://widget/kanban-board.html',
 *   `
 *     <div id="kanban-root"></div>
 *     <style>${kanbanCSS}</style>
 *     <script type="module">${kanbanJS}</script>
 *   `,
 *   {
 *     'openai/widgetDescription': 'Displays an interactive kanban board',
 *     'openai/widgetCSP': {
 *       connect_domains: [],
 *       resource_domains: ['https://cdn.example.com']
 *     },
 *     'openai/widgetPrefersBorder': true
 *   }
 * )
 * ```
 */
export declare function createAppsSdkResource(uri: string, htmlTemplate: string, metadata?: AppsSdkMetadata): UIResourceContent;
/**
 * Create a UIResource from a high-level definition
 *
 * This is the main function that routes to the appropriate resource creator
 * based on the discriminated union type.
 *
 * @param definition - UIResource definition (discriminated union)
 * @param params - Runtime parameters for the widget (for externalUrl type)
 * @param config - URL configuration for building widget URLs
 * @returns UIResourceContent object
 */
export declare function createUIResourceFromDefinition(definition: UIResourceDefinition, params: Record<string, any>, config: UrlConfig): Promise<UIResourceContent>;
//# sourceMappingURL=mcp-ui-adapter.d.ts.map