@casys/mcp-server 0.13.0 → 0.14.0

package/README.md

@@ -331,6 +331,58 @@ server.registerResource(
 );
 ```
 
+#### Capability negotiation (clients that don't support MCP Apps)
+
+Not every MCP client renders UI resources. Clients that do advertise the
+[MCP Apps extension](https://github.com/modelcontextprotocol/ext-apps) in their
+capabilities (per the SDK 1.29 `extensions` field). Read it from a tool handler
+to decide between rich UI and a text-only fallback:
+
+```typescript
+import { MCP_APP_MIME_TYPE, McpApp } from "@casys/mcp-server";
+
+const app = new McpApp({ name: "weather-server", version: "1.0.0" });
+
+app.registerTool(
+  {
+    name: "get-weather",
+    description: "Get the weather forecast for a city",
+    inputSchema: {
+      type: "object",
+      properties: { city: { type: "string" } },
+      required: ["city"],
+    },
+  },
+  async ({ city }) => {
+    const forecast = await fetchForecast(city);
+    const cap = app.getClientMcpAppsCapability();
+
+    if (cap?.mimeTypes?.includes(MCP_APP_MIME_TYPE)) {
+      // Rich UI: small text summary + interactive resource
+      return {
+        content: [{ type: "text", text: `Forecast for ${city} loaded` }],
+        _meta: { ui: { resourceUri: `ui://weather/${city}` } },
+      };
+    }
+
+    // Text-only fallback for clients that can't render the UI
+    return {
+      content: [{ type: "text", text: formatForecastAsText(forecast) }],
+    };
+  },
+);
+```
+
+`getClientMcpAppsCapability()` returns `undefined` before the client has
+completed its initialize handshake, when the client doesn't advertise MCP Apps
+support, or when the advertised capability is malformed. The standalone
+`getMcpAppsCapability(clientCapabilities)` function is also exported for use
+against arbitrary capability objects.
+
+The constants `MCP_APPS_EXTENSION_ID` (`"io.modelcontextprotocol/ui"`) and
+`MCP_APPS_PROTOCOL_VERSION` (`"2026-01-26"`) are exported for agents that need
+to introspect the protocol target directly.
+
 ---
 
 ## API Reference

package/mod.ts

@@ -102,7 +102,16 @@ export type {
 export type { McpAppOptions as ConcurrentServerOptions } from "./src/types.js";
 
 // MCP Apps constants & viewer utilities
-export { MCP_APP_MIME_TYPE } from "./src/types.js";
+export {
+  MCP_APP_MIME_TYPE,
+  MCP_APPS_EXTENSION_ID,
+  MCP_APPS_PROTOCOL_VERSION,
+} from "./src/types.js";
+
+// MCP Apps capability negotiation (per ext-apps spec 2026-01-26 + SDK 1.29 extensions)
+export { getMcpAppsCapability } from "./src/types.js";
+export type { McpAppsClientCapability } from "./src/types.js";
+
 export type {
   RegisterViewersConfig,
   RegisterViewersSummary,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@casys/mcp-server",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Production-ready MCP server framework with concurrency control, auth, and observability",
   "type": "module",
   "main": "mod.ts",
@@ -10,7 +10,7 @@
     "test": "tsx --test src/**/*_test.ts"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.15.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "hono": "^4.0.0",
     "ajv": "^8.17.1",
     "jose": "^6.0.0",

package/src/mcp-app.ts

@@ -51,6 +51,7 @@ import type {
   HttpRateLimitContext,
   HttpServerOptions,
   McpAppOptions,
+  McpAppsClientCapability,
   MCPResource,
   MCPTool,
   QueueMetrics,
@@ -59,7 +60,11 @@ import type {
   StructuredToolResult,
   ToolHandler,
 } from "./types.js";
-import { MCP_APP_MIME_TYPE, MCP_APP_URI_SCHEME } from "./types.js";
+import {
+  getMcpAppsCapability,
+  MCP_APP_MIME_TYPE,
+  MCP_APP_URI_SCHEME,
+} from "./types.js";
 import { discoverViewers, resolveViewerDistPath } from "./ui/viewer-utils.js";
 import type { DirEntry, DiscoverViewersFS } from "./ui/viewer-utils.js";
 import { buildCspHeader, injectCspMetaTag } from "./security/csp.js";
@@ -1908,6 +1913,43 @@ export class McpApp {
     return this.samplingBridge;
   }
 
+  /**
+   * Read the MCP Apps capability advertised by the connected client.
+   *
+   * Returns the capability object (possibly empty `{}`) when the client
+   * advertised support for MCP Apps via its `extensions` capability,
+   * or `undefined` when:
+   * - the client did not send capabilities yet (called before initialize)
+   * - the client did not advertise the MCP Apps extension at all
+   * - the client sent a malformed extension value
+   *
+   * Use this from a tool handler to decide whether to return a UI
+   * resource (`_meta.ui`) or a text-only fallback. Hosts that don't
+   * support MCP Apps will silently drop the `_meta.ui` field, but
+   * checking explicitly lets you serve a richer text response when
+   * the UI path isn't available.
+   *
+   * @returns MCP Apps capability or `undefined` if not supported.
+   *
+   * @example
+   * ```typescript
+   * const cap = app.getClientMcpAppsCapability();
+   * if (cap?.mimeTypes?.includes(MCP_APP_MIME_TYPE)) {
+   *   return {
+   *     content: [{ type: "text", text: summary }],
+   *     _meta: { ui: { resourceUri: "ui://my-app/dashboard" } },
+   *   };
+   * }
+   * return { content: [{ type: "text", text: detailedTextFallback }] };
+   * ```
+   *
+   * @see {@link getMcpAppsCapability} for the standalone reader
+   * @see {@link MCP_APPS_EXTENSION_ID} for the extension key
+   */
+  getClientMcpAppsCapability(): McpAppsClientCapability | undefined {
+    return getMcpAppsCapability(this.mcpServer.server.getClientCapabilities());
+  }
+
   /**
    * Get queue metrics for monitoring
    */

package/src/types.ts

@@ -251,6 +251,117 @@ export const MCP_APP_MIME_TYPE = "text/html;profile=mcp-app" as const;
 /** URI scheme for MCP Apps resources */
 export const MCP_APP_URI_SCHEME = "ui:" as const;
 
+/**
+ * Well-known extension identifier for the MCP Apps protocol.
+ *
+ * Clients advertise MCP Apps support by including this key in
+ * `clientCapabilities.extensions` (per the MCP SDK 1.29 extensions
+ * feature). Servers read it via {@link getMcpAppsCapability} to decide
+ * whether to register UI-rendering tools or fall back to text-only.
+ *
+ * @see {@link https://github.com/modelcontextprotocol/ext-apps | MCP Apps spec}
+ */
+export const MCP_APPS_EXTENSION_ID = "io.modelcontextprotocol/ui" as const;
+
+/**
+ * MCP Apps protocol spec version this package targets.
+ *
+ * Matches the dated spec at
+ * https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx
+ *
+ * Bump this constant in the same commit that adopts a newer dated spec.
+ */
+export const MCP_APPS_PROTOCOL_VERSION = "2026-01-26" as const;
+
+/**
+ * MCP Apps capability advertised by a client.
+ *
+ * Returned by {@link getMcpAppsCapability} after reading
+ * `clientCapabilities.extensions[MCP_APPS_EXTENSION_ID]`.
+ *
+ * The capability object is intentionally minimal — the spec keeps it
+ * extensible by adding fields rather than removing them, so consumers
+ * MUST tolerate unknown fields.
+ */
+export interface McpAppsClientCapability {
+  /**
+   * MIME types the client can render as MCP Apps.
+   *
+   * Typically includes `"text/html;profile=mcp-app"`. An empty or
+   * absent array means the client advertised support but listed no
+   * concrete mime types — defensively assume nothing.
+   */
+  mimeTypes?: string[];
+}
+
+/**
+ * Read the MCP Apps capability from a client's advertised capabilities.
+ *
+ * Best-effort, defensive reader. Returns `undefined` for any of:
+ * - `null` / `undefined` input
+ * - `clientCapabilities` without an `extensions` field
+ * - `extensions` without the {@link MCP_APPS_EXTENSION_ID} key
+ * - extension value that is not a plain object (string, number, null, ...)
+ *
+ * Malformed `mimeTypes` (wrong type, non-string entries) are silently
+ * filtered rather than thrown — agents reading this function need a
+ * predictable contract that never crashes downstream consumers on
+ * untrusted client data.
+ *
+ * **Validation scope:** this function only validates the *type* of
+ * `mimeTypes` entries (must be string). It does NOT validate that the
+ * strings look like valid mime types (e.g. empty strings or garbage
+ * content pass through). Consumers should compare against known
+ * constants like {@link MCP_APP_MIME_TYPE} via `.includes()` rather
+ * than treating the array as a generic allowlist.
+ *
+ * @param clientCapabilities - The `ClientCapabilities` object from the
+ *   MCP SDK initialize handshake. May be `null` or `undefined` if the
+ *   client never sent capabilities.
+ * @returns The MCP Apps capability if the client advertised support,
+ *   otherwise `undefined`.
+ *
+ * @example
+ * ```typescript
+ * const cap = getMcpAppsCapability(client.getClientCapabilities());
+ * if (cap?.mimeTypes?.includes(MCP_APP_MIME_TYPE)) {
+ *   // register UI-rendering tools
+ * } else {
+ *   // register text-only fallback tools
+ * }
+ * ```
+ */
+export function getMcpAppsCapability(
+  clientCapabilities:
+    | (Record<string, unknown> & { extensions?: Record<string, unknown> })
+    | null
+    | undefined,
+): McpAppsClientCapability | undefined {
+  if (clientCapabilities === null || clientCapabilities === undefined) {
+    return undefined;
+  }
+  const extensions = clientCapabilities.extensions;
+  if (extensions === null || typeof extensions !== "object") {
+    return undefined;
+  }
+  const raw = extensions[MCP_APPS_EXTENSION_ID];
+  if (raw === null || typeof raw !== "object") {
+    return undefined;
+  }
+  // We have a capability object — extract known fields defensively.
+  const result: McpAppsClientCapability = {};
+  const rawMimeTypes = (raw as Record<string, unknown>).mimeTypes;
+  if (Array.isArray(rawMimeTypes)) {
+    const validMimeTypes = rawMimeTypes.filter(
+      (m): m is string => typeof m === "string",
+    );
+    if (validMimeTypes.length > 0) {
+      result.mimeTypes = validMimeTypes;
+    }
+  }
+  return result;
+}
+
 // ============================================
 // MCP Tool Types
 // ============================================