skybridge 0.0.0-dev.4f33eea → 0.0.0-dev.51c9c19

package/dist/src/web/hooks/use-mcp-app-bridge.d.ts

@@ -0,0 +1,22 @@
+import { type McpUiHostContext, type McpUiInitializeRequest } from "../types/ext-apps.js";
+type McpAppInitializationOptions = Pick<McpUiInitializeRequest["params"], "appInfo">;
+export declare class McpAppBridge {
+    context: McpUiHostContext | null;
+    private listeners;
+    private pendingRequests;
+    private nextId;
+    private initialized;
+    private appInitializationOptions;
+    constructor(options: McpAppInitializationOptions);
+    subscribe: (onChange: () => void) => () => boolean;
+    private request;
+    private emit;
+    private setContext;
+    private init;
+    private handleMessage;
+    private connect;
+    private notify;
+}
+export declare function getMcpHost(options?: Partial<McpAppInitializationOptions>): McpAppBridge;
+export declare function useMcpAppBridge<K extends keyof McpUiHostContext>(key: K, options?: Partial<McpAppInitializationOptions>): McpUiHostContext[K] | undefined;
+export {};

package/dist/src/web/hooks/use-mcp-app-bridge.js

@@ -0,0 +1,105 @@
+import { useSyncExternalStore } from "react";
+import { LATEST_PROTOCOL_VERSION, } from "../types/ext-apps.js";
+export class McpAppBridge {
+    context = null;
+    listeners = new Set();
+    pendingRequests = new Map();
+    nextId = 1;
+    initialized;
+    appInitializationOptions;
+    constructor(options) {
+        this.initialized = false;
+        this.appInitializationOptions = {
+            appInfo: options.appInfo,
+            appCapabilities: {},
+            protocolVersion: LATEST_PROTOCOL_VERSION,
+        };
+    }
+    subscribe = (onChange) => {
+        this.listeners.add(onChange);
+        this.init();
+        return () => this.listeners.delete(onChange);
+    };
+    request({ method, params, }) {
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            this.pendingRequests.set(id, {
+                resolve: resolve,
+                reject,
+            });
+            window.parent.postMessage({ jsonrpc: "2.0", id, method, params }, "*");
+        });
+    }
+    emit() {
+        this.listeners.forEach((l) => {
+            l();
+        });
+    }
+    setContext(context) {
+        if (context !== undefined)
+            this.context = context;
+        this.emit();
+    }
+    init() {
+        if (this.initialized)
+            return;
+        this.initialized = true;
+        if (typeof window === "undefined" || window.parent === window) {
+            return;
+        }
+        window.addEventListener("message", this.handleMessage);
+        this.connect();
+    }
+    handleMessage = (event) => {
+        const data = event.data;
+        if (data?.jsonrpc !== "2.0")
+            return;
+        if (data.id !== undefined && this.pendingRequests.has(data.id)) {
+            const request = this.pendingRequests.get(data.id);
+            if (request) {
+                this.pendingRequests.delete(data.id);
+                if (data.error) {
+                    request.reject(new Error(data.error.message));
+                }
+                else {
+                    request.resolve(data.result);
+                }
+            }
+            return;
+        }
+        if (data.method === "ui/notifications/host-context-changed") {
+            this.setContext({ ...this.context, ...data.params });
+        }
+    };
+    async connect() {
+        try {
+            const result = await this.request({
+                method: "ui/initialize",
+                params: this.appInitializationOptions,
+            });
+            this.setContext(result.hostContext);
+            this.notify({ method: "ui/notifications/initialized" });
+        }
+        catch (err) {
+            console.error(err);
+        }
+    }
+    notify(notification) {
+        window.parent.postMessage({ jsonrpc: "2.0", ...notification }, "*");
+    }
+}
+let instance = null;
+const defaultOptions = {
+    appInfo: { name: "skybridge-app", version: "0.0.1" },
+};
+export function getMcpHost(options) {
+    if (!instance) {
+        instance = new McpAppBridge({ ...defaultOptions, ...options });
+    }
+    return instance;
+}
+export function useMcpAppBridge(key, options) {
+    const host = getMcpHost(options);
+    return useSyncExternalStore(host.subscribe, () => host.context?.[key]);
+}
+//# sourceMappingURL=use-mcp-app-bridge.js.map

