@casys/mcp-bridge 0.2.0

package/esm/core/protocol.js

@@ -0,0 +1,203 @@
+/**
+ * JSON-RPC 2.0 message builders and validators for the MCP Apps protocol.
+ *
+ * Provides type-safe construction of all MCP Apps messages and a
+ * message validator to guard incoming data at system boundaries.
+ */
+import { McpAppsMethod } from "./types.js";
+// ---------------------------------------------------------------------------
+// ID generation
+// ---------------------------------------------------------------------------
+let _nextId = 1;
+/** Generate a monotonically increasing request ID. */
+export function nextRequestId() {
+    return _nextId++;
+}
+/** Reset the ID counter. @internal — exported for tests only. */
+export function resetRequestIdCounter() {
+    _nextId = 1;
+}
+// ---------------------------------------------------------------------------
+// Message type guards
+// ---------------------------------------------------------------------------
+/** Check if a value is a valid JSON-RPC 2.0 message. */
+export function isJsonRpcMessage(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "jsonrpc" in value &&
+        value.jsonrpc === "2.0");
+}
+/** Check if a message is a JSON-RPC request (has `id` and `method`). */
+export function isRequest(msg) {
+    return "method" in msg && "id" in msg;
+}
+/** Check if a message is a JSON-RPC notification (has `method`, no `id`). */
+export function isNotification(msg) {
+    return "method" in msg && !("id" in msg);
+}
+/** Check if a message is a JSON-RPC success response. */
+export function isResponse(msg) {
+    return "result" in msg && "id" in msg && !("method" in msg);
+}
+/** Check if a message is a JSON-RPC error response. */
+export function isErrorResponse(msg) {
+    return "error" in msg && "id" in msg;
+}
+// ---------------------------------------------------------------------------
+// Request builders (App -> Host)
+// ---------------------------------------------------------------------------
+/** Build a `ui/initialize` request. */
+export function buildInitializeRequest(params) {
+    return {
+        jsonrpc: "2.0",
+        id: nextRequestId(),
+        method: McpAppsMethod.UI_INITIALIZE,
+        params,
+    };
+}
+/** Build a `tools/call` request. */
+export function buildToolCallRequest(params) {
+    return {
+        jsonrpc: "2.0",
+        id: nextRequestId(),
+        method: McpAppsMethod.TOOLS_CALL,
+        params,
+    };
+}
+/** Build a `resources/read` request. */
+export function buildResourceReadRequest(params) {
+    return {
+        jsonrpc: "2.0",
+        id: nextRequestId(),
+        method: McpAppsMethod.RESOURCES_READ,
+        params,
+    };
+}
+/** Build a `ui/open-link` request. */
+export function buildOpenLinkRequest(params) {
+    return {
+        jsonrpc: "2.0",
+        id: nextRequestId(),
+        method: McpAppsMethod.UI_OPEN_LINK,
+        params,
+    };
+}
+/** Build a `ui/message` request. */
+export function buildMessageRequest(params) {
+    return {
+        jsonrpc: "2.0",
+        id: nextRequestId(),
+        method: McpAppsMethod.UI_MESSAGE,
+        params,
+    };
+}
+/** Build a `ui/update-model-context` request. */
+export function buildUpdateModelContextRequest(params) {
+    return {
+        jsonrpc: "2.0",
+        id: nextRequestId(),
+        method: McpAppsMethod.UI_UPDATE_MODEL_CONTEXT,
+        params,
+    };
+}
+/** Build a `ui/request-display-mode` request. */
+export function buildDisplayModeRequest(params) {
+    return {
+        jsonrpc: "2.0",
+        id: nextRequestId(),
+        method: McpAppsMethod.UI_REQUEST_DISPLAY_MODE,
+        params,
+    };
+}
+// ---------------------------------------------------------------------------
+// Notification builders (Host -> App)
+// ---------------------------------------------------------------------------
+/** Build a `ui/notifications/initialized` notification (App -> Host). */
+export function buildInitializedNotification() {
+    return {
+        jsonrpc: "2.0",
+        method: McpAppsMethod.UI_NOTIFICATIONS_INITIALIZED,
+    };
+}
+/** Build a `ui/notifications/tool-input` notification (Host -> App). */
+export function buildToolInputNotification(params) {
+    return {
+        jsonrpc: "2.0",
+        method: McpAppsMethod.UI_TOOL_INPUT,
+        params,
+    };
+}
+/** Build a `ui/notifications/tool-result` notification (Host -> App). */
+export function buildToolResultNotification(params) {
+    return {
+        jsonrpc: "2.0",
+        method: McpAppsMethod.UI_TOOL_RESULT,
+        params,
+    };
+}
+/** Build a `ui/notifications/tool-cancelled` notification (Host -> App). */
+export function buildToolCancelledNotification(params) {
+    return {
+        jsonrpc: "2.0",
+        method: McpAppsMethod.UI_TOOL_CANCELLED,
+        params,
+    };
+}
+/** Build a `ui/notifications/host-context-changed` notification. */
+export function buildHostContextChangedNotification(params) {
+    return {
+        jsonrpc: "2.0",
+        method: McpAppsMethod.UI_HOST_CONTEXT_CHANGED,
+        params: params,
+    };
+}
+/** Build a `ui/resource-teardown` request (Host -> App). */
+export function buildResourceTeardownRequest(params) {
+    return {
+        jsonrpc: "2.0",
+        id: nextRequestId(),
+        method: McpAppsMethod.UI_RESOURCE_TEARDOWN,
+        params,
+    };
+}
+/** Build a `notifications/message` notification (logging). */
+export function buildLogNotification(params) {
+    return {
+        jsonrpc: "2.0",
+        method: McpAppsMethod.NOTIFICATIONS_MESSAGE,
+        params,
+    };
+}
+// ---------------------------------------------------------------------------
+// Response builders
+// ---------------------------------------------------------------------------
+/** Build a `ui/initialize` success response. */
+export function buildInitializeResponse(id, params) {
+    return {
+        jsonrpc: "2.0",
+        id,
+        result: params,
+    };
+}
+/** Build a generic JSON-RPC success response. */
+export function buildSuccessResponse(id, result) {
+    return { jsonrpc: "2.0", id, result };
+}
+/** Build a JSON-RPC error response. */
+export function buildErrorResponse(id, code, message, data) {
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: { code, message, ...(data !== undefined ? { data } : {}) },
+    };
+}
+// ---------------------------------------------------------------------------
+// Standard JSON-RPC error codes
+// ---------------------------------------------------------------------------
+export const JsonRpcErrorCode = {
+    PARSE_ERROR: -32700,
+    INVALID_REQUEST: -32600,
+    METHOD_NOT_FOUND: -32601,
+    INVALID_PARAMS: -32602,
+    INTERNAL_ERROR: -32603,
+};

