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

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",

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

@@ -7,6 +7,7 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import express from "express";
 import { LocalContext } from "../../cli.js";
+import { resolveMcpApps } from "../../apps/config.js";
 import {
   ConsoleLoggerLevel,
   createConsoleLogger,
@@ -76,6 +77,7 @@ async function startStreamableHTTP(cliFlags: ServeCommandFlags) {
       serverIdx: cliFlags["server-index"],
       region: cliFlags.region,
       host: cliFlags["api-host"],
+      mcpApps: resolveMcpApps(cliFlags["mcp-apps"]),
     });
 
     mcpServer.server.onerror = (error) => {

package/src/mcp-server/cli/start/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 startCommand = 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 startCommand = buildCommand({
         optional: true,
         parse: (value) => value,
       },
+      "mcp-apps": mcpAppsFlag,
       "log-level": {
         kind: "enum",
         brief: "The log level to use for the server",

package/src/mcp-server/cli/start/impl.ts

@@ -7,6 +7,7 @@ import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import express from "express";
 import { LocalContext } from "../../cli.js";
+import { resolveMcpApps } from "../../apps/config.js";
 import {
   ConsoleLoggerLevel,
   createConsoleLogger,
@@ -70,6 +71,7 @@ async function startStdio(flags: StartCommandFlags) {
     serverIdx: flags["server-index"],
     region: flags.region,
     host: flags["api-host"],
+    mcpApps: resolveMcpApps(flags["mcp-apps"]),
   });
   await server.connect(transport);
 
@@ -135,6 +137,7 @@ async function startSSE(cliFlags: StartCommandFlags) {
       serverIdx: flags["server-index"],
       region: flags.region,
       host: flags["api-host"],
+      mcpApps: resolveMcpApps(flags["mcp-apps"]),
     });
 
     // Message path includes session ID for routing

package/src/mcp-server/flags.ts

@@ -4,6 +4,7 @@
  */
 
 import { SDKOptions } from "../lib/config.js";
+import type { McpApp } from "./apps/config.js";
 import { MCPScope } from "./scopes.js";
 
 /**
@@ -23,4 +24,5 @@ export interface MCPServerFlags {
   readonly "server-index"?: SDKOptions["serverIdx"];
   readonly region?: SDKOptions["region"];
   readonly "api-host"?: SDKOptions["host"];
+  readonly "mcp-apps"?: McpApp[] | undefined;
 }

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

@@ -22,7 +22,7 @@ const routes = buildRouteMap({
 export const app = buildApplication(routes, {
   name: "mcp",
   versionInfo: {
-    currentVersion: "0.9.0-rc.0",
+    currentVersion: "0.9.1",
   },
 });
 

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

@@ -7,23 +7,17 @@ import { Register } from "./extensions.js";
 import { formatResult } from "./tools.js";
 import { assetsExplicitAsset } from "../funcs/assetsExplicitAsset.js";
 import { ResourceType$zodSchema } from "../models/resourcetype.js";
-import {
-  ASSET_GALLERY_RESOURCE_URI,
-  MCP_APP_MIME_TYPE,
-  getAssetGalleryHtml,
-} from "./widgets/asset-gallery-widget.js";
-import {
-  ASSET_DETAILS_RESOURCE_URI,
-  getAssetDetailsHtml,
-} from "./widgets/asset-details-widget.js";
-import {
-  ASSET_UPLOAD_RESOURCE_URI,
-  getAssetUploadHtml,
-} from "./widgets/asset-upload-widget.js";
+import type { McpApp } from "./apps/config.js";
+import { registerAppResources } from "./apps/extensions.js";
 
 const TX_RULES_URL = "https://cloudinary.com/documentation/cloudinary_transformation_rules.md";
 
-export function registerMCPExtensions(register: Register): void {
+export function registerMCPExtensions(
+  register: Register,
+  mcpApps: McpApp[] = [],
+): void {
+  registerAppResources(register, new Set(mcpApps));
+
   // Get transformation reference tool
   register.tool({
     name: "get-tx-reference",
@@ -68,90 +62,6 @@ export function registerMCPExtensions(register: Register): void {
     }
   });
 
-  // Asset gallery MCP App — interactive UI for list-images results
-  register.resource({
-    name: "Asset Gallery Widget",
-    description: "Interactive asset gallery for browsing Cloudinary images",
-    metadata: {
-      mimeType: MCP_APP_MIME_TYPE,
-    },
-    resource: ASSET_GALLERY_RESOURCE_URI,
-    scopes: [],
-    read: async (_client, _uri, _extra) => ({
-      contents: [{
-        uri: ASSET_GALLERY_RESOURCE_URI,
-        mimeType: MCP_APP_MIME_TYPE,
-        text: getAssetGalleryHtml(),
-        _meta: {
-          ui: {
-            csp: {
-              resourceDomains: [
-                "https://res.cloudinary.com",
-                "https://*.cloudinary.com",
-              ],
-            },
-          },
-        },
-      } as any],
-    }),
-  });
-
-  // Asset details MCP App — interactive UI for get-asset-details results
-  register.resource({
-    name: "Asset Details Widget",
-    description: "Interactive single-asset detail view for Cloudinary assets",
-    metadata: {
-      mimeType: MCP_APP_MIME_TYPE,
-    },
-    resource: ASSET_DETAILS_RESOURCE_URI,
-    scopes: [],
-    read: async (_client, _uri, _extra) => ({
-      contents: [{
-        uri: ASSET_DETAILS_RESOURCE_URI,
-        mimeType: MCP_APP_MIME_TYPE,
-        text: getAssetDetailsHtml(),
-        _meta: {
-          ui: {
-            csp: {
-              resourceDomains: [
-                "https://res.cloudinary.com",
-                "https://*.cloudinary.com",
-              ],
-            },
-          },
-        },
-      } as any],
-    }),
-  });
-
-  // Asset upload MCP App — interactive upload UI for upload-asset tool
-  register.resource({
-    name: "Asset Upload Widget",
-    description: "Interactive upload interface for uploading assets to Cloudinary",
-    metadata: {
-      mimeType: MCP_APP_MIME_TYPE,
-    },
-    resource: ASSET_UPLOAD_RESOURCE_URI,
-    scopes: [],
-    read: async (_client, _uri, _extra) => ({
-      contents: [{
-        uri: ASSET_UPLOAD_RESOURCE_URI,
-        mimeType: MCP_APP_MIME_TYPE,
-        text: getAssetUploadHtml(),
-        _meta: {
-          ui: {
-            csp: {
-              resourceDomains: [
-                "https://res.cloudinary.com",
-                "https://*.cloudinary.com",
-              ],
-            },
-          },
-        },
-      } as any],
-    }),
-  });
-
   // Transform asset tool using explicit API with eager transformations
   register.tool({
     name: "transform-asset",

package/src/mcp-server/server.ts

@@ -6,6 +6,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CloudinaryAssetMgmtCore } from "../core.js";
 import { SDKOptions } from "../lib/config.js";
+import type { McpApp } from "./apps/config.js";
 import type { ConsoleLogger } from "./console-logger.js";
 import { Register } from "./extensions.js";
 import { createRegisterPrompt } from "./prompts.js";
@@ -55,10 +56,11 @@ export function createMCPServer(deps: {
   serverIdx?: SDKOptions["serverIdx"] | undefined;
   region?: SDKOptions["region"] | undefined;
   host?: SDKOptions["host"] | undefined;
+  mcpApps?: McpApp[] | undefined;
 }) {
   const server = new McpServer({
     name: "CloudinaryAssetMgmt",
-    version: "0.9.0-rc.0",
+    version: "0.9.1",
   });
 
   const getClient = deps.getSDK || (() =>
@@ -89,6 +91,7 @@ export function createMCPServer(deps: {
     allowedTools,
     deps.dynamic,
     deps.annotationFilter,
+    deps.mcpApps,
   );
   const resource = createRegisterResource(
     deps.logger,
@@ -132,7 +135,7 @@ export function createMCPServer(deps: {
     registerDynamicTools(deps.logger, server, getClient, toolMap, scopes);
   }
 
-  registerMCPExtensions(register satisfies Register);
+  registerMCPExtensions(register satisfies Register, deps.mcpApps);
 
   return { server, tools };
 }

package/src/mcp-server/tools/assetRelationsCreateAssetRelationsByAssetId.ts

@@ -5,14 +5,15 @@
 
 import * as z from "zod";
 import { assetRelationsCreateAssetRelationsByAssetId } from "../../funcs/assetRelationsCreateAssetRelationsByAssetId.js";
-import { CreateAssetRelationsByAssetIdRequestBody$zodSchema } from "../../models/createassetrelationsbyassetidop.js";
+import { RelateAssetsByAssetIdRequest$zodSchema } from "../../models/relateassetsbyassetidrequest.js";
 import { formatResult, ToolDefinition } from "../tools.js";
 
 const args = {
   asset_id: z.string().describe(
     "The asset ID of the resource. Must be a 32-character hexadecimal string.",
   ),
-  RequestBody: CreateAssetRelationsByAssetIdRequestBody$zodSchema,
+  relate_assets_by_asset_id_request: RelateAssetsByAssetIdRequest$zodSchema
+    .describe(`The asset IDs to relate.`),
 };
 
 export const tool$assetRelationsCreateAssetRelationsByAssetId: ToolDefinition<
@@ -21,7 +22,7 @@ export const tool$assetRelationsCreateAssetRelationsByAssetId: ToolDefinition<
   name: "create-asset-relations",
   description: `Add related assets by asset ID
 
-Relates an asset to other assets by their asset IDs, an immutable identifier, regardless of public ID, display name, asset folder, resource type or deliver type. This is a bidirectional process, meaning that the asset will also be added as a related_asset to all the other assets specified. The relation is also a one to many relationship, where the asset is related to all the assets specified, but those assets aren't also related to each other.`,
+Relates an asset to other assets by their asset IDs, an immutable identifier, regardless of public ID, display name, asset folder, resource type or delivery type. This is a bidirectional process, meaning that the asset will also be added as a related_asset to all the other assets specified. The relation is also a one to many relationship, where the asset is related to all the assets specified, but those assets aren't also related to each other.`,
   scopes: ["librarian"],
   annotations: {
     "title": "Create Asset Relations",
@@ -35,7 +36,7 @@ Relates an asset to other assets by their asset IDs, an immutable identifier, re
     const [result] = await assetRelationsCreateAssetRelationsByAssetId(
       client,
       args.asset_id,
-      args.RequestBody,
+      args.relate_assets_by_asset_id_request,
       { fetchOptions: { signal: ctx.signal } },
     ).$inspect();
 

package/src/mcp-server/tools/assetRelationsDeleteAssetRelationsByAssetId.ts

@@ -5,14 +5,15 @@
 
 import * as z from "zod";
 import { assetRelationsDeleteAssetRelationsByAssetId } from "../../funcs/assetRelationsDeleteAssetRelationsByAssetId.js";
-import { DeleteAssetRelationsByAssetIdRequestBody$zodSchema } from "../../models/deleteassetrelationsbyassetidop.js";
+import { UnrelateAssetsByAssetIdRequest$zodSchema } from "../../models/unrelateassetsbyassetidrequest.js";
 import { formatResult, ToolDefinition } from "../tools.js";
 
 const args = {
   asset_id: z.string().describe(
     "The asset ID of the resource. Must be a 32-character hexadecimal string.",
   ),
-  RequestBody: DeleteAssetRelationsByAssetIdRequestBody$zodSchema,
+  unrelate_assets_by_asset_id_request: UnrelateAssetsByAssetIdRequest$zodSchema
+    .describe(`The asset IDs to unrelate.`),
 };
 
 export const tool$assetRelationsDeleteAssetRelationsByAssetId: ToolDefinition<
@@ -21,7 +22,7 @@ export const tool$assetRelationsDeleteAssetRelationsByAssetId: ToolDefinition<
   name: "delete-asset-relations",
   description: `Delete asset relations by asset ID
 
-Unrelates the asset from other assets, specified by their asset IDs, an immutable identifier, regardless of public ID, display name, asset folder, resource type or deliver type. This is a bidirectional process, meaning that the asset will also be removed as a related_asset from all the other assets specified.`,
+Unrelates the asset from other assets, specified by their asset IDs, an immutable identifier, regardless of public ID, display name, asset folder, resource type or delivery type. This is a bidirectional process, meaning that the asset will also be removed as a related_asset from all the other assets specified.`,
   scopes: ["librarian"],
   annotations: {
     "title": "Delete Asset Relations",
@@ -35,7 +36,7 @@ Unrelates the asset from other assets, specified by their asset IDs, an immutabl
     const [result] = await assetRelationsDeleteAssetRelationsByAssetId(
       client,
       args.asset_id,
-      args.RequestBody,
+      args.unrelate_assets_by_asset_id_request,
       { fetchOptions: { signal: ctx.signal } },
     ).$inspect();
 

package/src/mcp-server/tools/assetsDerivedDestroy.ts

@@ -8,7 +8,9 @@ import { DerivedDestroyRequest$zodSchema } from "../../models/deriveddestroyrequ
 import { formatResult, ToolDefinition } from "../tools.js";
 
 const args = {
-  request: DerivedDestroyRequest$zodSchema,
+  request: DerivedDestroyRequest$zodSchema.describe(
+    `The derived resource IDs to delete.`,
+  ),
 };
 
 export const tool$assetsDerivedDestroy: ToolDefinition<typeof args> = {

package/src/mcp-server/tools/assetsDestroyByAssetId.ts

@@ -4,19 +4,20 @@
  */
 
 import { assetsDestroyByAssetId } from "../../funcs/assetsDestroyByAssetId.js";
-import { DestroyRequest$zodSchema } from "../../models/destroyrequest.js";
+import { ComponentsDestroyRequest$zodSchema } from "../../models/componentsdestroyrequest.js";
 import { formatResult, ToolDefinition } from "../tools.js";
 
 const args = {
-  request: DestroyRequest$zodSchema,
+  request: ComponentsDestroyRequest$zodSchema.describe(
+    `The asset to delete and related options.`,
+  ),
 };
 
 export const tool$assetsDestroyByAssetId: ToolDefinition<typeof args> = {
   name: "delete-asset",
-  description: `Delete asset by asset-id
+  description: `Delete asset by asset ID
 
-Deletes an asset using its asset ID. This endpoint replaces the legacy /resources/by_asset_id endpoint.
-Returns the deletion status and asset folder information when folder decoupling is enabled.
+Deletes an asset using its immutable asset ID.
 `,
   scopes: ["admin"],
   annotations: {

package/src/mcp-server/tools/assetsDownloadBackupAsset.ts

@@ -14,15 +14,6 @@ const args = {
   version_id: z.string().describe(
     "The version ID of the backup to download. Must be a 32-character hexadecimal string.",
   ),
-  api_key: z.string().describe(
-    "The API key to use for the request. This is automatically computed by the Cloudinary's SDKs.",
-  ).optional(),
-  signature: z.string().describe(
-    "(Required for signed REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs for signed requests, the signature is automatically generated and added to the request. If you manually generate your own signed POST request, you need to manually generate the signature parameter and add it to the request together with the api_key and timestamp parameters.\n",
-  ).optional(),
-  timestamp: z.int().describe(
-    "The timestamp to use for the request in unix time. This is automatically computed by the Cloudinary's SDKs.",
-  ).optional(),
 };
 
 export const tool$assetsDownloadBackupAsset: ToolDefinition<typeof args> = {
@@ -31,7 +22,7 @@ export const tool$assetsDownloadBackupAsset: ToolDefinition<typeof args> = {
   annotations: {
     "title": "Download Asset Backup",
     "destructiveHint": false,
-    "idempotentHint": false,
+    "idempotentHint": true,
     "openWorldHint": false,
     "readOnlyHint": true,
   },
@@ -41,9 +32,6 @@ export const tool$assetsDownloadBackupAsset: ToolDefinition<typeof args> = {
       client,
       args.asset_id,
       args.version_id,
-      args.api_key,
-      args.signature,
-      args.timestamp,
       { fetchOptions: { signal: ctx.signal } },
     ).$inspect();
 

package/src/mcp-server/tools/assetsGenerateArchive.ts

@@ -10,9 +10,11 @@ import { formatResult, ToolDefinition } from "../tools.js";
 
 const args = {
   resource_type: ArchiveResourceType$zodSchema.describe(
-    `The type of resources to include in the archive. "image" for images, "video" for videos, "raw" for non-media files, or "all" for mixed types.`,
+    `The type of resource for archive generation (image, video, or raw).`,
+  ),
+  RequestBody: GenerateArchiveRequestBody$zodSchema.describe(
+    `The archive generation parameters.`,
   ),
-  RequestBody: GenerateArchiveRequestBody$zodSchema,
 };
 
 export const tool$assetsGenerateArchive: ToolDefinition<typeof args> = {