@cloudinary/environment-config-mcp 0.5.0 → 0.6.0

package/src/lib/base64.ts

@@ -29,9 +29,9 @@ export function stringFromBase64(b64str: string): string {
 }
 
 export const zodOutbound = z
-  .instanceof(Uint8Array)
+  .custom<Uint8Array>((x) => x instanceof Uint8Array)
   .or(z.string().transform(stringToBytes));
 
 export const zodInbound = z
-  .instanceof(Uint8Array)
+  .custom<Uint8Array>((x) => x instanceof Uint8Array)
   .or(z.string().transform(bytesFromBase64));

package/src/lib/config.ts

@@ -2,6 +2,7 @@
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
  */
 
+import * as z from "zod";
 import { Security } from "../models/security.js";
 import { ClosedEnum } from "../types/enums.js";
 import { HTTPClient } from "./http.js";
@@ -36,6 +37,12 @@ export const ServerRegion = {
  */
 export type ServerRegion = ClosedEnum<typeof ServerRegion>;
 
+export const ServerRegion$zodSchema = z.enum([
+  "api",
+  "api-eu",
+  "api-ap",
+]).describe("Regional endpoint selection");
+
 export type SDKOptions = {
   /**
    * The security details required to authenticate the SDK
@@ -104,9 +111,9 @@ export function serverURLFromOptions(options: SDKOptions): URL | null {
 
 export const SDK_METADATA = {
   language: "typescript",
-  openapiDocVersion: "0.3.6",
-  sdkVersion: "0.5.0",
-  genVersion: "2.767.2",
+  openapiDocVersion: "0.4.0",
+  sdkVersion: "0.6.0",
+  genVersion: "2.865.2",
   userAgent:
-    "speakeasy-sdk/mcp-typescript 0.5.0 2.767.2 0.3.6 @cloudinary/environment-config-mcp",
+    "speakeasy-sdk/mcp-typescript 0.6.0 2.865.2 0.4.0 @cloudinary/environment-config-mcp",
 } as const;

package/src/lib/encodings.ts

@@ -366,6 +366,12 @@ function serializeValue(value: unknown): string {
   } else if (value instanceof Uint8Array) {
     return bytesToBase64(value);
   } else if (typeof value === "object") {
+    if (
+      "toJSON" in value
+      && typeof value.toJSON === "function"
+    ) {
+      return String(value.toJSON());
+    }
     return JSON.stringify(value, jsonReplacer);
   }
 
@@ -375,6 +381,8 @@ function serializeValue(value: unknown): string {
 function jsonReplacer(_: string, value: unknown): unknown {
   if (value instanceof Uint8Array) {
     return bytesToBase64(value);
+  } else if (typeof value === "bigint") {
+    return value.toString();
   } else {
     return value;
   }

package/src/lib/env.ts

@@ -20,7 +20,7 @@ export interface Env {
   CLOUDINARY_DEBUG?: boolean | undefined;
 }
 
-export const envSchema: z.ZodType<Env, z.ZodTypeDef, unknown> = z.object({
+export const envSchema: z.ZodType<Env> = z.object({
   CLOUDINARY_API_KEY: z.string().optional(),
   CLOUDINARY_API_SECRET: z.string().optional(),
   CLOUDINARY_OAUTH2: z.string().optional(),

package/src/lib/schemas.ts

@@ -2,34 +2,22 @@
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
  */
 
-import {
-  output,
-  ZodEffects,
-  ZodError,
-  ZodObject,
-  ZodRawShape,
-  ZodTypeAny,
-} from "zod";
+import * as z from "zod";
 import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
 import { ERR, OK, Result } from "../types/fp.js";
 
 export function collectExtraKeys<
-  Shape extends ZodRawShape,
-  Catchall extends ZodTypeAny,
+  Shape extends z.ZodRawShape,
+  Catchall extends z.ZodType,
   K extends string,
+  Optional extends boolean,
 >(
-  obj: ZodObject<Shape, "strip", Catchall>,
+  obj: z.ZodObject<Shape, z.core.$catchall<Catchall>>,
   extrasKey: K,
-  optional: boolean,
-): ZodEffects<
-  typeof obj,
-  & output<ZodObject<Shape, "strict">>
-  & {
-    [k in K]: Record<string, output<Catchall>>;
-  }
-> {
-  return obj.transform((val) => {
-    const extras: Record<string, output<Catchall>> = {};
+  optional: Optional,
+) {
+  return obj.transform((val: any) => {
+    const extras: Record<string, z.output<Catchall>> = {};
     const { shape } = obj;
     for (const [key] of Object.entries(val)) {
       if (key in shape) {
@@ -66,7 +54,7 @@ export function parse<Inp, Out>(
   try {
     return fn(rawValue);
   } catch (err) {
-    if (err instanceof ZodError) {
+    if (err instanceof z.ZodError) {
       throw new SDKValidationError(errorMessage, err, rawValue);
     }
     throw err;

package/src/lib/sdks.ts

@@ -310,9 +310,9 @@ export class ClientSDK {
   }
 }
 
-const jsonLikeContentTypeRE = /(application|text)\/.*?\+*json.*/;
+const jsonLikeContentTypeRE = /^(application|text)\/([^+]+\+)*json.*/;
 const jsonlLikeContentTypeRE =
-  /(application|text)\/(.*?\+*\bjsonl\b.*|.*?\+*\bx-ndjson\b.*)/;
+  /^(application|text)\/([^+]+\+)*(jsonl|x-ndjson)\b.*/;
 async function logRequest(logger: Logger | undefined, req: Request) {
   if (!logger) {
     return;

package/src/lib/security.ts

@@ -84,7 +84,10 @@ type SecurityInputOAuth2 = {
 type SecurityInputOAuth2ClientCredentials = {
   type: "oauth2:client_credentials";
   value:
-    | { clientID?: string | undefined; clientSecret?: string | undefined }
+    | {
+      clientID?: string | undefined;
+      clientSecret?: string | undefined;
+    }
     | null
     | string
     | undefined;
@@ -244,9 +247,9 @@ export function resolveGlobalSecurity(
         type: "http:custom",
         value: {
           api_key: security?.cloudinaryAuth?.api_key
-            ?? env().CLOUDINARY_API_KEY,
+            || env().CLOUDINARY_API_KEY,
           api_secret: security?.cloudinaryAuth?.api_secret
-            ?? env().CLOUDINARY_API_SECRET,
+            || env().CLOUDINARY_API_SECRET,
         },
       },
     ],
@@ -254,7 +257,7 @@ export function resolveGlobalSecurity(
       {
         fieldName: "Authorization",
         type: "oauth2",
-        value: security?.oauth2 ?? env().CLOUDINARY_OAUTH2,
+        value: security?.oauth2 || env().CLOUDINARY_OAUTH2,
       },
     ],
   );

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

@@ -0,0 +1,147 @@
+/*
+ * 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 serveCommand = buildCommand({
+  loader: async () => {
+    const { main } = await import("./impl.js");
+    return main;
+  },
+  parameters: {
+    flags: {
+      port: {
+        kind: "parsed",
+        brief: "The port to listen on for Streamable HTTP connections",
+        default: "2718",
+        parse: (val: string) =>
+          z.coerce.number().int().gte(0).lt(65536).parse(val),
+      },
+      "disable-static-auth": {
+        kind: "boolean",
+        brief:
+          "Disable static authentication, allowing credentials to be passed via request headers only",
+        default: false,
+      },
+      tool: {
+        kind: "parsed",
+        brief: "Specify tools to mount on the server",
+        optional: true,
+        variadic: true,
+        parse: (value) => {
+          return z.string().parse(value);
+        },
+      },
+      mode: {
+        kind: "enum",
+        brief:
+          "Server mode (dynamic: expose list_tools, describe_tool, and execute_tool instead of individual tools)",
+        values: ["dynamic"],
+        optional: true,
+      },
+      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 MCP server with Streamable HTTP transport",
+  },
+});

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

@@ -0,0 +1,114 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import express from "express";
+import { LocalContext } from "../../cli.js";
+import {
+  ConsoleLoggerLevel,
+  createConsoleLogger,
+} from "../../console-logger.js";
+import { MCPServerFlags } from "../../flags.js";
+import { createMCPServer } from "../../server.js";
+import { buildSDK } from "../../tools.js";
+
+import { landingPageExpress } from "../../../landing-page.js";
+
+interface ServeCommandFlags extends MCPServerFlags {
+  readonly port: number;
+  readonly "disable-static-auth": boolean;
+  readonly "log-level": ConsoleLoggerLevel;
+  readonly env?: [string, string][];
+}
+
+export async function main(this: LocalContext, flags: ServeCommandFlags) {
+  flags.env?.forEach(([key, value]) => {
+    process.env[key] = value;
+  });
+
+  await startStreamableHTTP(flags);
+}
+
+async function startStreamableHTTP(cliFlags: ServeCommandFlags) {
+  const logger = createConsoleLogger(cliFlags["log-level"]);
+  const app = express();
+
+  // Enable CORS for cross-origin requests
+  app.use((req, res, next) => {
+    res.header("Access-Control-Allow-Origin", "*");
+    res.header("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+    res.header("Access-Control-Allow-Headers", "Content-Type, *");
+    if (req.method === "OPTIONS") {
+      res.sendStatus(204);
+      return;
+    }
+    next();
+  });
+
+  app.use(express.json());
+
+  app.post("/mcp", async (req, res) => {
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(req.headers)) {
+      if (Array.isArray(value)) {
+        for (const v of value) headers.append(key, v);
+      } else if (value !== undefined) {
+        headers.set(key, value);
+      }
+    }
+
+    const transport = new StreamableHTTPServerTransport({});
+
+    const { server: mcpServer } = createMCPServer({
+      logger,
+      allowedTools: cliFlags.tool,
+      dynamic: cliFlags.mode === "dynamic",
+      scopes: cliFlags.scope,
+      serverURL: cliFlags["server-url"],
+      getSDK: () =>
+        buildSDK(headers, cliFlags, cliFlags["disable-static-auth"], logger),
+      cloud_name: cliFlags["cloud-name"],
+      serverIdx: cliFlags["server-index"],
+      region: cliFlags.region,
+      host: cliFlags["api-host"],
+    });
+
+    mcpServer.server.onerror = (error) => {
+      logger.error("MCP protocol error", {
+        error: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+      });
+    };
+
+    await mcpServer.connect(transport as Transport);
+    await transport.handleRequest(req, res, req.body);
+  });
+
+  app.get("/", landingPageExpress);
+
+  const httpServer = app.listen(cliFlags.port, "0.0.0.0", () => {
+    const ha = httpServer.address();
+    const host = typeof ha === "string" ? ha : `${ha?.address}:${ha?.port}`;
+    logger.info("MCP Streamable HTTP server started", { host });
+  });
+
+  const shutdown = () => {
+    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);
+    });
+  };
+
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
+}

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

@@ -38,6 +38,13 @@ export const startCommand = buildCommand({
           return z.string().parse(value);
         },
       },
+      mode: {
+        kind: "enum",
+        brief:
+          "Server mode (dynamic: expose list_tools, describe_tool, and execute_tool instead of individual tools)",
+        values: ["dynamic"],
+        optional: true,
+      },
       scope: {
         kind: "enum",
         brief: "Mount tools/resources that match given scope (repeatable flag)",

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

@@ -5,32 +5,29 @@
 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 { MCPServerFlags } from "../../flags.js";
 import { createMCPServer } from "../../server.js";
 
-interface StartCommandFlags {
+import { landingPageExpress } from "../../../landing-page.js";
+
+interface StartCommandFlags extends MCPServerFlags {
   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][];
 }
 
+interface Session {
+  mcpServer: ReturnType<typeof createMCPServer>["server"];
+  transport: SSEServerTransport;
+  cleanup: () => Promise<void>;
+}
+
 export async function main(this: LocalContext, flags: StartCommandFlags) {
   flags.env?.forEach(([key, value]) => {
     process.env[key] = value;
@@ -51,9 +48,10 @@ export async function main(this: LocalContext, flags: StartCommandFlags) {
 async function startStdio(flags: StartCommandFlags) {
   const logger = createConsoleLogger(flags["log-level"]);
   const transport = new StdioServerTransport();
-  const server = createMCPServer({
+  const { server } = createMCPServer({
     logger,
     allowedTools: flags.tool,
+    dynamic: flags.mode === "dynamic",
     scopes: flags.scope,
     security: {
       cloudinaryAuth: flags["api-key"] != null && flags["api-secret"] != null
@@ -80,50 +78,122 @@ async function startStdio(flags: StartCommandFlags) {
   process.on("SIGINT", abort);
 }
 
-async function startSSE(flags: StartCommandFlags) {
-  const logger = createConsoleLogger(flags["log-level"]);
+async function startSSE(cliFlags: StartCommandFlags) {
+  const logger = createConsoleLogger(cliFlags["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 sessions = new Map<string, Session>();
   const controller = new AbortController();
 
-  app.get("/sse", async (_req, res) => {
-    transport = new SSEServerTransport("/message", res);
+  app.get("/sse", async (req, res) => {
+    const sessionId = crypto.randomUUID();
+
+    logger.info("SSE connection initiated", {
+      sessionId,
+      userAgent: req.headers["user-agent"],
+    });
+
+    // Track early disconnection
+    let connectionClosed = false;
+    res.on("close", () => {
+      if (!connectionClosed) {
+        logger.info("Connection closed early", { sessionId });
+      }
+      connectionClosed = true;
+    });
+
+    // Merge CLI flags with header overrides for security credentials
+    const flags: StartCommandFlags = {
+      ...cliFlags,
+      // Security fields can be overridden via headers
+      "api-key": (req.headers["api_key"] as string) ?? cliFlags["api-key"],
+      "api-secret": (req.headers["api_secret"] as string)
+        ?? cliFlags["api-secret"],
+      "oauth2": (req.headers["oauth2"] as string) ?? cliFlags["oauth2"],
+    };
+
+    // Create a new MCP server for this connection with its auth
+    const { server: mcpServer } = createMCPServer({
+      logger,
+      allowedTools: flags.tool,
+      dynamic: flags.mode === "dynamic",
+      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"],
+    });
+
+    // Message path includes session ID for routing
+    const transport = new SSEServerTransport(`/message/${sessionId}`, res);
+
+    const cleanup = async () => {
+      await mcpServer.close();
+    };
+
+    sessions.set(sessionId, { mcpServer, transport, cleanup });
+    logger.info("Session created", { sessionId, totalSessions: sessions.size });
+    controller.signal.addEventListener("abort", cleanup);
+
+    // Log server-side errors for debugging (e.g. tools/list handler failures)
+    mcpServer.server.onerror = (error) => {
+      logger.error("MCP protocol error", {
+        sessionId,
+        error: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+      });
+    };
+
+    // Wrap transport.send to log error responses for debugging
+    const originalSend = transport.send.bind(transport);
+    transport.send = async (message) => {
+      if ("error" in message && message.error) {
+        logger.error("MCP sending error response", {
+          sessionId,
+          id: message.id,
+          errorCode: message.error.code,
+          errorMessage: message.error.message,
+        });
+      }
+      return originalSend(message);
+    };
 
     await mcpServer.connect(transport);
 
     mcpServer.server.onclose = async () => {
+      connectionClosed = true;
+      controller.signal.removeEventListener("abort", cleanup);
+      sessions.delete(sessionId);
+      logger.info("Session closed", {
+        sessionId,
+        totalSessions: sessions.size,
+      });
       res.end();
     };
   });
 
-  app.post("/message", async (req, res) => {
-    if (!transport) {
-      throw new Error("Server transport not initialized");
+  app.post("/message/:sessionId", async (req, res) => {
+    const session = sessions.get(req.params.sessionId);
+    if (!session) {
+      res.status(404).send("Session not found");
+      return;
     }
 
-    await transport.handlePostMessage(req, res);
+    await session.transport.handlePostMessage(req, res);
   });
 
-  const httpServer = app.listen(flags.port, "0.0.0.0", () => {
+  app.get("/", landingPageExpress);
+
+  const httpServer = app.listen(cliFlags.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 });
@@ -137,10 +207,6 @@ async function startSSE(flags: StartCommandFlags) {
     }
     closing = true;
 
-    logger.info("Shutting down MCP server");
-
-    await mcpServer.close();
-
     logger.info("Shutting down HTTP server");
 
     const timer = setTimeout(() => {