@modelcontextprotocol/ext-apps 0.3.1 → 0.4.1

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

@@ -2,27 +2,29 @@ import { Implementation } from "@modelcontextprotocol/sdk/types.js";
 import { App, McpUiAppCapabilities } from "../app";
 export * from "../app";
 /**
- * Options for configuring the useApp hook.
+ * Options for configuring the {@link 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.
+ * Note: This interface does NOT expose {@link 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
+ * @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 */
+    /**
+     * Declares what features this app supports.
+     */
     capabilities: McpUiAppCapabilities;
     /**
-     * Called after App is created but before connection.
+     * Called after {@link 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
+     * @param app - The newly created `App` instance
      *
      * @example Register a notification handler
      * ```typescript
@@ -41,10 +43,10 @@ export interface UseAppOptions {
     onAppCreated?: (app: App) => void;
 }
 /**
- * State returned by the useApp hook.
+ * State returned by the {@link useApp} hook.
  */
 export interface AppState {
-    /** The connected App instance, null during initialization */
+    /** The connected {@link App} instance, null during initialization */
     app: App | null;
     /** Whether initialization completed successfully */
     isConnected: boolean;
@@ -54,16 +56,19 @@ export interface AppState {
 /**
  * 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.
+ * This hook manages {@link App} creation and connection. It automatically
+ * creates a {@link PostMessageTransport} to window.parent and handles
+ * initialization.
+ *
+ * This hook 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.
  *
  * **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.
+ * Furthermore, the `App` instance is NOT closed on unmount. This avoids cleanup
+ * issues during React Strict Mode's double-mount cycle. If you need to
+ * explicitly close the `App`, call {@link App.close} manually.
  *
  * @param options - Configuration for the app
  * @returns Current connection state and app instance. If connection fails during

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

@@ -3,15 +3,17 @@ 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
+ * Uses `ResizeObserver` to watch `document.body` and `document.documentElement` for
  * size changes and sends `ui/notifications/size-changed` notifications.
  *
+ * The hook automatically cleans up the `ResizeObserver` when the component unmounts.
+ *
  * **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 app - The connected {@link 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.
@@ -30,7 +32,7 @@ import { App } from "../app";
  *       { autoResize: false } // Disable default auto-resize
  *     );
  *
- *     const transport = new PostMessageTransport(window.parent);
+ *     const transport = new PostMessageTransport(window.parent, window.parent);
  *     myApp.connect(transport)
  *       .then(() => setApp(myApp))
  *       .catch((err) => setError(err));

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

@@ -2,11 +2,13 @@ import { McpUiTheme } from "../types";
 /**
  * React hook that provides the current document theme reactively.
  *
- * Uses a MutationObserver to watch for changes to the `data-theme` attribute
+ * Uses a `MutationObserver` to watch for changes to the `data-theme` attribute
  * or `class` on `document.documentElement`. When the theme changes (e.g., from
  * host context updates), the hook automatically re-renders your component with
  * the new theme value.
  *
+ * The `MutationObserver` is automatically disconnected when the component unmounts.
+ *
  * @returns The current theme ("light" or "dark")
  *
  * @example Conditionally render based on theme

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

@@ -14,14 +14,13 @@ import { McpUiHostContext } from "../types";
  * this hook ensures they work correctly by setting the `color-scheme` property
  * based on the host's theme preference.
  *
- * @param app - The connected App instance, or null during initialization
+ * @param app - The connected {@link App} instance, or null during initialization
  * @param initialContext - Initial host context from the connection (optional).
  *   If provided, styles and theme will be applied immediately on mount.
  *
- * @example Basic usage with useApp
+ * @example
  * ```tsx
- * import { useApp } from '@modelcontextprotocol/ext-apps/react';
- * import { useHostStyleVariables } from '@modelcontextprotocol/ext-apps/react';
+ * import { useApp, useHostStyleVariables } from '@modelcontextprotocol/ext-apps/react';
  *
  * function MyApp() {
  *   const { app, isConnected } = useApp({
@@ -29,8 +28,8 @@ import { McpUiHostContext } from "../types";
  *     capabilities: {},
  *   });
  *
- *   // Automatically apply host style variables and theme
- *   useHostStyleVariables(app);
+ *   // Apply host styles - pass initial context to apply styles from connect() immediately
+ *   useHostStyleVariables(app, app?.getHostContext());
  *
  *   return (
  *     <div style={{ background: 'var(--color-background-primary)' }}>
@@ -40,15 +39,6 @@ import { McpUiHostContext } from "../types";
  * }
  * ```
  *
- * @example With initial context
- * ```tsx
- * const [hostContext, setHostContext] = useState<McpUiHostContext | null>(null);
- *
- * // ... get initial context from app.connect() result
- *
- * useHostStyleVariables(app, hostContext);
- * ```
- *
  * @see {@link applyHostStyleVariables} for the underlying styles function
  * @see {@link applyDocumentTheme} for the underlying theme function
  * @see {@link useHostFonts} for applying host fonts
@@ -67,7 +57,7 @@ export declare function useHostStyleVariables(app: App | null, initialContext?:
  * The hook also applies fonts from the initial host context when
  * the app first connects.
  *
- * @param app - The connected App instance, or null during initialization
+ * @param app - The connected {@link App} instance, or null during initialization
  * @param initialContext - Initial host context from the connection (optional).
  *   If provided, fonts will be applied immediately on mount.
  *
@@ -107,13 +97,24 @@ export declare function useHostStyleVariables(app: App | null, initialContext?:
  */
 export declare function useHostFonts(app: App | null, initialContext?: McpUiHostContext | null): void;
 /**
- * React hook that applies host styles, fonts, and theme.
+ * Applies all host styling (CSS variables, theme, and fonts) to match the host application.
  *
  * This is a convenience hook that combines {@link useHostStyleVariables} and
  * {@link useHostFonts}. Use the individual hooks if you need more control.
  *
- * @param app - The connected App instance, or null during initialization
+ * @param app - The connected {@link App} instance, or null during initialization
  * @param initialContext - Initial host context from the connection (optional).
+ *   Pass `app?.getHostContext()` to apply styles immediately on mount.
+ *
+ * @example
+ * ```tsx
+ * function MyApp() {
+ *   const { app } = useApp({ appInfo, capabilities: {} });
+ *   useHostStyles(app, app?.getHostContext());
+ *
+ *   return <div style={{ background: 'var(--color-background-primary)' }}>...</div>;
+ * }
+ * ```
  *
  * @see {@link useHostStyleVariables} for style variables and theme only
  * @see {@link useHostFonts} for fonts only

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

@@ -1,7 +1,25 @@
 /**
- * Server Helpers for MCP Apps.
+ * Utilities for MCP servers to register tools and resources that display interactive UIs.
+ *
+ * Use these helpers instead of the base SDK's `registerTool` and `registerResource` when
+ * your tool should render an {@link app!App} in the client. They handle UI metadata normalization
+ * and provide sensible defaults for the MCP Apps MIME type ({@link RESOURCE_MIME_TYPE}).
  *
  * @module server-helpers
+ *
+ * @example
+ * ```typescript
+ * import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE } from '@modelcontextprotocol/ext-apps/server';
+ *
+ * // Register a tool that displays a widget
+ * registerAppTool(server, "weather", {
+ *   description: "Get weather forecast",
+ *   _meta: { ui: { resourceUri: "ui://weather/widget.html" } },
+ * }, handler);
+ *
+ * // Register the HTML resource the tool references
+ * registerAppResource(server, "Weather Widget", "ui://weather/widget.html", {}, readCallback);
+ * ```
  */
 import { RESOURCE_URI_META_KEY, RESOURCE_MIME_TYPE, McpUiResourceMeta, McpUiToolMeta } from "../app.js";
 import type { McpServer, RegisteredTool, ResourceMetadata, ToolCallback, ReadResourceCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -10,7 +28,8 @@ import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 export { RESOURCE_URI_META_KEY, RESOURCE_MIME_TYPE };
 export type { ResourceMetadata, ToolCallback, ReadResourceCallback };
 /**
- * Tool configuration (same as McpServer.registerTool).
+ * Base tool configuration matching the standard MCP server tool options.
+ * Extended by {@link McpUiAppToolConfig} to add UI metadata requirements.
  */
 export interface ToolConfig {
     title?: string;
@@ -21,7 +40,14 @@ export interface ToolConfig {
     _meta?: Record<string, unknown>;
 }
 /**
- * MCP App Tool configuration for `registerAppTool`.
+ * Configuration for tools that render an interactive UI.
+ *
+ * Extends {@link ToolConfig} with a required `_meta` field that specifies UI metadata.
+ * The UI resource can be specified in two ways:
+ * - `_meta.ui.resourceUri` (preferred)
+ * - `_meta["ui/resourceUri"]` (deprecated, for backward compatibility)
+ *
+ * @see {@link registerAppTool} for the recommended way to register app tools
  */
 export interface McpUiAppToolConfig extends ToolConfig {
     _meta: {
@@ -41,10 +67,22 @@ export interface McpUiAppToolConfig extends ToolConfig {
     });
 }
 /**
- * MCP App Resource configuration for `registerAppResource`.
+ * MCP App Resource configuration for {@link registerAppResource}.
+ *
+ * Extends the base MCP SDK `ResourceMetadata` with optional UI metadata
+ * for configuring security policies and rendering preferences.
+ *
+ * @see {@link registerAppResource} for usage
  */
 export interface McpUiAppResourceConfig extends ResourceMetadata {
+    /**
+     * Optional UI metadata for the resource.
+     * Used to configure security policies (CSP) and rendering preferences.
+     */
     _meta?: {
+        /**
+         * UI-specific metadata including CSP configuration and rendering preferences.
+         */
         ui?: McpUiResourceMeta;
         [key: string]: unknown;
     };
@@ -52,14 +90,16 @@ export interface McpUiAppResourceConfig extends ResourceMetadata {
 /**
  * Register an app tool with the MCP server.
  *
- * This is a convenience wrapper around `server.registerTool` that will allow more backwards-compatibility.
+ * This is a convenience wrapper around `server.registerTool` that normalizes
+ * UI metadata: if `_meta.ui.resourceUri` is set, the legacy `_meta["ui/resourceUri"]`
+ * key is also populated (and vice versa) for compatibility with older hosts.
  *
  * @param server - The MCP server instance
  * @param name - Tool name/identifier
- * @param config - Tool configuration with required `ui` field
- * @param handler - Tool handler function
+ * @param config - Tool configuration with `_meta` field containing UI metadata
+ * @param cb - Tool handler function
  *
- * @example
+ * @example Basic usage
  * ```typescript
  * import { registerAppTool } from '@modelcontextprotocol/ext-apps/server';
  * import { z } from 'zod';
@@ -69,13 +109,50 @@ export interface McpUiAppResourceConfig extends ResourceMetadata {
  *   description: "Get current weather for a location",
  *   inputSchema: { location: z.string() },
  *   _meta: {
- *     [RESOURCE_URI_META_KEY]: "ui://weather/widget.html",
+ *     ui: { resourceUri: "ui://weather/widget.html" },
  *   },
  * }, async (args) => {
  *   const weather = await fetchWeather(args.location);
  *   return { content: [{ type: "text", text: JSON.stringify(weather) }] };
  * });
  * ```
+ *
+ * @example Tool visibility - create app-only tools for UI actions
+ * ```typescript
+ * import { registerAppTool } from '@modelcontextprotocol/ext-apps/server';
+ * import { z } from 'zod';
+ *
+ * // Main tool - visible to both model and app (default)
+ * registerAppTool(server, "show-cart", {
+ *   description: "Display the user's shopping cart",
+ *   _meta: {
+ *     ui: {
+ *       resourceUri: "ui://shop/cart.html",
+ *       visibility: ["model", "app"],
+ *     },
+ *   },
+ * }, async () => {
+ *   const cart = await getCart();
+ *   return { content: [{ type: "text", text: JSON.stringify(cart) }] };
+ * });
+ *
+ * // App-only tool - hidden from the model, only callable by the UI
+ * registerAppTool(server, "update-quantity", {
+ *   description: "Update item quantity in cart",
+ *   inputSchema: { itemId: z.string(), quantity: z.number() },
+ *   _meta: {
+ *     ui: {
+ *       resourceUri: "ui://shop/cart.html",
+ *       visibility: ["app"],
+ *     },
+ *   },
+ * }, async ({ itemId, quantity }) => {
+ *   const cart = await updateCartItem(itemId, quantity);
+ *   return { content: [{ type: "text", text: JSON.stringify(cart) }] };
+ * });
+ * ```
+ *
+ * @see {@link registerAppResource} to register the HTML resource referenced by the tool
  */
 export declare function registerAppTool<OutputArgs extends ZodRawShapeCompat | AnySchema, InputArgs extends undefined | ZodRawShapeCompat | AnySchema = undefined>(server: Pick<McpServer, "registerTool">, name: string, config: McpUiAppToolConfig & {
     inputSchema?: InputArgs;
@@ -85,22 +162,21 @@ export declare function registerAppTool<OutputArgs extends ZodRawShapeCompat | A
  * Register an app resource with the MCP server.
  *
  * This is a convenience wrapper around `server.registerResource` that:
- * - Defaults the MIME type to "text/html;profile=mcp-app"
+ * - Defaults the MIME type to {@link RESOURCE_MIME_TYPE} (`"text/html;profile=mcp-app"`)
  * - Provides a cleaner API matching the SDK's callback signature
  *
  * @param server - The MCP server instance
  * @param name - Human-readable resource name
- * @param uri - Resource URI (should match the `ui` field in tool config)
+ * @param uri - Resource URI (should match the `_meta.ui` field in tool config)
  * @param config - Resource configuration
  * @param readCallback - Callback that returns the resource contents
  *
- * @example
+ * @example Basic usage
  * ```typescript
  * import { registerAppResource } from '@modelcontextprotocol/ext-apps/server';
  *
  * registerAppResource(server, "Weather Widget", "ui://weather/widget.html", {
  *   description: "Interactive weather display",
- *   mimeType: RESOURCE_MIME_TYPE,
  * }, async () => ({
  *   contents: [{
  *     uri: "ui://weather/widget.html",
@@ -109,5 +185,22 @@ export declare function registerAppTool<OutputArgs extends ZodRawShapeCompat | A
  *   }],
  * }));
  * ```
+ *
+ * @example With CSP configuration for external domains
+ * ```typescript
+ * registerAppResource(server, "Music Player", "ui://music/player.html", {
+ *   description: "Audio player with external soundfonts",
+ *   _meta: {
+ *     ui: {
+ *       csp: {
+ *         connectDomains: ["https://api.example.com"],  // For fetch/WebSocket
+ *         resourceDomains: ["https://cdn.example.com"], // For scripts/styles/images
+ *       },
+ *     },
+ *   },
+ * }, readCallback);
+ * ```
+ *
+ * @see {@link registerAppTool} to register tools that reference this resource
  */
 export declare function registerAppResource(server: Pick<McpServer, "registerResource">, name: string, uri: string, config: McpUiAppResourceConfig, readCallback: ReadResourceCallback): void;