@cloudinary/asset-management-mcp 0.9.0-rc.0 → 0.9.0

package/src/funcs/uploadDestroyAsset.ts

@@ -4,7 +4,7 @@
  */
 
 import { CloudinaryAssetMgmtCore } from "../core.js";
-import { encodeFormQuery, encodeSimple } from "../lib/encodings.js";
+import { encodeJSON, encodeSimple } from "../lib/encodings.js";
 import { compactMap } from "../lib/primitives.js";
 import { safeParse } from "../lib/schemas.js";
 import { RequestOptions } from "../lib/sdks.js";
@@ -13,6 +13,7 @@ import { pathToFunc } from "../lib/url.js";
 import {
   DestroyAssetRequest,
   DestroyAssetRequest$zodSchema,
+  DestroyAssetRequestBody,
 } from "../models/destroyassetop.js";
 import { APIError } from "../models/errors/apierror.js";
 import {
@@ -33,8 +34,7 @@ import { Result } from "../types/fp.js";
 export function uploadDestroyAsset(
   client$: CloudinaryAssetMgmtCore,
   resource_type: ResourceType,
-  public_id: string,
-  invalidate?: boolean | undefined,
+  RequestBody: DestroyAssetRequestBody,
   options?: RequestOptions,
 ): APIPromise<
   Result<
@@ -51,8 +51,7 @@ export function uploadDestroyAsset(
   return new APIPromise($do(
     client$,
     resource_type,
-    public_id,
-    invalidate,
+    RequestBody,
     options,
   ));
 }
@@ -60,8 +59,7 @@ export function uploadDestroyAsset(
 async function $do(
   client$: CloudinaryAssetMgmtCore,
   resource_type: ResourceType,
-  public_id: string,
-  invalidate?: boolean | undefined,
+  RequestBody: DestroyAssetRequestBody,
   options?: RequestOptions,
 ): Promise<
   [
@@ -80,8 +78,7 @@ async function $do(
 > {
   const input$: DestroyAssetRequest = {
     resource_type: resource_type,
-    public_id: public_id,
-    invalidate: invalidate,
+    RequestBody: RequestBody,
   };
 
   const parsed$ = safeParse(
@@ -93,7 +90,7 @@ async function $do(
     return [parsed$, { status: "invalid" }];
   }
   const payload$ = parsed$.value;
-  const body$ = null;
+  const body$ = encodeJSON("body", payload$.RequestBody, { explode: true });
 
   const pathParams$ = {
     cloud_name: encodeSimple("cloud_name", client$._options.cloud_name, {
@@ -108,12 +105,9 @@ async function $do(
   const path$ = pathToFunc("/v1_1/{cloud_name}/{resource_type}/destroy")(
     pathParams$,
   );
-  const query$ = encodeFormQuery({
-    "invalidate": payload$.invalidate,
-    "public_id": payload$.public_id,
-  });
 
   const headers$ = new Headers(compactMap({
+    "Content-Type": "application/json",
     Accept: "application/json",
   }));
   const securityInput = await extractSecurity(client$._options.security);
@@ -144,7 +138,6 @@ async function $do(
     baseURL: options?.serverURL,
     path: path$,
     headers: headers$,
-    query: query$,
     body: body$,
     userAgent: client$._options.userAgent,
     timeoutMs: options?.timeoutMs || client$._options.timeoutMs

package/src/funcs/uploadText.ts

@@ -20,11 +20,11 @@ import {
 } from "../models/errors/httpclienterrors.js";
 import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
 import {
-  TextRequest,
-  TextRequest$zodSchema,
-  TextRequestBody,
+  TextRequestRequest,
+  TextRequestRequest$zodSchema,
   TextResourceType,
 } from "../models/textop.js";
+import { TextRequest } from "../models/textrequest.js";
 import { APICall, APIPromise } from "../types/async.js";
 import { Result } from "../types/fp.js";
 
@@ -37,7 +37,7 @@ import { Result } from "../types/fp.js";
 export function uploadText(
   client$: CloudinaryAssetMgmtCore,
   resource_type: TextResourceType,
-  RequestBody: TextRequestBody,
+  text_request: TextRequest,
   options?: RequestOptions,
 ): APIPromise<
   Result<
@@ -54,7 +54,7 @@ export function uploadText(
   return new APIPromise($do(
     client$,
     resource_type,
-    RequestBody,
+    text_request,
     options,
   ));
 }
@@ -62,7 +62,7 @@ export function uploadText(
 async function $do(
   client$: CloudinaryAssetMgmtCore,
   resource_type: TextResourceType,
-  RequestBody: TextRequestBody,
+  text_request: TextRequest,
   options?: RequestOptions,
 ): Promise<
   [
@@ -79,21 +79,21 @@ async function $do(
     APICall,
   ]
 > {
-  const input$: TextRequest = {
+  const input$: TextRequestRequest = {
     resource_type: resource_type,
-    RequestBody: RequestBody,
+    text_request: text_request,
   };
 
   const parsed$ = safeParse(
     input$,
-    (value$) => TextRequest$zodSchema.parse(value$),
+    (value$) => TextRequestRequest$zodSchema.parse(value$),
     "Input validation failed",
   );
   if (!parsed$.ok) {
     return [parsed$, { status: "invalid" }];
   }
   const payload$ = parsed$.value;
-  const body$ = encodeJSON("body", payload$.RequestBody, { explode: true });
+  const body$ = encodeJSON("body", payload$.text_request, { explode: true });
 
   const pathParams$ = {
     cloud_name: encodeSimple("cloud_name", client$._options.cloud_name, {

package/src/landing-page.ts

@@ -933,7 +933,7 @@ http_headers = { "api-key" = "YOUR_API_KEY", "api-secret" = "YOUR_API_SECRET", "
         <h1>Instructions</h1>
         <p>One-click installation for Claude Desktop users</p>
         <div class="instruction-item">
-          <a href="https://github.com/cloudinary/asset-management-mcp/releases/download/v0.9.0-rc.0/mcp-server.mcpb" download="mcp-server.mcpb" class="action-button header-action" style="display: inline-flex; margin-bottom: 16px;">
+          <a href="https://github.com/cloudinary/asset-management-mcp/releases/download/v0.9.0/mcp-server.mcpb" download="mcp-server.mcpb" class="action-button header-action" style="display: inline-flex; margin-bottom: 16px;">
             📥 Download MCP Bundle
           </a>
         </div>

package/src/lib/config.ts

@@ -112,9 +112,9 @@ export function serverURLFromOptions(options: SDKOptions): URL | null {
 
 export const SDK_METADATA = {
   language: "typescript",
-  openapiDocVersion: "0.4.0",
-  sdkVersion: "0.9.0-rc.0",
-  genVersion: "2.879.11",
+  openapiDocVersion: "0.5.0",
+  sdkVersion: "0.9.0",
+  genVersion: "2.881.4",
   userAgent:
-    "speakeasy-sdk/mcp-typescript 0.9.0-rc.0 2.879.11 0.4.0 @cloudinary/asset-management-mcp",
+    "speakeasy-sdk/mcp-typescript 0.9.0 2.881.4 0.5.0 @cloudinary/asset-management-mcp",
 } as const;

package/src/lib/sdks.ts

@@ -384,8 +384,6 @@ async function logResponse(
       break;
     case matchContentType(res, "application/jsonl")
       || jsonlLikeContentTypeRE.test(ct):
-      logger.log(await res.clone().text());
-      break;
     case matchContentType(res, "text/event-stream"):
       logger.log(`<${contentType}>`);
       break;

package/src/mcp-server/{widgets/widget-shared.ts → apps/app-shared.ts}

@@ -1,7 +1,7 @@
 /*
- * Shared building blocks for MCP App widgets (gallery + details).
+ * Shared building blocks for MCP Apps (gallery + details).
  * Each export is a raw string fragment to be interpolated into the
- * final HTML template literal of each widget.
+ * final HTML template literal of each app.
  */
 
 import { toJSONSchema } from "zod";
@@ -380,7 +380,7 @@ details.detail-section > summary.detail-section-title::-webkit-details-marker {
 .media-modal-audio-wrap audio { width: 100%; max-width: 480px; }
 .thumb-overlay.playable { pointer-events: auto; cursor: pointer; }
 
-/* Upload widget */
+/* Upload app */
 .upload-zone {
   border: 2px dashed var(--cld-border2); border-radius: var(--cld-radius);
   padding: 40px 24px; text-align: center; cursor: pointer;

package/src/mcp-server/{widgets/asset-details-widget.ts → apps/asset-details-app.ts}

@@ -1,9 +1,9 @@
 /*
- * Standalone MCP App widget for displaying a single Cloudinary asset
+ * Standalone MCP App for displaying a single Cloudinary asset
  * in a rich detail view. Attached to the get-asset-details tool.
  *
  * Shares CLDS tokens, MCPApp client, helpers, and detail renderers
- * with the gallery widget via widget-shared.ts.
+ * with the gallery app via app-shared.ts.
  */
 
 import {
@@ -15,12 +15,11 @@ import {
   SHARED_JS_MODAL,
   SHARED_JS_DETAIL_RENDERERS,
   SHARED_JS_HOST_CONTEXT,
-} from "./widget-shared.js";
+} from "./app-shared.js";
+import { injectToolName } from "./uri.js";
 
-export const ASSET_DETAILS_RESOURCE_URI = "ui://cloudinary/asset-details.html";
-
-export function getAssetDetailsHtml(): string {
-  return ASSET_DETAILS_HTML;
+export function getAssetDetailsHtml(toolName?: string): string {
+  return injectToolName(ASSET_DETAILS_HTML, toolName);
 }
 
 const ASSET_DETAILS_CSS = /* css */ `

package/src/mcp-server/{widgets/asset-gallery-widget.ts → apps/asset-gallery-app.ts}

@@ -1,10 +1,10 @@
 /*
- * MCP App widget for displaying Cloudinary assets in an interactive
+ * MCP App for displaying Cloudinary assets in an interactive
  * gallery. Attached to list-images, list-videos, list-files, and
  * search-assets tools.
  *
  * Shares CLDS tokens, MCPApp client, helpers, and detail renderers
- * with the details widget via widget-shared.ts.
+ * with the details app via app-shared.ts.
  */
 
 import {
@@ -16,13 +16,11 @@ import {
   SHARED_JS_MODAL,
   SHARED_JS_DETAIL_RENDERERS,
   SHARED_JS_HOST_CONTEXT,
-} from "./widget-shared.js";
+} from "./app-shared.js";
+import { injectToolName } from "./uri.js";
 
-export const ASSET_GALLERY_RESOURCE_URI = "ui://cloudinary/asset-gallery.html";
-export const MCP_APP_MIME_TYPE = "text/html;profile=mcp-app";
-
-export function getAssetGalleryHtml(): string {
-  return ASSET_GALLERY_HTML;
+export function getAssetGalleryHtml(toolName?: string): string {
+  return injectToolName(ASSET_GALLERY_HTML, toolName);
 }
 
 const GALLERY_CSS = /* css */ `
@@ -303,7 +301,10 @@ var LOG_PREFIX = "[gallery]";
 var MIN_HEIGHT = 120;
 var allResources = [];
 var lastCursor = null;
-var pendingCall = { name: null, args: null };
+var pendingCall = {
+  name: (typeof window.__MCP_TOOL_NAME__ === "string" && window.__MCP_TOOL_NAME__) || null,
+  args: null,
+};
 var selected = new Set();
 var filterQuery = "";
 var aspectFilter = "";
@@ -915,23 +916,23 @@ app.ontoolcancelled = function(params) {
   showCancelledPrompt(pendingCall, fetchDirect);
 };
 
-function inferToolName(data) {
-  if (data.total_count !== undefined) return "search-assets";
-  var resources = data.resources;
-  if (!resources || !resources.length) return null;
-  var rt = resources[0].resource_type;
-  if (rt === "video") return "list-videos";
-  if (rt === "raw") return "list-files";
-  return "list-images";
+function resolveToolName(result) {
+  if (typeof window.__MCP_TOOL_NAME__ === "string" && window.__MCP_TOOL_NAME__) {
+    return window.__MCP_TOOL_NAME__;
+  }
+  var fromMeta = result && result._meta && result._meta["cloudinary/toolName"];
+  if (fromMeta) return fromMeta;
+  return pendingCall.name;
 }
 
 app.ontoolresult = function(result) {
   var data = ingestResult(result);
+  var name = resolveToolName(result);
+  if (name) pendingCall.name = name;
   if (data && data.resources) {
     console.log(LOG_PREFIX, "host result:", data.resources.length, "resources");
     allResources = data.resources;
     lastCursor = data.next_cursor || null;
-    pendingCall.name = inferToolName(data) || pendingCall.name;
     render(); attachEvents();
     return;
   }
@@ -952,7 +953,11 @@ app.ontoolresult = function(result) {
 };
 
 function showFetchPrompt() {
-  var name = pendingCall.name || "list-images";
+  var name = pendingCall.name;
+  if (!name) {
+    showPersistentError("Unknown Tool", "Could not determine which tool produced this result. Please retry from the host.");
+    return;
+  }
   var root = document.getElementById("app");
   var h = '<div class="prompt">';
   h += '<div class="prompt-icon">\\u{1F4E6}</div>';
@@ -975,7 +980,11 @@ function jsonArgs(src) {
 }
 
 async function fetchDirect() {
-  var name = pendingCall.name || "list-images";
+  var name = pendingCall.name;
+  if (!name) {
+    showPersistentError("Unknown Tool", "Could not determine which tool to call. Please retry from the host.");
+    return;
+  }
   var args = jsonArgs(pendingCall.args || {});
   console.log(LOG_PREFIX, "fetchDirect ->", name);
 
@@ -1000,7 +1009,11 @@ async function fetchDirect() {
 
 async function loadMore() {
   if (!lastCursor) return;
-  var name = pendingCall.name || "list-images";
+  var name = pendingCall.name;
+  if (!name) {
+    showError("Unknown Tool", "Could not determine which tool to call for pagination.");
+    return;
+  }
   var args = name === "search-assets"
     ? { request: { next_cursor: lastCursor } }
     : { next_cursor: lastCursor };

package/src/mcp-server/{widgets/asset-upload-widget.ts → apps/asset-upload-app.ts}

@@ -1,5 +1,5 @@
 /*
- * MCP App widget for uploading assets to Cloudinary.
+ * MCP App for uploading assets to Cloudinary.
  * Attached to the upload-asset tool.
  *
  * Features:
@@ -11,7 +11,7 @@
  *  - Folder picker: combobox with search-folders tool for autocomplete.
  *
  * Shares CLDS tokens, MCPApp client, helpers, and detail renderers
- * with the gallery/details widgets via widget-shared.ts.
+ * with the gallery/details apps via app-shared.ts.
  */
 
 import { toJSONSchema } from "zod";
@@ -24,14 +24,13 @@ import {
   SHARED_JS_MODAL,
   SHARED_JS_DETAIL_RENDERERS,
   SHARED_JS_HOST_CONTEXT,
-} from "./widget-shared.js";
+} from "./app-shared.js";
 import { UploadRequest$zodSchema } from "../../models/uploadrequest.js";
 import { UploadResourceType$zodSchema } from "../../models/uploadresourcetype.js";
+import { injectToolName } from "./uri.js";
 
-export const ASSET_UPLOAD_RESOURCE_URI = "ui://cloudinary/asset-upload.html";
-
-export function getAssetUploadHtml(): string {
-  return ASSET_UPLOAD_HTML;
+export function getAssetUploadHtml(toolName?: string): string {
+  return injectToolName(ASSET_UPLOAD_HTML, toolName);
 }
 
 // ── Build-time schema generation ────────────────────────────────────
@@ -711,7 +710,7 @@ function renderUploadError(title, msg) {
     var safeMsg = esc(msg).replace(/\\n/g, "<br>");
     var h = '<div class="upload-error-msg">' + safeMsg + "</div>";
     h += '<div class="upload-another" style="margin-top:14px">';
-    h += '<button class="prompt-btn prompt-btn-primary" id="retry-upload-btn">Try from Widget</button>';
+    h += '<button class="prompt-btn prompt-btn-primary" id="retry-upload-btn">Try from App</button>';
     h += "</div>";
     wrap.innerHTML = h;
   } else {
@@ -723,7 +722,7 @@ function renderUploadError(title, msg) {
     h += "</div>";
     h += '<div class="upload-error-msg">' + safeMsg + "</div>";
     h += '<div class="upload-another" style="margin-top:14px;text-align:center">';
-    h += '<button class="prompt-btn prompt-btn-primary" id="retry-upload-btn">Try from Widget</button>';
+    h += '<button class="prompt-btn prompt-btn-primary" id="retry-upload-btn">Try from App</button>';
     h += "</div>";
     root.innerHTML = h;
   }
@@ -861,7 +860,7 @@ async function doUpload(fileData, displayHint) {
       if (uploadOrigin === "host") {
         try {
           app._rpc("ui/updateModelContext", {
-            content: [{ type: "text", text: "File uploaded successfully via widget. public_id: " + data.public_id + ", secure_url: " + (data.secure_url || data.url || "") }]
+            content: [{ type: "text", text: "File uploaded successfully via app. public_id: " + data.public_id + ", secure_url: " + (data.secure_url || data.url || "") }]
           });
         } catch (e) { console.warn(LOG_PREFIX, "updateModelContext failed:", e); }
       }
@@ -1028,7 +1027,7 @@ app.ontoolcancelled = function(params) {
   h += '<div style="font-size:14px;font-weight:600;color:var(--cld-text);margin-bottom:4px">Upload Cancelled</div>';
   h += renderParamsList(pendingCall.args);
   h += '<div class="prompt-actions" style="margin-top:14px">';
-  h += '<button class="prompt-btn prompt-btn-primary" id="cancelled-retry-btn">Upload from Widget</button>';
+  h += '<button class="prompt-btn prompt-btn-primary" id="cancelled-retry-btn">Upload from App</button>';
   h += '</div>';
   h += '</div>';
   root.innerHTML = h;

package/src/mcp-server/apps/cli-flag.ts

@@ -0,0 +1,14 @@
+/*
+ * Stricli flag definition for --mcp-apps. Shared between start/serve commands.
+ */
+
+import { parseMcpAppsList } from "./config.js";
+
+export const mcpAppsFlag = {
+  kind: "parsed" as const,
+  brief:
+    "Enable MCP Apps (interactive UI). Bare flag or 'all'/'true' enables all; 'none'/'false' disables; or comma-separated: asset-gallery,asset-details,asset-upload. Env: CLOUDINARY_MCP_APPS.",
+  optional: true as const,
+  inferEmpty: true as const,
+  parse: parseMcpAppsList,
+};

package/src/mcp-server/apps/config.ts

@@ -0,0 +1,48 @@
+/*
+ * MCP Apps configuration: types, constants, flag/env parsing, and resolution.
+ */
+
+import { appUriPrefix } from "./uri.js";
+
+export type McpApp = "asset-gallery" | "asset-details" | "asset-upload";
+
+export const MCP_APPS: readonly McpApp[] = [
+  "asset-gallery",
+  "asset-details",
+  "asset-upload",
+];
+
+// Flip to [...MCP_APPS] to enable MCP Apps by default.
+export const DEFAULT_MCP_APPS: readonly McpApp[] = [];
+
+export function parseMcpAppsList(value: string): McpApp[] {
+  const parts = value.split(",").map((s) => s.trim()).filter(Boolean);
+  // Bare `--mcp-apps` (empty value via inferEmpty) behaves like "all".
+  if (parts.length === 0) return [...MCP_APPS];
+  if (parts.length === 1) {
+    const v = parts[0]!.toLowerCase();
+    if (v === "all" || v === "true") return [...MCP_APPS];
+    if (v === "none" || v === "false") return [];
+  }
+  for (const p of parts) {
+    if (!MCP_APPS.includes(p as McpApp)) {
+      throw new Error(
+        `Invalid mcp-apps value: "${p}". Valid: ${
+          MCP_APPS.join(", ")
+        }, all/true, none/false`,
+      );
+    }
+  }
+  return parts as McpApp[];
+}
+
+export function resolveMcpApps(flag: McpApp[] | undefined): McpApp[] {
+  if (flag !== undefined) return flag;
+  const env = process.env["CLOUDINARY_MCP_APPS"];
+  if (env != null) return parseMcpAppsList(env);
+  return [...DEFAULT_MCP_APPS];
+}
+
+export function enabledAppUriPrefixes(apps: readonly McpApp[]): string[] {
+  return apps.map(appUriPrefix);
+}

package/src/mcp-server/apps/extensions.ts

@@ -0,0 +1,102 @@
+/*
+ * Registers MCP App UI resource templates (gallery, details, upload) on the
+ * server. Each template handles all per-tool variants and bakes the tool name
+ * into the served HTML so the app knows which tool it represents — without
+ * relying on _meta surviving the host's tool-result pipeline.
+ *
+ * Each registration is gated on the set of enabled apps so users can opt in
+ * per app via --mcp-apps or CLOUDINARY_MCP_APPS.
+ */
+
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { Register } from "../extensions.js";
+import { getAssetGalleryHtml } from "./asset-gallery-app.js";
+import { getAssetDetailsHtml } from "./asset-details-app.js";
+import { getAssetUploadHtml } from "./asset-upload-app.js";
+import type { McpApp } from "./config.js";
+import { appUri, appUriTemplate, MCP_APP_MIME_TYPE } from "./uri.js";
+
+const CSP_RESOURCE_DOMAINS = [
+  "https://res.cloudinary.com",
+  "https://*.cloudinary.com",
+];
+
+type AppSpec = {
+  app: McpApp;
+  name: string;
+  description: string;
+  tools: readonly { tool: string; title: string }[];
+  render: (toolName?: string) => string;
+};
+
+const APP_SPECS: readonly AppSpec[] = [
+  {
+    app: "asset-gallery",
+    name: "Asset Gallery",
+    description:
+      "Interactive asset gallery for browsing Cloudinary images, videos, files, and search results",
+    tools: [
+      { tool: "list-images", title: "Browse Images" },
+      { tool: "list-videos", title: "Browse Videos" },
+      { tool: "list-files", title: "Browse Files" },
+      { tool: "search-assets", title: "Search Assets" },
+    ],
+    render: getAssetGalleryHtml,
+  },
+  {
+    app: "asset-details",
+    name: "Asset Details",
+    description: "Interactive single-asset detail view for Cloudinary assets",
+    tools: [{ tool: "get-asset-details", title: "Asset Details" }],
+    render: getAssetDetailsHtml,
+  },
+  {
+    app: "asset-upload",
+    name: "Asset Upload",
+    description:
+      "Interactive upload interface for uploading assets to Cloudinary",
+    tools: [{ tool: "upload-asset", title: "Upload Asset" }],
+    render: getAssetUploadHtml,
+  },
+];
+
+function appResourceContent(uri: URL, html: string) {
+  return {
+    contents: [{
+      uri: uri.toString(),
+      mimeType: MCP_APP_MIME_TYPE,
+      text: html,
+      _meta: { ui: { csp: { resourceDomains: CSP_RESOURCE_DOMAINS } } },
+      // deno-lint-ignore no-explicit-any
+    } as any],
+  };
+}
+
+export function registerAppResources(
+  register: Register,
+  enabledApps: Set<McpApp>,
+): void {
+  for (const spec of APP_SPECS) {
+    if (!enabledApps.has(spec.app)) continue;
+
+    register.resourceTemplate({
+      name: spec.name,
+      description: spec.description,
+      metadata: { mimeType: MCP_APP_MIME_TYPE },
+      resource: new ResourceTemplate(appUriTemplate(spec.app), {
+        list: async () => ({
+          resources: spec.tools.map(({ tool, title }) => ({
+            uri: appUri(spec.app, tool),
+            name: title,
+            mimeType: MCP_APP_MIME_TYPE,
+          })),
+        }),
+      }),
+      scopes: [],
+      read: async (_client, uri, vars, _extra) => {
+        const tool = String(vars["tool"] ?? "");
+        return appResourceContent(uri, spec.render(tool || undefined));
+      },
+    });
+  }
+}

package/src/mcp-server/apps/tool-hooks.ts

@@ -0,0 +1,19 @@
+/*
+ * Hooks wired into tools.ts to gate App UI metadata on the --mcp-apps flag.
+ * Tool identity is conveyed via the per-tool resource URI itself (the
+ * gallery/details/upload apps inject window.__MCP_TOOL_NAME__ into their HTML
+ * at serve time), so we no longer stamp the tool name onto CallToolResult.
+ */
+
+export function shouldForwardToolMeta(
+  meta: Record<string, unknown> | undefined,
+  enabledUriPrefixes: readonly string[],
+): boolean {
+  if (!meta) return false;
+  const ui = (meta as { ui?: { resourceUri?: unknown } }).ui;
+  const uri = ui && typeof ui.resourceUri === "string"
+    ? ui.resourceUri
+    : undefined;
+  if (!uri) return true;
+  return enabledUriPrefixes.some((p) => uri.startsWith(p));
+}

package/src/mcp-server/apps/uri.ts

@@ -0,0 +1,38 @@
+/*
+ * Single convention for MCP App UI resource URIs.
+ *
+ * Shape: ui://cloudinary/<app>/<tool>.html
+ *
+ * The tool name in the URI is the sole carrier of tool identity for the UI
+ * (baked into the served HTML as window.__MCP_TOOL_NAME__), so every URI
+ * produced or matched by the server goes through the helpers below.
+ */
+
+import type { McpApp } from "./config.js";
+
+export const MCP_APP_MIME_TYPE = "text/html;profile=mcp-app";
+
+const ROOT = "ui://cloudinary";
+
+export function appUri(app: McpApp, toolName: string): string {
+  return `${ROOT}/${app}/${toolName}.html`;
+}
+
+export function appUriTemplate(app: McpApp): string {
+  return `${ROOT}/${app}/{tool}.html`;
+}
+
+export function appUriPrefix(app: McpApp): string {
+  return `${ROOT}/${app}/`;
+}
+
+/**
+ * Bake the tool name into the served HTML so the app can read it from
+ * `window.__MCP_TOOL_NAME__` regardless of whether the host forwards _meta.
+ */
+export function injectToolName(html: string, toolName?: string): string {
+  if (!toolName) return html;
+  const inject =
+    `<script>window.__MCP_TOOL_NAME__=${JSON.stringify(toolName)};</script>`;
+  return html.replace("</head>", `${inject}</head>`);
+}

package/src/mcp-server/cli/serve/command.ts

@@ -7,6 +7,7 @@ import { buildCommand } from "@stricli/core";
 import { numberParser } from "@stricli/core";
 import * as z from "zod";
 import { ServerRegion } from "../../../lib/config.js";
+import { mcpAppsFlag } from "../../apps/cli-flag.js";
 import { consoleLoggerLevels } from "../../console-logger.js";
 import { mcpScopes } from "../../scopes.js";
 
@@ -42,7 +43,7 @@ export const serveCommand = buildCommand({
       mode: {
         kind: "enum",
         brief:
-          "Server mode (dynamic: expose list_tools, describe_tool, and execute_tool instead of individual tools)",
+          "Server mode (dynamic: expose list_tools, describe_tool_input, and execute_tool instead of individual tools)",
         values: ["dynamic"],
         optional: true,
       },
@@ -117,6 +118,7 @@ export const serveCommand = buildCommand({
         optional: true,
         parse: (value) => value,
       },
+      "mcp-apps": mcpAppsFlag,
       "log-level": {
         kind: "enum",
         brief: "The log level to use for the server",