@cloudinary/asset-management-mcp 0.6.2 → 0.7.0

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

@@ -4,8 +4,11 @@
 
 import { z } from "zod";
 import { Register } from "./extensions.js";
+import { formatResult } from "./tools.js";
 import { assetsExplicitAsset } from "../funcs/assetsExplicitAsset.js";
-import { ResourceType } from "../models/resourcetype.js";
+import { ResourceType$zodSchema } from "../models/resourcetype.js";
+
+const TX_RULES_URL = "https://cloudinary.com/documentation/cloudinary_transformation_rules.md";
 
 export function registerMCPExtensions(register: Register): void {
   // Get transformation reference tool
@@ -17,12 +20,12 @@ export function registerMCPExtensions(register: Register): void {
       title: "Get Cloudinary Transformation Reference",
       destructiveHint: false,
       idempotentHint: true,
-      openWorldHint: false,
+      openWorldHint: true,
       readOnlyHint: true,
     },
-    tool: async (_client, _ctx) => {
+    tool: async (_client, ctx) => {
       try {
-        const response = await fetch("https://cloudinary.com/documentation/cloudinary_transformation_rules.md");
+        const response = await fetch(TX_RULES_URL, { signal: ctx.signal });
 
         if (!response.ok) {
           throw new Error(`HTTP error! status: ${response.status}`);
@@ -43,7 +46,7 @@ export function registerMCPExtensions(register: Register): void {
           content: [
             {
               type: "text",
-              text: `Error fetching transformation rules documentation: ${error instanceof Error ? error.message : 'Unknown error'}\n\nYou can view the documentation directly at: https://cloudinary.com/documentation/cloudinary_transformation_rules.md`
+              text: `Error fetching transformation rules documentation: ${error instanceof Error ? error.message : 'Unknown error'}\n\nYou can view the documentation directly at: ${TX_RULES_URL}`
             }
           ],
           isError: true
@@ -60,47 +63,33 @@ export function registerMCPExtensions(register: Register): void {
     args: {
       publicId: z.string().describe("The public ID of the existing asset to transform"),
       transformations: z.string().describe("VALIDATED transformation string using ONLY parameters from get-tx-reference docs. Examples: 'c_fill,w_300,h_200' or 'e_sepia/a_90'. MUST follow component rules: commas within components, slashes between components."),
-      resourceType: z.enum(["image", "video", "raw"]).optional().default("image").describe("The resource type of the asset"),
+      resourceType: ResourceType$zodSchema.optional().default("image").describe("The resource type of the asset"),
       invalidate: z.boolean().optional().default(false).describe("Whether to invalidate cached versions"),
     },
     annotations: {
       title: "Transform Cloudinary Asset",
       destructiveHint: false,
-      idempotentHint: false,
+      idempotentHint: true,
       openWorldHint: false,
       readOnlyHint: false,
     },
-    tool: async (client, args, _ctx) => {
+    tool: async (client, args, ctx) => {
       try {
-        // Use the explicit API to generate eager transformations
-        const result = await assetsExplicitAsset(client, args.resourceType as ResourceType, {
+        const [result] = await assetsExplicitAsset(client, args.resourceType, {
           public_id: args.publicId,
           type: "upload",
           eager: args.transformations,
           invalidate: args.invalidate,
-        });
+        }, { fetchOptions: { signal: ctx.signal } }).$inspect();
 
         if (!result.ok) {
           return {
-            content: [
-              {
-                type: "text",
-                text: `Error transforming asset: ${result.error.message}`
-              }
-            ],
-            isError: true
+            content: [{ type: "text", text: result.error.message }],
+            isError: true,
           };
         }
 
-        // Return raw API response
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(result.value, null, 2)
-            }
-          ]
-        };
+        return formatResult(result.value);
       } catch (error) {
         return {
           content: [

package/src/mcp-server/server.ts

@@ -14,7 +14,7 @@ import {
 } from "./resources.js";
 import { MCPScope } from "./scopes.js";
 import { registerMCPExtensions } from "./server.extensions.js";
-import { createRegisterTool } from "./tools.js";
+import { createRegisterTool, registerDynamicTools } from "./tools.js";
 import { tool$assetRelationsCreateAssetRelationsByAssetId } from "./tools/assetRelationsCreateAssetRelationsByAssetId.js";
 import { tool$assetRelationsDeleteAssetRelationsByAssetId } from "./tools/assetRelationsDeleteAssetRelationsByAssetId.js";
 import { tool$assetsDerivedDestroy } from "./tools/assetsDerivedDestroy.js";
@@ -40,6 +40,7 @@ import { tool$usageGetUsage } from "./tools/usageGetUsage.js";
 export function createMCPServer(deps: {
   logger: ConsoleLogger;
   allowedTools?: string[] | undefined;
+  dynamic?: boolean | undefined;
   scopes?: MCPScope[] | undefined;
   getSDK?: () => CloudinaryAssetMgmtCore;
   serverURL?: string | undefined;
@@ -51,7 +52,7 @@ export function createMCPServer(deps: {
 }) {
   const server = new McpServer({
     name: "CloudinaryAssetMgmt",
-    version: "0.6.2",
+    version: "0.7.0",
   });
 
   const getClient = deps.getSDK || (() =>
@@ -74,12 +75,13 @@ export function createMCPServer(deps: {
   const scopes = new Set(deps.scopes);
 
   const allowedTools = deps.allowedTools && new Set(deps.allowedTools);
-  const tool = createRegisterTool(
+  const [tool, tools, toolMap] = createRegisterTool(
     deps.logger,
     server,
     getClient,
     scopes,
     allowedTools,
+    deps.dynamic,
   );
   const resource = createRegisterResource(
     deps.logger,
@@ -119,7 +121,11 @@ export function createMCPServer(deps: {
   tool(tool$searchSearchAssets);
   tool(tool$searchVisualSearchAssets);
 
+  if (deps.dynamic) {
+    registerDynamicTools(deps.logger, server, getClient, toolMap, scopes);
+  }
+
   registerMCPExtensions(register satisfies Register);
 
-  return server;
+  return { server, tools };
 }

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

@@ -31,7 +31,7 @@ Relates an asset to other assets by their asset IDs, an immutable identifier, re
   },
   args,
   tool: async (client, args, ctx) => {
-    const [result, apiCall] = await assetRelationsCreateAssetRelationsByAssetId(
+    const [result] = await assetRelationsCreateAssetRelationsByAssetId(
       client,
       args.asset_id,
       args.RequestBody,
@@ -45,8 +45,6 @@ Relates an asset to other assets by their asset IDs, an immutable identifier, re
       };
     }
 
-    const value = result.value;
-
-    return formatResult(value, apiCall);
+    return formatResult(result.value);
   },
 };

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

@@ -31,7 +31,7 @@ Unrelates the asset from other assets, specified by their asset IDs, an immutabl
   },
   args,
   tool: async (client, args, ctx) => {
-    const [result, apiCall] = await assetRelationsDeleteAssetRelationsByAssetId(
+    const [result] = await assetRelationsDeleteAssetRelationsByAssetId(
       client,
       args.asset_id,
       args.RequestBody,
@@ -45,8 +45,6 @@ Unrelates the asset from other assets, specified by their asset IDs, an immutabl
       };
     }
 
-    const value = result.value;
-
-    return formatResult(value, apiCall);
+    return formatResult(result.value);
   },
 };

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

@@ -25,7 +25,7 @@ Deletes derived resources by derived resource ID`,
   },
   args,
   tool: async (client, args, ctx) => {
-    const [result, apiCall] = await assetsDerivedDestroy(
+    const [result] = await assetsDerivedDestroy(
       client,
       args.request,
       { fetchOptions: { signal: ctx.signal } },
@@ -38,8 +38,6 @@ Deletes derived resources by derived resource ID`,
       };
     }
 
-    const value = result.value;
-
-    return formatResult(value, apiCall);
+    return formatResult(result.value);
   },
 };

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

@@ -27,7 +27,7 @@ Returns the deletion status and asset folder information when folder decoupling
   },
   args,
   tool: async (client, args, ctx) => {
-    const [result, apiCall] = await assetsDestroyByAssetId(
+    const [result] = await assetsDestroyByAssetId(
       client,
       args.request,
       { fetchOptions: { signal: ctx.signal } },
@@ -40,8 +40,6 @@ Returns the deletion status and asset folder information when folder decoupling
       };
     }
 
-    const value = result.value;
-
-    return formatResult(value, apiCall);
+    return formatResult(result.value);
   },
 };

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

@@ -17,10 +17,9 @@ const args = {
     "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"
-      + "",
+    "(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.number().int().describe(
+  timestamp: z.int().describe(
     "The timestamp to use for the request in unix time. This is automatically computed by the Cloudinary's SDKs.",
   ).optional(),
 };
@@ -37,7 +36,7 @@ export const tool$assetsDownloadBackupAsset: ToolDefinition<typeof args> = {
   },
   args,
   tool: async (client, args, ctx) => {
-    const [result, apiCall] = await assetsDownloadBackupAsset(
+    const [result] = await assetsDownloadBackupAsset(
       client,
       args.asset_id,
       args.version_id,
@@ -54,8 +53,6 @@ export const tool$assetsDownloadBackupAsset: ToolDefinition<typeof args> = {
       };
     }
 
-    const value = result.value;
-
-    return formatResult(value, apiCall);
+    return formatResult(result.value);
   },
 };

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

@@ -28,7 +28,7 @@ Creates a downloadable ZIP or other archive format containing the specified reso
   },
   args,
   tool: async (client, args, ctx) => {
-    const [result, apiCall] = await assetsGenerateArchive(
+    const [result] = await assetsGenerateArchive(
       client,
       args.resource_type,
       args.RequestBody,
@@ -42,8 +42,6 @@ Creates a downloadable ZIP or other archive format containing the specified reso
       };
     }
 
-    const value = result.value;
-
-    return formatResult(value, apiCall);
+    return formatResult(result.value);
   },
 };

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

@@ -37,7 +37,7 @@ const args = {
   versions: z.boolean().default(false).describe(
     "Whether to include details of all the backed up versions of the asset. Default: false.",
   ),
-  max_results: z.number().int().default(10).describe(
+  max_results: z.int().default(10).describe(
     "Maximum number of derived assets to return. Default: 10.",
   ),
   derived_next_cursor: z.string().describe(
@@ -60,7 +60,7 @@ Returns the details of a single resource specified by its asset ID.`,
   },
   args,
   tool: async (client, args, ctx) => {
-    const [result, apiCall] = await assetsGetResourceByAssetId(
+    const [result] = await assetsGetResourceByAssetId(
       client,
       args.asset_id,
       args.colors,
@@ -84,8 +84,6 @@ Returns the details of a single resource specified by its asset ID.`,
       };
     }
 
-    const value = result.value;
-
-    return formatResult(value, apiCall);
+    return formatResult(result.value);
   },
 };

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

@@ -20,11 +20,10 @@ const args = {
     "Whether to include the list of tag names assigned to each asset. Default: false",
   ).optional(),
   next_cursor: z.string().describe("Cursor for pagination.").optional(),
-  max_results: z.number().int().describe(
-    "Maximum number of results to return (1-500).",
-  ).optional(),
+  max_results: z.int().describe("Maximum number of results to return (1-500).")
+    .optional(),
   direction: Direction$zodSchema.optional(),
-  start_at: z.string().datetime({ offset: true }).describe(
+  start_at: z.iso.datetime({ offset: true }).describe(
     "Retrieve resources uploaded after this timestamp.",
   ).optional(),
   fields: z.array(FieldsSpec$zodSchema).optional(),
@@ -46,7 +45,7 @@ Retrieves a list of image assets. Results can be filtered by various criteria li
   },
   args,
   tool: async (client, args, ctx) => {
-    const [result, apiCall] = await assetsListImages(
+    const [result] = await assetsListImages(
       client,
       args.type,
       args.prefix,
@@ -67,8 +66,6 @@ Retrieves a list of image assets. Results can be filtered by various criteria li
       };
     }
 
-    const value = result.value;
-
-    return formatResult(value, apiCall);
+    return formatResult(result.value);
   },
 };

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

@@ -20,11 +20,10 @@ const args = {
     "Whether to include the list of tag names assigned to each asset. Default: false",
   ).optional(),
   next_cursor: z.string().describe("Cursor for pagination.").optional(),
-  max_results: z.number().int().describe(
-    "Maximum number of results to return (1-500).",
-  ).optional(),
+  max_results: z.int().describe("Maximum number of results to return (1-500).")
+    .optional(),
   direction: Direction$zodSchema.optional(),
-  start_at: z.string().datetime({ offset: true }).describe(
+  start_at: z.iso.datetime({ offset: true }).describe(
     "An ISO-8601 formatted timestamp. When specified, assets created since that timestamp are returned.  Supported only if neither `prefix` nor `public_ids` were passed.",
   ).optional(),
   fields: z.array(FieldsSpec$zodSchema).optional(),
@@ -46,7 +45,7 @@ Retrieves a list of raw assets. Results can be filtered by various criteria like
   },
   args,
   tool: async (client, args, ctx) => {
-    const [result, apiCall] = await assetsListRawFiles(
+    const [result] = await assetsListRawFiles(
       client,
       args.type,
       args.prefix,
@@ -67,8 +66,6 @@ Retrieves a list of raw assets. Results can be filtered by various criteria like
       };
     }
 
-    const value = result.value;
-
-    return formatResult(value, apiCall);
+    return formatResult(result.value);
   },
 };

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

@@ -13,9 +13,8 @@ const args = {
     "The prefix to use if you want to limit the returned tags to those that start with the specified prefix.",
   ).optional(),
   next_cursor: z.string().describe("Cursor for pagination.").optional(),
-  max_results: z.number().int().describe(
-    "Maximum number of results to return (1-500).",
-  ).optional(),
+  max_results: z.int().describe("Maximum number of results to return (1-500).")
+    .optional(),
 };
 
 export const tool$assetsListResourceTags: ToolDefinition<typeof args> = {
@@ -37,7 +36,7 @@ Retrieves a comprehensive list of all tags that exist in your product environmen
   },
   args,
   tool: async (client, args, ctx) => {
-    const [result, apiCall] = await assetsListResourceTags(
+    const [result] = await assetsListResourceTags(
       client,
       args.resource_type,
       args.prefix,
@@ -53,8 +52,6 @@ Retrieves a comprehensive list of all tags that exist in your product environmen
       };
     }
 
-    const value = result.value;
-
-    return formatResult(value, apiCall);
+    return formatResult(result.value);
   },
 };

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

@@ -20,11 +20,10 @@ const args = {
     "Whether to include the list of tag names assigned to each asset. Default: false",
   ).optional(),
   next_cursor: z.string().describe("Cursor for pagination.").optional(),
-  max_results: z.number().int().describe(
-    "Maximum number of results to return (1-500).",
-  ).optional(),
+  max_results: z.int().describe("Maximum number of results to return (1-500).")
+    .optional(),
   direction: Direction$zodSchema.optional(),
-  start_at: z.string().datetime({ offset: true }).describe(
+  start_at: z.iso.datetime({ offset: true }).describe(
     "An ISO-8601 formatted timestamp. When specified, assets created since that timestamp are returned.  Supported only if neither `prefix` nor `public_ids` were passed.",
   ).optional(),
   fields: z.array(FieldsSpec$zodSchema).optional(),
@@ -46,7 +45,7 @@ Retrieves a list of video assets. Results can be filtered by various criteria li
   },
   args,
   tool: async (client, args, ctx) => {
-    const [result, apiCall] = await assetsListVideos(
+    const [result] = await assetsListVideos(
       client,
       args.type,
       args.prefix,
@@ -67,8 +66,6 @@ Retrieves a list of video assets. Results can be filtered by various criteria li
       };
     }
 
-    const value = result.value;
-
-    return formatResult(value, apiCall);
+    return formatResult(result.value);
   },
 };

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

