cloudinary-mcp-server

Instructions

Implementation Reference

• src/tools/getAssetTool.js:15-52 (handler)

  The core handler function `getAssetTool` that implements the logic to retrieve Cloudinary asset details using either `publicId` or `assetId` via the Cloudinary API.

  const getAssetTool = async (cloudinary, params) => {
  	if (!params.assetId && !params.publicId) {
  		return getToolError("Error: Either assetId or publicId must be provided", cloudinary);
  	}
  
  	try {
  		const { assetId, publicId, tags, context, metadata, resourceType, type } = params;
  		let resource;
  
  		if (publicId) {
  			resource = await cloudinary.api.resource(publicId, {
  				resource_type: resourceType,
  				type: type,
  				tags,
  				context,
  				metadata,
  			});
  		} else {
  			const result = await cloudinary.api
  				.resources_by_asset_ids([assetId], {
  					tags, context, metadata,
  				});
  
  			resource = result.resources[0] || null;
  		}
  
  		return {
  			content: [{
  				type: "text",
  				text: JSON.stringify(resource, null, 2),
  			}],
  			isError: false,
  		};
  
  	} catch (error) {
  		return getToolError(`Error retrieving asset: ${error.message || "unknown error"}`, cloudinary);
  	}
  };

• src/tools/getAssetTool.js:5-13 (schema)

  Zod schema defining input parameters for the `get-asset` tool, including assetId, publicId, and various options for resource type, delivery type, and metadata inclusion.

  export const getAssetToolParams = {
  	assetId: z.string().optional().describe("The Cloudinary asset ID"),
  	publicId: z.string().optional().describe("The public ID of the asset"),
  	resourceType: z.enum(["image", "raw", "video"]).optional().describe("Type of asset. Default: image"),
  	type: z.enum(["upload", "private", "authenticated", "fetch", "facebook", "twitter", "gravatar", "youtube", "hulu", "vimeo", "animoto", "worldstarhiphop", "dailymotion", "list"]).optional().describe("Delivery type. Default: upload"),
  	tags: z.boolean().optional().describe("Whether to include the list of tag names. Default: false"),
  	context: z.boolean().optional().describe("Whether to include contextual metadata. Default: false"),
  	metadata: z.boolean().optional().describe("Whether to include structured metadata. Default: false"),
  };

• src/index.js:57-62 (registration)

  Registration of the `get-asset` tool on the MCP server instance, specifying name, description, input schema, and handler.

  server.tool(
  	"get-asset",
  	"Get the details of a specific file (asset)",
  	getAssetToolParams,
  	getGetAssetTool(cloudinary),
  );

• src/tools/getCloudinaryTool.js:1-5 (helper)

  Helper function that curries the raw tool handler to produce a function accepting `cloudinary` instance first, then `params`, matching the expected tool signature.

  const getCloudinaryTool = (tool) => {
  	return (cloudinary) => (params) => tool(cloudinary, params);
  };
  
  export default getCloudinaryTool;

• src/utils.js:1-10 (helper)

  Utility helper to generate standardized error responses for tools, including partial Cloudinary config for debugging.

  export const getToolError = (msg, cloudinary) => {
  	const conf = cloudinary.config()
  	return {
  		content: [{
  			type: "text",
  			text: `${msg} (cloud: ${conf.cloud_name}, key: ${conf.api_key.slice(0,4)}...)`,
  		}],
  		isError: true,
  	};
  };