@cloudinary/asset-management-mcp 0.6.0

package/manifest.json

@@ -0,0 +1,159 @@
+{
+  "author": {
+    "name": "Cloudinary",
+    "url": "https://cloudinary.com"
+  },
+  "description": "Cloudinary Asset Management MCP Server",
+  "display_name": "Cloudinary Asset Management",
+  "icon": "icon.png",
+  "keywords": [
+    "cloudinary",
+    "asset-management",
+    "images",
+    "videos",
+    "media",
+    "cdn",
+    "transformation"
+  ],
+  "long_description": "A comprehensive MCP server for managing your Cloudinary assets. Upload, organize, search, and transform images, videos, and files with AI-powered tools.",
+  "manifest_version": "0.3",
+  "name": "@cloudinary/asset-management-mcp",
+  "prompts": [],
+  "screenshots": [
+      "icon.png"
+    ],
+  "server": {
+      "type": "node",
+      "entry_point": "./bin/mcp-server.js",
+      "mcp_config": {
+        "command": "node",
+        "args": [
+          "${__dirname}/bin/mcp-server.js",
+          "start",
+          "--api-key",
+          "${user_config.api_key}",
+          "--api-secret",
+          "${user_config.api_secret}",
+          "--cloud-name",
+          "${user_config.cloud_name}"
+        ]
+      }
+    },
+  "tools": [
+      {
+        "name": "upload-asset",
+        "description": "Uploads media assets (images, videos, raw files) to your Cloudinary product environment\n\nUploads media assets (images, videos, raw files) to your Cloudinary product environment. The file is securely stored\nin the cloud with backup and revision history. Cloudinary automatically analyzes and saves important data about each\nasset, such as format, size, resolution, and prominent colors, which is indexed to enable searching on those attributes.\n\nSupports uploading from:\n- Local file paths (SDKs/MCP server only). For MCP server path MUST start with file://\n- Remote HTTP/HTTPS URLs\n- Base64 Data URIs (max ~60 MB)\n- Private storage buckets (S3 or Google Storage)\n- FTP addresses\n\nThe uploaded asset is immediately available for transformation and delivery upon successful upload.\n\nTransform media files using transformation syntax in delivery URLs, which creates derived files accessible immediately without re-uploading the original.\n"
+      },
+      {
+        "name": "asset-rename",
+        "description": "Updates an existing asset's identifier (public ID) and optionally other metadata in your Cloudinary account"
+      },
+      {
+        "name": "generate-archive",
+        "description": "Creates an archive (ZIP or TGZ file) that contains a set of assets from your product environment.\n\nCreates a downloadable ZIP or other archive format containing the specified resources."
+      },
+      {
+        "name": "download-asset-backup",
+        "description": "Download a backup copy of an asset"
+      },
+      {
+        "name": "delete-asset",
+        "description": "Delete asset by asset-id\n\nDeletes an asset using its asset ID. This endpoint replaces the legacy /resources/by_asset_id endpoint.\nReturns the deletion status and asset folder information when folder decoupling is enabled.\n"
+      },
+      {
+        "name": "list-images",
+        "description": "Get image assets\n\nRetrieves a list of image assets. Results can be filtered by various criteria like tags, moderation status, prefix, or specific public IDs.\n"
+      },
+      {
+        "name": "list-videos",
+        "description": "Get video assets\n\nRetrieves a list of video assets. Results can be filtered by various criteria like tags, moderation status, prefix, or specific public IDs.\n"
+      },
+      {
+        "name": "list-files",
+        "description": "Get raw assets\n\nRetrieves a list of raw assets. Results can be filtered by various criteria like tags, moderation status, prefix, or specific public IDs.\n"
+      },
+      {
+        "name": "get-asset-details",
+        "description": "Get resource by asset ID\n\nReturns the details of a single resource specified by its asset ID."
+      },
+      {
+        "name": "asset-update",
+        "description": "Updates an existing asset's metadata, tags, and other attributes using its asset ID\n\nUpdates 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.\n"
+      },
+      {
+        "name": "list-tags",
+        "description": "Retrieves a list of tags currently applied to assets in your Cloudinary account\n\nRetrieves a comprehensive list of all tags that exist in your product environment for assets of the specified type.\n\n[Cloudinary Admin API documentation](https://cloudinary.com/documentation/admin_api)\n"
+      },
+      {
+        "name": "delete-derived-assets",
+        "description": "Delete derived resources\n\nDeletes derived resources by derived resource ID"
+      },
+      {
+        "name": "get-usage-details",
+        "description": "Retrieves comprehensive usage metrics and account statistics\n\nA 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."
+      },
+      {
+        "name": "create-asset-relations",
+        "description": "Add related assets by asset ID\n\nRelates 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."
+      },
+      {
+        "name": "delete-asset-relations",
+        "description": "Delete asset relations by asset ID\n\nUnrelates 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."
+      },
+      {
+        "name": "move-folder",
+        "description": "Renames or moves an entire folder (along with all assets it contains) to a new location\n\nRenames or moves an entire folder (along with all assets it contains) to a new location within your Cloudinary media library."
+      },
+      {
+        "name": "create-folder",
+        "description": "Creates a new empty folder in your Cloudinary media library\n\nCreates a new folder at the specified path"
+      },
+      {
+        "name": "delete-folder",
+        "description": "Deletes an existing folder from your media library\n\nDeletes a folder and all assets within it."
+      },
+      {
+        "name": "search-folders",
+        "description": "Searches for folders whose attributes match a given expression\n\nLists 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.\n"
+      },
+      {
+        "name": "search-assets",
+        "description": "Provides a powerful query interface to filter and retrieve assets and their details\n\nReturns a list of resources matching the specified search criteria.\n\nUses 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.\n\nExamples: tags:shirt AND uploaded_at>1d, resource_type:image AND bytes>1mb, folder:products OR context.category:electronics\n"
+      },
+      {
+        "name": "visual-search-assets",
+        "description": "Finds images in your asset library based on visual similarity or content\n\nReturns 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:\n- Provide a URL of an image\n- Specify the public ID or asset ID of an existing image\n- Provide a textual description\n"
+      },
+      {
+        "name": "get-tx-reference",
+        "description": "Get Cloudinary transformation rules documentation from official docs."
+      },
+      {
+        "name": "transform-asset",
+        "description": "Generate derived transformations for existing assets using Cloudinary's explicit API with eager transformations."
+      }
+    ],
+  "user_config": {
+      "cloud_name": {
+        "description": "Your Cloudinary cloud name (required). Find it in your Cloudinary Dashboard.",
+        "required": true,
+        "title": "Cloud Name",
+        "type": "string"
+      },
+      "api_key": {
+        "description": "Your Cloudinary API key. Found in Dashboard → Settings → Access Keys.",
+        "required": true,
+        "sensitive": true,
+        "title": "API Key",
+        "type": "string"
+      },
+      "api_secret": {
+        "description": "Your Cloudinary API secret. Found in Dashboard → Settings → Access Keys.",
+        "required": true,
+        "sensitive": true,
+        "title": "API Secret",
+        "type": "string"
+      }
+    },
+  "version": "0.6.0"
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@cloudinary/asset-management-mcp",
+  "version": "0.6.0",
+  "author": "Cloudinary",
+  "type": "module",
+  "sideEffects": false,
+  "bin": {
+    "@cloudinary/asset-management-mcp": "bin/mcp-server.js",
+    "mcp": "bin/mcp-server.js"
+  },
+  "scripts": {
+    "build": "bun i && bun src/mcp-server/build.mts && tsc",
+    "check": "npm run lint",
+    "lint": "eslint --cache --max-warnings=0 src",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.0",
+    "@stricli/core": "^1.1.2",
+    "bun": "^1.2.12",
+    "express": "^5.1.0",
+    "zod": "^3.25.7"
+  },
+  "devDependencies": {
+    "@anthropic-ai/mcpb": "^1.2.0",
+    "@eslint/js": "^9.26.0",
+    "@types/bun": "^1.2.13",
+    "@types/express": "^5.0.1",
+    "@types/node": "^22.15.20",
+    "eslint": "^9.26.0",
+    "globals": "^16.0.0",
+    "typescript": "~5.8.3",
+    "typescript-eslint": "^8.31.1"
+  }
+}