@@ -26,7 +26,7 @@ export const tool$assetsRenameAsset: ToolDefinition<typeof args> = {
   },
   args,
   tool: async (client, args, ctx) => {
-    const [result, apiCall] = await assetsRenameAsset(
+    const [result] = await assetsRenameAsset(
       client,
       args.resource_type,
       args.RequestBody,
@@ -40,8 +40,6 @@ export const tool$assetsRenameAsset: ToolDefinition<typeof args> = {
       };
     }
 
-    const value = result.value;
-
-    return formatResult(value, apiCall);
+    return formatResult(result.value);
   },
 };

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

@@ -31,7 +31,7 @@ Updates one or more attributes of a specified resource (asset) by its asset ID.
   },
   args,
   tool: async (client, args, ctx) => {
-    const [result, apiCall] = await assetsUpdateResourceByAssetId(
+    const [result] = await assetsUpdateResourceByAssetId(
       client,
       args.asset_id,
       args.ResourceUpdateRequest,
@@ -45,8 +45,6 @@ Updates one or more attributes of a specified resource (asset) by its asset ID.
       };
     }
 
-    const value = result.value;
-
-    return formatResult(value, apiCall);
+    return formatResult(result.value);
   },
 };

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

@@ -25,7 +25,7 @@ Creates a new folder at the specified path`,
   },
   args,
   tool: async (client, args, ctx) => {
-    const [result, apiCall] = await foldersCreateFolder(
+    const [result] = await foldersCreateFolder(
       client,
       args.folder,
       { fetchOptions: { signal: ctx.signal } },
@@ -38,8 +38,6 @@ Creates a new folder at the specified path`,
       };
     }
 
