@cloudinary/asset-management-mcp 0.6.0

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

@@ -0,0 +1,26 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { buildApplication, buildRouteMap, run } from "@stricli/core";
+import process from "node:process";
+import { buildContext } from "./cli.js";
+import { startCommand } from "./cli/start/command.js";
+
+const routes = buildRouteMap({
+  routes: {
+    start: startCommand,
+  },
+  docs: {
+    brief: "MCP server CLI",
+  },
+});
+
+export const app = buildApplication(routes, {
+  name: "mcp",
+  versionInfo: {
+    currentVersion: "0.6.0",
+  },
+});
+
+run(app, process.argv.slice(2), buildContext(process));

package/src/mcp-server/prompts.ts

@@ -0,0 +1,121 @@
+/*
+ * 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 {
+  GetPromptResult,
+  ServerNotification,
+  ServerRequest,
+} from "@modelcontextprotocol/sdk/types.js";
+import {
+  objectOutputType,
+  ZodOptional,
+  ZodType,
+  ZodTypeAny,
+  ZodTypeDef,
+} from "zod";
+import { CloudinaryAssetMgmtCore } from "../core.js";
+import { ConsoleLogger } from "./console-logger.js";
+import { MCPScope } from "./scopes.js";
+
+// '@modelcontextprotocol/sdk' currently does not export this type
+export type PromptArgsRawShape = {
+  [k: string]:
+    | ZodType<string, ZodTypeDef, string>
+    | ZodOptional<ZodType<string, ZodTypeDef, string>>;
+};
+
+export type PromptDefinition<
+  Args extends undefined | PromptArgsRawShape = undefined,
+> = Args extends PromptArgsRawShape ? {
+    name: string;
+    description?: string;
+    scopes?: MCPScope[];
+    args: Args;
+    prompt: (
+      client: CloudinaryAssetMgmtCore,
+      args: objectOutputType<Args, ZodTypeAny>,
+      extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
+    ) => GetPromptResult | Promise<GetPromptResult>;
+  }
+  : {
+    name: string;
+    description?: string;
+    scopes?: MCPScope[];
+    args?: undefined;
+    prompt: (
+      client: CloudinaryAssetMgmtCore,
+      extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
+    ) => GetPromptResult | Promise<GetPromptResult>;
+  };
+
+// Optional function to assist with formatting prompt results
+export async function formatResult(value: string): Promise<GetPromptResult> {
+  return {
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: value,
+        },
+      },
+    ],
+  };
+}
+
+export function createRegisterPrompt(
+  logger: ConsoleLogger,
+  server: McpServer,
+  getSDK: () => CloudinaryAssetMgmtCore,
+  allowedScopes: Set<MCPScope>,
+): <A extends PromptArgsRawShape | undefined>(
+  prompt: PromptDefinition<A>,
+) => void {
+  return <A extends PromptArgsRawShape | undefined>(
+    prompt: PromptDefinition<A>,
+  ): void => {
+    const scopes = prompt.scopes ?? [];
+    if (allowedScopes.size > 0 && scopes.length === 0) {
+      return;
+    }
+
+    if (
+      allowedScopes.size > 0
+      && !scopes.every((s: MCPScope) => allowedScopes.has(s))
+    ) {
+      return;
+    }
+
+    if (prompt.args) {
+      if (prompt.description) {
+        server.prompt(
+          prompt.name,
+          prompt.description,
+          prompt.args,
+          async (args, ctx) => prompt.prompt(getSDK(), args, ctx),
+        );
+      } else {
+        server.prompt(
+          prompt.name,
+          prompt.args,
+          async (args, ctx) => prompt.prompt(getSDK(), args, ctx),
+        );
+      }
+    } else {
+      if (prompt.description) {
+        server.prompt(
+          prompt.name,
+          prompt.description,
+          async (ctx) => prompt.prompt(getSDK(), ctx),
+        );
+      } else {
+        server.prompt(prompt.name, async (ctx) => prompt.prompt(getSDK(), ctx));
+      }
+    }
+
+    logger.debug("Registered prompt", { name: prompt.name });
+  };
+}

package/src/mcp-server/resources.ts

@@ -0,0 +1,176 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import {
+  McpServer,
+  ResourceMetadata,
+  ResourceTemplate,
+} from "@modelcontextprotocol/sdk/server/mcp.js";
+import { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import { Variables } from "@modelcontextprotocol/sdk/shared/uriTemplate.js";
+import {
+  ReadResourceResult,
+  ServerNotification,
+  ServerRequest,
+} from "@modelcontextprotocol/sdk/types.js";
+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 ReadResourceCallback = (
+  client: CloudinaryAssetMgmtCore,
+  uri: URL,
+  extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
+) => ReadResourceResult | Promise<ReadResourceResult>;
+
+export type ResourceDefinition = {
+  name: string;
+  description?: string;
+  metadata?: ResourceMetadata;
+  scopes?: MCPScope[];
+  resource: string;
+  read: ReadResourceCallback;
+};
+
+export type ReadResourceTemplateCallback = (
+  client: CloudinaryAssetMgmtCore,
+  uri: URL,
+  vars: Variables,
+  extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
+) => ReadResourceResult | Promise<ReadResourceResult>;
+
+export type ResourceTemplateDefinition = {
+  name: string;
+  description: string;
+  metadata?: ResourceMetadata;
+  scopes?: MCPScope[];
+  resource: ResourceTemplate;
+  read: ReadResourceTemplateCallback;
+};
+
+// Optional function to assist with formatting resource results
+export async function formatResult(
+  value: unknown,
+  uri: URL,
+  init: { mimeType?: string | undefined; response?: Response | undefined },
+): Promise<ReadResourceResult> {
+  if (typeof value === "undefined") {
+    return { contents: [] };
+  }
+
+  let contents: ReadResourceResult["contents"] = [];
+
+  const mimeType = init.mimeType ?? init.response?.headers.get("content-type")
+    ?? "";
+
+  if (mimeType.search(/\bjson\b/g) !== -1) {
+    contents = [{ uri: uri.toString(), mimeType, text: JSON.stringify(value) }];
+  } else if (
+    mimeType.startsWith("text/event-stream")
+    && isAsyncIterable(value)
+  ) {
+    contents = [
+      {
+        uri: uri.toString(),
+        mimeType: "application/json",
+        text: await stringifySSEToJSON(value),
+      },
+    ];
+  } else if (
+    (mimeType.startsWith("text/") || mimeType.startsWith("application/"))
+    && typeof value === "string"
+  ) {
+    contents = [{ uri: uri.toString(), mimeType, text: value }];
+  } else if (isBinaryData(value)) {
+    const blob = await valueToBase64(value);
+    contents = blob == null ? [] : [{ uri: uri.toString(), blob, mimeType }];
+  } else {
+    throw new Error(`Unsupported content type: "${mimeType}"`);
+  }
+
+  return { contents };
+}
+
+async function stringifySSEToJSON(
+  value: AsyncIterable<unknown>,
+): Promise<string> {
+  const payloads = [];
+
+  for await (const chunk of value) {
+    payloads.push(chunk);
+  }
+
+  return JSON.stringify(payloads);
+}
+
+export function createRegisterResource(
+  logger: ConsoleLogger,
+  server: McpServer,
+  getSDK: () => CloudinaryAssetMgmtCore,
+  allowedScopes: Set<MCPScope>,
+): (resource: ResourceDefinition) => void {
+  return (resource: ResourceDefinition): void => {
+    const scopes = resource.scopes ?? [];
+    if (allowedScopes.size > 0 && scopes.length === 0) {
+      return;
+    }
+
+    if (
+      allowedScopes.size > 0
+      && !scopes.every((s: MCPScope) => allowedScopes.has(s))
+    ) {
+      return;
+    }
+
+    const metadata: ResourceMetadata = {
+      ...resource.metadata,
+      description: resource.description,
+    };
+
+    server.resource(
+      resource.name,
+      resource.resource,
+      metadata,
+      async (uri, ctx) => resource.read(getSDK(), uri, ctx),
+    );
+
+    logger.debug("Registered resource", { name: resource.name });
+  };
+}
+
+export function createRegisterResourceTemplate(
+  logger: ConsoleLogger,
+  server: McpServer,
+  getSDK: () => CloudinaryAssetMgmtCore,
+  allowedScopes: Set<MCPScope>,
+): (resource: ResourceTemplateDefinition) => void {
+  return (resource: ResourceTemplateDefinition): void => {
+    const scopes = resource.scopes ?? [];
+    if (allowedScopes.size > 0 && scopes.length === 0) {
+      return;
+    }
+
+    if (
+      allowedScopes.size > 0
+      && !scopes.every((s: MCPScope) => allowedScopes.has(s))
+    ) {
+      return;
+    }
+
+    const metadata: ResourceMetadata = {
+      ...resource.metadata,
+      description: resource.description,
+    };
+
+    server.resource(
+      resource.name,
+      resource.resource,
+      metadata,
+      async (uri, vars, ctx) => resource.read(getSDK(), uri, vars, ctx),
+    );
+
+    logger.debug("Registered resource template", { name: resource.name });
+  };
+}

package/src/mcp-server/scopes.ts

@@ -0,0 +1,11 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+export const mcpScopes = [
+  "admin",
+  "builder",
+  "librarian",
+] as const;
+
+export type MCPScope = (typeof mcpScopes)[number];

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

@@ -0,0 +1,118 @@
+/*
+ * Custom MCP server extensions
+ */
+
+import { z } from "zod";
+import { Register } from "./extensions.js";
+import { assetsExplicitAsset } from "../funcs/assetsExplicitAsset.js";
+import { ResourceType } from "../models/resourcetype.js";
+
+export function registerMCPExtensions(register: Register): void {
+  // Get transformation reference tool
+  register.tool({
+    name: "get-tx-reference",
+    description: "Get Cloudinary transformation rules documentation from official docs\n\n🚨 WHEN TO USE:\n- MANDATORY before creating, modifying, or discussing Cloudinary transformations\n- REQUIRED when user asks for image/video effects, resizing, cropping, filters, etc.\n- NOT needed for simple asset management (upload, list, delete, etc.)\n- ⚠️ CALL ONLY ONCE per session - documentation doesn't change, reuse the knowledge\n\n🚨 STRICT REQUIREMENTS (when transformations are involved):\n- MUST call this tool BEFORE any transformation-related task (but only once)\n- MUST read and understand the returned documentation\n- DO NOT attempt transformations without consulting this reference\n- DO NOT make up transformation parameters\n- DO NOT guess syntax - only use documented parameters\n- DO NOT call this tool multiple times - the docs are static, remember them\n\nThis tool returns the complete, authoritative Cloudinary transformation reference that contains all valid parameters, syntax rules, and best practices.",
+    scopes: ["librarian", "builder"],
+    annotations: {
+      title: "Get Cloudinary Transformation Reference",
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+      readOnlyHint: true,
+    },
+    tool: async (_client, _ctx) => {
+      try {
+        const response = await fetch("https://cloudinary.com/documentation/cloudinary_transformation_rules.md");
+
+        if (!response.ok) {
+          throw new Error(`HTTP error! status: ${response.status}`);
+        }
+
+        const content = await response.text();
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `# Cloudinary Transformation Rules Documentation\n\n${content}`
+            }
+          ]
+        };
+      } catch (error) {
+        return {
+          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`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  });
+
+  // Transform asset tool using explicit API with eager transformations
+  register.tool({
+    name: "transform-asset",
+    description: "Generate derived transformations for existing assets using Cloudinary's explicit API with eager transformations\n\n⚠️ CRITICAL PREREQUISITES:\n1. MUST call get-tx-reference tool first\n2. MUST validate transformation syntax against official docs\n3. MUST use only documented parameters from the reference\n4. MUST follow proper URL component structure (slashes between components, commas within)\n\n📋 VALIDATION CHECKLIST:\n- ✅ Called get-tx-reference tool\n- ✅ Verified all parameters exist in official docs\n- ✅ Used correct syntax (e.g., f_auto/q_auto not f_auto,q_auto)\n- ✅ Applied proper component chaining rules\n- ✅ Included crop mode when using width/height\n\nThis tool creates actual derived assets on Cloudinary using the explicit API.",
+    scopes: ["librarian", "builder"],
+    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"),
+      invalidate: z.boolean().optional().default(false).describe("Whether to invalidate cached versions"),
+    },
+    annotations: {
+      title: "Transform Cloudinary Asset",
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false,
+      readOnlyHint: false,
+    },
+    tool: async (client, args, _ctx) => {
+      try {
+        // Use the explicit API to generate eager transformations
+        const result = await assetsExplicitAsset(client, args.resourceType as ResourceType, {
+          public_id: args.publicId,
+          type: "upload",
+          eager: args.transformations,
+          invalidate: args.invalidate,
+        });
+
+        if (!result.ok) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Error transforming asset: ${result.error.message}`
+              }
+            ],
+            isError: true
+          };
+        }
+
+        // Return raw API response
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result.value, null, 2)
+            }
+          ]
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error transforming asset: ${error instanceof Error ? error.message : 'Unknown error'}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  });
+}
+

