feat(server): add getUiCapability helper for capability negotiation (#313)

* feat(server): add hasUiSupport/getUiCapability for experimental+extensions

Support double-tagging for MCP Apps capability negotiation:
- Check both experimental and extensions fields in client capabilities
- Add hasUiSupport() to easily check if client supports MCP Apps
- Add getUiCapability() to retrieve the capability settings
- Update spec to document both capability locations

This enables forward compatibility as MCP transitions from experimental
to the extensions field (SEP-1724).

Claude-Generated-By: Claude Code (cli/claude-opus-4-5=100%)
Claude-Steers: 0
Claude-Permission-Prompts: 0
Claude-Escapes: 0

* fix: update @types/node version in package-lock.json

Replace invalid 22.19.5/22.19.6/22.19.7 versions with valid 22.19.3

* docs(spec): clarify hosts SHOULD double-tag, servers SHOULD check both

- Hosts SHOULD advertise capabilities in both experimental and extensions
- Servers SHOULD check both locations, preferring extensions when present
- Updated example to show double-tagging pattern

* chore: remove double-tagging recommendation, keep hasUiSupport helper

Reverts the spec changes that recommended clients double-tag capabilities
in both experimental and extensions fields. The helper functions remain
as they're useful for checking capability in either location.

* refactor(server): simplify to only getUiCapability, remove hasUiSupport

- Remove hasUiSupport function (use getUiCapability directly)
- Remove double-tagging logic (only check extensions field)
- Add ClientCapabilitiesWithExtensions type using SDK's ClientCapabilities
- Update spec to use getUiCapability
- Simplify tests

* fix: update @see link to getUiCapability

* refactor(server): inline ClientCapabilitiesWithExtensions type in getUiCapability

* refactor: move McpUiClientCapabilities to spec.types.ts

src/generated/schema.json

@@ -28,6 +28,20 @@
       },
       "additionalProperties": false
     },