-    const value = result.value;
-
-    return formatResult(value, apiCall);
+    return formatResult(result.value);
   },
 };

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

@@ -25,7 +25,7 @@ Deletes a folder and all assets within it.`,
   },
   args,
   tool: async (client, args, ctx) => {
-    const [result, apiCall] = await foldersDestroyFolder(
+    const [result] = await foldersDestroyFolder(
       client,
       args.folder,
       { fetchOptions: { signal: ctx.signal } },
@@ -38,8 +38,6 @@ Deletes a folder and all assets within it.`,
       };
     }
 
-    const value = result.value;
-
-    return formatResult(value, apiCall);
+    return formatResult(result.value);
   },
 };

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

@@ -12,7 +12,7 @@ const args = {
   sort_by: z.array(z.string()).describe(
     "An array of key-value pairs for sorting. Each value is a key and direction (asc/desc).",
   ).optional(),
-  max_results: z.number().int().default(50).describe(
+  max_results: z.int().default(50).describe(
     "Maximum number of folders to return (max 500, default 50).",
   ),
   next_cursor: z.string().describe(
@@ -36,7 +36,7 @@ Lists the folders that match the specified search expression. Limited to 2000 re
   },
   args,
   tool: async (client, args, ctx) => {
-    const [result, apiCall] = await foldersSearchFolders(
+    const [result] = await foldersSearchFolders(
       client,
       args.expression,
       args.sort_by,
@@ -52,8 +52,6 @@ Lists the folders that match the specified search expression. Limited to 2000 re
       };
     }
 
-    const value = result.value;
-
-    return formatResult(value, apiCall);
+    return formatResult(result.value);
   },
 };

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

@@ -28,7 +28,7 @@ Renames or moves an entire folder (along with all assets it contains) to a new l
   },
   args,
   tool: async (client, args, ctx) => {
-    const [result, apiCall] = await foldersUpdateFolder(
+    const [result] = await foldersUpdateFolder(
       client,
       args.folder,
       args.RequestBody,
@@ -42,8 +42,6 @@ Renames or moves an entire folder (along with all assets it contains) to a new l
       };
     }
 
-    const value = result.value;
-
-    return formatResult(value, apiCall);
+    return formatResult(result.value);
   },
 };

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