package/esm/core/resource-resolver.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Resolves `ui://` resource URIs to HTTP URLs served by the resource server.
+ *
+ * The `ui://` scheme is defined by the MCP Apps specification:
+ *   `ui://<server>/<path>?<query>`
+ *
+ * The resolver rewrites these to the resource server's HTTP base URL so that
+ * platform WebViews can fetch the assets over plain HTTP(S).
+ */
+import type { ResourceUri } from "./types.js";
+/**
+ * Parse a raw `ui://` URI string into its components.
+ *
+ * @throws {Error} if the URI does not start with `ui://`.
+ */
+export declare function parseResourceUri(raw: string): ResourceUri;
+/**
+ * Resolve a `ui://` URI to an HTTP URL using the given base URL.
+ *
+ * Example:
+ * ```
+ * resolveToHttp("ui://my-app/index.html", "https://resource.example.com")
+ * // => "https://resource.example.com/my-app/index.html"
+ * ```
+ */
+export declare function resolveToHttp(uriOrString: ResourceUri | string, httpBaseUrl: string): string;
+//# sourceMappingURL=resource-resolver.d.ts.map

package/esm/core/resource-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-resolver.d.ts","sourceRoot":"","sources":["../../src/core/resource-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAI9C;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAqDzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,WAAW,GAAG,MAAM,EACjC,WAAW,EAAE,MAAM,GAClB,MAAM,CAwBR"}

package/esm/core/resource-resolver.js

