@cloudinary/asset-management-mcp 0.6.0

package/src/lib/security.ts

@@ -0,0 +1,271 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { Security } from "../models/security.js";
+import { env } from "./env.js";
+
+type OAuth2PasswordFlow = {
+  username: string;
+  password: string;
+  clientID?: string | undefined;
+  clientSecret?: string | undefined;
+  tokenURL: string;
+};
+
+export enum SecurityErrorCode {
+  Incomplete = "incomplete",
+  UnrecognisedSecurityType = "unrecognized_security_type",
+}
+
+export class SecurityError extends Error {
+  constructor(
+    public code: SecurityErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = "SecurityError";
+  }
+
+  static incomplete(): SecurityError {
+    return new SecurityError(
+      SecurityErrorCode.Incomplete,
+      "Security requirements not met in order to perform the operation",
+    );
+  }
+  static unrecognizedType(type: string): SecurityError {
+    return new SecurityError(
+      SecurityErrorCode.UnrecognisedSecurityType,
+      `Unrecognised security type: ${type}`,
+    );
+  }
+}
+
+export type SecurityState = {
+  basic: { username?: string | undefined; password?: string | undefined };
+  headers: Record<string, string>;
+  queryParams: Record<string, string>;
+  cookies: Record<string, string>;
+  oauth2: ({ type: "password" } & OAuth2PasswordFlow) | { type: "none" };
+};
+
+type SecurityInputBasic = {
+  type: "http:basic";
+  value:
+    | { username?: string | undefined; password?: string | undefined }
+    | null
+    | undefined;
+};
+
+type SecurityInputBearer = {
+  type: "http:bearer";
+  value: string | null | undefined;
+  fieldName: string;
+};
+
+type SecurityInputAPIKey = {
+  type: "apiKey:header" | "apiKey:query" | "apiKey:cookie";
+  value: string | null | undefined;
+  fieldName: string;
+};
+
+type SecurityInputOIDC = {
+  type: "openIdConnect";
+  value: string | null | undefined;
+  fieldName: string;
+};
+
+type SecurityInputOAuth2 = {
+  type: "oauth2";
+  value: string | null | undefined;
+  fieldName: string;
+};
+
+type SecurityInputOAuth2ClientCredentials = {
+  type: "oauth2:client_credentials";
+  value:
+    | { clientID?: string | undefined; clientSecret?: string | undefined }
+    | null
+    | string
+    | undefined;
+  fieldName?: string;
+};
+
+type SecurityInputOAuth2PasswordCredentials = {
+  type: "oauth2:password";
+  value:
+    | string
+    | null
+    | undefined;
+  fieldName?: string;
+};
+
+type SecurityInputCustom = {
+  type: "http:custom";
+  value: any | null | undefined;
+  fieldName?: string;
+};
+
+export type SecurityInput =
+  | SecurityInputBasic
+  | SecurityInputBearer
+  | SecurityInputAPIKey
+  | SecurityInputOAuth2
+  | SecurityInputOAuth2ClientCredentials
+  | SecurityInputOAuth2PasswordCredentials
+  | SecurityInputOIDC
+  | SecurityInputCustom;
+
+export function resolveSecurity(
+  ...options: SecurityInput[][]
+): SecurityState | null {
+  const state: SecurityState = {
+    basic: {},
+    headers: {},
+    queryParams: {},
+    cookies: {},
+    oauth2: { type: "none" },
+  };
+
+  const option = options.find((opts) => {
+    return opts.every((o) => {
+      if (o.value == null) {
+        return false;
+      } else if (o.type === "http:basic") {
+        return o.value.username != null || o.value.password != null;
+      } else if (o.type === "http:custom") {
+        return null;
+      } else if (o.type === "oauth2:password") {
+        return (
+          typeof o.value === "string" && !!o.value
+        );
+      } else if (o.type === "oauth2:client_credentials") {
+        if (typeof o.value == "string") {
+          return !!o.value;
+        }
+        return o.value.clientID != null || o.value.clientSecret != null;
+      } else if (typeof o.value === "string") {
+        return !!o.value;
+      } else {
+        throw new Error(
+          `Unrecognized security type: ${o.type} (value type: ${typeof o
+            .value})`,
+        );
+      }
+    });
+  });
+  if (option == null) {
+    return null;
+  }
+
+  option.forEach((spec) => {
+    if (spec.value == null) {
+      return;
+    }
+
+    const { type } = spec;
+
+    switch (type) {
+      case "apiKey:header":
+        state.headers[spec.fieldName] = spec.value;
+        break;
+      case "apiKey:query":
+        state.queryParams[spec.fieldName] = spec.value;
+        break;
+      case "apiKey:cookie":
+        state.cookies[spec.fieldName] = spec.value;
+        break;
+      case "http:basic":
+        applyBasic(state, spec);
+        break;
+      case "http:custom":
+        break;
+      case "http:bearer":
+        applyBearer(state, spec);
+        break;
+      case "oauth2":
+        applyBearer(state, spec);
+        break;
+      case "oauth2:password":
+        applyBearer(state, spec);
+        break;
+      case "oauth2:client_credentials":
+        break;
+      case "openIdConnect":
+        applyBearer(state, spec);
+        break;
+      default:
+        spec satisfies never;
+        throw SecurityError.unrecognizedType(type);
+    }
+  });
+
+  return state;
+}
+
+function applyBasic(
+  state: SecurityState,
+  spec: SecurityInputBasic,
+) {
+  if (spec.value == null) {
+    return;
+  }
+
+  state.basic = spec.value;
+}
+
+function applyBearer(
+  state: SecurityState,
+  spec:
+    | SecurityInputBearer
+    | SecurityInputOAuth2
+    | SecurityInputOIDC
+    | SecurityInputOAuth2PasswordCredentials,
+) {
+  if (typeof spec.value !== "string" || !spec.value) {
+    return;
+  }
+
+  let value = spec.value;
+  if (value.slice(0, 7).toLowerCase() !== "bearer ") {
+    value = `Bearer ${value}`;
+  }
+
+  if (spec.fieldName !== undefined) {
+    state.headers[spec.fieldName] = value;
+  }
+}
+export function resolveGlobalSecurity(
+  security: Partial<Security> | null | undefined,
+): SecurityState | null {
+  return resolveSecurity(
+    [
+      {
+        type: "http:custom",
+        value: {
+          api_key: security?.cloudinaryAuth?.api_key
+            ?? env().CLOUDINARY_API_KEY,
+          api_secret: security?.cloudinaryAuth?.api_secret
+            ?? env().CLOUDINARY_API_SECRET,
+        },
+      },
+    ],
+    [
+      {
+        fieldName: "Authorization",
+        type: "oauth2",
+        value: security?.oauth2 ?? env().CLOUDINARY_OAUTH2,
+      },
+    ],
+  );
+}
+
+export async function extractSecurity<
+  T extends string | Record<string, unknown>,
+>(sec: T | (() => Promise<T>) | undefined): Promise<T | undefined> {
+  if (sec == null) {
+    return;
+  }
+
+  return typeof sec === "function" ? sec() : sec;
+}