@@ -31,7 +31,7 @@ Examples: tags:shirt AND uploaded_at>1d, resource_type:image AND bytes>1mb, fold
   },
   args,
   tool: async (client, args, ctx) => {
-    const [result, apiCall] = await searchSearchAssets(
+    const [result] = await searchSearchAssets(
       client,
       args.request,
       { fetchOptions: { signal: ctx.signal } },
@@ -44,8 +44,6 @@ Examples: tags:shirt AND uploaded_at>1d, resource_type:image AND bytes>1mb, fold
       };
     }
 
-    const value = result.value;
-
-    return formatResult(value, apiCall);
+    return formatResult(result.value);
   },
 };

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

@@ -30,7 +30,7 @@ Returns a list of resources that are visually similar to a specified image. You
   },
   args,
   tool: async (client, args, ctx) => {
-    const [result, apiCall] = await searchVisualSearchAssets(
+    const [result] = await searchVisualSearchAssets(
       client,
       args.request,
       { fetchOptions: { signal: ctx.signal } },
@@ -43,8 +43,6 @@ Returns a list of resources that are visually similar to a specified image. You
       };
     }
 
-    const value = result.value;
-
-    return formatResult(value, apiCall);
+    return formatResult(result.value);
   },
 };

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

@@ -42,7 +42,7 @@ Transform media files using transformation syntax in delivery URLs, which create
   },
   args,
   tool: async (client, args, ctx) => {
-    const [result, apiCall] = await uploadUpload(
+    const [result] = await uploadUpload(
       client,
       args.resource_type,
       args.upload_request,
@@ -56,8 +56,6 @@ Transform media files using transformation syntax in delivery URLs, which create
       };
     }
 
-    const value = result.value;
-
-    return formatResult(value, apiCall);
+    return formatResult(result.value);
   },
 };

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

@@ -25,7 +25,7 @@ A report on the status of product environment usage, including storage, credits,
   },
   args,
   tool: async (client, args, ctx) => {
-    const [result, apiCall] = await usageGetUsage(
+    const [result] = await usageGetUsage(
       client,
       args.date,
       { fetchOptions: { signal: ctx.signal } },
@@ -38,8 +38,6 @@ A report on the status of product environment usage, including storage, credits,
       };
     }
 
-    const value = result.value;
-
-    return formatResult(value, apiCall);
+    return formatResult(result.value);
   },
 };