package/src/core.ts

@@ -0,0 +1,13 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { ClientSDK } from "./lib/sdks.js";
+
+/**
+ * A minimal client to use when calling standalone SDK functions. Typically, an
+ * instance of this class would be instantiated once at the start of an
+ * application and passed around through some dependency injection mechanism  to
+ * parts of an application that need to make SDK calls.
+ */
+export class CloudinaryAssetMgmtCore extends ClientSDK {}

package/src/funcs/assetRelationsCreateAssetRelationsByAssetId.ts

@@ -0,0 +1,190 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { CloudinaryAssetMgmtCore } from "../core.js";
+import { encodeJSON, encodeSimple } from "../lib/encodings.js";
+import * as M from "../lib/matchers.js";
+import { compactMap } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
+import { pathToFunc } from "../lib/url.js";
+import {
+  CreateAssetRelationsByAssetIdRequest,
+  CreateAssetRelationsByAssetIdRequest$zodSchema,
+  CreateAssetRelationsByAssetIdRequestBody,
+  CreateAssetRelationsByAssetIdResponse,
+  CreateAssetRelationsByAssetIdResponse$zodSchema,
+} from "../models/createassetrelationsbyassetidop.js";
+import { APIError } from "../models/errors/apierror.js";
+import {
+  ConnectionError,
+  InvalidRequestError,
+  RequestAbortedError,
+  RequestTimeoutError,
+  UnexpectedClientError,
+} from "../models/errors/httpclienterrors.js";
+import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
+import { APICall, APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+
+/**
+ * Add related assets by asset ID
+ *
+ * @remarks
+ * 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.
+ */
+export function assetRelationsCreateAssetRelationsByAssetId(
+  client$: CloudinaryAssetMgmtCore,
+  asset_id: string,
+  RequestBody: CreateAssetRelationsByAssetIdRequestBody,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    CreateAssetRelationsByAssetIdResponse,
+    | APIError
+    | SDKValidationError
+    | UnexpectedClientError
+    | InvalidRequestError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | ConnectionError
+  >
+> {
+  return new APIPromise($do(
+    client$,
+    asset_id,
+    RequestBody,
+    options,
+  ));
+}
+
+async function $do(
+  client$: CloudinaryAssetMgmtCore,
+  asset_id: string,
+  RequestBody: CreateAssetRelationsByAssetIdRequestBody,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      CreateAssetRelationsByAssetIdResponse,
+      | APIError
+      | SDKValidationError
+      | UnexpectedClientError
+      | InvalidRequestError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | ConnectionError
+    >,
+    APICall,
+  ]
+> {
+  const input$: CreateAssetRelationsByAssetIdRequest = {
+    asset_id: asset_id,
+    RequestBody: RequestBody,
+  };
+
+  const parsed$ = safeParse(
+    input$,
+    (value$) => CreateAssetRelationsByAssetIdRequest$zodSchema.parse(value$),
+    "Input validation failed",
+  );
+  if (!parsed$.ok) {
+    return [parsed$, { status: "invalid" }];
+  }
+  const payload$ = parsed$.value;
+  const body$ = encodeJSON("body", payload$.RequestBody, { explode: true });
+
+  const pathParams$ = {
+    asset_id: encodeSimple("asset_id", payload$.asset_id, {
+      explode: false,
+      charEncoding: "percent",
+    }),
+    cloud_name: encodeSimple("cloud_name", client$._options.cloud_name, {
+      explode: false,
+      charEncoding: "percent",
+    }),
+  };
+  const path$ = pathToFunc(
+    "/v1_1/{cloud_name}/resources/related_assets/{asset_id}",
+  )(
+    pathParams$,
+  );
+
+  const headers$ = new Headers(compactMap({
+    "Content-Type": "application/json",
+    Accept: "application/json",
+  }));
+  const securityInput = await extractSecurity(client$._options.security);
+  const requestSecurity = resolveGlobalSecurity(securityInput);
+
+  const context = {
+    options: client$._options,
+    baseURL: options?.serverURL ?? client$._baseURL ?? "",
+    operationID: "createAssetRelationsByAssetId",
+    oAuth2Scopes: null,
+    resolvedSecurity: requestSecurity,
+    securitySource: client$._options.security,
+    retryConfig: options?.retries
+      || client$._options.retryConfig
+      || { strategy: "none" },
+    retryCodes: options?.retryCodes || [
+      "429",
+      "500",
+      "502",
+      "503",
+      "504",
+    ],
+  };
+
+  const requestRes = client$._createRequest(context, {
+    security: requestSecurity,
+    method: "POST",
+    baseURL: options?.serverURL,
+    path: path$,
+    headers: headers$,
+    body: body$,
+    userAgent: client$._options.userAgent,
+    timeoutMs: options?.timeoutMs || client$._options.timeoutMs
+      || -1,
+  }, options);
+  if (!requestRes.ok) {
+    return [requestRes, { status: "invalid" }];
+  }
+  const req$ = requestRes.value;
+
+  const doResult = await client$._do(req$, {
+    context,
+    errorCodes: [],
+    retryConfig: context.retryConfig,
+    retryCodes: context.retryCodes,
+  });
+  if (!doResult.ok) {
+    return [doResult, { status: "request-error", request: req$ }];
+  }
+  const response = doResult.value;
+  const responseFields$ = {
+    HttpMeta: { Response: response, Request: req$ },
+  };
+
+  const [result$] = await M.match<
+    CreateAssetRelationsByAssetIdResponse,
+    | APIError
+    | SDKValidationError
+    | UnexpectedClientError
+    | InvalidRequestError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | ConnectionError
+  >(
+    M.json([200, 207], CreateAssetRelationsByAssetIdResponse$zodSchema, {
+      key: "asset_relations_response",
+    }),
+    M.json([400, 401, 404], CreateAssetRelationsByAssetIdResponse$zodSchema, {
+      key: "api_error",
+    }),
+  )(response, req$, { extraFields: responseFields$ });
+
+  return [result$, { status: "complete", request: req$, response }];
+}

package/src/funcs/assetRelationsCreateAssetRelationsByPublicId.ts

@@ -0,0 +1,208 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { CloudinaryAssetMgmtCore } from "../core.js";
+import { encodeJSON, encodeSimple } from "../lib/encodings.js";
+import * as M from "../lib/matchers.js";
+import { compactMap } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
+import { pathToFunc } from "../lib/url.js";
+import {
+  CreateAssetRelationsByPublicIdRequest,
+  CreateAssetRelationsByPublicIdRequest$zodSchema,
+  CreateAssetRelationsByPublicIdRequestBody,
+  CreateAssetRelationsByPublicIdResponse,
+  CreateAssetRelationsByPublicIdResponse$zodSchema,
+} from "../models/createassetrelationsbypublicidop.js";
+import { APIError } from "../models/errors/apierror.js";
+import {
+  ConnectionError,
+  InvalidRequestError,
+  RequestAbortedError,
+  RequestTimeoutError,
+  UnexpectedClientError,
+} from "../models/errors/httpclienterrors.js";
+import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
+import { ResourceType } from "../models/resourcetype.js";
+import { StorageTypeParameter } from "../models/storagetypeparameter.js";
+import { APICall, APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+
+/**
+ * Create asset relations by public ID
+ *
+ * @remarks
+ * Relates an asset to other assets by public IDs. This allows you to indicate that the asset is logically related to other assets in some way (e.g., similar content, or a peripheral asset like video/transcript, etc). This is a bidirectional process, meaning that the asset is also 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.
+ */
+export function assetRelationsCreateAssetRelationsByPublicId(
+  client$: CloudinaryAssetMgmtCore,
+  resource_type: ResourceType,
+  type: StorageTypeParameter | undefined,
+  public_id: string,
+  RequestBody: CreateAssetRelationsByPublicIdRequestBody,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    CreateAssetRelationsByPublicIdResponse,
+    | APIError
+    | SDKValidationError
+    | UnexpectedClientError
+    | InvalidRequestError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | ConnectionError
+  >
+> {
+  return new APIPromise($do(
+    client$,
+    resource_type,
+    type,
+    public_id,
+    RequestBody,
+    options,
+  ));
+}
+
+async function $do(
+  client$: CloudinaryAssetMgmtCore,
+  resource_type: ResourceType,
+  type: StorageTypeParameter | undefined,
+  public_id: string,
+  RequestBody: CreateAssetRelationsByPublicIdRequestBody,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      CreateAssetRelationsByPublicIdResponse,
+      | APIError
+      | SDKValidationError
+      | UnexpectedClientError
+      | InvalidRequestError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | ConnectionError
+    >,
+    APICall,
+  ]
+> {
+  const input$: CreateAssetRelationsByPublicIdRequest = {
+    resource_type: resource_type,
+    type: type,
+    public_id: public_id,
+    RequestBody: RequestBody,
+  };
+
+  const parsed$ = safeParse(
+    input$,
+    (value$) => CreateAssetRelationsByPublicIdRequest$zodSchema.parse(value$),
+    "Input validation failed",
+  );
+  if (!parsed$.ok) {
+    return [parsed$, { status: "invalid" }];
+  }
+  const payload$ = parsed$.value;
+  const body$ = encodeJSON("body", payload$.RequestBody, { explode: true });
+
+  const pathParams$ = {
+    cloud_name: encodeSimple("cloud_name", client$._options.cloud_name, {
+      explode: false,
+      charEncoding: "percent",
+    }),
+    public_id: encodeSimple("public_id", payload$.public_id, {
+      explode: false,
+      charEncoding: "percent",
+    }),
+    resource_type: encodeSimple("resource_type", payload$.resource_type, {
+      explode: false,
+      charEncoding: "percent",
+    }),
+    type: encodeSimple("type", payload$.type, {
+      explode: false,
+      charEncoding: "percent",
+    }),
+  };
+  const path$ = pathToFunc(
+    "/v1_1/{cloud_name}/resources/related_assets/{resource_type}/{type}/{public_id}",
+  )(
+    pathParams$,
+  );
+
+  const headers$ = new Headers(compactMap({
+    "Content-Type": "application/json",
+    Accept: "application/json",
+  }));
+  const securityInput = await extractSecurity(client$._options.security);
+  const requestSecurity = resolveGlobalSecurity(securityInput);
+
+  const context = {
+    options: client$._options,
+    baseURL: options?.serverURL ?? client$._baseURL ?? "",
+    operationID: "createAssetRelationsByPublicId",
+    oAuth2Scopes: null,
+    resolvedSecurity: requestSecurity,
+    securitySource: client$._options.security,
+    retryConfig: options?.retries
+      || client$._options.retryConfig
+      || { strategy: "none" },
+    retryCodes: options?.retryCodes || [
+      "429",
+      "500",
+      "502",
+      "503",
+      "504",
+    ],
+  };
+
+  const requestRes = client$._createRequest(context, {
+    security: requestSecurity,
+    method: "POST",
+    baseURL: options?.serverURL,
+    path: path$,
+    headers: headers$,
+    body: body$,
+    userAgent: client$._options.userAgent,
+    timeoutMs: options?.timeoutMs || client$._options.timeoutMs
+      || -1,
+  }, options);
+  if (!requestRes.ok) {
+    return [requestRes, { status: "invalid" }];
+  }
+  const req$ = requestRes.value;
+
+  const doResult = await client$._do(req$, {
+    context,
+    errorCodes: [],
+    retryConfig: context.retryConfig,
+    retryCodes: context.retryCodes,
+  });
+  if (!doResult.ok) {
+    return [doResult, { status: "request-error", request: req$ }];
+  }
+  const response = doResult.value;
+  const responseFields$ = {
+    HttpMeta: { Response: response, Request: req$ },
+  };
+
+  const [result$] = await M.match<
+    CreateAssetRelationsByPublicIdResponse,
+    | APIError
+    | SDKValidationError
+    | UnexpectedClientError
+    | InvalidRequestError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | ConnectionError
+  >(
+    M.json([200, 207], CreateAssetRelationsByPublicIdResponse$zodSchema, {
+      key: "asset_relations_response",
+    }),
+    M.json([400, 401, 404], CreateAssetRelationsByPublicIdResponse$zodSchema, {
+      key: "api_error",
+    }),
+  )(response, req$, { extraFields: responseFields$ });
+
+  return [result$, { status: "complete", request: req$, response }];
+}