@modelcontextprotocol/ext-apps 0.0.1

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

@@ -0,0 +1,101 @@
+import { Implementation } from "@modelcontextprotocol/sdk/types.js";
+import { App, McpUiAppCapabilities } from "../app";
+export * from "../app";
+/**
+ * Options for configuring the useApp hook.
+ *
+ * Note: This interface does NOT expose App options like `autoResize`.
+ * The hook creates the App with default options (autoResize: true). If you need
+ * custom App options, create the App manually instead of using this hook.
+ *
+ * @see {@link useApp} for the hook that uses these options
+ * @see {@link useAutoResize} for manual auto-resize control with custom App options
+ */
+export interface UseAppOptions {
+    /** App identification (name and version) */
+    appInfo: Implementation;
+    /** Features and capabilities this app provides */
+    capabilities: McpUiAppCapabilities;
+    /**
+     * Called after App is created but before connection.
+     *
+     * Use this to register request/notification handlers that need to be in place
+     * before the initialization handshake completes.
+     *
+     * @param app - The newly created App instance
+     *
+     * @example Register a notification handler
+     * ```typescript
+     * import { McpUiToolInputNotificationSchema } from '@modelcontextprotocol/ext-apps/react';
+     *
+     * onAppCreated: (app) => {
+     *   app.setNotificationHandler(
+     *     McpUiToolInputNotificationSchema,
+     *     (notification) => {
+     *       console.log("Tool input:", notification.params.arguments);
+     *     }
+     *   );
+     * }
+     * ```
+     */
+    onAppCreated?: (app: App) => void;
+}
+/**
+ * State returned by the useApp hook.
+ */
+export interface AppState {
+    /** The connected App instance, null during initialization */
+    app: App | null;
+    /** Whether initialization completed successfully */
+    isConnected: boolean;
+    /** Connection error if initialization failed, null otherwise */
+    error: Error | null;
+}
+/**
+ * React hook to create and connect an MCP App.
+ *
+ * This hook manages the complete lifecycle of an {@link App}: creation, connection,
+ * and cleanup. It automatically creates a {@link PostMessageTransport} to window.parent
+ * and handles initialization.
+ *
+ * **Important**: The hook intentionally does NOT re-run when options change
+ * to avoid reconnection loops. Options are only used during the initial mount.
+ *
+ * **Note**: This is part of the optional React integration. The core SDK
+ * (App, PostMessageTransport) is framework-agnostic and can be
+ * used with any UI framework or vanilla JavaScript.
+ *
+ * @param options - Configuration for the app
+ * @returns Current connection state and app instance. If connection fails during
+ *   initialization, the `error` field will contain the error (typically connection
+ *   timeouts, initialization handshake failures, or transport errors).
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { useApp, McpUiToolInputNotificationSchema } from '@modelcontextprotocol/ext-apps/react';
+ *
+ * function MyApp() {
+ *   const { app, isConnected, error } = useApp({
+ *     appInfo: { name: "MyApp", version: "1.0.0" },
+ *     capabilities: {},
+ *     onAppCreated: (app) => {
+ *       // Register handlers before connection
+ *       app.setNotificationHandler(
+ *         McpUiToolInputNotificationSchema,
+ *         (notification) => {
+ *           console.log("Tool input:", notification.params.arguments);
+ *         }
+ *       );
+ *     },
+ *   });
+ *
+ *   if (error) return <div>Error: {error.message}</div>;
+ *   if (!isConnected) return <div>Connecting...</div>;
+ *   return <div>Connected!</div>;
+ * }
+ * ```
+ *
+ * @see {@link App.connect} for the underlying connection method
+ * @see {@link useAutoResize} for manual auto-resize control when using custom App options
+ */
+export declare function useApp({ appInfo, capabilities, onAppCreated, }: UseAppOptions): AppState;

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

@@ -0,0 +1,51 @@
+import { RefObject } from "react";
+import { App } from "../app";
+/**
+ * React hook that automatically reports UI size changes to the host.
+ *
+ * Uses ResizeObserver to watch `document.body` and `document.documentElement` for
+ * size changes and sends `ui/notifications/size-changed` notifications.
+ *
+ * **Note**: This hook is rarely needed since the {@link useApp} hook automatically enables
+ * auto-resize by default. This hook is provided for advanced cases where you
+ * create the {@link App} manually with `autoResize: false` and want to add auto-resize
+ * behavior later.
+ *
+ * @param app - The connected App instance, or null during initialization
+ * @param elementRef - Currently unused. The hook always observes `document.body`
+ *   and `document.documentElement` regardless of this value. Passing a ref will
+ *   cause unnecessary effect re-runs; omit this parameter.
+ *
+ * @example Manual App creation with custom auto-resize control
+ * ```tsx
+ * function MyComponent() {
+ *   // For custom App options, create App manually instead of using useApp
+ *   const [app, setApp] = useState<App | null>(null);
+ *   const [error, setError] = useState<Error | null>(null);
+ *
+ *   useEffect(() => {
+ *     const myApp = new App(
+ *       { name: "MyApp", version: "1.0.0" },
+ *       {}, // capabilities
+ *       { autoResize: false } // Disable default auto-resize
+ *     );
+ *
+ *     const transport = new PostMessageTransport(window.parent);
+ *     myApp.connect(transport)
+ *       .then(() => setApp(myApp))
+ *       .catch((err) => setError(err));
+ *   }, []);
+ *
+ *   // Add manual auto-resize control
+ *   useAutoResize(app);
+ *
+ *   if (error) return <div>Connection failed: {error.message}</div>;
+ *   return <div>My content</div>;
+ * }
+ * ```
+ *
+ * @see {@link App.setupSizeChangedNotifications} for the underlying implementation
+ * @see {@link useApp} which enables auto-resize by default
+ * @see {@link App} constructor for configuring `autoResize` option
+ */
+export declare function useAutoResize(app: App | null, elementRef?: RefObject<HTMLElement | null>): void;