package/dist/src/web/hooks/use-mcp-app-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-mcp-app-bridge.js","sourceRoot":"","sources":["../../../../src/web/hooks/use-mcp-app-bridge.ts"],"names":[],"mappings":"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"}

package/dist/src/web/hooks/use-mcp-app-bridge.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/web/hooks/use-mcp-app-bridge.test.js

@@ -0,0 +1,46 @@
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+describe("useMcpAppBridge", () => {
+    let mockPostMessage;
+    const useHook = async () => {
+        const { useMcpAppBridge } = await import("./use-mcp-app-bridge.js");
+        return useMcpAppBridge;
+    };
+    beforeEach(() => {
+        vi.resetModules();
+        mockPostMessage = vi.fn();
+        Object.defineProperty(window, "parent", {
+            value: { postMessage: mockPostMessage },
+            writable: true,
+            configurable: true,
+        });
+    });
+    afterEach(() => {
+        vi.clearAllMocks();
+    });
+    it("should return the theme value from host context", async () => {
+        const useMcpAppBridge = await useHook();
+        const { result } = renderHook(() => useMcpAppBridge("theme"));
+        const initCall = mockPostMessage.mock.calls.find((call) => call[0].method === "ui/initialize");
+        if (initCall) {
+            act(() => {
+                window.dispatchEvent(new MessageEvent("message", {
+                    data: {
+                        jsonrpc: "2.0",
+                        id: initCall[0].id,
+                        result: {
+                            protocolVersion: "2025-06-18",
+                            hostInfo: { name: "test-host", version: "1.0.0" },
+                            hostCapabilities: {},
+                            hostContext: { theme: "light" },
+                        },
+                    },
+                }));
+            });
+        }
+        await waitFor(() => {
+            expect(result.current).toBe("light");
+        });
+    });
+});
+//# sourceMappingURL=use-mcp-app-bridge.test.js.map

package/dist/src/web/hooks/use-mcp-app-bridge.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-mcp-app-bridge.test.js","sourceRoot":"","sources":["../../../../src/web/hooks/use-mcp-app-bridge.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAEzE,QAAQ,CAAC,iBAAiB,EAAE,GAAG,EAAE;IAC/B,IAAI,eAAyC,CAAC;IAE9C,MAAM,OAAO,GAAG,KAAK,IAAI,EAAE;QACzB,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,MAAM,CAAC,yBAAyB,CAAC,CAAC;QACpE,OAAO,eAAe,CAAC;IACzB,CAAC,CAAC;IAEF,UAAU,CAAC,GAAG,EAAE;QACd,EAAE,CAAC,YAAY,EAAE,CAAC;QAClB,eAAe,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QAC1B,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,QAAQ,EAAE;YACtC,KAAK,EAAE,EAAE,WAAW,EAAE,eAAe,EAAE;YACvC,QAAQ,EAAE,IAAI;YACd,YAAY,EAAE,IAAI;SACnB,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,EAAE;QACb,EAAE,CAAC,aAAa,EAAE,CAAC;IACrB,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iDAAiD,EAAE,KAAK,IAAI,EAAE;QAC/D,MAAM,eAAe,GAAG,MAAM,OAAO,EAAE,CAAC;QACxC,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC;QAE9D,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAC9C,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,eAAe,CAC7C,CAAC;QAEF,IAAI,QAAQ,EAAE,CAAC;YACb,GAAG,CAAC,GAAG,EAAE;gBACP,MAAM,CAAC,aAAa,CAClB,IAAI,YAAY,CAAC,SAAS,EAAE;oBAC1B,IAAI,EAAE;wBACJ,OAAO,EAAE,KAAK;wBACd,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE;wBAClB,MAAM,EAAE;4BACN,eAAe,EAAE,YAAY;4BAC7B,QAAQ,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE;4BACjD,gBAAgB,EAAE,EAAE;4BACpB,WAAW,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE;yBAChC;qBACF;iBACF,CAAC,CACH,CAAC;YACJ,CAAC,CAAC,CAAC;QACL,CAAC;QAED,MAAM,OAAO,CAAC,GAAG,EAAE;YACjB,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACvC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/src/web/types/ext-apps.d.ts