@@ -0,0 +1,85 @@
+/**
+ * Resolves `ui://` resource URIs to HTTP URLs served by the resource server.
+ *
+ * The `ui://` scheme is defined by the MCP Apps specification:
+ *   `ui://<server>/<path>?<query>`
+ *
+ * The resolver rewrites these to the resource server's HTTP base URL so that
+ * platform WebViews can fetch the assets over plain HTTP(S).
+ */
+const UI_SCHEME = "ui://";
+/**
+ * Parse a raw `ui://` URI string into its components.
+ *
+ * @throws {Error} if the URI does not start with `ui://`.
+ */
+export function parseResourceUri(raw) {
+    if (!raw.startsWith(UI_SCHEME)) {
+        throw new Error(`[ResourceResolver] Invalid resource URI: expected "ui://" scheme, got "${raw}".`);
+    }
+    const withoutScheme = raw.slice(UI_SCHEME.length);
+    const queryIdx = withoutScheme.indexOf("?");
+    let serverAndPath;
+    let queryString = "";
+    if (queryIdx >= 0) {
+        serverAndPath = withoutScheme.slice(0, queryIdx);
+        queryString = withoutScheme.slice(queryIdx + 1);
+    }
+    else {
+        serverAndPath = withoutScheme;
+    }
+    const slashIdx = serverAndPath.indexOf("/");
+    let server;
+    let path;
+    if (slashIdx >= 0) {
+        server = serverAndPath.slice(0, slashIdx);
+        path = serverAndPath.slice(slashIdx);
+    }
+    else {
+        server = serverAndPath;
+        path = "/";
+    }
+    if (server.length === 0) {
+        throw new Error(`[ResourceResolver] Invalid resource URI: empty server in "${raw}".`);
+    }
+    const query = {};
+    if (queryString.length > 0) {
+        for (const pair of queryString.split("&")) {
+            const eqIdx = pair.indexOf("=");
+            if (eqIdx >= 0) {
+                query[decodeURIComponent(pair.slice(0, eqIdx))] = decodeURIComponent(pair.slice(eqIdx + 1));
+            }
+            else {
+                query[decodeURIComponent(pair)] = "";
+            }
+        }
+    }
+    return { raw, server, path, query };
+}
+/**
+ * Resolve a `ui://` URI to an HTTP URL using the given base URL.
+ *
+ * Example:
+ * ```
+ * resolveToHttp("ui://my-app/index.html", "https://resource.example.com")
+ * // => "https://resource.example.com/my-app/index.html"
+ * ```
+ */
+export function resolveToHttp(uriOrString, httpBaseUrl) {
+    const uri = typeof uriOrString === "string"
+        ? parseResourceUri(uriOrString)
+        : uriOrString;
+    const base = httpBaseUrl.endsWith("/")
+        ? httpBaseUrl.slice(0, -1)
+        : httpBaseUrl;
+    const pathPart = uri.path.startsWith("/") ? uri.path : `/${uri.path}`;
+    const queryEntries = Object.entries(uri.query);
+    let url = `${base}/${uri.server}${pathPart}`;
+    if (queryEntries.length > 0) {
+        const qs = queryEntries
+            .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+            .join("&");
+        url += `?${qs}`;
+    }
+    return url;
+}

package/esm/core/transport.d.ts

@@ -0,0 +1,46 @@
+import type { McpAppsMessage } from "./types.js";
+/** Handler invoked when the transport receives a message. */
+export type TransportMessageHandler = (message: McpAppsMessage) => void;
+/** Handler invoked when the transport connection state changes. */
+export type TransportStateHandler = (connected: boolean) => void;
+/**
+ * Transport layer for bidirectional JSON-RPC communication between
+ * the bridge adapter and the resource server.
+ */
+export interface BridgeTransport {
+    /** Send a JSON-RPC message to the resource server. */
+    send(message: McpAppsMessage): void;
+    /** Register a handler for incoming messages from the resource server. */
+    onMessage(handler: TransportMessageHandler): void;
+    /** Register a handler for connection state changes. */
+    onStateChange(handler: TransportStateHandler): void;
+    /** Connect to the resource server at the given URL. */
+    connect(url: string): Promise<void>;
+    /** Disconnect from the resource server. */
+    disconnect(): void;
+    /** Whether the transport is currently connected. */
+    readonly connected: boolean;
+}
+/**
+ * WebSocket-based transport for the MCP Apps Bridge.
+ *
+ * This is the primary transport. It provides full-duplex communication
+ * so the resource server can push notifications (tool results, context
+ * changes) to the app without polling.
+ *
+ * NOTE: This class uses browser WebSocket APIs. It is designed to run
+ * inside a platform webview (Telegram, LINE), not on the server side.
+ */
+export declare class WebSocketTransport implements BridgeTransport {
+    private ws;
+    private messageHandlers;
+    private stateHandlers;
+    send(message: McpAppsMessage): void;
+    onMessage(handler: TransportMessageHandler): void;
+    onStateChange(handler: TransportStateHandler): void;
+    connect(url: string): Promise<void>;
+    disconnect(): void;
+    get connected(): boolean;
+    private notifyState;
+}
+//# sourceMappingURL=transport.d.ts.map