package/src/lib/url.ts

@@ -0,0 +1,33 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+const hasOwn = Object.prototype.hasOwnProperty;
+
+export type Params = Partial<Record<string, string | number>>;
+
+export function pathToFunc(
+  pathPattern: string,
+  options?: { charEncoding?: "percent" | "none" },
+): (params?: Params) => string {
+  const paramRE = /\{([a-zA-Z0-9_]+?)\}/g;
+
+  return function buildURLPath(params: Record<string, unknown> = {}): string {
+    return pathPattern.replace(paramRE, function (_, placeholder) {
+      if (!hasOwn.call(params, placeholder)) {
+        throw new Error(`Parameter '${placeholder}' is required`);
+      }
+
+      const value = params[placeholder];
+      if (typeof value !== "string" && typeof value !== "number") {
+        throw new Error(
+          `Parameter '${placeholder}' must be a string or number`,
+        );
+      }
+
+      return options?.charEncoding === "percent"
+        ? encodeURIComponent(`${value}`)
+        : `${value}`;
+    });
+  };
+}

package/src/mcp-server/cli/start/command.ts

@@ -0,0 +1,140 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { buildCommand } from "@stricli/core";
+import { numberParser } from "@stricli/core";
+import * as z from "zod";
+import { ServerRegion } from "../../../lib/config.js";
+import { consoleLoggerLevels } from "../../console-logger.js";
+import { mcpScopes } from "../../scopes.js";
+
+export const startCommand = buildCommand({
+  loader: async () => {
+    const { main } = await import("./impl.js");
+    return main;
+  },
+  parameters: {
+    flags: {
+      transport: {
+        kind: "enum",
+        brief: "The transport to use for communicating with the server",
+        default: "stdio",
+        values: ["stdio", "sse"],
+      },
+      port: {
+        kind: "parsed",
+        brief: "The port to use when the SSE transport is enabled",
+        default: "2718",
+        parse: (val: string) =>
+          z.coerce.number().int().gte(0).lt(65536).parse(val),
+      },
+      tool: {
+        kind: "parsed",
+        brief: "Specify tools to mount on the server",
+        optional: true,
+        variadic: true,
+        parse: (value) => {
+          return z.string().parse(value);
+        },
+      },
+      scope: {
+        kind: "enum",
+        brief: "Mount tools/resources that match given scope (repeatable flag)",
+        values: mcpScopes,
+        variadic: true,
+        optional: true,
+      },
+      "api-key": {
+        kind: "parsed",
+        brief: "Sets the api_key auth field for the API",
+        optional: true,
+        parse: (value) => {
+          return z.string().parse(value);
+        },
+      },
+      "api-secret": {
+        kind: "parsed",
+        brief: "Sets the api_secret auth field for the API",
+        optional: true,
+        parse: (value) => {
+          return z.string().parse(value);
+        },
+      },
+      oauth2: {
+        kind: "parsed",
+        brief: "Sets the oauth2 auth field for the API",
+        optional: true,
+        parse: (value) => {
+          return z.string().parse(value);
+        },
+      },
+      "cloud-name": {
+        kind: "parsed",
+        brief:
+          "Allows setting the cloud_name parameter for all supported operations",
+        optional: true,
+        parse: (value) => {
+          return z.string().parse(value);
+        },
+      },
+      "server-url": {
+        kind: "parsed",
+        brief: "Overrides the default server URL used by the SDK",
+        optional: true,
+        parse: (value) => new URL(value).toString(),
+      },
+      "server-index": {
+        kind: "parsed",
+        brief: "Selects a predefined server used by the SDK",
+        optional: true,
+        parse: numberParser,
+      },
+      region: {
+        kind: "enum",
+        brief: "Sets the region variable for url substitution",
+        optional: true,
+        values: Object.values(ServerRegion) as Array<ServerRegion>,
+      },
+      "api-host": {
+        kind: "parsed",
+        brief: "Sets the host variable for url substitution",
+        optional: true,
+        parse: (value) => value,
+      },
+      "log-level": {
+        kind: "enum",
+        brief: "The log level to use for the server",
+        default: "info",
+        values: consoleLoggerLevels,
+      },
+      env: {
+        kind: "parsed",
+        brief: "Environment variables made available to the server",
+        optional: true,
+        variadic: true,
+        parse: (val: string) => {
+          const sepIdx = val.indexOf("=");
+          if (sepIdx === -1) {
+            throw new Error("Invalid environment variable format");
+          }
+
+          const key = val.slice(0, sepIdx);
+          const value = val.slice(sepIdx + 1);
+
+          return [
+            z.string().nonempty({
+              message: "Environment variable key must be a non-empty string",
+            }).parse(key),
+            z.string().nonempty({
+              message: "Environment variable value must be a non-empty string",
+            }).parse(value),
+          ] satisfies [string, string];
+        },
+      },
+    },
+  },
+  docs: {
+    brief: "Run the Model Context Protocol server",
+  },
+});

