@cloudinary/asset-management-mcp 0.6.0

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

@@ -0,0 +1,47 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { assetsRenameAsset } from "../../funcs/assetsRenameAsset.js";
+import { RenameAssetRequestBody$zodSchema } from "../../models/renameassetop.js";
+import { ResourceType$zodSchema } from "../../models/resourcetype.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  resource_type: ResourceType$zodSchema,
+  RequestBody: RenameAssetRequestBody$zodSchema,
+};
+
+export const tool$assetsRenameAsset: ToolDefinition<typeof args> = {
+  name: "asset-rename",
+  description:
+    `Updates an existing asset's identifier (public ID) and optionally other metadata in your Cloudinary account`,
+  scopes: ["librarian"],
+  annotations: {
+    "title": "Asset Rename",
+    "destructiveHint": false,
+    "idempotentHint": true,
+    "openWorldHint": false,
+    "readOnlyHint": false,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await assetsRenameAsset(
+      client,
+      args.resource_type,
+      args.RequestBody,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

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

@@ -0,0 +1,52 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { assetsUpdateResourceByAssetId } from "../../funcs/assetsUpdateResourceByAssetId.js";
+import { ResourceUpdateRequest$zodSchema } from "../../models/resourceupdaterequest.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.",
+  ),
+  ResourceUpdateRequest: ResourceUpdateRequest$zodSchema,
+};
+
+export const tool$assetsUpdateResourceByAssetId: ToolDefinition<typeof args> = {
+  name: "asset-update",
+  description:
+    `Updates an existing asset's metadata, tags, and other attributes using its asset ID
+
+Updates one or more attributes of a specified resource (asset) by its asset ID. This enables you to update details of an asset by its unique and immutable identifier, regardless of public ID, display name, asset folder, resource type or deliver type. Note that you can also update many attributes of an existing asset using the explicit method, which is not rate-limited.
+`,
+  scopes: ["librarian"],
+  annotations: {
+    "title": "Asset Update",
+    "destructiveHint": false,
+    "idempotentHint": true,
+    "openWorldHint": false,
+    "readOnlyHint": false,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await assetsUpdateResourceByAssetId(
+      client,
+      args.asset_id,
+      args.ResourceUpdateRequest,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

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

@@ -0,0 +1,45 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { foldersCreateFolder } from "../../funcs/foldersCreateFolder.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  folder: z.string(),
+};
+
+export const tool$foldersCreateFolder: ToolDefinition<typeof args> = {
+  name: "create-folder",
+  description: `Creates a new empty folder in your Cloudinary media library
+
+Creates a new folder at the specified path`,
+  scopes: ["librarian"],
+  annotations: {
+    "title": "Create Folder",
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": false,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await foldersCreateFolder(
+      client,
+      args.folder,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

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

@@ -0,0 +1,45 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { foldersDestroyFolder } from "../../funcs/foldersDestroyFolder.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  folder: z.string(),
+};
+
+export const tool$foldersDestroyFolder: ToolDefinition<typeof args> = {
+  name: "delete-folder",
+  description: `Deletes an existing folder from your media library
+
+Deletes a folder and all assets within it.`,
+  scopes: ["librarian"],
+  annotations: {
+    "title": "Delete Folder",
+    "destructiveHint": true,
+    "idempotentHint": true,
+    "openWorldHint": false,
+    "readOnlyHint": false,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await foldersDestroyFolder(
+      client,
+      args.folder,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

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

@@ -0,0 +1,59 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { foldersSearchFolders } from "../../funcs/foldersSearchFolders.js";
+import { ExpressionUnion$zodSchema } from "../../models/searchfoldersop.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  expression: ExpressionUnion$zodSchema.optional(),
+  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(
+    "Maximum number of folders to return (max 500, default 50).",
+  ),
+  next_cursor: z.string().describe(
+    "The cursor for pagination. Use the next_cursor value from a previous response to get the next page of results.",
+  ).optional(),
+};
+
+export const tool$foldersSearchFolders: ToolDefinition<typeof args> = {
+  name: "search-folders",
+  description: `Searches for folders whose attributes match a given expression
+
+Lists the folders that match the specified search expression. Limited to 2000 results. If no parameters are passed, returns the 50 most recently created folders in descending order of creation time.
+`,
+  scopes: ["librarian"],
+  annotations: {
+    "title": "Search Folders",
+    "destructiveHint": false,
+    "idempotentHint": true,
+    "openWorldHint": false,
+    "readOnlyHint": true,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await foldersSearchFolders(
+      client,
+      args.expression,
+      args.sort_by,
+      args.max_results,
+      args.next_cursor,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

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

@@ -0,0 +1,49 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { foldersUpdateFolder } from "../../funcs/foldersUpdateFolder.js";
+import { UpdateFolderRequestBody$zodSchema } from "../../models/updatefolderop.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  folder: z.string(),
+  RequestBody: UpdateFolderRequestBody$zodSchema,
+};
+
+export const tool$foldersUpdateFolder: ToolDefinition<typeof args> = {
+  name: "move-folder",
+  description:
+    `Renames or moves an entire folder (along with all assets it contains) to a new location
+
+Renames or moves an entire folder (along with all assets it contains) to a new location within your Cloudinary media library.`,
+  scopes: ["librarian"],
+  annotations: {
+    "title": "Move Folder",
+    "destructiveHint": false,
+    "idempotentHint": true,
+    "openWorldHint": false,
+    "readOnlyHint": false,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await foldersUpdateFolder(
+      client,
+      args.folder,
+      args.RequestBody,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

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

@@ -0,0 +1,51 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { searchSearchAssets } from "../../funcs/searchSearchAssets.js";
+import { SearchParameters$zodSchema } from "../../models/searchparameters.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: SearchParameters$zodSchema,
+};
+
+export const tool$searchSearchAssets: ToolDefinition<typeof args> = {
+  name: "search-assets",
+  description:
+    `Provides a powerful query interface to filter and retrieve assets and their details
+
+Returns a list of resources matching the specified search criteria.
+
+Uses Lucene-like query language to search by descriptive attributes (public_id, filename, folder, tags, context), file details (resource_type, format, bytes, width, height), embedded data (image_metadata), and analyzed data (face_count, colors, quality_score). Supports aggregate counts and complex Boolean expressions.
+
+Examples: tags:shirt AND uploaded_at>1d, resource_type:image AND bytes>1mb, folder:products OR context.category:electronics
+`,
+  scopes: ["librarian"],
+  annotations: {
+    "title": "Search Assets",
+    "destructiveHint": false,
+    "idempotentHint": true,
+    "openWorldHint": false,
+    "readOnlyHint": true,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await searchSearchAssets(
+      client,
+      args.request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

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

@@ -0,0 +1,50 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { searchVisualSearchAssets } from "../../funcs/searchVisualSearchAssets.js";
+import { VisualSearchParametersUnion$zodSchema } from "../../models/visualsearchparametersunion.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: VisualSearchParametersUnion$zodSchema,
+};
+
+export const tool$searchVisualSearchAssets: ToolDefinition<typeof args> = {
+  name: "visual-search-assets",
+  description:
+    `Finds images in your asset library based on visual similarity or content
+
+Returns a list of resources that are visually similar to a specified image. You can provide the source image for comparison in one of three ways:
+- Provide a URL of an image
+- Specify the public ID or asset ID of an existing image
+- Provide a textual description
+`,
+  scopes: ["librarian"],
+  annotations: {
+    "title": "Visual Search Assets",
+    "destructiveHint": false,
+    "idempotentHint": true,
+    "openWorldHint": false,
+    "readOnlyHint": true,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await searchVisualSearchAssets(
+      client,
+      args.request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

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

@@ -0,0 +1,63 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { uploadUpload } from "../../funcs/uploadUpload.js";
+import { UploadRequest$zodSchema } from "../../models/uploadrequest.js";
+import { UploadResourceType$zodSchema } from "../../models/uploadresourcetype.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  resource_type: UploadResourceType$zodSchema.default("auto"),
+  upload_request: UploadRequest$zodSchema,
+};
+
+export const tool$uploadUpload: ToolDefinition<typeof args> = {
+  name: "upload-asset",
+  description:
+    `Uploads media assets (images, videos, raw files) to your Cloudinary product environment
+
+Uploads media assets (images, videos, raw files) to your Cloudinary product environment. The file is securely stored
+in the cloud with backup and revision history. Cloudinary automatically analyzes and saves important data about each
+asset, such as format, size, resolution, and prominent colors, which is indexed to enable searching on those attributes.
+
+Supports uploading from:
+- Local file paths (SDKs/MCP server only). For MCP server path MUST start with file://
+- Remote HTTP/HTTPS URLs
+- Base64 Data URIs (max ~60 MB)
+- Private storage buckets (S3 or Google Storage)
+- FTP addresses
+
+The uploaded asset is immediately available for transformation and delivery upon successful upload.
+
+Transform media files using transformation syntax in delivery URLs, which creates derived files accessible immediately without re-uploading the original.
+`,
+  scopes: ["librarian", "builder"],
+  annotations: {
+    "title": "Upload Asset",
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": false,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await uploadUpload(
+      client,
+      args.resource_type,
+      args.upload_request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

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

@@ -0,0 +1,45 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { usageGetUsage } from "../../funcs/usageGetUsage.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  date: z.string().date().optional(),
+};
+
+export const tool$usageGetUsage: ToolDefinition<typeof args> = {
+  name: "get-usage-details",
+  description: `Retrieves comprehensive usage metrics and account statistics
+
+A report on the status of product environment usage, including storage, credits, bandwidth, requests, number of resources, and add-on usage. No date parameter needed to get current usage statistics.`,
+  scopes: ["admin"],
+  annotations: {
+    "title": "Get Usage Details",
+    "destructiveHint": false,
+    "idempotentHint": true,
+    "openWorldHint": false,
+    "readOnlyHint": true,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await usageGetUsage(
+      client,
+      args.date,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

package/src/mcp-server/tools.ts

@@ -0,0 +1,158 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import {
+  CallToolResult,
+  ServerNotification,
+  ServerRequest,
+} from "@modelcontextprotocol/sdk/types.js";
+import { objectOutputType, ZodRawShape, ZodTypeAny } from "zod";
+import { CloudinaryAssetMgmtCore } from "../core.js";
+import { ConsoleLogger } from "./console-logger.js";
+import { MCPScope } from "./scopes.js";
+import { isAsyncIterable, isBinaryData, valueToBase64 } from "./shared.js";
+
+export type ToolDefinition<Args extends undefined | ZodRawShape = undefined> =
+  Args extends ZodRawShape ? {
+      name: string;
+      description: string;
+      scopes?: MCPScope[];
+      args: Args;
+      annotations: {
+        title: string;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+        readOnlyHint: boolean;
+      };
+      tool: (
+        client: CloudinaryAssetMgmtCore,
+        args: objectOutputType<Args, ZodTypeAny>,
+        extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
+      ) => CallToolResult | Promise<CallToolResult>;
+    }
+    : {
+      name: string;
+      description: string;
+      scopes?: MCPScope[];
+      args?: undefined;
+      annotations: {
+        title: string;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+        readOnlyHint: boolean;
+      };
+      tool: (
+        client: CloudinaryAssetMgmtCore,
+        extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
+      ) => CallToolResult | Promise<CallToolResult>;
+    };
+
+// Optional function to assist with formatting tool results
+export async function formatResult(
+  value: unknown,
+  init: { response?: Response | undefined },
+): Promise<CallToolResult> {
+  if (typeof value === "undefined") {
+    return { content: [] };
+  }
+
+  const { response } = init;
+  const contentType = response?.headers.get("content-type") ?? "";
+  let content: CallToolResult["content"] = [];
+
+  if (contentType.search(/\bjson\b/g)) {
+    content = [{ type: "text", text: JSON.stringify(value) }];
+  } else if (
+    contentType.startsWith("text/event-stream")
+    && isAsyncIterable(value)
+  ) {
+    content = await consumeSSE(value);
+  } else if (contentType.startsWith("text/") && typeof value === "string") {
+    content = [{ type: "text", text: value }];
+  } else if (isBinaryData(value) && contentType.startsWith("image/")) {
+    const data = await valueToBase64(value);
+    content = data == null
+      ? []
+      : [{ type: "image", data, mimeType: contentType }];
+  } else {
+    return {
+      content: [{
+        type: "text",
+        text: `Unsupported content type: "${contentType}"`,
+      }],
+      isError: true,
+    };
+  }
+
+  return { content };
+}
+
+async function consumeSSE(
+  value: AsyncIterable<unknown>,
+): Promise<CallToolResult["content"]> {
+  const content: CallToolResult["content"] = [];
+
+  for await (const chunk of value) {
+    if (typeof chunk === "string") {
+      content.push({ type: "text", text: chunk });
+    } else {
+      content.push({ type: "text", text: JSON.stringify(chunk) });
+    }
+  }
+
+  return content;
+}
+
+export function createRegisterTool(
+  logger: ConsoleLogger,
+  server: McpServer,
+  getSDK: () => CloudinaryAssetMgmtCore,
+  allowedScopes: Set<MCPScope>,
+  allowedTools?: Set<string>,
+): <A extends ZodRawShape | undefined>(tool: ToolDefinition<A>) => void {
+  return <A extends ZodRawShape | undefined>(tool: ToolDefinition<A>): void => {
+    if (allowedTools && !allowedTools.has(tool.name)) {
+      return;
+    }
+
+    const scopes = tool.scopes ?? [];
+    if (allowedScopes.size > 0 && scopes.length === 0) {
+      return;
+    }
+
+    if (
+      allowedScopes.size > 0
+      && !scopes.every((s: MCPScope) => allowedScopes.has(s))
+    ) {
+      return;
+    }
+
+    if (tool.args) {
+      server.tool(
+        tool.name,
+        tool.description,
+        tool.args,
+        tool.annotations,
+        async (args, ctx) => {
+          return tool.tool(getSDK(), args, ctx);
+        },
+      );
+    } else {
+      server.tool(
+        tool.name,
+        tool.description,
+        tool.annotations,
+        async (_, ctx) => {
+          return tool.tool(getSDK(), ctx);
+        },
+      );
+    }
+
+    logger.debug("Registered tool", { name: tool.name });
+  };
+}