@casys/mcp-server 0.13.0 → 0.15.0

package/README.md

@@ -41,13 +41,35 @@ stack.
 ## Install
 
 ```bash
-# npm
-npm install @casys/mcp-server
-
-# Deno
+# Deno (primary target — JSR)
 deno add jsr:@casys/mcp-server
+
+# Node (secondary — npm, via build-node compilation)
+npm install @casys/mcp-server
 ```
 
+## Runtime targets
+
+`@casys/mcp-server` is **Deno-first**. The canonical deployment path is Deno 2.x
+running on [Deno Deploy](https://deno.com/deploy) or self-hosted Deno, with a
+Node 20+ distribution as a secondary target via `scripts/build-node.sh` (which
+swaps the HTTP runtime adapter and remaps `@std/*` imports to their npm
+equivalents).
+
+| Runtime                                       |      Status      |
+| --------------------------------------------- | :--------------: |
+| **Deno 2.x** (Deno Deploy, self-hosted)       |    ✅ Primary    |
+| **Node.js 20+** (Express, Hono-on-Node, bare) |   ✅ Secondary   |
+| **Cloudflare Workers / workerd**              | ❌ Not supported |
+| **Browser / WebContainer**                    | ❌ Not supported |
+
+If you need to target Cloudflare Workers or the browser, use
+[`@modelcontextprotocol/server`](https://www.npmjs.com/package/@modelcontextprotocol/server)
+directly with its workerd / browser shims — that package focuses on the protocol
+and runtime portability, while `@casys/mcp-server` focuses on the production
+stack (auth, middleware, observability, multi-tenant, MCP Apps helpers) for Deno
+deployments.
+
 ---
 
 ## Quick Start
@@ -331,6 +353,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.15.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/auth/config.ts

@@ -42,6 +42,17 @@ export interface AuthConfig {
   jwksUri?: string;
   /** Supported scopes */
   scopesSupported?: string[];
+  /**
+   * Absolute HTTP(S) URL where the `/.well-known/oauth-protected-resource`
+   * metadata document is served publicly (RFC 9728 § 3).
+   *
+   * Required when `resource` is an opaque URI (e.g., an OIDC project ID used
+   * as JWT audience per RFC 9728 § 2) — otherwise `JwtAuthProvider` will
+   * throw at construction. When `resource` is itself an HTTP(S) URL, this
+   * field is optional and auto-derived by the factory. Mirrors
+   * `JwtAuthProviderOptions.resourceMetadataUrl`.
+   */
+  resourceMetadataUrl?: string;
 }
 
 /**
@@ -56,6 +67,7 @@ interface ConfigFile {
     issuer?: string;
     jwksUri?: string;
     scopesSupported?: string[];
+    resourceMetadataUrl?: string;
   };
 }
 
@@ -75,6 +87,7 @@ interface ConfigFile {
  * - MCP_AUTH_ISSUER → auth.issuer
  * - MCP_AUTH_JWKS_URI → auth.jwksUri
  * - MCP_AUTH_SCOPES → auth.scopesSupported (space-separated)
+ * - MCP_AUTH_RESOURCE_METADATA_URL → auth.resourceMetadataUrl
  *
  * @param configPath - Path to YAML config file. Defaults to "mcp-server.yaml" in cwd.
  * @returns AuthConfig or null if no auth configured
@@ -94,6 +107,7 @@ export async function loadAuthConfig(
   const envIssuer = env("MCP_AUTH_ISSUER");
   const envJwksUri = env("MCP_AUTH_JWKS_URI");
   const envScopes = env("MCP_AUTH_SCOPES");
+  const envResourceMetadataUrl = env("MCP_AUTH_RESOURCE_METADATA_URL");
 
   // 3. Merge: env overrides YAML
   const provider = envProvider ?? yamlAuth?.provider;
@@ -135,6 +149,8 @@ export async function loadAuthConfig(
     scopesSupported: envScopes
       ? envScopes.split(" ").filter(Boolean)
       : yamlAuth?.scopesSupported,
+    resourceMetadataUrl: envResourceMetadataUrl ??
+      yamlAuth?.resourceMetadataUrl,
   };
 
   // Provider-specific validation (fail-fast)
@@ -165,6 +181,7 @@ export function createAuthProviderFromConfig(config: AuthConfig): AuthProvider {
     audience: config.audience,
     resource: config.resource,
     scopesSupported: config.scopesSupported,
+    resourceMetadataUrl: config.resourceMetadataUrl,
   };
 
   switch (config.provider) {
@@ -225,5 +242,8 @@ async function loadYamlAuth(
         typeof s === "string"
       )
       : undefined,
+    resourceMetadataUrl: typeof auth.resourceMetadataUrl === "string"
+      ? auth.resourceMetadataUrl
+      : undefined,
   };
 }

package/src/auth/jwt-provider.ts

@@ -28,6 +28,23 @@ export interface JwtAuthProviderOptions {
   authorizationServers: string[];
   /** Scopes supported by this server */
   scopesSupported?: string[];
+  /**
+   * Absolute HTTP(S) URL where the `/.well-known/oauth-protected-resource`
+   * metadata document is served publicly. Used to populate the
+   * `resource_metadata` parameter of the WWW-Authenticate challenge
+   * (RFC 9728 § 5) and the `resource_metadata_url` field of
+   * `ProtectedResourceMetadata`.
+   *
+   * - When omitted AND `resource` is an HTTP(S) URL, the factory
+   *   auto-derives `${resource}/.well-known/oauth-protected-resource`.
+   * - When omitted AND `resource` is an opaque URI (e.g., an OIDC project
+   *   ID used as JWT audience — valid per RFC 9728 § 2), the factory
+   *   throws at construction. Set this option explicitly in that case
+   *   (fail-fast, no silent broken header).
+   *
+   * @example "https://my-mcp.example.com/.well-known/oauth-protected-resource"
+   */
+  resourceMetadataUrl?: string;
 }
 
 /**
@@ -54,6 +71,7 @@ interface CachedAuth {
 export class JwtAuthProvider extends AuthProvider {
   private jwks: ReturnType<typeof createRemoteJWKSet>;
   private options: JwtAuthProviderOptions;
+  private readonly resourceMetadataUrl: string;
 
   // Token verification cache: hash(token) → AuthInfo with TTL
   // Prevents redundant JWKS fetches (network round-trip per tool call)
@@ -79,6 +97,32 @@ export class JwtAuthProvider extends AuthProvider {
       );
     }
 
+    // Resolve resource_metadata_url: explicit > auto-derive (if URL) > throw.
+    // Per RFC 9728 § 2, `resource` is an URI identifier and MAY be opaque
+    // (e.g., an OIDC project ID used as JWT audience). The metadata document
+    // URL is a separate concept — always an HTTP(S) URL. We used to derive
+    // it from `resource` by string concatenation, which produced a broken
+    // URL when `resource` was not itself an HTTP(S) URL. 0.15.0+ requires
+    // the caller to provide the URL explicitly whenever `resource` is opaque.
+    if (options.resourceMetadataUrl) {
+      this.resourceMetadataUrl = options.resourceMetadataUrl;
+    } else {
+      const isUrl = /^https?:\/\//.test(options.resource);
+      if (!isUrl) {
+        throw new Error(
+          `[JwtAuthProvider] resourceMetadataUrl is required when 'resource' ` +
+            `is not an HTTP(S) URL (got resource="${options.resource}"). ` +
+            `Per RFC 9728 § 2, 'resource' is an URI identifier that can be ` +
+            `opaque (e.g., an OIDC project ID used as JWT audience). The ` +
+            `metadata document URL is a separate concept. Set 'resourceMetadataUrl' ` +
+            `to the HTTPS URL where your /.well-known/oauth-protected-resource ` +
+            `endpoint is served publicly (e.g., "https://my-mcp.example.com/.well-known/oauth-protected-resource").`,
+        );
+      }
+      const base = options.resource.replace(/\/$/, "");
+      this.resourceMetadataUrl = `${base}/.well-known/oauth-protected-resource`;
+    }
+
     this.options = options;
     const jwksUri = options.jwksUri ??
       `${options.issuer}/.well-known/jwks.json`;
@@ -153,6 +197,7 @@ export class JwtAuthProvider extends AuthProvider {
   getResourceMetadata(): ProtectedResourceMetadata {
     return {
       resource: this.options.resource,
+      resource_metadata_url: this.resourceMetadataUrl,
       authorization_servers: this.options.authorizationServers,
       scopes_supported: this.options.scopesSupported,
       bearer_methods_supported: ["header"],

package/src/auth/middleware.ts

@@ -123,10 +123,10 @@ export function createAuthMiddleware(provider: AuthProvider): Middleware {
       return next();
     }
 
-    const metadata = provider.getResourceMetadata();
-    const resource = metadata.resource;
-    const base = resource.endsWith("/") ? resource.slice(0, -1) : resource;
-    const metadataUrl = `${base}/.well-known/oauth-protected-resource`;
+    // 0.15.0+: provider's getResourceMetadata() always returns a valid
+    // absolute URL in resource_metadata_url (type system guarantees it).
+    // No derivation needed at the middleware level anymore.
+    const metadataUrl = provider.getResourceMetadata().resource_metadata_url;
 
     const token = extractBearerToken(ctx.request);
     if (!token) {

package/src/auth/presets.ts

@@ -23,6 +23,12 @@ export interface PresetOptions {
   resource: string;
   /** Scopes supported by this server */
   scopesSupported?: string[];
+  /**
+   * Absolute HTTP(S) URL where the `/.well-known/oauth-protected-resource`
+   * metadata document is served publicly (RFC 9728 § 3). Required when
+   * `resource` is an opaque URI. See `JwtAuthProviderOptions.resourceMetadataUrl`.
+   */
+  resourceMetadataUrl?: string;
 }
 
 /**
@@ -48,6 +54,7 @@ export function createGitHubAuthProvider(
     resource: options.resource,
     authorizationServers: ["https://token.actions.githubusercontent.com"],
     scopesSupported: options.scopesSupported,
+    resourceMetadataUrl: options.resourceMetadataUrl,
   });
 }
 
@@ -75,6 +82,7 @@ export function createGoogleAuthProvider(
     authorizationServers: ["https://accounts.google.com"],
     jwksUri: "https://www.googleapis.com/oauth2/v3/certs",
     scopesSupported: options.scopesSupported,
+    resourceMetadataUrl: options.resourceMetadataUrl,
   });
 }
 
@@ -104,6 +112,7 @@ export function createAuth0AuthProvider(
     authorizationServers: [issuer],
     jwksUri: `${issuer}.well-known/jwks.json`,
     scopesSupported: options.scopesSupported,
+    resourceMetadataUrl: options.resourceMetadataUrl,
   });
 }
 

package/src/auth/provider.ts

@@ -24,6 +24,8 @@ import type { AuthInfo, ProtectedResourceMetadata } from "./types.js";
  *   getResourceMetadata(): ProtectedResourceMetadata {
  *     return {
  *       resource: "https://my-mcp.example.com",
+ *       resource_metadata_url:
+ *         "https://my-mcp.example.com/.well-known/oauth-protected-resource",
  *       authorization_servers: ["https://auth.example.com"],
  *       bearer_methods_supported: ["header"],
  *     };

package/src/auth/types.ts

@@ -66,9 +66,28 @@ import type { AuthProvider } from "./provider.js";
  * @see https://datatracker.ietf.org/doc/html/rfc9728
  */
 export interface ProtectedResourceMetadata {
-  /** Resource identifier (URL of this MCP server) */
+  /**
+   * RFC 9728 § 2 resource identifier. URI that identifies the protected
+   * resource — used as the JWT `aud` claim. Can be an HTTP(S) URL OR an
+   * opaque URI (e.g., an OIDC project ID). Do NOT assume it's an URL.
+   */
   resource: string;
 
+  /**
+   * Absolute HTTP(S) URL where this metadata document is served publicly.
+   * Per RFC 9728 § 3, this is the URL a client discovers via the
+   * WWW-Authenticate challenge. Always an HTTP(S) URL, regardless of
+   * whether `resource` itself is an URL or an opaque URI.
+   *
+   * REQUIRED as of 0.15.0 — previously derived at the middleware level
+   * from `resource`, which produced a broken URL when `resource` was not
+   * itself an HTTP(S) URL. Callers using the `createOIDCAuthProvider`
+   * factory or `JwtAuthProvider` can omit the explicit value when their
+   * `resource` IS an HTTP(S) URL (the factory auto-derives). Custom
+   * `AuthProvider` subclasses must always set it explicitly.
+   */
+  resource_metadata_url: string;
+
   /** Authorization servers that can issue valid tokens */
   authorization_servers: string[];
 

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";
@@ -1154,15 +1159,16 @@ export class McpApp {
       return c.json(this.authProvider.getResourceMetadata());
     });
 