package/src/mcp-server/cli/start/impl.ts

@@ -0,0 +1,161 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import express from "express";
+import { SDKOptions } from "../../../lib/config.js";
+import { LocalContext } from "../../cli.js";
+import {
+  ConsoleLoggerLevel,
+  createConsoleLogger,
+} from "../../console-logger.js";
+import { MCPScope } from "../../scopes.js";
+import { createMCPServer } from "../../server.js";
+
+interface StartCommandFlags {
+  readonly transport: "stdio" | "sse";
+  readonly port: number;
+  readonly tool?: string[];
+  readonly scope?: MCPScope[];
+  readonly "api-key"?: string;
+  readonly "api-secret"?: string;
+  readonly oauth2?: string;
+  readonly "cloud-name"?: SDKOptions["cloud_name"] | undefined;
+  readonly "server-url"?: string;
+  readonly "server-index"?: SDKOptions["serverIdx"];
+  readonly region?: SDKOptions["region"];
+  readonly "api-host"?: SDKOptions["host"];
+  readonly "log-level": ConsoleLoggerLevel;
+  readonly env?: [string, string][];
+}
+
+export async function main(this: LocalContext, flags: StartCommandFlags) {
+  flags.env?.forEach(([key, value]) => {
+    process.env[key] = value;
+  });
+
+  switch (flags.transport) {
+    case "stdio":
+      await startStdio(flags);
+      break;
+    case "sse":
+      await startSSE(flags);
+      break;
+    default:
+      throw new Error(`Invalid transport: ${flags.transport}`);
+  }
+}
+
+async function startStdio(flags: StartCommandFlags) {
+  const logger = createConsoleLogger(flags["log-level"]);
+  const transport = new StdioServerTransport();
+  const server = createMCPServer({
+    logger,
+    allowedTools: flags.tool,
+    scopes: flags.scope,
+    security: {
+      cloudinaryAuth: flags["api-key"] != null && flags["api-secret"] != null
+        ? {
+          api_key: flags["api-key"] ?? "",
+          api_secret: flags["api-secret"] ?? "",
+        }
+        : void 0,
+      oauth2: flags.oauth2 ?? "",
+    },
+    cloud_name: flags["cloud-name"],
+    serverURL: flags["server-url"],
+    serverIdx: flags["server-index"],
+    region: flags.region,
+    host: flags["api-host"],
+  });
+  await server.connect(transport);
+
+  const abort = async () => {
+    await server.close();
+    process.exit(0);
+  };
+  process.on("SIGTERM", abort);
+  process.on("SIGINT", abort);
+}
+
+async function startSSE(flags: StartCommandFlags) {
+  const logger = createConsoleLogger(flags["log-level"]);
+  const app = express();
+  const mcpServer = createMCPServer({
+    logger,
+    allowedTools: flags.tool,
+    scopes: flags.scope,
+    security: {
+      cloudinaryAuth: flags["api-key"] != null && flags["api-secret"] != null
+        ? {
+          api_key: flags["api-key"] ?? "",
+          api_secret: flags["api-secret"] ?? "",
+        }
+        : void 0,
+      oauth2: flags.oauth2 ?? "",
+    },
+    cloud_name: flags["cloud-name"],
+    serverURL: flags["server-url"],
+    serverIdx: flags["server-index"],
+    region: flags.region,
+    host: flags["api-host"],
+  });
+  let transport: SSEServerTransport | undefined;
+  const controller = new AbortController();
+
+  app.get("/sse", async (_req, res) => {
+    transport = new SSEServerTransport("/message", res);
+
+    await mcpServer.connect(transport);
+
+    mcpServer.server.onclose = async () => {
+      res.end();
+    };
+  });
+
+  app.post("/message", async (req, res) => {
+    if (!transport) {
+      throw new Error("Server transport not initialized");
+    }
+
+    await transport.handlePostMessage(req, res);
+  });
+
+  const httpServer = app.listen(flags.port, "0.0.0.0", () => {
+    const ha = httpServer.address();
+    const host = typeof ha === "string" ? ha : `${ha?.address}:${ha?.port}`;
+    logger.info("MCP HTTP server started", { host });
+  });
+
+  let closing = false;
+  controller.signal.addEventListener("abort", async () => {
+    if (closing) {
+      logger.info("Received second signal. Forcing shutdown.");
+      process.exit(1);
+    }
+    closing = true;
+
+    logger.info("Shutting down MCP server");
+
+    await mcpServer.close();
+
+    logger.info("Shutting down HTTP server");
+
+    const timer = setTimeout(() => {
+      logger.info("Forcing shutdown");
+      process.exit(1);
+    }, 5000);
+
+    httpServer.close(() => {
+      clearTimeout(timer);
+      logger.info("Graceful shutdown complete");
+      process.exit(0);
+    });
+  });
+
+  const abort = () => controller.abort();
+  process.on("SIGTERM", abort);
+  process.on("SIGINT", abort);
+}