package/esm/core/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/core/transport.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,6DAA6D;AAC7D,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAC;AAExE,mEAAmE;AACnE,MAAM,MAAM,qBAAqB,GAAG,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,CAAC;AAEjE;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,sDAAsD;IACtD,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IAEpC,yEAAyE;IACzE,SAAS,CAAC,OAAO,EAAE,uBAAuB,GAAG,IAAI,CAAC;IAElD,uDAAuD;IACvD,aAAa,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAEpD,uDAAuD;IACvD,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpC,2CAA2C;IAC3C,UAAU,IAAI,IAAI,CAAC;IAEnB,oDAAoD;IACpD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;GASG;AACH,qBAAa,kBAAmB,YAAW,eAAe;IAExD,OAAO,CAAC,EAAE,CAAa;IACvB,OAAO,CAAC,eAAe,CAAiC;IACxD,OAAO,CAAC,aAAa,CAA+B;IAEpD,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IASnC,SAAS,CAAC,OAAO,EAAE,uBAAuB,GAAG,IAAI;IAIjD,aAAa,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI;IAInD,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA8CnC,UAAU,IAAI,IAAI;IAOlB,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,OAAO,CAAC,WAAW;CAKpB"}

package/esm/core/transport.js

@@ -0,0 +1,85 @@
+/**
+ * Transport abstraction for the MCP Apps Bridge.
+ *
+ * Defines how JSON-RPC messages travel between the bridge adapter
+ * (client-side, in the webview) and the resource server.
+ *
+ * The primary implementation is WebSocket, with HTTP POST as a fallback.
+ */
+import * as dntShim from "../_dnt.shims.js";
+/**
+ * WebSocket-based transport for the MCP Apps Bridge.
+ *
+ * This is the primary transport. It provides full-duplex communication
+ * so the resource server can push notifications (tool results, context
+ * changes) to the app without polling.
+ *
+ * NOTE: This class uses browser WebSocket APIs. It is designed to run
+ * inside a platform webview (Telegram, LINE), not on the server side.
+ */
+export class WebSocketTransport {
+    // deno-lint-ignore no-explicit-any
+    ws = null; // WebSocket instance (browser API)
+    messageHandlers = [];
+    stateHandlers = [];
+    send(message) {
+        if (!this.ws || this.ws.readyState !== 1 /* WebSocket.OPEN */) {
+            throw new Error("[WebSocketTransport] Not connected. Call connect() first.");
+        }
+        this.ws.send(JSON.stringify(message));
+    }
+    onMessage(handler) {
+        this.messageHandlers.push(handler);
+    }
+    onStateChange(handler) {
+        this.stateHandlers.push(handler);
+    }
+    connect(url) {
+        // deno-lint-ignore no-explicit-any
+        const WS = dntShim.dntGlobalThis.WebSocket;
+        if (!WS) {
+            throw new Error("[WebSocketTransport] WebSocket API not available. " +
+                "This transport requires a browser environment.");
+        }
+        return new Promise((resolve, reject) => {
+            const ws = new WS(url);
+            ws.onopen = () => {
+                this.ws = ws;
+                this.notifyState(true);
+                resolve();
+            };
+            ws.onerror = () => {
+                reject(new Error(`[WebSocketTransport] Failed to connect to ${url}.`));
+            };
+            ws.onmessage = (event) => {
+                try {
+                    const message = JSON.parse(event.data);
+                    for (const handler of this.messageHandlers) {
+                        handler(message);
+                    }
+                }
+                catch (err) {
+                    console.warn("[WebSocketTransport] Received non-JSON message, dropping:", err instanceof Error ? err.message : err);
+                }
+            };
+            ws.onclose = () => {
+                this.ws = null;
+                this.notifyState(false);
+            };
+        });
+    }
+    disconnect() {
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+    }
+    get connected() {
+        return this.ws !== null && this.ws.readyState === 1; /* WebSocket.OPEN */
+    }
+    notifyState(connected) {
+        for (const handler of this.stateHandlers) {
+            handler(connected);
+        }
+    }
+}