+    "McpUiClientCapabilities": {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "type": "object",
+      "properties": {
+        "mimeTypes": {
+          "description": "Array of supported MIME types for UI resources.\nMust include `\"text/html;profile=mcp-app\"` for MCP Apps support.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
     "McpUiDisplayMode": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
       "anyOf": [

src/generated/schema.test.ts

@@ -119,6 +119,10 @@ export type McpUiToolMetaSchemaInferredType = z.infer<
   typeof generated.McpUiToolMetaSchema
 >;
 
+export type McpUiClientCapabilitiesSchemaInferredType = z.infer<
+  typeof generated.McpUiClientCapabilitiesSchema
+>;
+
 export type McpUiMessageRequestSchemaInferredType = z.infer<
   typeof generated.McpUiMessageRequestSchema
 >;
@@ -277,6 +281,12 @@ expectType<McpUiToolVisibilitySchemaInferredType>(
 );
 expectType<spec.McpUiToolMeta>({} as McpUiToolMetaSchemaInferredType);
 expectType<McpUiToolMetaSchemaInferredType>({} as spec.McpUiToolMeta);
+expectType<spec.McpUiClientCapabilities>(
+  {} as McpUiClientCapabilitiesSchemaInferredType,
+);
+expectType<McpUiClientCapabilitiesSchemaInferredType>(
+  {} as spec.McpUiClientCapabilities,
+);
 expectType<spec.McpUiMessageRequest>(
   {} as McpUiMessageRequestSchemaInferredType,
 );

src/generated/schema.ts

@@ -562,6 +562,26 @@ export const McpUiToolMetaSchema = z.object({
     ),
 });
 
+/**
+ * @description MCP Apps capability settings advertised by clients to servers.
+ *
+ * Clients advertise these capabilities via the `extensions` field in their
+ * capabilities during MCP initialization. Servers can check for MCP Apps
+ * support using {@link server-helpers!getUiCapability}.
+ */
+export const McpUiClientCapabilitiesSchema = z.object({
+  /**
+   * @description Array of supported MIME types for UI resources.
+   * Must include `"text/html;profile=mcp-app"` for MCP Apps support.
+   */
+  mimeTypes: z
+    .array(z.string())
+    .optional()
+    .describe(
+      'Array of supported MIME types for UI resources.\nMust include `"text/html;profile=mcp-app"` for MCP Apps support.',
+    ),
+});
+
 /**
  * @description Request to send a message to the host's chat interface.
  * @see {@link app!App.sendMessage `App.sendMessage`} for the method that sends this request

src/server/index.test.ts

@@ -4,6 +4,8 @@ import {
   registerAppResource,
   RESOURCE_URI_META_KEY,
   RESOURCE_MIME_TYPE,
+  getUiCapability,
+  EXTENSION_ID,
 } from "./index";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
@@ -318,3 +320,39 @@ describe("registerAppResource", () => {
     expect(result).toEqual(expectedResult);
   });
 });
+
+describe("getUiCapability", () => {
+  const MIME_TYPE = "text/html;profile=mcp-app";
+
+  it("should return undefined for null/undefined capabilities", () => {
+    expect(getUiCapability(null)).toBeUndefined();
+    expect(getUiCapability(undefined)).toBeUndefined();
+  });
+
+  it("should return undefined for empty capabilities", () => {
+    expect(getUiCapability({})).toBeUndefined();
+  });
+
+  it("should return capability from extensions field", () => {
+    const caps = {
+      extensions: {
+        [EXTENSION_ID]: {
+          mimeTypes: [MIME_TYPE],
+        },
+      },
+    };
+    const result = getUiCapability(caps);
+    expect(result).toEqual({ mimeTypes: [MIME_TYPE] });
+  });
+
+  it("should return undefined when extension ID is missing", () => {
+    const caps = {
+      extensions: {
+        "some-other-extension": {
+          mimeTypes: [MIME_TYPE],
+        },
+      },
+    };
+    expect(getUiCapability(caps)).toBeUndefined();
+  });
+});

src/server/index.ts

@@ -36,6 +36,7 @@ import {
   RESOURCE_MIME_TYPE,
   McpUiResourceMeta,
   McpUiToolMeta,
+  McpUiClientCapabilities,
 } from "../app.js";
 import type {
   BaseToolCallback,
@@ -49,7 +50,10 @@ 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";
 
 // Re-exports for convenience
 export { RESOURCE_URI_META_KEY, RESOURCE_MIME_TYPE };
@@ -313,3 +317,58 @@ export function registerAppResource(
     readCallback,
   );
 }
+
+/**
+ * Extension identifier for MCP Apps capability negotiation.
+ *
+ * Used as the key in `extensions` to advertise MCP Apps support.
+ */
+export 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 function getUiCapability(
+  clientCapabilities:
+    | (ClientCapabilities & { extensions?: Record<string, unknown> })
+    | null
+    | undefined,
+): McpUiClientCapabilities | undefined {
+  if (!clientCapabilities) {
+    return undefined;
+  }
+
+  return clientCapabilities.extensions?.[EXTENSION_ID] as
+    | McpUiClientCapabilities
+    | undefined;
+}

src/spec.types.ts

@@ -672,3 +672,18 @@ export const INITIALIZED_METHOD: McpUiInitializedNotification["method"] =
   "ui/notifications/initialized";
 export const REQUEST_DISPLAY_MODE_METHOD: McpUiRequestDisplayModeRequest["method"] =
   "ui/request-display-mode";
+
+/**
+ * @description MCP Apps capability settings advertised by clients to servers.
+ *
+ * Clients advertise these capabilities via the `extensions` field in their
+ * capabilities during MCP initialization. Servers can check for MCP Apps
+ * support using {@link server-helpers!getUiCapability}.
+ */
+export interface McpUiClientCapabilities {
+  /**
+   * @description Array of supported MIME types for UI resources.
+   * Must include `"text/html;profile=mcp-app"` for MCP Apps support.
+   */
+  mimeTypes?: string[];
+}

src/types.ts

@@ -61,6 +61,7 @@ export {
   type McpUiRequestDisplayModeResult,
   type McpUiToolVisibility,
   type McpUiToolMeta,
+  type McpUiClientCapabilities,
 } from "./spec.types.js";
 
 // Import types needed for protocol type unions (not re-exported, just used internally)