@cloudinary/asset-management-mcp 0.6.2 → 0.7.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
@@ -105,8 +112,8 @@ export function serverURLFromOptions(options: SDKOptions): URL | null {
 export const SDK_METADATA = {
   language: "typescript",
   openapiDocVersion: "0.3.5",
-  sdkVersion: "0.6.2",
-  genVersion: "2.760.2",
+  sdkVersion: "0.7.0",
+  genVersion: "2.824.1",
   userAgent:
-    "speakeasy-sdk/mcp-typescript 0.6.2 2.760.2 0.3.5 @cloudinary/asset-management-mcp",
+    "speakeasy-sdk/mcp-typescript 0.7.0 2.824.1 0.3.5 @cloudinary/asset-management-mcp",
 } as const;

package/src/lib/encodings.ts

@@ -102,8 +102,9 @@ export function encodeLabel(
       });
       encValue = mapped?.join("").slice(1);
     } else {
-      const k =
-        options?.explode && isPlainObject(value) ? `${encodeString(pk)}=` : "";
+      const k = options?.explode && isPlainObject(value)
+        ? `${encodeString(pk)}=`
+        : "";
       encValue = `${k}${encodeValue(pv)}`;
     }
 
@@ -365,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);
   }
 
@@ -374,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;
   }
@@ -440,7 +449,7 @@ type BulkQueryEncoder = (
 ) => string;
 
 export function queryEncoder(f: QueryEncoder): BulkQueryEncoder {
-  const bulkEncode = function (
+  const bulkEncode = function(
     values: Record<string, unknown>,
     options?: QueryEncoderOptions,
   ): string {

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

@@ -244,9 +244,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 +254,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/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(() => {

package/src/mcp-server/extensions.ts

@@ -2,16 +2,18 @@
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
  */
 
-import { ZodRawShape } from "zod";
-import { PromptArgsRawShape, PromptDefinition } from "./prompts.js";
+import { ZodRawShapeCompat } from "@modelcontextprotocol/sdk/server/zod-compat.js";
+import { 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;
+  tool: <A extends ZodRawShapeCompat | undefined>(
+    def: ToolDefinition<A>,
+  ) => void;
   resource: (def: ResourceDefinition) => void;
   resourceTemplate: (def: ResourceTemplateDefinition) => void;
-  prompt: <A extends PromptArgsRawShape | undefined>(
+  prompt: <A extends ZodRawShapeCompat | undefined>(
     prompt: PromptDefinition<A>,
   ) => void;
 };

package/src/mcp-server/flags.ts

@@ -0,0 +1,24 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { SDKOptions } from "../lib/config.js";
+import { MCPScope } from "./scopes.js";
+
+/**
+ * Base flags interface for MCP server configuration.
+ * Used by both CLI start command and Gram deployment wrapper.
+ */
+export interface MCPServerFlags {
+  readonly tool?: string[];
+  readonly mode?: "dynamic" | undefined;
+  readonly scope?: MCPScope[];
+  readonly "api-key"?: string | undefined;
+  readonly "api-secret"?: string | undefined;
+  readonly oauth2?: string | undefined;
+  readonly "cloud-name"?: SDKOptions["cloud_name"] | undefined;
+  readonly "server-url"?: string | undefined;
+  readonly "server-index"?: SDKOptions["serverIdx"];
+  readonly region?: SDKOptions["region"];
+  readonly "api-host"?: SDKOptions["host"];
+}

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

@@ -19,7 +19,7 @@ const routes = buildRouteMap({
 export const app = buildApplication(routes, {
   name: "mcp",
   versionInfo: {
-    currentVersion: "0.6.2",
+    currentVersion: "0.7.0",
   },
 });
 

package/src/mcp-server/prompts.ts

@@ -3,40 +3,30 @@
  */
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  ShapeOutput,
+  ZodRawShapeCompat,
+} from "@modelcontextprotocol/sdk/server/zod-compat.js";
 import { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
 import {
   GetPromptResult,
   ServerNotification,
   ServerRequest,
 } from "@modelcontextprotocol/sdk/types.js";
-import {
-  objectOutputType,
-  ZodOptional,
-  ZodType,
-  ZodTypeAny,
-  ZodTypeDef,
-} from "zod";
 import { CloudinaryAssetMgmtCore } from "../core.js";
 import { ConsoleLogger } from "./console-logger.js";
 import { MCPScope } from "./scopes.js";
 
-// '@modelcontextprotocol/sdk' currently does not export this type
-export type PromptArgsRawShape = {
-  [k: string]:
-    | ZodType<string, ZodTypeDef, string>
-    | ZodOptional<ZodType<string, ZodTypeDef, string>>;
-};
-
 export type PromptDefinition<
-  Args extends undefined | PromptArgsRawShape = undefined,
-> = Args extends PromptArgsRawShape ? {
+  Args extends undefined | ZodRawShapeCompat = undefined,
+> = Args extends ZodRawShapeCompat ? {
     name: string;
     description?: string;
     scopes?: MCPScope[];
     args: Args;
     prompt: (
       client: CloudinaryAssetMgmtCore,
-      args: objectOutputType<Args, ZodTypeAny>,
+      args: ShapeOutput<Args>,
       extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
     ) => GetPromptResult | Promise<GetPromptResult>;
   }
@@ -71,10 +61,10 @@ export function createRegisterPrompt(
   server: McpServer,
   getSDK: () => CloudinaryAssetMgmtCore,
   allowedScopes: Set<MCPScope>,
-): <A extends PromptArgsRawShape | undefined>(
+): <A extends ZodRawShapeCompat | undefined>(
   prompt: PromptDefinition<A>,
 ) => void {
-  return <A extends PromptArgsRawShape | undefined>(
+  return <A extends ZodRawShapeCompat | undefined>(
     prompt: PromptDefinition<A>,
   ): void => {
     const scopes = prompt.scopes ?? [];

package/src/mcp-server/resources.ts

@@ -17,7 +17,7 @@ import {
 import { CloudinaryAssetMgmtCore } from "../core.js";
 import { ConsoleLogger } from "./console-logger.js";
 import { MCPScope } from "./scopes.js";
-import { isAsyncIterable, isBinaryData, valueToBase64 } from "./shared.js";
+import { valueToBase64 } from "./shared.js";
 
 export type ReadResourceCallback = (
   client: CloudinaryAssetMgmtCore,
@@ -50,61 +50,26 @@ export type ResourceTemplateDefinition = {
   read: ReadResourceTemplateCallback;
 };
 
-// Optional function to assist with formatting resource results
+// Optional function to assist with formatting tool results
 export async function formatResult(
-  value: unknown,
+  response: Response,
   uri: URL,
-  init: { mimeType?: string | undefined; response?: Response | undefined },
+  init?: { mimeType?: string | undefined },
 ): Promise<ReadResourceResult> {
-  if (typeof value === "undefined") {
-    return { contents: [] };
-  }
-
   let contents: ReadResourceResult["contents"] = [];
+  const mimeType = init?.mimeType ?? response.headers.get("content-type") ?? "";
 
-  const mimeType = init.mimeType ?? init.response?.headers.get("content-type")
-    ?? "";
-
-  if (mimeType.search(/\bjson\b/g) !== -1) {
-    contents = [{ uri: uri.toString(), mimeType, text: JSON.stringify(value) }];
-  } else if (
-    mimeType.startsWith("text/event-stream")
-    && isAsyncIterable(value)
-  ) {
-    contents = [
-      {
-        uri: uri.toString(),
-        mimeType: "application/json",
-        text: await stringifySSEToJSON(value),
-      },
-    ];
-  } else if (
-    (mimeType.startsWith("text/") || mimeType.startsWith("application/"))
-    && typeof value === "string"
-  ) {
-    contents = [{ uri: uri.toString(), mimeType, text: value }];
-  } else if (isBinaryData(value)) {
-    const blob = await valueToBase64(value);
+  if (mimeType.startsWith("image/") || mimeType.startsWith("audio/")) {
+    const blob = await valueToBase64(await response.arrayBuffer());
     contents = blob == null ? [] : [{ uri: uri.toString(), blob, mimeType }];
   } else {
-    throw new Error(`Unsupported content type: "${mimeType}"`);
+    const text = await response.text();
+    contents = [{ uri: uri.toString(), mimeType, text }];
   }
 
   return { contents };
 }
 
-async function stringifySSEToJSON(
-  value: AsyncIterable<unknown>,
-): Promise<string> {
-  const payloads = [];
-
-  for await (const chunk of value) {
-    payloads.push(chunk);
-  }
-
-  return JSON.stringify(payloads);
-}
-
 export function createRegisterResource(
   logger: ConsoleLogger,
   server: McpServer,