@modelcontextprotocol/ext-apps 0.0.1

package/dist/src/message-transport.d.ts

@@ -0,0 +1,129 @@
+import { JSONRPCMessage, MessageExtraInfo } from "@modelcontextprotocol/sdk/types.js";
+import { Transport, TransportSendOptions } from "@modelcontextprotocol/sdk/shared/transport.js";
+/**
+ * JSON-RPC transport using window.postMessage for iframe↔parent communication.
+ *
+ * This transport enables bidirectional communication between MCP Apps running in
+ * iframes and their host applications using the browser's postMessage API. It
+ * implements the MCP SDK's Transport interface.
+ *
+ * ## Security
+ *
+ * The `eventSource` parameter provides origin validation by filtering messages
+ * from specific sources. Guest UIs typically don't need to specify this (they only
+ * communicate with their parent), but hosts should validate the iframe source for
+ * security.
+ *
+ * ## Usage
+ *
+ * **Guest UI (default)**:
+ * ```typescript
+ * const transport = new PostMessageTransport(window.parent);
+ * await app.connect(transport);
+ * ```
+ *
+ * **Host (with source validation)**:
+ * ```typescript
+ * const iframe = document.getElementById('app-iframe') as HTMLIFrameElement;
+ * const transport = new PostMessageTransport(
+ *   iframe.contentWindow!,
+ *   iframe.contentWindow  // Validate messages from this iframe only
+ * );
+ * await bridge.connect(transport);
+ * ```
+ *
+ * @see {@link app.App.connect} for Guest UI usage
+ * @see {@link app-bridge.AppBridge.connect} for Host usage
+ */
+export declare class PostMessageTransport implements Transport {
+    private eventTarget;
+    private eventSource?;
+    private messageListener;
+    /**
+     * Create a new PostMessageTransport.
+     *
+     * @param eventTarget - Target window to send messages to (default: window.parent)
+     * @param eventSource - Optional source validation. If specified, only messages from
+     *   this source will be accepted. Guest UIs typically don't need this (they only
+     *   receive from parent), but hosts should validate the iframe source.
+     *
+     * @example Guest UI connecting to parent
+     * ```typescript
+     * const transport = new PostMessageTransport(window.parent);
+     * ```
+     *
+     * @example Host connecting to iframe with validation
+     * ```typescript
+     * const iframe = document.getElementById('app') as HTMLIFrameElement;
+     * const transport = new PostMessageTransport(
+     *   iframe.contentWindow!,
+     *   iframe.contentWindow  // Only accept messages from this iframe
+     * );
+     * ```
+     */
+    constructor(eventTarget?: Window, eventSource?: MessageEventSource | undefined);
+    /**
+     * Begin listening for messages from the event source.
+     *
+     * Registers a message event listener on the window. Must be called before
+     * messages can be received.
+     */
+    start(): Promise<void>;
+    /**
+     * Send a JSON-RPC message to the target window.
+     *
+     * Messages are sent using postMessage with "*" origin, meaning they are visible
+     * to all frames. The receiver should validate the message source for security.
+     *
+     * @param message - JSON-RPC message to send
+     * @param options - Optional send options (currently unused)
+     */
+    send(message: JSONRPCMessage, options?: TransportSendOptions): Promise<void>;
+    /**
+     * Stop listening for messages and cleanup.
+     *
+     * Removes the message event listener and calls the {@link onclose} callback if set.
+     */
+    close(): Promise<void>;
+    /**
+     * Called when the transport is closed.
+     *
+     * Set this handler to be notified when {@link close} is called.
+     */
+    onclose?: () => void;
+    /**
+     * Called when a message parsing error occurs.
+     *
+     * This handler is invoked when a received message fails JSON-RPC schema
+     * validation. The error parameter contains details about the validation failure.
+     *
+     * @param error - Error describing the validation failure
+     */
+    onerror?: (error: Error) => void;
+    /**
+     * Called when a valid JSON-RPC message is received.
+     *
+     * This handler is invoked after message validation succeeds. The {@link start}
+     * method must be called before messages will be received.
+     *
+     * @param message - The validated JSON-RPC message
+     * @param extra - Optional metadata about the message (unused in this transport)
+     */
+    onmessage?: (message: JSONRPCMessage, extra?: MessageExtraInfo) => void;
+    /**
+     * Optional session identifier for this transport connection.
+     *
+     * Set by the MCP SDK to track the connection session. Not required for
+     * PostMessageTransport functionality.
+     */
+    sessionId?: string;
+    /**
+     * Callback to set the negotiated protocol version.
+     *
+     * The MCP SDK calls this during initialization to communicate the protocol
+     * version negotiated with the peer.
+     *
+     * @param version - The negotiated protocol version string
+     */
+    setProtocolVersion?: (version: string) => void;
+}

package/dist/src/react/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * React utilities for building MCP Apps.
+ *
+ * This module provides React hooks and utilities for easily building
+ * interactive MCP Apps using React. This is optional - the core SDK
+ * ({@link App}, {@link PostMessageTransport}) is framework-agnostic and can be
+ * used with any UI framework or vanilla JavaScript.
+ *
+ * ## Main Exports
+ *
+ * - {@link useApp} - React hook to create and connect an MCP App
+ * - {@link useAutoResize} - React hook for manual auto-resize control (rarely needed)
+ *
+ * @module @modelcontextprotocol/ext-apps/react
+ *
+ * @example Basic React App
+ * ```tsx
+ * import { useApp } from '@modelcontextprotocol/ext-apps/react';
+ *
+ * function MyApp() {
+ *   const { app, isConnected, error } = useApp({
+ *     appInfo: { name: "MyApp", version: "1.0.0" },
+ *     capabilities: {}
+ *   });
+ *
+ *   if (error) return <div>Error: {error.message}</div>;
+ *   if (!isConnected) return <div>Connecting...</div>;
+ *
+ *   return <div>Connected!</div>;
+ * }
+ * ```
+ */
+export * from "./useApp";
+export * from "./useAutoResize";