@modelcontextprotocol/ext-apps 0.4.1 → 1.0.0

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

@@ -2,34 +2,43 @@
  * 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}).
+ * your tool should render an {@link app!App `App`} in the client. They handle UI metadata normalization
+ * and provide sensible defaults for the MCP Apps MIME type ({@link RESOURCE_MIME_TYPE `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);
+ * ```ts source="./index.examples.ts#index_overview"
+ * // Register a tool that displays a view
+ * registerAppTool(
+ *   server,
+ *   "weather",
+ *   {
+ *     description: "Get weather forecast",
+ *     _meta: { ui: { resourceUri: "ui://weather/view.html" } },
+ *   },
+ *   toolCallback,
+ * );
  *
  * // Register the HTML resource the tool references
- * registerAppResource(server, "Weather Widget", "ui://weather/widget.html", {}, readCallback);
+ * registerAppResource(
+ *   server,
+ *   "Weather View",
+ *   "ui://weather/view.html",
+ *   {},
+ *   readCallback,
+ * );
  * ```
  */
-import { RESOURCE_URI_META_KEY, RESOURCE_MIME_TYPE, McpUiResourceMeta, McpUiToolMeta } from "../app.js";
+import { RESOURCE_URI_META_KEY, RESOURCE_MIME_TYPE, McpUiResourceMeta, McpUiToolMeta, McpUiClientCapabilities } from "../app.js";
 import type { McpServer, RegisteredTool, ResourceMetadata, ToolCallback, ReadResourceCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { AnySchema, ZodRawShapeCompat } from "@modelcontextprotocol/sdk/server/zod-compat.js";
-import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import type { ClientCapabilities, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 export { RESOURCE_URI_META_KEY, RESOURCE_MIME_TYPE };
 export type { ResourceMetadata, ToolCallback, ReadResourceCallback };
 /**
  * Base tool configuration matching the standard MCP server tool options.
- * Extended by {@link McpUiAppToolConfig} to add UI metadata requirements.
+ * Extended by {@link McpUiAppToolConfig `McpUiAppToolConfig`} to add UI metadata requirements.
  */
 export interface ToolConfig {
     title?: string;
@@ -42,12 +51,12 @@ export interface ToolConfig {
 /**
  * Configuration for tools that render an interactive UI.
  *
- * Extends {@link ToolConfig} with a required `_meta` field that specifies UI metadata.
+ * Extends {@link ToolConfig `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
+ * @see {@link registerAppTool `registerAppTool`} for the recommended way to register app tools
  */
 export interface McpUiAppToolConfig extends ToolConfig {
     _meta: {
@@ -59,7 +68,7 @@ export interface McpUiAppToolConfig extends ToolConfig {
          * URI of the UI resource to display for this tool.
          * This is converted to `_meta["ui/resourceUri"]`.
          *
-         * @example "ui://weather/widget.html"
+         * @example "ui://weather/view.html"
          *
          * @deprecated Use `_meta.ui.resourceUri` instead.
          */
@@ -67,12 +76,12 @@ export interface McpUiAppToolConfig extends ToolConfig {
     });
 }
 /**
- * MCP App Resource configuration for {@link registerAppResource}.
+ * MCP App Resource configuration for {@link registerAppResource `registerAppResource`}.
  *
  * Extends the base MCP SDK `ResourceMetadata` with optional UI metadata
  * for configuring security policies and rendering preferences.
  *
- * @see {@link registerAppResource} for usage
+ * @see {@link registerAppResource `registerAppResource`} for usage
  */
 export interface McpUiAppResourceConfig extends ResourceMetadata {
     /**
@@ -100,59 +109,69 @@ export interface McpUiAppResourceConfig extends ResourceMetadata {
  * @param cb - Tool handler function
  *
  * @example Basic usage
- * ```typescript
- * import { registerAppTool } from '@modelcontextprotocol/ext-apps/server';
- * import { z } from 'zod';
- *
- * registerAppTool(server, "get-weather", {
- *   title: "Get Weather",
- *   description: "Get current weather for a location",
- *   inputSchema: { location: z.string() },
- *   _meta: {
- *     ui: { resourceUri: "ui://weather/widget.html" },
+ * ```ts source="./index.examples.ts#registerAppTool_basicUsage"
+ * registerAppTool(
+ *   server,
+ *   "get-weather",
+ *   {
+ *     title: "Get Weather",
+ *     description: "Get current weather for a location",
+ *     inputSchema: { location: z.string() },
+ *     _meta: {
+ *       ui: { resourceUri: "ui://weather/view.html" },
+ *     },
+ *   },
+ *   async (args) => {
+ *     const weather = await fetchWeather(args.location);
+ *     return { content: [{ type: "text", text: JSON.stringify(weather) }] };
  *   },
- * }, 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"],
+ * @example Tool visible to model but not callable by UI
+ * ```ts source="./index.examples.ts#registerAppTool_modelOnlyVisibility"
+ * registerAppTool(
+ *   server,
+ *   "show-cart",
+ *   {
+ *     description: "Display the user's shopping cart",
+ *     _meta: {
+ *       ui: {
+ *         resourceUri: "ui://shop/cart.html",
+ *         visibility: ["model"],
+ *       },
  *     },
  *   },
- * }, 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 () => {
+ *     const cart = await getCart();
+ *     return { content: [{ type: "text", text: JSON.stringify(cart) }] };
+ *   },
+ * );
+ * ```
+ *
+ * @example Tool hidden from model, only callable by UI
+ * ```ts source="./index.examples.ts#registerAppTool_appOnlyVisibility"
+ * 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) }] };
- * });
+ *   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
+ * @see {@link registerAppResource `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;
@@ -162,7 +181,7 @@ 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 {@link RESOURCE_MIME_TYPE} (`"text/html;profile=mcp-app"`)
+ * - Defaults the MIME type to {@link RESOURCE_MIME_TYPE `RESOURCE_MIME_TYPE`} (`"text/html;profile=mcp-app"`)
  * - Provides a cleaner API matching the SDK's callback signature
  *
  * @param server - The MCP server instance
@@ -172,35 +191,97 @@ export declare function registerAppTool<OutputArgs extends ZodRawShapeCompat | A
  * @param readCallback - Callback that returns the resource contents
  *
  * @example Basic usage
- * ```typescript
- * import { registerAppResource } from '@modelcontextprotocol/ext-apps/server';
- *
- * registerAppResource(server, "Weather Widget", "ui://weather/widget.html", {
- *   description: "Interactive weather display",
- * }, async () => ({
- *   contents: [{
- *     uri: "ui://weather/widget.html",
- *     mimeType: RESOURCE_MIME_TYPE,
- *     text: await fs.readFile("dist/widget.html", "utf-8"),
- *   }],
- * }));
+ * ```ts source="./index.examples.ts#registerAppResource_basicUsage"
+ * registerAppResource(
+ *   server,
+ *   "Weather View",
+ *   "ui://weather/view.html",
+ *   {
+ *     description: "Interactive weather display",
+ *   },
+ *   async () => ({
+ *     contents: [
+ *       {
+ *         uri: "ui://weather/view.html",
+ *         mimeType: RESOURCE_MIME_TYPE,
+ *         text: await fs.readFile("dist/view.html", "utf-8"),
+ *       },
+ *     ],
+ *   }),
+ * );
  * ```
  *
  * @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
- *       },
- *     },
+ * ```ts source="./index.examples.ts#registerAppResource_withCsp"
+ * registerAppResource(
+ *   server,
+ *   "Music Player",
+ *   "ui://music/player.html",
+ *   {
+ *     description: "Audio player with external soundfonts",
  *   },
- * }, readCallback);
+ *   async () => ({
+ *     contents: [
+ *       {
+ *         uri: "ui://music/player.html",
+ *         mimeType: RESOURCE_MIME_TYPE,
+ *         text: musicPlayerHtml,
+ *         _meta: {
+ *           ui: {
+ *             csp: {
+ *               resourceDomains: ["https://cdn.example.com"], // For scripts/styles/images
+ *               connectDomains: ["https://api.example.com"], // For fetch/WebSocket
+ *             },
+ *           },
+ *         },
+ *       },
+ *     ],
+ *   }),
+ * );
  * ```
  *
- * @see {@link registerAppTool} to register tools that reference this resource
+ * @see {@link registerAppTool `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;
+/**
+ * Extension identifier for MCP Apps capability negotiation.
+ *
+ * Used as the key in `extensions` to advertise MCP Apps support.
+ */
+export declare const EXTENSION_ID = "io.modelcontextprotocol/ui";
+/**
+ * Get MCP Apps capability settings from client capabilities.
+ *
+ * This helper retrieves the capability object from the `extensions` field
+ * where MCP Apps advertises its support.
+ *
+ * Note: The `clientCapabilities` parameter extends the SDK's `ClientCapabilities`
+ * type with an `extensions` field (pending SEP-1724). Once `extensions` is added
+ * to the SDK, this can use `ClientCapabilities` directly.
+ *
+ * @param clientCapabilities - The client capabilities from the initialize response
+ * @returns The MCP Apps capability settings, or `undefined` if not supported
+ *
+ * @example Check for MCP Apps support in server initialization
+ * ```typescript
+ * import { getUiCapability, RESOURCE_MIME_TYPE, registerAppTool } from "@modelcontextprotocol/ext-apps/server";
+ *
+ * server.oninitialized = ({ clientCapabilities }) => {
+ *   const uiCap = getUiCapability(clientCapabilities);
+ *   if (uiCap?.mimeTypes?.includes(RESOURCE_MIME_TYPE)) {
+ *     registerAppTool(server, "weather", {
+ *       description: "Get weather with interactive dashboard",
+ *       _meta: { ui: { resourceUri: "ui://weather/dashboard" } },
+ *     }, weatherHandler);
+ *   } else {
+ *     // Register text-only fallback
+ *     server.registerTool("weather", {
+ *       description: "Get weather as text",
+ *     }, textWeatherHandler);
+ *   }
+ * };
+ * ```
+ */
+export declare function getUiCapability(clientCapabilities: (ClientCapabilities & {
+    extensions?: Record<string, unknown>;
+}) | null | undefined): McpUiClientCapabilities | undefined;

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

@@ -0,0 +1,9 @@
+/**
+ * Type-checked examples for {@link registerAppTool `registerAppTool`} and {@link registerAppResource `registerAppResource`}.
+ *
+ * These examples are included in the API documentation via `@includeCode` tags.
+ * Each function's region markers define the code snippet that appears in the docs.
+ *
+ * @module
+ */
+export {};