package/src/mcp-server/cli.ts

@@ -0,0 +1,13 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { CommandContext, StricliProcess } from "@stricli/core";
+
+export interface LocalContext extends CommandContext {
+  readonly process: StricliProcess;
+}
+
+export function buildContext(process: NodeJS.Process): LocalContext {
+  return { process: process as StricliProcess };
+}

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

@@ -0,0 +1,76 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+export const consoleLoggerLevels = [
+  "debug",
+  "warning",
+  "info",
+  "error",
+] as const;
+
+export type ConsoleLoggerLevel = (typeof consoleLoggerLevels)[number];
+
+export type ConsoleLogger =
+  & {
+    [key in ConsoleLoggerLevel]: (
+      message: string,
+      data?: Record<string, unknown>,
+    ) => void;
+  }
+  & {
+    level: ConsoleLoggerLevel;
+  };
+
+export function createConsoleLogger(level: ConsoleLoggerLevel): ConsoleLogger {
+  const min = consoleLoggerLevels.indexOf(level);
+  const noop = () => {};
+
+  const logger: ConsoleLogger = {
+    debug: noop,
+    warning: noop,
+    info: noop,
+    error: noop,
+    level,
+  };
+
+  return consoleLoggerLevels.reduce((logger, level, i) => {
+    if (i < min) {
+      return logger;
+    }
+
+    logger[level] = log.bind(null, level);
+
+    return logger;
+  }, logger);
+}
+
+function log(
+  level: ConsoleLoggerLevel,
+  message: string,
+  data?: Record<string, unknown>,
+) {
+  let line = "";
+  const allData = [{ msg: message, l: level }, data];
+
+  for (const ctx of allData) {
+    for (const [key, value] of Object.entries(ctx || {})) {
+      if (value == null) {
+        line += ` ${key}=<${value}>`;
+      } else if (typeof value === "function") {
+        line += ` ${key}=<function>`;
+      } else if (typeof value === "symbol") {
+        line += ` ${key}=${value.toString()}`;
+      } else if (typeof value === "string") {
+        const v = value.search(/\s/g) >= 0 ? JSON.stringify(value) : value;
+        line += ` ${key}=${v}`;
+      } else if (typeof value !== "object") {
+        line += ` ${key}=${value}`;
+      } else {
+        line += ` ${key}="${JSON.stringify(value)}"`;
+      }
+    }
+  }
+
+  console.error(line);
+}

package/src/mcp-server/extensions.ts

@@ -0,0 +1,17 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { ZodRawShape } from "zod";
+import { PromptArgsRawShape, PromptDefinition } from "./prompts.js";
+import { ResourceDefinition, ResourceTemplateDefinition } from "./resources.js";
+import { ToolDefinition } from "./tools.js";
+
+export type Register = {
+  tool: <A extends ZodRawShape | undefined>(def: ToolDefinition<A>) => void;
+  resource: (def: ResourceDefinition) => void;
+  resourceTemplate: (def: ResourceTemplateDefinition) => void;
+  prompt: <A extends PromptArgsRawShape | undefined>(
+    prompt: PromptDefinition<A>,
+  ) => void;
+};