package/src/mcp-server/server.ts

@@ -0,0 +1,125 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CloudinaryAssetMgmtCore } from "../core.js";
+import { SDKOptions } from "../lib/config.js";
+import type { ConsoleLogger } from "./console-logger.js";
+import { Register } from "./extensions.js";
+import { createRegisterPrompt } from "./prompts.js";
+import {
+  createRegisterResource,
+  createRegisterResourceTemplate,
+} from "./resources.js";
+import { MCPScope } from "./scopes.js";
+import { registerMCPExtensions } from "./server.extensions.js";
+import { createRegisterTool } from "./tools.js";
+import { tool$assetRelationsCreateAssetRelationsByAssetId } from "./tools/assetRelationsCreateAssetRelationsByAssetId.js";
+import { tool$assetRelationsDeleteAssetRelationsByAssetId } from "./tools/assetRelationsDeleteAssetRelationsByAssetId.js";
+import { tool$assetsDerivedDestroy } from "./tools/assetsDerivedDestroy.js";
+import { tool$assetsDestroyByAssetId } from "./tools/assetsDestroyByAssetId.js";
+import { tool$assetsDownloadBackupAsset } from "./tools/assetsDownloadBackupAsset.js";
+import { tool$assetsGenerateArchive } from "./tools/assetsGenerateArchive.js";
+import { tool$assetsGetResourceByAssetId } from "./tools/assetsGetResourceByAssetId.js";
+import { tool$assetsListImages } from "./tools/assetsListImages.js";
+import { tool$assetsListRawFiles } from "./tools/assetsListRawFiles.js";
+import { tool$assetsListResourceTags } from "./tools/assetsListResourceTags.js";
+import { tool$assetsListVideos } from "./tools/assetsListVideos.js";
+import { tool$assetsRenameAsset } from "./tools/assetsRenameAsset.js";
+import { tool$assetsUpdateResourceByAssetId } from "./tools/assetsUpdateResourceByAssetId.js";
+import { tool$foldersCreateFolder } from "./tools/foldersCreateFolder.js";
+import { tool$foldersDestroyFolder } from "./tools/foldersDestroyFolder.js";
+import { tool$foldersSearchFolders } from "./tools/foldersSearchFolders.js";
+import { tool$foldersUpdateFolder } from "./tools/foldersUpdateFolder.js";
+import { tool$searchSearchAssets } from "./tools/searchSearchAssets.js";
+import { tool$searchVisualSearchAssets } from "./tools/searchVisualSearchAssets.js";
+import { tool$uploadUpload } from "./tools/uploadUpload.js";
+import { tool$usageGetUsage } from "./tools/usageGetUsage.js";
+
+export function createMCPServer(deps: {
+  logger: ConsoleLogger;
+  allowedTools?: string[] | undefined;
+  scopes?: MCPScope[] | undefined;
+  getSDK?: () => CloudinaryAssetMgmtCore;
+  serverURL?: string | undefined;
+  security?: SDKOptions["security"] | undefined;
+  cloud_name?: SDKOptions["cloud_name"] | undefined;
+  serverIdx?: SDKOptions["serverIdx"] | undefined;
+  region?: SDKOptions["region"] | undefined;
+  host?: SDKOptions["host"] | undefined;
+}) {
+  const server = new McpServer({
+    name: "CloudinaryAssetMgmt",
+    version: "0.6.0",
+  });
+
+  const getClient = deps.getSDK || (() =>
+    new CloudinaryAssetMgmtCore({
+      security: deps.security,
+      cloud_name: deps.cloud_name,
+      serverURL: deps.serverURL,
+      serverIdx: deps.serverIdx,
+      region: deps.region,
+      host: deps.host,
+      debugLogger: deps.logger.level === "debug"
+        ? {
+          log: (...args) => console.log(...args),
+          group: (...args) => console.group(...args),
+          groupEnd: (...args) => console.groupEnd(...args),
+        }
+        : undefined,
+    }));
+
+  const scopes = new Set(deps.scopes);
+
+  const allowedTools = deps.allowedTools && new Set(deps.allowedTools);
+  const tool = createRegisterTool(
+    deps.logger,
+    server,
+    getClient,
+    scopes,
+    allowedTools,
+  );
+  const resource = createRegisterResource(
+    deps.logger,
+    server,
+    getClient,
+    scopes,
+  );
+  const resourceTemplate = createRegisterResourceTemplate(
+    deps.logger,
+    server,
+    getClient,
+    scopes,
+  );
+  const prompt = createRegisterPrompt(deps.logger, server, getClient, scopes);
+  const register = { tool, resource, resourceTemplate, prompt };
+  void register; // suppress unused warnings
+
+  tool(tool$uploadUpload);
+  tool(tool$assetsRenameAsset);
+  tool(tool$assetsGenerateArchive);
+  tool(tool$assetsDownloadBackupAsset);
+  tool(tool$assetsDestroyByAssetId);
+  tool(tool$assetsListImages);
+  tool(tool$assetsListVideos);
+  tool(tool$assetsListRawFiles);
+  tool(tool$assetsGetResourceByAssetId);
+  tool(tool$assetsUpdateResourceByAssetId);
+  tool(tool$assetsListResourceTags);
+  tool(tool$assetsDerivedDestroy);
+  tool(tool$usageGetUsage);
+  tool(tool$assetRelationsCreateAssetRelationsByAssetId);
+  tool(tool$assetRelationsDeleteAssetRelationsByAssetId);
+  tool(tool$foldersUpdateFolder);
+  tool(tool$foldersCreateFolder);
+  tool(tool$foldersDestroyFolder);
+  tool(tool$foldersSearchFolders);
+  tool(tool$searchSearchAssets);
+  tool(tool$searchVisualSearchAssets);
+
+  registerMCPExtensions(register satisfies Register);
+
+  return server;
+}

