@casys/mcp-bridge 0.2.0

package/script/core/bridge-client.js

@@ -0,0 +1,302 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BridgeClient = void 0;
+/**
+ * BridgeClient — the core of the MCP Apps Bridge.
+ *
+ * Runs client-side inside the platform webview. It:
+ * 1. Monkey-patches `window.parent.postMessage` to intercept MCP JSON-RPC
+ *    messages from the App class (`@modelcontextprotocol/ext-apps`).
+ * 2. Routes intercepted messages to the resource server via BridgeTransport.
+ * 3. Dispatches incoming messages from the resource server as MessageEvents
+ *    to the App class.
+ * 4. Translates platform lifecycle events into MCP notifications.
+ * 5. Synthesizes the `ui/initialize` response using platform adapter data.
+ *
+ * This allows unmodified MCP App HTML to work inside Telegram/LINE webviews.
+ */
+const dntShim = __importStar(require("../_dnt.shims.js"));
+const message_router_js_1 = require("./message-router.js");
+const protocol_js_1 = require("./protocol.js");
+const types_js_1 = require("./types.js");
+/**
+ * The MCP Apps Bridge client.
+ *
+ * Injected into the MCP App HTML by the resource server (`bridge.js`).
+ * Intercepts postMessage, routes via WebSocket, translates platform events.
+ */
+class BridgeClient {
+    platform;
+    transport;
+    router;
+    options;
+    hostContext = null;
+    started = false;
+    // deno-lint-ignore no-explicit-any
+    originalPostMessage = null;
+    constructor(options) {
+        this.options = options;
+        this.platform = options.platform;
+        this.transport = options.transport;
+        this.router = new message_router_js_1.MessageRouter();
+    }
+    /**
+     * Start the bridge:
+     * 1. Initialize the platform adapter to get HostContext
+     * 2. Connect transport to resource server
+     * 3. Intercept postMessage from App class
+     * 4. Listen for platform lifecycle events
+     * 5. Register ui/initialize handler to synthesize response
+     */
+    async start() {
+        if (this.started) {
+            throw new Error("[BridgeClient] Already started.");
+        }
+        // 1. Init platform and get host context
+        this.hostContext = await this.platform.initialize();
+        // 2. Connect transport
+        const wsUrl = `${this.options.serverUrl}/bridge?session=${this.options.sessionId}`;
+        await this.transport.connect(wsUrl);
+        // 3. Forward incoming messages from resource server to App class
+        this.transport.onMessage((message) => {
+            this.handleIncomingMessage(message);
+        });
+        // 4. Register handler for ui/initialize (App -> Bridge)
+        this.router.onRequest(types_js_1.McpAppsMethod.UI_INITIALIZE, (params) => {
+            return this.handleInitialize(params);
+        });
+        // 5. Register handler for ui/open-link (delegate to platform)
+        this.router.onRequest(types_js_1.McpAppsMethod.UI_OPEN_LINK, async (params) => {
+            const url = params?.url;
+            if (typeof url !== "string") {
+                throw new Error("ui/open-link requires a 'url' parameter.");
+            }
+            await this.platform.openLink(url);
+            return {};
+        });
+        // 6. Intercept postMessage
+        this.interceptPostMessage();
+        // 7. Listen for platform lifecycle events
+        this.platform.onLifecycleEvent((event) => {
+            this.handleLifecycleEvent(event);
+        });
+        this.started = true;
+    }
+    /** Stop the bridge, restore postMessage, disconnect transport. */
+    destroy() {
+        this.restorePostMessage();
+        this.transport.disconnect();
+        this.router.destroy();
+        this.started = false;
+    }
+    /** Whether the bridge is currently running. */
+    get isStarted() {
+        return this.started;
+    }
+    /** The current host context (null before start). */
+    get currentHostContext() {
+        return this.hostContext;
+    }
+    // -------------------------------------------------------------------------
+    // postMessage interception
+    // -------------------------------------------------------------------------
+    interceptPostMessage() {
+        // deno-lint-ignore no-explicit-any
+        const _global = dntShim.dntGlobalThis;
+        if (!_global.parent?.postMessage) {
+            // Not in a frame context (e.g. server-side). Skip interception.
+            return;
+        }
+        this.originalPostMessage = _global.parent.postMessage.bind(_global.parent);
+        _global.parent.postMessage = (message, targetOrigin, transfer) => {
+            if ((0, protocol_js_1.isJsonRpcMessage)(message)) {
+                // Route MCP JSON-RPC messages through the bridge
+                this.handleOutgoingMessage(message);
+            }
+            else if (this.originalPostMessage) {
+                // Non-JSON-RPC messages pass through untouched
+                this.originalPostMessage(message, targetOrigin, transfer);
+            }
+        };
+    }
+    restorePostMessage() {
+        if (this.originalPostMessage) {
+            // deno-lint-ignore no-explicit-any
+            const _global = dntShim.dntGlobalThis;
+            if (_global.parent) {
+                _global.parent.postMessage = this.originalPostMessage;
+            }
+            this.originalPostMessage = null;
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Message handling
+    // -------------------------------------------------------------------------
+    /**
+     * Handle an outgoing message from the MCP App (intercepted from postMessage).
+     *
+     * Requests that the bridge handles locally (ui/initialize, ui/open-link)
+     * are dispatched to the router. All other messages are forwarded to the
+     * resource server via transport.
+     */
+    async handleOutgoingMessage(message) {
+        // Check if the router has a handler for this method
+        if ("method" in message && this.router.hasRequestHandler(message.method)) {
+            const response = await this.router.handleMessage(message);
+            if (response) {
+                this.dispatchToApp(response);
+            }
+            return;
+        }
+        // Check notification handlers
+        if ("method" in message &&
+            !("id" in message) &&
+            this.router.hasNotificationHandler(message.method)) {
+            await this.router.handleMessage(message);
+            return;
+        }
+        // Forward to resource server
+        this.transport.send(message);
+        // Track outgoing requests for response matching
+        if ("id" in message && "method" in message) {
+            const req = message;
+            this.router
+                .trackRequest(req.id, req.method, this.options.requestTimeoutMs ?? 30_000)
+                .then((result) => {
+                this.dispatchToApp({
+                    jsonrpc: "2.0",
+                    id: req.id,
+                    result,
+                });
+            })
+                .catch((err) => {
+                this.dispatchToApp({
+                    jsonrpc: "2.0",
+                    id: req.id,
+                    error: { code: -32603, message: err.message },
+                });
+            });
+        }
+    }
+    /**
+     * Handle an incoming message from the resource server.
+     *
+     * Responses are routed to the pending request tracker (which resolves the
+     * Promise created in handleOutgoingMessage — that Promise already calls
+     * dispatchToApp, so we must NOT dispatch responses again here).
+     *
+     * Notifications are dispatched directly to the App class.
+     */
+    async handleIncomingMessage(message) {
+        // Responses: let the router resolve the tracked request.
+        // The .then() in handleOutgoingMessage will call dispatchToApp.
+        if ("result" in message || "error" in message) {
+            await this.router.handleMessage(message);
+            return;
+        }
+        // Notifications from resource server: dispatch to App class.
+        // Only notifications (method + no id), not requests (method + id).
+        if ("method" in message && !("id" in message)) {
+            this.dispatchToApp(message);
+        }
+    }
+    /** Dispatch a message to the MCP App class as a MessageEvent. */
+    dispatchToApp(message) {
+        // deno-lint-ignore no-explicit-any
+        const _global = dntShim.dntGlobalThis;
+        if (typeof _global.dispatchEvent === "function" && typeof _global.MessageEvent === "function") {
+            _global.dispatchEvent(new _global.MessageEvent("message", {
+                data: message,
+                origin: this.options.serverUrl,
+            }));
+        }
+    }
+    // -------------------------------------------------------------------------
+    // ui/initialize handler
+    // -------------------------------------------------------------------------
+    handleInitialize(_params) {
+        if (!this.hostContext) {
+            throw new Error("[BridgeClient] Platform not initialized. Cannot handle ui/initialize.");
+        }
+        const info = this.options.bridgeInfo ?? {
+            name: "@casys/mcp-apps-bridge",
+            version: "0.1.0",
+        };
+        const capabilities = {
+            serverTools: { listChanged: false },
+            serverResources: { listChanged: false },
+            logging: {},
+            openLinks: {},
+        };
+        const response = (0, protocol_js_1.buildInitializeResponse)("__placeholder__", {
+            protocolVersion: "2025-11-25",
+            hostInfo: info,
+            hostCapabilities: capabilities,
+            hostContext: this.hostContext,
+        });
+        // Return just the result (the router wraps it in a response)
+        return response.result;
+    }
+    // -------------------------------------------------------------------------
+    // Platform lifecycle events
+    // -------------------------------------------------------------------------
+    handleLifecycleEvent(event) {
+        switch (event.type) {
+            case "theme-changed": {
+                const theme = this.platform.getTheme();
+                if (this.hostContext) {
+                    this.hostContext = { ...this.hostContext, theme };
+                }
+                this.dispatchToApp((0, protocol_js_1.buildHostContextChangedNotification)({ theme }));
+                break;
+            }
+            case "viewport-changed": {
+                const containerDimensions = this.platform.getContainerDimensions();
+                if (this.hostContext) {
+                    this.hostContext = { ...this.hostContext, containerDimensions };
+                }
+                this.dispatchToApp((0, protocol_js_1.buildHostContextChangedNotification)({ containerDimensions }));
+                break;
+            }
+            case "teardown": {
+                // Notify the app it's being torn down, then disconnect
+                this.dispatchToApp({
+                    jsonrpc: "2.0",
+                    method: types_js_1.McpAppsMethod.UI_RESOURCE_TEARDOWN,
+                    params: { reason: event.reason ?? "platform-close" },
+                });
+                this.destroy();
+                break;
+            }
+            case "activated":
+            case "deactivated":
+                // Internal lifecycle events — no MCP equivalent.
+                // Could be used for session keepalive in the future.
+                break;
+        }
+    }
+}
+exports.BridgeClient = BridgeClient;

package/script/core/message-router.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Routes incoming JSON-RPC messages to registered method handlers.
+ *
+ * Supports:
+ * - Request/response dispatch with automatic JSON-RPC response generation
+ * - Notification dispatch (fire-and-forget)
+ * - Pending request tracking for outgoing requests (match response by `id`)
+ * - Handler removal
+ */
+import type { McpAppsErrorResponse, McpAppsMessage, McpAppsResponse } from "./types.js";
+/** Handler for a JSON-RPC request that returns a result. */
+export type RequestHandler = (params: Record<string, unknown> | undefined) => Promise<unknown> | unknown;
+/** Handler for a JSON-RPC notification (fire-and-forget). */
+export type NotificationHandler = (params: Record<string, unknown> | undefined) => void;
+/**
+ * JSON-RPC message router.
+ *
+ * Register handlers for specific method names, then call `handleMessage()`
+ * for each incoming message. The router will dispatch to the correct handler
+ * and produce the appropriate JSON-RPC response.
+ *
+ * For outgoing requests, use `trackRequest()` to get a Promise that resolves
+ * when the matching response arrives.
+ */
+export declare class MessageRouter {
+    private readonly requestHandlers;
+    private readonly notificationHandlers;
+    private readonly pendingRequests;
+    /** Register a handler for a JSON-RPC request method. */
+    onRequest(method: string, handler: RequestHandler): void;
+    /** Register a handler for a JSON-RPC notification method. */
+    onNotification(method: string, handler: NotificationHandler): void;
+    /** Remove a previously registered request handler. */
+    removeRequestHandler(method: string): boolean;
+    /** Remove a previously registered notification handler. */
+    removeNotificationHandler(method: string): boolean;
+    /** Check if a request handler is registered for a method. */
+    hasRequestHandler(method: string): boolean;
+    /** Check if a notification handler is registered for a method. */
+    hasNotificationHandler(method: string): boolean;
+    /**
+     * Track an outgoing request by its `id`.
+     *
+     * Returns a Promise that resolves with the result when the matching
+     * response arrives, or rejects if an error response is received.
+     *
+     * @param id - The request `id` to track.
+     * @param method - The method name (for error messages).
+     * @param timeoutMs - Timeout in ms. Defaults to 30_000.
+     */
+    trackRequest(id: string | number, method: string, timeoutMs?: number): Promise<unknown>;
+    /** Number of pending outgoing requests. */
+    get pendingCount(): number;
+    /**
+     * Route an incoming message to the appropriate handler.
+     *
+     * - **Responses** (with `result` or `error`, no `method`) are matched
+     *   against pending outgoing requests by `id`.
+     * - **Requests** (with `id` and `method`) are dispatched to request
+     *   handlers and return a JSON-RPC response.
+     * - **Notifications** (with `method`, no `id`) are dispatched to
+     *   notification handlers and return `null`.
+     */
+    handleMessage(message: McpAppsMessage): Promise<McpAppsResponse | McpAppsErrorResponse | null>;
+    /**
+     * Clean up all pending requests by rejecting them.
+     * Call this when tearing down the router.
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=message-router.d.ts.map

package/script/core/message-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-router.d.ts","sourceRoot":"","sources":["../../src/core/message-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,oBAAoB,EACpB,cAAc,EAGd,eAAe,EAChB,MAAM,YAAY,CAAC;AAEpB,4DAA4D;AAC5D,MAAM,MAAM,cAAc,GAAG,CAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,KACxC,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;AAEhC,6DAA6D;AAC7D,MAAM,MAAM,mBAAmB,GAAG,CAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,KACxC,IAAI,CAAC;AAUV;;;;;;;;;GASG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqC;IACrE,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAA0C;IAC/E,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA8C;IAM9E,wDAAwD;IACxD,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI;IASxD,6DAA6D;IAC7D,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,IAAI;IASlE,sDAAsD;IACtD,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAI7C,2DAA2D;IAC3D,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIlD,6DAA6D;IAC7D,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAI1C,kEAAkE;IAClE,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAQ/C;;;;;;;;;OASG;IACH,YAAY,CACV,EAAE,EAAE,MAAM,GAAG,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,SAAS,SAAS,GACjB,OAAO,CAAC,OAAO,CAAC;IAkCnB,2CAA2C;IAC3C,IAAI,YAAY,IAAI,MAAM,CAEzB;IAMD;;;;;;;;;OASG;IACG,aAAa,CACjB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,eAAe,GAAG,oBAAoB,GAAG,IAAI,CAAC;IAuDzD;;;OAGG;IACH,OAAO,IAAI,IAAI;CAYhB"}

package/script/core/message-router.js

@@ -0,0 +1,191 @@
+"use strict";
+/**
+ * Routes incoming JSON-RPC messages to registered method handlers.
+ *
+ * Supports:
+ * - Request/response dispatch with automatic JSON-RPC response generation
+ * - Notification dispatch (fire-and-forget)
+ * - Pending request tracking for outgoing requests (match response by `id`)
+ * - Handler removal
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MessageRouter = void 0;
+/**
+ * JSON-RPC message router.
+ *
+ * Register handlers for specific method names, then call `handleMessage()`
+ * for each incoming message. The router will dispatch to the correct handler
+ * and produce the appropriate JSON-RPC response.
+ *
+ * For outgoing requests, use `trackRequest()` to get a Promise that resolves
+ * when the matching response arrives.
+ */
+class MessageRouter {
+    requestHandlers = new Map();
+    notificationHandlers = new Map();
+    pendingRequests = new Map();
+    // -------------------------------------------------------------------------
+    // Handler registration
+    // -------------------------------------------------------------------------
+    /** Register a handler for a JSON-RPC request method. */
+    onRequest(method, handler) {
+        if (this.requestHandlers.has(method)) {
+            throw new Error(`[MessageRouter] Request handler already registered for method "${method}".`);
+        }
+        this.requestHandlers.set(method, handler);
+    }
+    /** Register a handler for a JSON-RPC notification method. */
+    onNotification(method, handler) {
+        if (this.notificationHandlers.has(method)) {
+            throw new Error(`[MessageRouter] Notification handler already registered for method "${method}".`);
+        }
+        this.notificationHandlers.set(method, handler);
+    }
+    /** Remove a previously registered request handler. */
+    removeRequestHandler(method) {
+        return this.requestHandlers.delete(method);
+    }
+    /** Remove a previously registered notification handler. */
+    removeNotificationHandler(method) {
+        return this.notificationHandlers.delete(method);
+    }
+    /** Check if a request handler is registered for a method. */
+    hasRequestHandler(method) {
+        return this.requestHandlers.has(method);
+    }
+    /** Check if a notification handler is registered for a method. */
+    hasNotificationHandler(method) {
+        return this.notificationHandlers.has(method);
+    }
+    // -------------------------------------------------------------------------
+    // Outgoing request tracking
+    // -------------------------------------------------------------------------
+    /**
+     * Track an outgoing request by its `id`.
+     *
+     * Returns a Promise that resolves with the result when the matching
+     * response arrives, or rejects if an error response is received.
+     *
+     * @param id - The request `id` to track.
+     * @param method - The method name (for error messages).
+     * @param timeoutMs - Timeout in ms. Defaults to 30_000.
+     */
+    trackRequest(id, method, timeoutMs = 30_000) {
+        if (this.pendingRequests.has(id)) {
+            throw new Error(`[MessageRouter] Request with id "${id}" is already being tracked.`);
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingRequests.delete(id);
+                reject(new Error(`[MessageRouter] Request "${method}" (id=${id}) timed out after ${timeoutMs}ms.`));
+            }, timeoutMs);
+            this.pendingRequests.set(id, {
+                resolve: (result) => {
+                    clearTimeout(timer);
+                    this.pendingRequests.delete(id);
+                    resolve(result);
+                },
+                reject: (error) => {
+                    clearTimeout(timer);
+                    this.pendingRequests.delete(id);
+                    reject(error);
+                },
+                method,
+                createdAt: Date.now(),
+            });
+        });
+    }
+    /** Number of pending outgoing requests. */
+    get pendingCount() {
+        return this.pendingRequests.size;
+    }
+    // -------------------------------------------------------------------------
+    // Message dispatch
+    // -------------------------------------------------------------------------
+    /**
+     * Route an incoming message to the appropriate handler.
+     *
+     * - **Responses** (with `result` or `error`, no `method`) are matched
+     *   against pending outgoing requests by `id`.
+     * - **Requests** (with `id` and `method`) are dispatched to request
+     *   handlers and return a JSON-RPC response.
+     * - **Notifications** (with `method`, no `id`) are dispatched to
+     *   notification handlers and return `null`.
+     */
+    async handleMessage(message) {
+        // Response -> resolve/reject pending request
+        if (isSuccessResponse(message)) {
+            const pending = this.pendingRequests.get(message.id);
+            if (pending) {
+                pending.resolve(message.result);
+            }
+            return null;
+        }
+        if (isErrorResponseMsg(message)) {
+            const pending = message.id !== null
+                ? this.pendingRequests.get(message.id)
+                : undefined;
+            if (pending) {
+                pending.reject(new Error(`[MessageRouter] RPC error ${message.error.code}: ${message.error.message}`));
+            }
+            return null;
+        }
+        if (!isRequestOrNotification(message)) {
+            return null;
+        }
+        const { method, params } = message;
+        // Notification (no id)
+        if (!("id" in message) || message.id === undefined) {
+            const handler = this.notificationHandlers.get(method);
+            if (handler) {
+                handler(params);
+            }
+            return null;
+        }
+        // Request (with id)
+        const reqId = message.id;
+        const handler = this.requestHandlers.get(method);
+        if (!handler) {
+            return errorResponse(reqId, -32601, `Method not found: ${method}`);
+        }
+        try {
+            const result = await handler(params);
+            return successResponse(reqId, result);
+        }
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            return errorResponse(reqId, -32603, errorMessage);
+        }
+    }
+    /**
+     * Clean up all pending requests by rejecting them.
+     * Call this when tearing down the router.
+     */
+    destroy() {
+        for (const [id, pending] of this.pendingRequests) {
+            pending.reject(new Error(`[MessageRouter] Router destroyed while request "${pending.method}" (id=${id}) was pending.`));
+        }
+        this.pendingRequests.clear();
+        this.requestHandlers.clear();
+        this.notificationHandlers.clear();
+    }
+}
+exports.MessageRouter = MessageRouter;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function isRequestOrNotification(msg) {
+    return "method" in msg;
+}
+function isSuccessResponse(msg) {
+    return "result" in msg && "id" in msg && !("method" in msg);
+}
+function isErrorResponseMsg(msg) {
+    return "error" in msg && "id" in msg && !("method" in msg);
+}
+function successResponse(id, result) {
+    return { jsonrpc: "2.0", id, result };
+}
+function errorResponse(id, code, message) {
+    return { jsonrpc: "2.0", id, error: { code, message } };
+}