@@ -0,0 +1,421 @@
+/**
+ * MCP Apps Protocol Types (spec.types.ts)
+ *
+ * This file contains pure TypeScript interface definitions for the MCP Apps protocol.
+ * These types are the source of truth and are used to generate Zod schemas via ts-to-zod.
+ *
+ * - Use `@description` JSDoc tags to generate `.describe()` calls on schemas
+ * - Run `npm run generate:schemas` to regenerate schemas from these types
+ *
+ * @see https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx
+ */
+import type { CallToolResult, ContentBlock, Implementation, RequestId, Tool } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * Current protocol version supported by this SDK.
+ *
+ * The SDK automatically handles version negotiation during initialization.
+ * Apps and hosts don't need to manage protocol versions manually.
+ */
+export declare const LATEST_PROTOCOL_VERSION = "2025-11-21";
+/**
+ * @description Color theme preference for the host environment.
+ */
+export type McpUiTheme = "light" | "dark";
+/**
+ * @description Display mode for UI presentation.
+ */
+export type McpUiDisplayMode = "inline" | "fullscreen" | "pip";
+/**
+ * @description CSS variable keys available to MCP apps for theming.
+ */
+export type McpUiStyleVariableKey = "--color-background-primary" | "--color-background-secondary" | "--color-background-tertiary" | "--color-background-inverse" | "--color-background-ghost" | "--color-background-info" | "--color-background-danger" | "--color-background-success" | "--color-background-warning" | "--color-background-disabled" | "--color-text-primary" | "--color-text-secondary" | "--color-text-tertiary" | "--color-text-inverse" | "--color-text-info" | "--color-text-danger" | "--color-text-success" | "--color-text-warning" | "--color-text-disabled" | "--color-text-ghost" | "--color-border-primary" | "--color-border-secondary" | "--color-border-tertiary" | "--color-border-inverse" | "--color-border-ghost" | "--color-border-info" | "--color-border-danger" | "--color-border-success" | "--color-border-warning" | "--color-border-disabled" | "--color-ring-primary" | "--color-ring-secondary" | "--color-ring-inverse" | "--color-ring-info" | "--color-ring-danger" | "--color-ring-success" | "--color-ring-warning" | "--font-sans" | "--font-mono" | "--font-weight-normal" | "--font-weight-medium" | "--font-weight-semibold" | "--font-weight-bold" | "--font-text-xs-size" | "--font-text-sm-size" | "--font-text-md-size" | "--font-text-lg-size" | "--font-heading-xs-size" | "--font-heading-sm-size" | "--font-heading-md-size" | "--font-heading-lg-size" | "--font-heading-xl-size" | "--font-heading-2xl-size" | "--font-heading-3xl-size" | "--font-text-xs-line-height" | "--font-text-sm-line-height" | "--font-text-md-line-height" | "--font-text-lg-line-height" | "--font-heading-xs-line-height" | "--font-heading-sm-line-height" | "--font-heading-md-line-height" | "--font-heading-lg-line-height" | "--font-heading-xl-line-height" | "--font-heading-2xl-line-height" | "--font-heading-3xl-line-height" | "--border-radius-xs" | "--border-radius-sm" | "--border-radius-md" | "--border-radius-lg" | "--border-radius-xl" | "--border-radius-full" | "--border-width-regular" | "--shadow-hairline" | "--shadow-sm" | "--shadow-md" | "--shadow-lg";
+/**
+ * @description Style variables for theming MCP apps.
+ *
+ * Individual style keys are optional - hosts may provide any subset of these values.
+ * Values are strings containing CSS values (colors, sizes, font stacks, etc.).
+ *
+ * Note: This type uses `Record<K, string | undefined>` rather than `Partial<Record<K, string>>`
+ * for compatibility with Zod schema generation. Both are functionally equivalent for validation.
+ */
+export type McpUiStyles = Record<McpUiStyleVariableKey, string | undefined>;
+/**
+ * @description Request to open an external URL in the host's default browser.
+ * @see {@link app.App.sendOpenLink} for the method that sends this request
+ */
+export interface McpUiOpenLinkRequest {
+    method: "ui/open-link";
+    params: {
+        /** @description URL to open in the host's browser */
+        url: string;
+    };
+}
+/**
+ * @description Result from opening a URL.
+ * @see {@link McpUiOpenLinkRequest}
+ */
+export interface McpUiOpenLinkResult {
+    /** @description True if the host failed to open the URL (e.g., due to security policy). */
+    isError?: boolean;
+    /**
+     * Index signature required for MCP SDK `Protocol` class compatibility.
+     * Note: The schema intentionally omits this to enforce strict validation.
+     */
+    [key: string]: unknown;
+}
+/**
+ * @description Request to send a message to the host's chat interface.
+ * @see {@link app.App.sendMessage} for the method that sends this request
+ */
+export interface McpUiMessageRequest {
+    method: "ui/message";
+    params: {
+        /** @description Message role, currently only "user" is supported. */
+        role: "user";
+        /** @description Message content blocks (text, image, etc.). */
+        content: ContentBlock[];
+    };
+}
+/**
+ * @description Result from sending a message.
+ * @see {@link McpUiMessageRequest}
+ */
+export interface McpUiMessageResult {
+    /** @description True if the host rejected or failed to deliver the message. */
+    isError?: boolean;
+    /**
+     * Index signature required for MCP SDK `Protocol` class compatibility.
+     * Note: The schema intentionally omits this to enforce strict validation.
+     */
+    [key: string]: unknown;
+}
+/**
+ * @description Notification that the sandbox proxy iframe is ready to receive content.
+ * @internal
+ * @see https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx#sandbox-proxy
+ */
+export interface McpUiSandboxProxyReadyNotification {
+    method: "ui/notifications/sandbox-proxy-ready";
+    params: Record<string, unknown>;
+}
+/**
+ * @description Notification containing HTML resource for the sandbox proxy to load.
+ * @internal
+ * @see https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx#sandbox-proxy
+ */
+export interface McpUiSandboxResourceReadyNotification {
+    method: "ui/notifications/sandbox-resource-ready";
+    params: {
+        /** @description HTML content to load into the inner iframe. */
+        html: string;
+        /** @description Optional override for the inner iframe's sandbox attribute. */
+        sandbox?: string;
+        /** @description CSP configuration from resource metadata. */
+        csp?: {
+            /** @description Origins for network requests (fetch/XHR/WebSocket). */
+            connectDomains?: string[];
+            /** @description Origins for static resources (scripts, images, styles, fonts). */
+            resourceDomains?: string[];
+        };
+    };
+}
+/**
+ * @description Notification of UI size changes (bidirectional: Guest <-> Host).
+ * @see {@link app.App.sendSizeChanged} for the method to send this from Guest UI
+ */
+export interface McpUiSizeChangedNotification {
+    method: "ui/notifications/size-changed";
+    params: {
+        /** @description New width in pixels. */
+        width?: number;
+        /** @description New height in pixels. */
+        height?: number;
+    };
+}
+/**
+ * @description Notification containing complete tool arguments (Host -> Guest UI).
+ */
+export interface McpUiToolInputNotification {
+    method: "ui/notifications/tool-input";
+    params: {
+        /** @description Complete tool call arguments as key-value pairs. */
+        arguments?: Record<string, unknown>;
+    };
+}
+/**
+ * @description Notification containing partial/streaming tool arguments (Host -> Guest UI).
+ */
+export interface McpUiToolInputPartialNotification {
+    method: "ui/notifications/tool-input-partial";
+    params: {
+        /** @description Partial tool call arguments (incomplete, may change). */
+        arguments?: Record<string, unknown>;
+    };
+}
+/**
+ * @description Notification containing tool execution result (Host -> Guest UI).
+ */
+export interface McpUiToolResultNotification {
+    method: "ui/notifications/tool-result";
+    /** @description Standard MCP tool execution result. */
+    params: CallToolResult;
+}
+/**
+ * @description Notification that tool execution was cancelled (Host -> Guest UI).
+ * Host MUST send this if tool execution was cancelled for any reason (user action,
+ * sampling error, classifier intervention, etc.).
+ */
+export interface McpUiToolCancelledNotification {
+    method: "ui/notifications/tool-cancelled";
+    params: {
+        /** @description Optional reason for the cancellation (e.g., "user action", "timeout"). */
+        reason?: string;
+    };
+}
+/**
+ * @description CSS blocks that can be injected by apps.
+ */
+export interface McpUiHostCss {
+    /** @description CSS for font loading (@font-face rules or @import statements). Apps must apply using applyHostFonts(). */
+    fonts?: string;
+}
+/**
+ * @description Style configuration for theming MCP apps.
+ */
+export interface McpUiHostStyles {
+    /** @description CSS variables for theming the app. */
+    variables?: McpUiStyles;
+    /** @description CSS blocks that apps can inject. */
+    css?: McpUiHostCss;
+}
+/**
+ * @description Rich context about the host environment provided to Guest UIs.
+ */
+export interface McpUiHostContext {
+    /** @description Allow additional properties for forward compatibility. */
+    [key: string]: unknown;
+    /** @description Metadata of the tool call that instantiated this App. */
+    toolInfo?: {
+        /** @description JSON-RPC id of the tools/call request. */
+        id: RequestId;
+        /** @description Tool definition including name, inputSchema, etc. */
+        tool: Tool;
+    };
+    /** @description Current color theme preference. */
+    theme?: McpUiTheme;
+    /** @description Style configuration for theming the app. */
+    styles?: McpUiHostStyles;
+    /** @description How the UI is currently displayed. */
+    displayMode?: McpUiDisplayMode;
+    /** @description Display modes the host supports. */
+    availableDisplayModes?: string[];
+    /** @description Current and maximum dimensions available to the UI. */
+    viewport?: {
+        /** @description Current viewport width in pixels. */
+        width: number;
+        /** @description Current viewport height in pixels. */
+        height: number;
+        /** @description Maximum available height in pixels (if constrained). */
+        maxHeight?: number;
+        /** @description Maximum available width in pixels (if constrained). */
+        maxWidth?: number;
+    };
+    /** @description User's language and region preference in BCP 47 format. */
+    locale?: string;
+    /** @description User's timezone in IANA format. */
+    timeZone?: string;
+    /** @description Host application identifier. */
+    userAgent?: string;
+    /** @description Platform type for responsive design decisions. */
+    platform?: "web" | "desktop" | "mobile";
+    /** @description Device input capabilities. */
+    deviceCapabilities?: {
+        /** @description Whether the device supports touch input. */
+        touch?: boolean;
+        /** @description Whether the device supports hover interactions. */
+        hover?: boolean;
+    };
+    /** @description Mobile safe area boundaries in pixels. */
+    safeAreaInsets?: {
+        /** @description Top safe area inset in pixels. */
+        top: number;
+        /** @description Right safe area inset in pixels. */
+        right: number;
+        /** @description Bottom safe area inset in pixels. */
+        bottom: number;
+        /** @description Left safe area inset in pixels. */
+        left: number;
+    };
+}
+/**
+ * @description Notification that host context has changed (Host -> Guest UI).
+ * @see {@link McpUiHostContext} for the full context structure
+ */
+export interface McpUiHostContextChangedNotification {
+    method: "ui/notifications/host-context-changed";
+    /** @description Partial context update containing only changed fields. */
+    params: McpUiHostContext;
+}
+/**
+ * @description Request for graceful shutdown of the Guest UI (Host -> Guest UI).
+ * @see {@link app-bridge.AppBridge.teardownResource} for the host method that sends this
+ */
+export interface McpUiResourceTeardownRequest {
+    method: "ui/resource-teardown";
+    params: Record<string, unknown>;
+}
+/**
+ * @description Result from graceful shutdown request.
+ * @see {@link McpUiResourceTeardownRequest}
+ */
+export interface McpUiResourceTeardownResult {
+    /**
+     * Index signature required for MCP SDK `Protocol` class compatibility.
+     */
+    [key: string]: unknown;
+}
+/**
+ * @description Capabilities supported by the host application.
+ * @see {@link McpUiInitializeResult} for the initialization result that includes these capabilities
+ */
+export interface McpUiHostCapabilities {
+    /** @description Experimental features (structure TBD). */
+    experimental?: Record<string, unknown>;
+    /** @description Host supports opening external URLs. */
+    openLinks?: Record<string, unknown>;
+    /** @description Host can proxy tool calls to the MCP server. */
+    serverTools?: {
+        /** @description Host supports tools/list_changed notifications. */
+        listChanged?: boolean;
+    };
+    /** @description Host can proxy resource reads to the MCP server. */
+    serverResources?: {
+        /** @description Host supports resources/list_changed notifications. */
+        listChanged?: boolean;
+    };
+    /** @description Host accepts log messages. */
+    logging?: Record<string, unknown>;
+}
+/**
+ * @description Capabilities provided by the Guest UI (App).
+ * @see {@link McpUiInitializeRequest} for the initialization request that includes these capabilities
+ */
+export interface McpUiAppCapabilities {
+    /** @description Experimental features (structure TBD). */
+    experimental?: Record<string, unknown>;
+    /** @description App exposes MCP-style tools that the host can call. */
+    tools?: {
+        /** @description App supports tools/list_changed notifications. */
+        listChanged?: boolean;
+    };
+}
+/**
+ * @description Initialization request sent from Guest UI to Host.
+ * @see {@link app.App.connect} for the method that sends this request
+ */
+export interface McpUiInitializeRequest {
+    method: "ui/initialize";
+    params: {
+        /** @description App identification (name and version). */
+        appInfo: Implementation;
+        /** @description Features and capabilities this app provides. */
+        appCapabilities: McpUiAppCapabilities;
+        /** @description Protocol version this app supports. */
+        protocolVersion: string;
+    };
+}
+/**
+ * @description Initialization result returned from Host to Guest UI.
+ * @see {@link McpUiInitializeRequest}
+ */
+export interface McpUiInitializeResult {
+    /** @description Negotiated protocol version string (e.g., "2025-11-21"). */
+    protocolVersion: string;
+    /** @description Host application identification and version. */
+    hostInfo: Implementation;
+    /** @description Features and capabilities provided by the host. */
+    hostCapabilities: McpUiHostCapabilities;
+    /** @description Rich context about the host environment. */
+    hostContext: McpUiHostContext;
+    /**
+     * Index signature required for MCP SDK `Protocol` class compatibility.
+     * Note: The schema intentionally omits this to enforce strict validation.
+     */
+    [key: string]: unknown;
+}
+/**
+ * @description Notification that Guest UI has completed initialization (Guest UI -> Host).
+ * @see {@link app.App.connect} for the method that sends this notification
+ */
+export interface McpUiInitializedNotification {
+    method: "ui/notifications/initialized";
+    params?: object;
+}
+/**
+ * @description Content Security Policy configuration for UI resources.
+ */
+export interface McpUiResourceCsp {
+    /** @description Origins for network requests (fetch/XHR/WebSocket). */
+    connectDomains?: string[];
+    /** @description Origins for static resources (scripts, images, styles, fonts). */
+    resourceDomains?: string[];
+}
+/**
+ * @description UI Resource metadata for security and rendering configuration.
+ */
+export interface McpUiResourceMeta {
+    /** @description Content Security Policy configuration. */
+    csp?: McpUiResourceCsp;
+    /** @description Dedicated origin for widget sandbox. */
+    domain?: string;
+    /** @description Visual boundary preference - true if UI prefers a visible border. */
+    prefersBorder?: boolean;
+}
+/**
+ * @description Request to change the display mode of the UI.
+ * The host will respond with the actual display mode that was set,
+ * which may differ from the requested mode if not supported.
+ * @see {@link app.App.requestDisplayMode} for the method that sends this request
+ */
+export interface McpUiRequestDisplayModeRequest {
+    method: "ui/request-display-mode";
+    params: {
+        /** @description The display mode being requested. */
+        mode: McpUiDisplayMode;
+    };
+}
+/**
+ * @description Result from requesting a display mode change.
+ * @see {@link McpUiRequestDisplayModeRequest}
+ */
+export interface McpUiRequestDisplayModeResult {
+    /** @description The display mode that was actually set. May differ from requested if not supported. */
+    mode: McpUiDisplayMode;
+    /**
+     * Index signature required for MCP SDK `Protocol` class compatibility.
+     * Note: The schema intentionally omits this to enforce strict validation.
+     */
+    [key: string]: unknown;
+}
+/**
+ * @description Tool visibility scope - who can access the tool.
+ */
+export type McpUiToolVisibility = "model" | "app";
+/**
+ * @description UI-related metadata for tools.
+ */
+export interface McpUiToolMeta {
+    /**
+     * URI of the UI resource to display for this tool.
+     * This is converted to `_meta["ui/resourceUri"]`.
+     *
+     * @example "ui://weather/widget.html"
+     */
+    resourceUri: string;
+    /**
+     * @description Who can access this tool. Default: ["model", "app"]
+     * - "model": Tool visible to and callable by the agent
+     * - "app": Tool callable by the app from this server only
+     */
+    visibility?: McpUiToolVisibility[];
+}

package/dist/src/web/types/ext-apps.js

@@ -0,0 +1,19 @@
+/**
+ * MCP Apps Protocol Types (spec.types.ts)
+ *
+ * This file contains pure TypeScript interface definitions for the MCP Apps protocol.
+ * These types are the source of truth and are used to generate Zod schemas via ts-to-zod.
+ *
+ * - Use `@description` JSDoc tags to generate `.describe()` calls on schemas
+ * - Run `npm run generate:schemas` to regenerate schemas from these types
+ *
+ * @see https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx
+ */
+/**
+ * Current protocol version supported by this SDK.
+ *
+ * The SDK automatically handles version negotiation during initialization.
+ * Apps and hosts don't need to manage protocol versions manually.
+ */
+export const LATEST_PROTOCOL_VERSION = "2025-11-21";
+//# sourceMappingURL=ext-apps.js.map

package/dist/src/web/types/ext-apps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ext-apps.js","sourceRoot":"","sources":["../../../../src/web/types/ext-apps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAUH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,YAAY,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skybridge",
-  "version": "0.0.0-dev.4f33eea",
+  "version": "0.0.0-dev.51c9c19",
   "description": "Skybridge is a framework for building ChatGPT apps",
   "type": "module",
   "files": [