@creature-ai/sdk 0.1.1

package/dist/server/index.d.ts

@@ -0,0 +1,543 @@
+import { z } from 'zod';
+import { Server } from 'http';
+import { A as AppSessionOptions, W as WidgetState, a as AppSessionState, b as AppSessionListener } from '../types-DcoqlK46.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+/**
+ * MIME types for cross-platform compatibility.
+ */
+declare const MIME_TYPES: {
+    readonly MCP_APPS: "text/html;profile=mcp-app";
+    readonly CHATGPT: "text/html+skybridge";
+};
+/**
+ * Display modes for UI resources.
+ */
+type DisplayMode = "pip" | "inline" | "fullscreen";
+/**
+ * Visibility options for tools.
+ * - "model": AI/Agent can call the tool
+ * - "app": UI can call the tool
+ */
+type ToolVisibility = "model" | "app";
+/**
+ * Icon configuration for UI resources.
+ */
+interface IconConfig {
+    /** SVG string (must use currentColor for theming) */
+    svg: string;
+    /** Alt text for accessibility */
+    alt: string;
+}
+/**
+ * Resource configuration.
+ */
+interface ResourceConfig {
+    /** Display name shown in UI */
+    name: string;
+    /** Resource URI (must start with ui://) */
+    uri: string;
+    /** Optional description */
+    description?: string;
+    /** Supported display modes */
+    displayModes: DisplayMode[];
+    /**
+     * HTML content for the resource.
+     * Can be a string path (resolved relative to the server file's directory),
+     * or a function that returns the HTML content.
+     *
+     * @example
+     * // Simple path (recommended)
+     * html: "ui/main.html"
+     *
+     * // Function for dynamic content
+     * html: () => loadHtml("./ui/main.html")
+     */
+    html: string | (() => string | Promise<string>);
+    /** Optional icon for pips */
+    icon?: IconConfig;
+    /** CSP configuration for external API access */
+    csp?: {
+        connectDomains?: string[];
+        resourceDomains?: string[];
+    };
+}
+/**
+ * Tool configuration.
+ */
+interface ToolConfig<TInput extends z.ZodType = z.ZodType> {
+    /** Tool description (shown to AI) */
+    description: string;
+    /** Zod schema for input validation */
+    input?: TInput;
+    /** Resource URI to link this tool to a UI */
+    ui?: string;
+    /** Who can call this tool */
+    visibility?: ToolVisibility[];
+    /** Supported display modes for this tool */
+    displayModes?: DisplayMode[];
+    /** Preferred display mode */
+    defaultDisplayMode?: DisplayMode;
+    /**
+     * Whether this tool creates new sessions (multi-instance MCP).
+     * When true, the Host will always create a new pip instead of
+     * reusing an existing one for the same resourceUri.
+     * Use this for tools that spawn independent sessions (e.g., terminal_run).
+     */
+    multiSession?: boolean;
+    /** Loading message shown while tool is running (used by ChatGPT) */
+    loadingMessage?: string;
+    /** Completion message shown when tool finishes (used by ChatGPT) */
+    completedMessage?: string;
+}
+/**
+ * Tool result returned from handler.
+ */
+interface ToolResult {
+    /** Structured data for UI rendering */
+    data?: Record<string, unknown>;
+    /** Text content for AI context */
+    text?: string;
+    /** Title for panel/widget */
+    title?: string;
+    /** Height hint for inline widgets (60-300px) */
+    inlineHeight?: number;
+    /** Whether this is an error result */
+    isError?: boolean;
+}
+/**
+ * Tool handler function type.
+ */
+type ToolHandler<TInput> = (input: TInput, context: ToolContext) => ToolResult | Promise<ToolResult>;
+/**
+ * Context passed to tool handlers.
+ * Reserved for future use.
+ */
+interface ToolContext {
+}
+/**
+ * Resource cache configuration.
+ * Controls caching behavior for UI resource HTML content.
+ */
+interface ResourceCacheConfig {
+    /** Maximum number of cached entries (default: 100) */
+    maxSize?: number;
+    /** Time-to-live in milliseconds. 0 = no expiry (default: 0) */
+    ttlMs?: number;
+    /** Whether caching is enabled (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Supported MCP transport types.
+ * Currently only StreamableHTTP is supported by the SDK server.
+ * Stdio may be added in the future.
+ */
+type TransportType = "streamable-http" | "stdio";
+/**
+ * Information about a transport session.
+ * Provides details about an active MCP protocol connection.
+ */
+interface TransportSessionInfo {
+    /** Unique session identifier */
+    id: string;
+    /** The transport type for this session */
+    transport: TransportType;
+}
+/**
+ * App configuration.
+ */
+interface AppConfig {
+    /** App name (used in protocol handshake) */
+    name: string;
+    /** App version */
+    version: string;
+    /** Port for HTTP transport (default: 3000 or MCP_PORT env) */
+    port?: number;
+    /** Enable dev mode with HMR support (default: auto-detect from NODE_ENV) */
+    dev?: boolean;
+    /** HMR port override (default: auto-detect from Vite config or 5173) */
+    hmrPort?: number;
+    /**
+     * Called when a new transport session is created.
+     * Transport sessions are MCP protocol connections (not AppSessions).
+     */
+    onTransportSessionCreated?: (info: TransportSessionInfo) => void;
+    /**
+     * Called when a transport session is closed.
+     * Clients should re-initialize to continue.
+     */
+    onTransportSessionClosed?: (info: TransportSessionInfo) => void;
+    /**
+     * Called when a transport session error occurs.
+     * Useful for logging and monitoring connection health.
+     */
+    onTransportSessionError?: (info: TransportSessionInfo, error: Error) => void;
+    /**
+     * Called when a tool handler throws an error.
+     * The error is still returned to the client as an MCP error.
+     */
+    onToolError?: (toolName: string, error: Error, args: unknown) => void;
+    /**
+     * Called during graceful shutdown, before closing connections.
+     * Use this to clean up resources (e.g., close database connections).
+     */
+    onShutdown?: () => Promise<void> | void;
+    /**
+     * Timeout for graceful shutdown in milliseconds (default: 5000).
+     * After this timeout, remaining connections are force-closed.
+     */
+    gracefulShutdownTimeout?: number;
+    /**
+     * HTTP keep-alive timeout during shutdown in milliseconds (default: 5000).
+     * Controls how long to wait for in-flight requests to complete.
+     */
+    keepAliveTimeout?: number;
+    /**
+     * Configuration for resource content caching.
+     * Resources are cached to avoid repeated file reads.
+     */
+    resourceCache?: ResourceCacheConfig;
+}
+
+/**
+ * WebSocket channel support for real-time bidirectional communication.
+ *
+ * Channels provide a type-safe abstraction over WebSockets, allowing MCP Apps
+ * to stream data to connected UIs without polling.
+ */
+
+/**
+ * Handler for incoming client messages.
+ */
+type MessageHandler<T> = (message: T) => void;
+/**
+ * Configuration for a channel definition.
+ */
+interface ChannelConfig<_TServer = unknown, _TClient = unknown> {
+    /** Zod schema for server → client messages (optional, for documentation) */
+    server?: z.ZodType;
+    /** Zod schema for client → server messages (validated on receive) */
+    client?: z.ZodType;
+}
+/**
+ * A WebSocket channel instance for a specific AppSession.
+ *
+ * This provides real-time bidirectional communication between the server
+ * and all UI clients connected to a particular AppSession.
+ */
+interface AppSessionChannel<TServer = unknown, TClient = unknown> {
+    /** The AppSession ID this channel belongs to */
+    appSessionId: string;
+    /** WebSocket URL for clients to connect */
+    url: string;
+    /** Send a message to all connected clients */
+    send: (message: TServer) => void;
+    /** Register a handler for incoming client messages */
+    onMessage: (handler: MessageHandler<TClient>) => void;
+    /** Register a handler called when a new client connects */
+    onConnect: (handler: () => void) => void;
+    /** Close the channel and disconnect all clients */
+    close: () => void;
+    /** Number of connected clients */
+    readonly clientCount: number;
+}
+/**
+ * Manages WebSocket connections and routes messages to AppSession channels.
+ */
+declare class ChannelManager {
+    private wss;
+    private channels;
+    /**
+     * Attach the WebSocket server to an HTTP server.
+     */
+    attach(server: Server): void;
+    /**
+     * Create a new channel for an AppSession.
+     *
+     * @param channelName - The channel name (e.g., "updates", "terminal")
+     * @param appSessionId - The AppSession ID this channel belongs to
+     * @param config - Channel configuration
+     * @param port - Server port for WebSocket URL
+     * @returns An AppSessionChannel for bidirectional communication
+     */
+    createChannel<TServer, TClient>(channelName: string, appSessionId: string, config: ChannelConfig<TServer, TClient>, port: number): AppSessionChannel<TServer, TClient>;
+    /**
+     * Check if a channel exists for an AppSession.
+     */
+    hasChannel(channelName: string, appSessionId: string): boolean;
+    /**
+     * Check if any channels exist.
+     */
+    hasAnyChannels(): boolean;
+    /**
+     * Close all channels and shut down the WebSocket server.
+     */
+    closeAll(): void;
+}
+/**
+ * A channel definition that can create AppSession channel instances.
+ */
+declare class ChannelDefinition<TServer = unknown, TClient = unknown> {
+    private manager;
+    private name;
+    private config;
+    private getPort;
+    constructor(manager: ChannelManager, name: string, config: ChannelConfig<TServer, TClient>, getPort: () => number);
+    /**
+     * Create a channel for a specific AppSession.
+     *
+     * @param appSessionId - The AppSession ID (e.g., from a terminal AppSession)
+     * @returns An AppSessionChannel for bidirectional communication
+     */
+    forAppSession(appSessionId: string): AppSessionChannel<TServer, TClient>;
+    /**
+     * Check if a channel exists for an AppSession.
+     */
+    hasChannel(appSessionId: string): boolean;
+    /**
+     * Get the channel name.
+     */
+    get channelName(): string;
+}
+
+type PartialState<TState extends AppSessionState> = {
+    [K in keyof TState]?: Partial<TState[K]> | TState[K];
+};
+interface ServerAppSessionOptions extends AppSessionOptions {
+    websockets?: boolean;
+}
+/**
+ * Server-side AppSession for managing application state.
+ *
+ * AppSessions are distinct from TransportSessions:
+ * - AppSession: Application-level state (internal, backend, ui)
+ * - TransportSession: MCP protocol connection (StreamableHTTP session)
+ */
+declare class ServerAppSession<TInternal extends Record<string, unknown> = Record<string, unknown>, TBackend extends Record<string, unknown> = Record<string, unknown>, TUi extends WidgetState | null = WidgetState | null> {
+    readonly id: string;
+    private _state;
+    private listeners;
+    private _channel;
+    constructor(initialState?: Partial<AppSessionState<TInternal, TBackend, TUi>>, options?: {
+        id?: string;
+    });
+    private generateId;
+    get state(): AppSessionState<TInternal, TBackend, TUi>;
+    get internal(): TInternal;
+    get backend(): TBackend;
+    get ui(): TUi;
+    get channel(): AppSessionChannel<unknown, unknown> | null;
+    get channelUrl(): string | undefined;
+    setChannel(channel: AppSessionChannel<unknown, unknown>): void;
+    subscribe(listener: AppSessionListener<AppSessionState<TInternal, TBackend, TUi>>): () => void;
+    private notify;
+    setState(partial: PartialState<AppSessionState<TInternal, TBackend, TUi>>): void;
+    setInternal(internal: TInternal | Partial<TInternal>): void;
+    setBackend(backend: TBackend | Partial<TBackend>): void;
+    setUi(ui: TUi): void;
+    updateUi(partial: TUi extends null ? never : Partial<NonNullable<TUi>>): void;
+    injectAppSessionId<T extends Record<string, unknown>>(data: T): T & {
+        appSessionId: string;
+    };
+    close(): void;
+}
+/**
+ * Manages ServerAppSession instances.
+ *
+ * This manages AppSessions (application state), not TransportSessions
+ * (MCP protocol connections).
+ */
+declare class AppSessionManager {
+    private appSessions;
+    private channelManager;
+    private getPort;
+    private appSessionChannelName;
+    constructor(config: {
+        channelManager?: ChannelManager;
+        getPort: () => number;
+    });
+    setChannelManager(channelManager: ChannelManager): void;
+    create<TInternal extends Record<string, unknown> = Record<string, unknown>, TBackend extends Record<string, unknown> = Record<string, unknown>, TUi extends WidgetState | null = WidgetState | null>(initialState?: Partial<AppSessionState<TInternal, TBackend, TUi>>, options?: ServerAppSessionOptions): ServerAppSession<TInternal, TBackend, TUi>;
+    get(id: string): ServerAppSession | undefined;
+    require(id: string): ServerAppSession;
+    has(id: string): boolean;
+    delete(id: string): boolean;
+    closeAll(): void;
+    get size(): number;
+}
+
+declare class App {
+    private config;
+    private tools;
+    private resources;
+    private transports;
+    private channelManager;
+    private channels;
+    private appSessionManager;
+    private httpServer;
+    private isDev;
+    private hmrPort;
+    private hmrConfigChecked;
+    private callerDir;
+    private shutdownRegistered;
+    private isShuttingDown;
+    private resourceCache;
+    private resourceCacheConfig;
+    constructor(config: AppConfig, callerDir?: string);
+    /**
+     * Get list of active transport sessions.
+     * Transport sessions are MCP protocol connections (not AppSessions).
+     * Useful for monitoring and debugging connection state.
+     */
+    getTransportSessions(): TransportSessionInfo[];
+    /**
+     * Get the count of active transport sessions.
+     */
+    getTransportSessionCount(): number;
+    /**
+     * Close a specific transport session.
+     *
+     * @param sessionId - The transport session ID to close
+     * @returns true if the session was found and closed
+     */
+    closeTransportSession(sessionId: string): boolean;
+    /**
+     * Clear all cached resource content.
+     * Use after updating UI files during development.
+     */
+    clearResourceCache(): void;
+    /**
+     * Clear a specific resource from the cache.
+     *
+     * @param uri - The resource URI to clear
+     * @returns true if the resource was in the cache and removed
+     */
+    clearResourceCacheEntry(uri: string): boolean;
+    /**
+     * Get resource cache statistics.
+     * Useful for monitoring cache performance.
+     */
+    getResourceCacheStats(): {
+        size: number;
+        maxSize: number;
+        enabled: boolean;
+    };
+    /**
+     * Get a cached resource if valid, or null if not cached/expired.
+     */
+    private getCachedResource;
+    /**
+     * Store a resource in the cache with LRU eviction.
+     */
+    private setCachedResource;
+    /**
+     * Get the HMR port, reading from hmr.json lazily if not already set.
+     * This handles the timing issue where Vite may not have written hmr.json
+     * when the server first starts.
+     */
+    private getHmrPort;
+    private getCallerDir;
+    /**
+     * Define a UI resource.
+     */
+    resource(config: ResourceConfig): this;
+    tool<TInput extends z.ZodType>(name: string, config: ToolConfig<TInput>, handler: ToolHandler<z.infer<TInput>>): this;
+    channel<TServer = unknown, TClient = unknown>(name: string, config?: ChannelConfig<TServer, TClient>): ChannelDefinition<TServer, TClient>;
+    private getPort;
+    session<TInternal extends Record<string, unknown> = Record<string, unknown>, TBackend extends Record<string, unknown> = Record<string, unknown>, TUi extends WidgetState | null = WidgetState | null>(initialState?: Partial<AppSessionState<TInternal, TBackend, TUi>>, options?: ServerAppSessionOptions): ServerAppSession<TInternal, TBackend, TUi>;
+    getSession(id: string): ServerAppSession | undefined;
+    requireSession(id: string): ServerAppSession;
+    hasSession(id: string): boolean;
+    closeSession(id: string): boolean;
+    /**
+     * Create an MCP server instance with all registered tools and resources.
+     */
+    private createMcpServer;
+    /**
+     * Format a tool result into MCP format.
+     */
+    private formatToolResult;
+    start(): Promise<void>;
+    /**
+     * Stop the MCP server gracefully.
+     *
+     * Calls the onShutdown callback, closes all sessions and channels,
+     * then waits for active transports to close (with timeout).
+     */
+    stop(): Promise<void>;
+}
+/**
+ * Create a new MCP App.
+ */
+declare function createApp(config: AppConfig): App;
+
+declare function svgToDataUri(svg: string): string;
+/**
+ * Load HTML from a file path.
+ * Automatically resolves paths like "ui/main.html" to "dist/ui/main.html"
+ * regardless of whether running from src/ or dist/.
+ */
+declare function loadHtml(filePath: string, basePath?: string): string;
+/**
+ * Create an HTML loader function for a file path.
+ * Useful for defining resources with lazy-loaded HTML.
+ */
+declare function htmlLoader(filePath: string, basePath?: string): () => string;
+
+/**
+ * Middleware for adding cross-platform compatibility to the official MCP SDK.
+ *
+ * Wrap your McpServer to automatically output dual formats for both
+ * MCP Apps (Creature) and ChatGPT Apps SDK.
+ *
+ * @example
+ * ```ts
+ * import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+ * import { wrapServer } from "@creature-ai/sdk/server";
+ *
+ * const server = wrapServer(new McpServer({ name: "my-app", version: "1.0.0" }));
+ *
+ * // Use the standard MCP SDK API - dual format is automatic
+ * server.registerResource("Panel", "ui://app/panel", { ... }, handler);
+ * server.registerTool("search", { ... }, handler);
+ * ```
+ */
+
+/**
+ * Wrap an McpServer to automatically add dual-format support.
+ *
+ * This intercepts `registerResource` and `registerTool` calls to automatically
+ * include both MCP Apps and ChatGPT metadata/MIME types.
+ *
+ * @param server - An McpServer instance from @modelcontextprotocol/sdk
+ * @returns The same server with intercepted registration methods
+ *
+ * @example
+ * ```ts
+ * import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+ * import { wrapServer } from "@creature-ai/sdk/server";
+ *
+ * const server = wrapServer(new McpServer({ name: "my-app", version: "1.0.0" }));
+ *
+ * // Register resources normally - dual MIME types added automatically
+ * server.registerResource("Panel", "ui://app/panel", {
+ *   mimeType: "text/html",
+ *   description: "My panel",
+ * }, async () => ({
+ *   contents: [{ uri: "ui://app/panel", mimeType: "text/html", text: html }],
+ * }));
+ *
+ * // Register tools normally - dual metadata added automatically
+ * server.registerTool("search", {
+ *   description: "Search",
+ *   inputSchema: z.object({ query: z.string() }),
+ *   _meta: {
+ *     ui: { resourceUri: "ui://app/panel", displayModes: ["pip"] },
+ *     loadingMessage: "Searching...",  // Will become openai/toolInvocation/invoking
+ *   },
+ * }, handler);
+ * ```
+ */
+declare function wrapServer<T extends McpServer>(server: T): T;
+
+export { App, type AppConfig, type AppSessionChannel, AppSessionListener, AppSessionManager, AppSessionOptions, AppSessionState, type ChannelConfig, ChannelDefinition, type DisplayMode, type IconConfig, MIME_TYPES, type ResourceCacheConfig, type ResourceConfig, ServerAppSession, type ServerAppSessionOptions, type ToolConfig, type ToolContext, type ToolHandler, type ToolResult, type ToolVisibility, type TransportSessionInfo, type TransportType, createApp, htmlLoader, loadHtml, svgToDataUri, wrapServer };