package/src/mcp-server/shared.ts

@@ -0,0 +1,78 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+
+type BinaryData =
+  | Uint8Array
+  | ArrayBuffer
+  | Blob
+  | ReadableStream
+  | Response
+  | string;
+
+const base64Schema = z.string().base64();
+
+export function bytesToBase64(u8arr: Uint8Array): string {
+  return btoa(String.fromCodePoint(...u8arr));
+}
+
+export async function consumeStream(
+  stream: ReadableStream<Uint8Array>,
+): Promise<Uint8Array> {
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (value != null) chunks.push(value);
+      if (done) break;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+
+  return new Uint8Array(await new Blob(chunks).arrayBuffer());
+}
+
+export function isAsyncIterable(
+  value: unknown,
+): value is AsyncIterable<string> {
+  return (
+    typeof value === "object" && value != null && Symbol.asyncIterator in value
+  );
+}
+
+export function isBinaryData(value: unknown): value is BinaryData {
+  return (
+    value instanceof Uint8Array
+    || value instanceof ArrayBuffer
+    || value instanceof Blob
+    || value instanceof ReadableStream
+    || value instanceof Response
+    || typeof value === "string"
+  );
+}
+
+export async function valueToBase64(
+  value: BinaryData | null | undefined,
+): Promise<string | null> {
+  if (value == null) {
+    return null;
+  } else if (value instanceof Uint8Array) {
+    return bytesToBase64(value);
+  } else if (value instanceof ArrayBuffer) {
+    return bytesToBase64(new Uint8Array(value));
+  } else if (value instanceof Response || value instanceof Blob) {
+    return bytesToBase64(new Uint8Array(await value.arrayBuffer()));
+  } else if (value instanceof ReadableStream) {
+    return bytesToBase64(await consumeStream(value));
+  } else if (typeof value === "string") {
+    return base64Schema.parse(value);
+  } else {
+    value satisfies never;
+    throw new Error(`Unsupported image value type: ${typeof value}`);
+  }
+}