package/script/core/protocol.d.ts

@@ -0,0 +1,116 @@
+/**
+ * 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 type { HostCapabilities, HostContext, McpAppsErrorResponse, McpAppsMessage, McpAppsNotification, McpAppsRequest, McpAppsResponse } from "./types.js";
+/** Generate a monotonically increasing request ID. */
+export declare function nextRequestId(): number;
+/** Reset the ID counter. @internal — exported for tests only. */
+export declare function resetRequestIdCounter(): void;
+/** Check if a value is a valid JSON-RPC 2.0 message. */
+export declare function isJsonRpcMessage(value: unknown): value is McpAppsMessage;
+/** Check if a message is a JSON-RPC request (has `id` and `method`). */
+export declare function isRequest(msg: McpAppsMessage): msg is McpAppsRequest;
+/** Check if a message is a JSON-RPC notification (has `method`, no `id`). */
+export declare function isNotification(msg: McpAppsMessage): msg is McpAppsNotification;
+/** Check if a message is a JSON-RPC success response. */
+export declare function isResponse(msg: McpAppsMessage): msg is McpAppsResponse;
+/** Check if a message is a JSON-RPC error response. */
+export declare function isErrorResponse(msg: McpAppsMessage): msg is McpAppsErrorResponse;
+/** Build a `ui/initialize` request. */
+export declare function buildInitializeRequest(params: {
+    protocolVersion: string;
+    clientInfo: {
+        name: string;
+        version: string;
+    };
+    capabilities?: Record<string, unknown>;
+}): McpAppsRequest;
+/** Build a `tools/call` request. */
+export declare function buildToolCallRequest(params: {
+    name: string;
+    arguments?: Record<string, unknown>;
+}): McpAppsRequest;
+/** Build a `resources/read` request. */
+export declare function buildResourceReadRequest(params: {
+    uri: string;
+}): McpAppsRequest;
+/** Build a `ui/open-link` request. */
+export declare function buildOpenLinkRequest(params: {
+    url: string;
+}): McpAppsRequest;
+/** Build a `ui/message` request. */
+export declare function buildMessageRequest(params: {
+    content: ReadonlyArray<{
+        type: string;
+        text: string;
+    }>;
+}): McpAppsRequest;
+/** Build a `ui/update-model-context` request. */
+export declare function buildUpdateModelContextRequest(params: {
+    content: ReadonlyArray<{
+        type: string;
+        text: string;
+    }>;
+}): McpAppsRequest;
+/** Build a `ui/request-display-mode` request. */
+export declare function buildDisplayModeRequest(params: {
+    mode: "inline" | "fullscreen" | "pip";
+}): McpAppsRequest;
+/** Build a `ui/notifications/initialized` notification (App -> Host). */
+export declare function buildInitializedNotification(): McpAppsNotification;
+/** Build a `ui/notifications/tool-input` notification (Host -> App). */
+export declare function buildToolInputNotification(params: {
+    name: string;
+    arguments?: Record<string, unknown>;
+}): McpAppsNotification;
+/** Build a `ui/notifications/tool-result` notification (Host -> App). */
+export declare function buildToolResultNotification(params: {
+    content: ReadonlyArray<{
+        type: string;
+        text?: string;
+        data?: string;
+        mimeType?: string;
+    }>;
+    isError?: boolean;
+}): McpAppsNotification;
+/** Build a `ui/notifications/tool-cancelled` notification (Host -> App). */
+export declare function buildToolCancelledNotification(params?: {
+    reason?: string;
+}): McpAppsNotification;
+/** Build a `ui/notifications/host-context-changed` notification. */
+export declare function buildHostContextChangedNotification(params: Partial<HostContext>): McpAppsNotification;
+/** Build a `ui/resource-teardown` request (Host -> App). */
+export declare function buildResourceTeardownRequest(params?: {
+    reason?: string;
+}): McpAppsRequest;
+/** Build a `notifications/message` notification (logging). */
+export declare function buildLogNotification(params: {
+    level: "debug" | "info" | "warning" | "error";
+    data?: unknown;
+    logger?: string;
+}): McpAppsNotification;
+/** Build a `ui/initialize` success response. */
+export declare function buildInitializeResponse(id: string | number, params: {
+    protocolVersion: string;
+    hostInfo: {
+        name: string;
+        version: string;
+    };
+    hostCapabilities: HostCapabilities;
+    hostContext: HostContext;
+}): McpAppsResponse;
+/** Build a generic JSON-RPC success response. */
+export declare function buildSuccessResponse(id: string | number, result: unknown): McpAppsResponse;
+/** Build a JSON-RPC error response. */
+export declare function buildErrorResponse(id: string | number | null, code: number, message: string, data?: unknown): McpAppsErrorResponse;
+export declare const JsonRpcErrorCode: {
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+};
+//# sourceMappingURL=protocol.d.ts.map