@cloudinary/asset-management-mcp 0.6.2 → 0.7.0

package/src/hooks/cloudinaryAuthHook.ts

@@ -1,239 +1,135 @@
-import {CloudConfig} from "./cloudConfig.js";
-import {BeforeRequestContext, BeforeRequestHook} from "./types.js";
-
-export class CloudinaryAuthHook
-    implements BeforeRequestHook {
-
-    private readonly cloudConfig: CloudConfig;
-
-    constructor() {
-        this.cloudConfig = new CloudConfig();
+import { CloudConfig } from "./cloudConfig.js";
+import { BeforeRequestContext, BeforeRequestHook } from "./types.js";
+
+/**
+ * Attaches Cloudinary authentication to every outgoing request.
+ *
+ * Priority:
+ *   1. OAuth2 Bearer token (if provided via security source)
+ *   2. Basic auth (apiKey:apiSecret) — works for all endpoints including upload
+ *
+ * Also preprocesses JSON request bodies to convert local `file://` URIs
+ * into base64 data URIs so uploads work with local file paths.
+ */
+export class CloudinaryAuthHook implements BeforeRequestHook {
+    private readonly config: CloudConfig;
+
+    constructor(config: CloudConfig) {
+        this.config = config;
     }
 
-    async beforeRequest(hookCtx: BeforeRequestContext, request: Request): Promise<Request> {
-        let security = hookCtx.securitySource;
-        // Resolve the security source if it's a function (for dynamic token refresh)
-        if (typeof security === 'function') {
-            security = await security();
-        }
-
-        // Prioritize OAuth2 bearer token if it's provided.
-        if (security && typeof security === 'object' && 'oauth2' in security && typeof security.oauth2 === 'string') {
-            const token = security.oauth2;
-            if (token) {
-                request.headers.set("Authorization", `Bearer ${token}`);
-                return request;
-            }
-        }
-
-        // Fallback to API key/secret signing if no OAuth token is present.
-        let { apiKey, apiSecret } = this.cloudConfig;
-
-        // Optionally merge user-supplied security overrides
-        if (security) {
-            // Handle custom cloudinaryAuth format
-            if ('cloudinaryAuth' in security && security.cloudinaryAuth) {
-                // Support both camelCase and snake_case for compatibility
-                if (security.cloudinaryAuth.apiKey || security.cloudinaryAuth.api_key) {
-                    apiKey = security.cloudinaryAuth.apiKey || security.cloudinaryAuth.api_key;
-                }
-                if (security.cloudinaryAuth.apiSecret || security.cloudinaryAuth.api_secret) {
-                    apiSecret = security.cloudinaryAuth.apiSecret || security.cloudinaryAuth.api_secret;
-                }
-            }
-            // Handle standard SDK security format (used by MCP server)
-            else if ('apiKey' in security || 'apiSecret' in security) {
-                if ('apiKey' in security && security.apiKey) {
-                    apiKey = security.apiKey;
-                }
-                if ('apiSecret' in security && security.apiSecret) {
-                    apiSecret = security.apiSecret;
-                }
-            }
-        }
+    async beforeRequest(
+        hookCtx: BeforeRequestContext,
+        request: Request,
+    ): Promise<Request> {
+        const security = await this.resolveSecurity(hookCtx.securitySource);
 
-        if (!apiKey || !apiSecret) {
+        // 1. OAuth2 Bearer token takes priority
+        if (this.isOAuth2Token(security)) {
+            request.headers.set("Authorization", `Bearer ${security.oauth2}`);
             return request;
         }
 
-        if (this.SIGNED_PATHS.every(path => request.url.indexOf(path) === -1)) {
-            // generate  Authorization header using basic auth where apiKey:apiSecret is encoded in base64
-            const authHeader = `Basic ${Buffer.from(`${apiKey}:${apiSecret}`).toString("base64")}`;
-            request.headers.set("Authorization", authHeader);
+        // 2. Resolve API key / secret (env → security overrides)
+        const { apiKey, apiSecret } = this.resolveCredentials(security);
+        if (!apiKey || !apiSecret) {
             return request;
         }
 
-        // Extract query parameters regardless of body existence
-        const url = new URL(request.url);
-        const queryParams = this.paramsFromQuery(url.searchParams);
-
-        // Handle case with only query parameters (no body)
-        if (!request.body) {
-            return this.signQueryOnlyRequest(request, apiKey, apiSecret, queryParams);
-        }
-
-        // if content-type is application/json, parse the body as json and add the signature, timestamp and apiKey to the body
-        if (request.headers.get("Content-Type") === "application/json") {
-            const preprocessedBody = await this.preprocessJsonRequest(request);
-            return this.signJsonRequest(request, apiKey, apiSecret, queryParams, preprocessedBody);
-        }
-
-        // if content-type is multipart/form-data, parse the body as form data and add the signature, timestamp and apiKey to the body
-        if (request.headers.get("Content-Type")?.startsWith("multipart/form-data")) {
-            return this.signFormDataRequest(request, apiKey, apiSecret, queryParams);
-        }
+        // Set Basic auth header
+        const encoded = Buffer.from(`${apiKey}:${apiSecret}`).toString("base64");
+        request.headers.set("Authorization", `Basic ${encoded}`);
 
-        // Default case - just sign query parameters if any exist
-        if (queryParams.length > 0) {
-            return this.signQueryOnlyRequest(request, apiKey, apiSecret, queryParams);
-        }
+        // Preprocess JSON bodies (e.g. convert file:// URIs to base64)
+        request = await this.preprocessBody(request);
 
         return request;
     }
 
-    paramsFromQuery(searchParams: URLSearchParams): string[] {
-        const params = [];
-        for (const [key, value] of searchParams.entries()) {
-            if (key !== "file" && key !== "cloud_name" && key !== "resource_type" && key !== "api_key" && key !== "signature" && key !== "timestamp") {
-                params.push(`${key}=${value}`);
-            }
-        }
-        return params;
-    }
-
-    async signQueryOnlyRequest(request: Request, apiKey: string, apiSecret: string, queryParams: string[]): Promise<Request> {
-        const url = new URL(request.url);
-        // Check if already signed
-        if (url.searchParams.has("signature")) {
-            return request;
-        }
-
-        const { signature, timestamp } = await this.computeSignature(queryParams, apiSecret);
-        url.searchParams.set("signature", signature);
-        url.searchParams.set("timestamp", timestamp.toString());
-        url.searchParams.set("api_key", apiKey);
+    // --- Security resolution ---
 
-        return new Request(url.toString(), request);
+    private async resolveSecurity(source: unknown): Promise<unknown> {
+        return typeof source === "function" ? source() : source;
     }
 
-    async computeSignature(params: string[], apiSecret: string) {
-        const crypto = await import('node:crypto');
-        // Create a string with the parameters used in the POST request to Cloudinary:
-        //     All parameters added to the method call should be included except: file, cloud_name, resource_type and your api_key.
-        //     Sort all the parameters in alphabetical order.
-        //     Separate the parameter names from their values with an = and join the parameter/value pairs together with an &.
-        // Append your API secret to the end of the string.
-        // Create a hexadecimal message digest (hash value) of the string using an SHA cryptographic function.
-        const timestamp = Math.floor(Date.now() / 1000);
-        params.push(`timestamp=${timestamp}`);
-        params.sort();
-        const paramsString = params.join("&");
-        const signature = crypto.createHash('sha256').update(`${paramsString}${apiSecret}`).digest('hex');
-
-        return { signature, timestamp };
+    private isOAuth2Token(
+        security: unknown,
+    ): security is { oauth2: string } {
+        return (
+            typeof security === "object"
+            && security !== null
+            && "oauth2" in security
+            && typeof (security as any).oauth2 === "string"
+            && (security as any).oauth2.length > 0
+        );
     }
 
-    paramsToSignFormData(form: FormData) {
-        const params = [];
-        for (const [key, value] of form.entries()) {
-            if (key !== "file" && key !== "cloud_name" && key !== "resource_type" && key !== "api_key" && key !== "signature") {
-                params.push(`${key}=${value}`);
-            }
-        }
-        return params;
-    }
+    private resolveCredentials(security: unknown): {
+        apiKey: string;
+        apiSecret: string;
+    } {
+        let { apiKey, apiSecret } = this.config;
 
-    paramsToSignJson(json: Record<string, string>) {
-        const params = [];
-        for (const [key, value] of Object.entries(json)) {
-            if (key !== "file" && key !== "cloud_name" && key !== "resource_type" && key !== "api_key" && key !== "signature") {
-                params.push(`${key}=${value}`);
-            }
+        if (!security || typeof security !== "object") {
+            return { apiKey, apiSecret };
         }
-        return params;
-    }
 
-    async preprocessJsonRequest(request: Request): Promise<any> {
-        const body = await request.json();
+        const sec = security as Record<string, any>;
 
-        // Handle file:// URLs by converting to base64 data URIs
-        if (body.file && typeof body.file === 'string' && body.file.startsWith('file://')) {
-            body.file = await this.convertFileToDataUri(body.file);
+        // cloudinaryAuth format (camelCase and snake_case)
+        if (sec["cloudinaryAuth"]) {
+            const auth = sec["cloudinaryAuth"];
+            apiKey = auth.apiKey || auth.api_key || apiKey;
+            apiSecret = auth.apiSecret || auth.api_secret || apiSecret;
+        }
+        // Standard SDK security format (used by MCP server)
+        else if ("apiKey" in sec || "apiSecret" in sec) {
+            apiKey = sec["apiKey"] || apiKey;
+            apiSecret = sec["apiSecret"] || apiSecret;
         }
 
-        return body;
+        return { apiKey, apiSecret };
     }
 
-    async signJsonRequest(request: Request, apiKey: string, apiSecret: string, queryParams: string[] = [], preprocessedBody?: any) {
-        const body = preprocessedBody || await request.json();
-        if (body.signature) {
+    // --- Body preprocessing ---
+
+    /**
+     * For JSON requests, converts local `file://` URIs to inline base64
+     * data URIs so Cloudinary can accept the upload payload.
+     */
+    private async preprocessBody(request: Request): Promise<Request> {
+        if (request.headers.get("Content-Type") !== "application/json") {
             return request;
         }
 
-        const bodyParams = this.paramsToSignJson(body);
-        const allParams = [...bodyParams, ...queryParams];
-        const { signature, timestamp } = await this.computeSignature(allParams, apiSecret);
-        body.signature = signature;
-        body.timestamp = timestamp;
-        body.api_key = apiKey;
+        const body = await request.json();
+
+        if (
+            typeof body?.file === "string"
+            && body.file.startsWith("file://")
+        ) {
+            body.file = await this.readLocalFileAsDataUri(body.file);
+            return new Request(request, { body: JSON.stringify(body) });
+        }
+
         return new Request(request, { body: JSON.stringify(body) });
     }
 
-    private async convertFileToDataUri(fileUrl: string): Promise<string> {
-        // Remove 'file://' prefix to get the actual file path
-        const filePath = fileUrl.replace(/^file:\/\//, '');
+    /**
+     * Reads a local file and returns it as a base64 data URI.
+     */
+    private async readLocalFileAsDataUri(fileUrl: string): Promise<string> {
+        const filePath = fileUrl.replace(/^file:\/\//, "");
 
         try {
-            // Import required Node.js modules
-            const { readFile } = await import('node:fs/promises');
-
-            // Read the file as a buffer
-            const fileBuffer = await readFile(filePath);
-
-            // Convert to base64
-            const base64Data = fileBuffer.toString('base64');
-
-            // Use generic MIME type for all files
-            const mimeType = 'application/octet-stream';
-
-            // Return as data URI
-            return `data:${mimeType};base64,${base64Data}`;
-
+            const { readFile } = await import("node:fs/promises");
+            const buffer = await readFile(filePath);
+            const base64 = buffer.toString("base64");
+            return `data:application/octet-stream;base64,${base64}`;
         } catch (error) {
-            // If file reading fails, log error and return original URL
-            console.error(`Failed to read file: ${filePath}`, error);
-            throw new Error(`Failed to read file: ${filePath}. ${error instanceof Error ? error.message : String(error)}`);
+            throw new Error(
+                `Failed to read file: ${filePath}. ${error instanceof Error ? error.message : String(error)}`,
+            );
         }
     }
-
-    async signFormDataRequest(request: Request, apiKey: string, apiSecret: string, queryParams: string[] = []) {
-        const form = await request.clone().formData();
-        if (form.get("signature")) {
-            return request;
-        }
-
-        const bodyParams = this.paramsToSignFormData(form);
-        const allParams = [...bodyParams, ...queryParams];
-        const { signature, timestamp } = await this.computeSignature(allParams, apiSecret);
-
-        // add the signature, timestamp and apiKey to the URL as query parameters
-        const url = new URL(request.url);
-        url.searchParams.set("signature", signature);
-        url.searchParams.set("timestamp", timestamp.toString());
-        url.searchParams.set("api_key", apiKey);
-
-        // construct a new request with the same URL and the same form data and the same method
-        // remove the basic authentication header
-        const newHeaders = new Headers(request.headers);
-        newHeaders.delete("Authorization");
-        return new Request(url.toString(), request);
-    }
-
-    SIGNED_ACTIONS = [
-        'explicit', 'upload', 'download', 'destroy', 'sprite', 'tags', 'context', 'metadata_update', 'text', 'multi', 'explode',
-        'rename', 'create_slideshow', 'create_video', 'create_collage', 'generate_archive'];
-
-    SIGNED_PATHS = ["image", "video", "raw", "auto", "asset"].flatMap(resourceType => this.SIGNED_ACTIONS.map(action => `${resourceType}/${action}`));
-
-
 }

package/src/hooks/customHeadersHook.ts

@@ -0,0 +1,30 @@
+import { BeforeRequestContext, BeforeRequestHook } from "./types.js";
+
+/**
+ * Injects custom headers into every outgoing request to the Cloudinary API.
+ *
+ * Headers are read from `hookCtx.options.customHeaders` (a Record<string, string>),
+ * which is set by mcp-service when constructing the SDK via getSDK.
+ *
+ * When no custom headers are configured, this hook is a no-op.
+ */
+export class CustomHeadersHook implements BeforeRequestHook {
+    async beforeRequest(
+        hookCtx: BeforeRequestContext,
+        request: Request,
+    ): Promise<Request> {
+        const customHeaders = (hookCtx.options as any)?.customHeaders as
+            | Record<string, string>
+            | undefined;
+
+        if (!customHeaders) {
+            return request;
+        }
+
+        for (const [name, value] of Object.entries(customHeaders)) {
+            request.headers.set(name, value);
+        }
+
+        return request;
+    }
+}

package/src/hooks/oauth2scopes.ts

@@ -0,0 +1,19 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+/**
+ * Available scopes for the oauth2 OAuth 2.0 scheme (authorizationCode flow).
+ *
+ * @remarks
+ * OAuth2 Authorization Code flow for user authentication
+ */
+export type OAuth2Scope =
+  /**
+   * Allows managing assets, including reading, updating, and deleting.
+   */
+  | "asset_management"
+  /**
+   * Allows uploading new assets.
+   */
+  | "upload";

package/src/hooks/registration.ts

@@ -1,5 +1,8 @@
-import { Hooks } from "./types.js";
+import { CloudConfig } from "./cloudConfig.js";
 import { CloudinaryAuthHook } from "./cloudinaryAuthHook.js";
+import { CustomHeadersHook } from "./customHeadersHook.js";
+import { ResponseHeadersHook } from "./responseHeadersHook.js";
+import { Hooks } from "./types.js";
 import { UserAgentHook } from "./userAgentHook.js";
 /*
  * This file is only ever generated once on the first generation and then is free to be modified.
@@ -8,12 +11,11 @@ import { UserAgentHook } from "./userAgentHook.js";
  */
 
 export function initHooks(hooks: Hooks) {
-  // Add hooks by calling hooks.register{ClientInit/BeforeCreateRequest/BeforeRequest/AfterSuccess/AfterError}Hook
-  // with an instance of a hook that implements that specific Hook interface
-  // Hooks are registered per SDK instance, and are valid for the lifetime of the SDK instance
-    const cloudinaryAuthHook = new CloudinaryAuthHook();
-    hooks.registerBeforeRequestHook(cloudinaryAuthHook);
+  // Shared config — parsed once from CLOUDINARY_URL and env vars
+  const config = new CloudConfig();
 
-    const userAgentHook = new UserAgentHook();
-    hooks.registerSDKInitHook(userAgentHook);
+  hooks.registerBeforeRequestHook(new CloudinaryAuthHook(config));
+  hooks.registerBeforeRequestHook(new CustomHeadersHook());
+  hooks.registerSDKInitHook(new UserAgentHook());
+  hooks.registerAfterSuccessHook(new ResponseHeadersHook(config.collectHeaders));
 }

package/src/hooks/responseHeadersHook.ts

@@ -0,0 +1,98 @@
+import { CollectHeaders } from "./cloudConfig.js";
+import { AfterSuccessContext, AfterSuccessHook } from "./types.js";
+
+/**
+ * Checks whether a lowercased header name matches a single collect spec.
+ *
+ * Supported spec formats:
+ *   - `"prefix:<value>"`  → headerName.startsWith(value)
+ *   - `"regex:<pattern>"` → new RegExp(pattern).test(headerName)
+ *   - any other string    → exact match
+ *
+ * Both headerName and spec are expected to be lowercased already.
+ */
+function matchesSpec(headerName: string, spec: string): boolean {
+  if (spec.startsWith("prefix:")) {
+    return headerName.startsWith(spec.slice(7));
+  }
+  if (spec.startsWith("regex:")) {
+    try {
+      return new RegExp(spec.slice(6)).test(headerName);
+    } catch {
+      return false; // invalid regex — skip
+    }
+  }
+  return headerName === spec;
+}
+
+/**
+ * Captures response headers and injects them into the JSON body as `_headers`
+ * so they survive through the generated formatResult() and surface in MCP tool
+ * output. The set of headers to collect is driven by configuration:
+ *   - `true`      → collect every response header
+ *   - `string[]`  → collect only matching headers (exact name, prefix:, or regex:)
+ */
+export class ResponseHeadersHook implements AfterSuccessHook {
+  private readonly collectHeaders: CollectHeaders;
+
+  constructor(collectHeaders: CollectHeaders) {
+    this.collectHeaders = collectHeaders;
+  }
+
+  async afterSuccess(
+    hookCtx: AfterSuccessContext,
+    response: Response,
+  ): Promise<Response> {
+    // Per-request SDK options override the constructor config (used by mcp-service)
+    const optCollect = (hookCtx.options as any)?.collectHeaders as
+      | CollectHeaders
+      | undefined;
+    const effective = optCollect ?? this.collectHeaders;
+
+    // Not configured — exit early
+    if (effective !== true && effective.length === 0) {
+      return response;
+    }
+
+    const contentType = response.headers.get("content-type") ?? "";
+    if (!contentType.includes("json")) {
+      return response;
+    }
+
+    const hdrs: Record<string, string> = {};
+    let found = false;
+
+    if (effective === true) {
+      // Collect all response headers
+      for (const [name, value] of response.headers.entries()) {
+        hdrs[name] = value;
+        found = true;
+      }
+    } else {
+      // Match each response header against the specs (exact, prefix:, regex:)
+      for (const [name, value] of response.headers.entries()) {
+        for (const spec of effective) {
+          if (matchesSpec(name, spec)) {
+            hdrs[name] = value;
+            found = true;
+            break;
+          }
+        }
+      }
+    }
+
+    if (!found) {
+      return response;
+    }
+
+    // Read body, inject headers, return a new Response so the stream is fresh.
+    const body = await response.json();
+    body._headers = hdrs;
+
+    return new Response(JSON.stringify(body), {
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers,
+    });
+  }
+}

package/src/hooks/userAgentHook.ts

@@ -45,16 +45,28 @@ function getEnvDetails(): string {
     return isRemoteMCP() ? '; RemoteMCP' : '';
 }
 
-function buildUserAgent(sdkVersion: string, genVersion: string, openapiDocVersion: string, packageName: string, runtime: string): string {
+function buildUserAgent(
+    sdkVersion: string,
+    genVersion: string,
+    openapiDocVersion: string,
+    packageName: string,
+    runtime: string,
+    callerUserAgent?: string,
+): string {
     const productName = getProductName(packageName);
     const systemInfo = getSystemInfo();
     const envDetails = getEnvDetails();
+    const origin = callerUserAgent ? `; origin ${callerUserAgent}` : '';
 
-    return `Cloudinary/${productName} ${runtime}/${sdkVersion} Gen/${genVersion} Schema/${openapiDocVersion} (${systemInfo}${envDetails})`;
+    return `Cloudinary/${productName} ${runtime}/${sdkVersion} Gen/${genVersion} Schema/${openapiDocVersion} (${systemInfo}${envDetails}${origin})`;
 }
 
 export class UserAgentHook implements SDKInitHook {
     sdkInit(opts: SDKOptions): SDKOptions {
+        // If opts.userAgent is pre-set (e.g. by mcp-service via getSDK),
+        // treat it as the caller's User-Agent to embed in the combined string.
+        const callerUserAgent = opts.userAgent || undefined;
+
         const originalUserAgent = SDK_METADATA.userAgent;
 
         if (originalUserAgent && originalUserAgent.startsWith("speakeasy-sdk/")) {
@@ -69,7 +81,10 @@ export class UserAgentHook implements SDKInitHook {
                 // Ensure all parts are defined before proceeding
                 if (sdkVersion && genVersion && openapiDocVersion && packageName) {
                     const runtime = getRuntime();
-                    opts.userAgent = buildUserAgent(sdkVersion, genVersion, openapiDocVersion, packageName, runtime);
+                    opts.userAgent = buildUserAgent(
+                        sdkVersion, genVersion, openapiDocVersion,
+                        packageName, runtime, callerUserAgent,
+                    );
                 }
             }
         }