-    // Helper: build resource metadata URL safely (avoid double slash)
-    const buildMetadataUrl = (resource: string): string => {
-      const base = resource.endsWith("/") ? resource.slice(0, -1) : resource;
-      return `${base}/.well-known/oauth-protected-resource`;
-    };
-
     // Auth verification helper for HTTP endpoints.
     // Returns an error Response if auth is required but token is missing/invalid.
     // Returns null if auth passes or is not configured.
+    //
+    // 0.15.0+: provider's getResourceMetadata() always returns a valid
+    // absolute URL in resource_metadata_url (type-enforced). We used to
+    // derive this URL from `metadata.resource` by string concatenation
+    // (see `buildMetadataUrl` helper, removed 0.15.0), which produced a
+    // broken URL when `resource` was an opaque URI per RFC 9728 § 2
+    // (e.g., an OIDC project ID used as JWT audience).
     const verifyHttpAuth = async (
       request: Request,
     ): Promise<Response | null> => {
@@ -1172,7 +1178,7 @@ export class McpApp {
       if (!token) {
         const metadata = this.authProvider.getResourceMetadata();
         return createUnauthorizedResponse(
-          buildMetadataUrl(metadata.resource),
+          metadata.resource_metadata_url,
           "missing_token",
           "Authorization header with Bearer token required",
         );
@@ -1182,7 +1188,7 @@ export class McpApp {
       if (!authInfo) {
         const metadata = this.authProvider.getResourceMetadata();
         return createUnauthorizedResponse(
-          buildMetadataUrl(metadata.resource),
+          metadata.resource_metadata_url,
           "invalid_token",
           "Invalid or expired token",
         );
@@ -1774,8 +1780,17 @@ export class McpApp {
   /**
    * Build the HTTP middleware stack and return its fetch handler without
    * binding a port. Use this when you want to mount the MCP HTTP layer
-   * inside another HTTP framework (Fresh, Hono, Express, Cloudflare Workers,
-   * etc.) instead of giving up port ownership to {@link startHttp}.
+   * inside another HTTP framework on Deno (Fresh, Hono, `Deno.serve`) or
+   * Node (Express, Hono-on-Node) instead of giving up port ownership to
+   * {@link startHttp}.
+   *
+   * **Runtime targets:** `@casys/mcp-server` is Deno-first — the canonical
+   * deployment path is Deno 2.x on Deno Deploy or self-hosted Deno, with
+   * a Node 20+ distribution via `scripts/build-node.sh` as a secondary
+   * target. Cloudflare Workers, workerd, and browser runtimes are not
+   * supported — if you target those, use
+   * [`@modelcontextprotocol/server`](https://www.npmjs.com/package/@modelcontextprotocol/server)
+   * directly instead.
    *
    * The returned handler accepts a Web Standard {@link Request} and returns
    * a Web Standard {@link Response}. It exposes the same routes as
@@ -1908,6 +1923,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
 // ============================================