package/esm/core/types.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Core types for the MCP Apps Bridge protocol.
+ *
+ * Defines the message envelope, resource URIs, adapter configuration,
+ * and tool declarations used throughout the bridge.
+ */
+/** A JSON-RPC 2.0 request sent between host and MCP App. */
+export interface McpAppsRequest {
+    readonly jsonrpc: "2.0";
+    readonly id: string | number;
+    readonly method: string;
+    readonly params?: Record<string, unknown>;
+}
+/** A JSON-RPC 2.0 success response. */
+export interface McpAppsResponse {
+    readonly jsonrpc: "2.0";
+    readonly id: string | number;
+    readonly result: unknown;
+}
+/** A JSON-RPC 2.0 error response. */
+export interface McpAppsErrorResponse {
+    readonly jsonrpc: "2.0";
+    readonly id: string | number | null;
+    readonly error: {
+        readonly code: number;
+        readonly message: string;
+        readonly data?: unknown;
+    };
+}
+/** A JSON-RPC 2.0 notification (no id, no response expected). */
+export interface McpAppsNotification {
+    readonly jsonrpc: "2.0";
+    readonly method: string;
+    readonly params?: Record<string, unknown>;
+}
+/** Union of all JSON-RPC message shapes. */
+export type McpAppsMessage = McpAppsRequest | McpAppsResponse | McpAppsErrorResponse | McpAppsNotification;
+/** Parsed representation of a `ui://` resource URI. */
+export interface ResourceUri {
+    /** The raw URI string, e.g. `ui://my-app/index.html`. */
+    readonly raw: string;
+    /** Server / app identifier (host portion of the URI). */
+    readonly server: string;
+    /** Path within the app, e.g. `/index.html`. */
+    readonly path: string;
+    /** Optional query parameters. */
+    readonly query: Record<string, string>;
+}
+/** Platform-specific configuration supplied when initializing an adapter. */
+export interface AdapterConfig {
+    /** Base URL where the resource server is reachable by the client. */
+    readonly resourceBaseUrl: string;
+    /** Optional platform-specific settings (e.g. Telegram bot token). */
+    readonly platformOptions?: Record<string, unknown>;
+}
+/** Global bridge options shared across all adapters. */
+export interface BridgeOptions {
+    /** Port for the local resource server. Defaults to 0 (OS-assigned). */
+    readonly resourceServerPort?: number;
+    /** Origin allowlist for CORS. Defaults to `["*"]`. */
+    readonly allowedOrigins?: readonly string[];
+    /** Enable debug logging. */
+    readonly debug?: boolean;
+}
+/** UI metadata attached to an MCP tool via `_meta`. */
+export interface McpToolUiMeta {
+    /** Resource URI pointing to the interactive UI for this tool. */
+    readonly resourceUri: string;
+    /** Optional human-readable label for the UI. */
+    readonly label?: string;
+    /** Optional width hint in pixels. */
+    readonly width?: number;
+    /** Optional height hint in pixels. */
+    readonly height?: number;
+}
+/** CSP (Content Security Policy) metadata for an MCP App resource. */
+export interface McpToolUiCsp {
+    /** Allowed script-src origins. */
+    readonly scriptSources?: readonly string[];
+    /** Allowed connect-src origins. */
+    readonly connectSources?: readonly string[];
+    /** Allowed frame-ancestors origins. */
+    readonly frameAncestors?: readonly string[];
+}
+/** Iframe sandbox permission flags that an MCP App can request. */
+export type McpAppPermission = "allow-downloads" | "allow-forms" | "allow-modals" | "allow-popups" | "allow-same-origin" | "allow-scripts" | "camera" | "microphone" | "geolocation" | "clipboard-read" | "clipboard-write";
+/** An MCP tool declaration that carries `_meta.ui`. */
+export interface McpToolDeclaration {
+    readonly name: string;
+    readonly description?: string;
+    readonly inputSchema: Record<string, unknown>;
+    readonly _meta?: {
+        readonly ui?: McpToolUiMeta & {
+            /** CSP directives for the UI resource. */
+            readonly csp?: McpToolUiCsp;
+            /** Additional sandbox permissions requested by the app. */
+            readonly permissions?: readonly McpAppPermission[];
+        };
+    };
+}
+/**
+ * Well-known JSON-RPC method names used in the MCP Apps protocol (SEP-1865).
+ *
+ * App -> Host requests.
+ */
+export declare const McpAppsMethod: {
+    readonly UI_INITIALIZE: "ui/initialize";
+    readonly UI_NOTIFICATIONS_INITIALIZED: "ui/notifications/initialized";
+    readonly TOOLS_CALL: "tools/call";
+    readonly RESOURCES_READ: "resources/read";
+    readonly UI_OPEN_LINK: "ui/open-link";
+    readonly UI_MESSAGE: "ui/message";
+    readonly UI_UPDATE_MODEL_CONTEXT: "ui/update-model-context";
+    readonly UI_REQUEST_DISPLAY_MODE: "ui/request-display-mode";
+    readonly NOTIFICATIONS_MESSAGE: "notifications/message";
+    readonly UI_TOOL_INPUT: "ui/notifications/tool-input";
+    readonly UI_TOOL_INPUT_PARTIAL: "ui/notifications/tool-input-partial";
+    readonly UI_TOOL_RESULT: "ui/notifications/tool-result";
+    readonly UI_TOOL_CANCELLED: "ui/notifications/tool-cancelled";
+    readonly UI_HOST_CONTEXT_CHANGED: "ui/notifications/host-context-changed";
+    readonly UI_SIZE_CHANGED: "ui/notifications/size-changed";
+    readonly UI_RESOURCE_TEARDOWN: "ui/resource-teardown";
+};
+/** Dimensions of the container rendering the MCP App. */
+export interface ContainerDimensions {
+    readonly width?: number;
+    readonly maxWidth?: number;
+    readonly height?: number;
+    readonly maxHeight?: number;
+}
+/** Safe area insets (e.g. notch, status bar) from the platform. */
+export interface SafeAreaInsets {
+    readonly top: number;
+    readonly right: number;
+    readonly bottom: number;
+    readonly left: number;
+}
+/** Host theme and style information provided to the MCP App. */
+export interface HostContextStyles {
+    /** CSS custom properties for theming (e.g. `--color-background-primary`). */
+    readonly variables?: Record<string, string>;
+    /** Optional CSS with font declarations. */
+    readonly css?: {
+        readonly fonts?: string;
+    };
+}
+/**
+ * Host context provided to an MCP App during `ui/initialize`.
+ *
+ * Contains theme, dimensions, locale, and other environment info
+ * needed for the app to adapt to its container.
+ */
+export interface HostContext {
+    readonly theme: "light" | "dark";
+    readonly styles?: HostContextStyles;
+    readonly containerDimensions?: ContainerDimensions;
+    readonly platform?: "web" | "desktop" | "mobile";
+    readonly locale?: string;
+    readonly timeZone?: string;
+    readonly safeAreaInsets?: SafeAreaInsets;
+}
+/** Display mode an MCP App can request via `ui/request-display-mode`. */
+export type DisplayMode = "inline" | "fullscreen" | "pip";
+/**
+ * Capabilities the host exposes to the MCP App during `ui/initialize`.
+ */
+export interface HostCapabilities {
+    readonly serverTools?: {
+        readonly listChanged?: boolean;
+    };
+    readonly serverResources?: {
+        readonly listChanged?: boolean;
+    };
+    readonly logging?: Record<string, never>;
+    readonly openLinks?: Record<string, never>;
+}
+/**
+ * Lifecycle events generated by platform adapters.
+ *
+ * The bridge translates these into MCP Apps notifications
+ * (e.g. `ui/notifications/host-context-changed`).
+ */
+export interface LifecycleEvent {
+    readonly type: "theme-changed" | "viewport-changed" | "activated" | "deactivated" | "teardown";
+    readonly reason?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/esm/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"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"}