@cloudinary/environment-config-mcp 0.5.0 → 0.6.1

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

@@ -0,0 +1,117 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 03e83f226068
+ */
+
+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 { buildAnnotationFilter } from "../../tools.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", "*");
+    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",
+      annotationFilter: buildAnnotationFilter(cliFlags["tool-annotations"]),
+      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

@@ -1,5 +1,6 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: b3e53408ccb4
  */
 
 import { buildCommand } from "@stricli/core";
@@ -38,6 +39,20 @@ export const startCommand = buildCommand({
           return z.string().parse(value);
         },
       },
+      mode: {
+        kind: "enum",
+        brief:
+          "Server mode (dynamic: expose list_tools, describe_tool_input, and execute_tool instead of individual tools)",
+        values: ["dynamic"],
+        optional: true,
+      },
+      "tool-annotations": {
+        kind: "parsed",
+        brief:
+          "Filter tools by annotations (comma-separated: readOnly, destructive, idempotent, openWorld). Listed = required true, unlisted = required false.",
+        optional: true,
+        parse: (value) => value.split(",").map(s => s.trim()),
+      },
       scope: {
         kind: "enum",
         brief: "Mount tools/resources that match given scope (repeatable flag)",

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

@@ -1,36 +1,35 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 37494f674015
  */
 
 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";
+import { buildAnnotationFilter } from "../../tools.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 +50,11 @@ 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",
+    annotationFilter: buildAnnotationFilter(flags["tool-annotations"]),
     scopes: flags.scope,
     security: {
       cloudinaryAuth: flags["api-key"] != null && flags["api-secret"] != null
@@ -80,50 +81,123 @@ 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",
+      annotationFilter: buildAnnotationFilter(flags["tool-annotations"]),
+      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 +211,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/cli.ts

@@ -1,5 +1,6 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 4ade0ef98b00
  */
 
 import { CommandContext, StricliProcess } from "@stricli/core";

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

@@ -1,5 +1,6 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 57aff4ff2e15
  */
 
 export const consoleLoggerLevels = [

package/src/mcp-server/extensions.ts

@@ -1,17 +1,20 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 3d9d20ff158f
  */
 
-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,26 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 0167e624a516
+ */
+
+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 "tool-annotations"?: string[] | 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

@@ -1,15 +1,18 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: aabbc4ab07c1
  */
 
 import { buildApplication, buildRouteMap, run } from "@stricli/core";
 import process from "node:process";
 import { buildContext } from "./cli.js";
+import { serveCommand } from "./cli/serve/command.js";
 import { startCommand } from "./cli/start/command.js";
 
 const routes = buildRouteMap({
   routes: {
     start: startCommand,
+    serve: serveCommand,
   },
   docs: {
     brief: "MCP server CLI",
@@ -19,7 +22,7 @@ const routes = buildRouteMap({
 export const app = buildApplication(routes, {
   name: "mcp",
   versionInfo: {
-    currentVersion: "0.5.0",
+    currentVersion: "0.6.1",
   },
 });
 

package/src/mcp-server/prompts.ts

@@ -1,42 +1,33 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 26f3d73cbf31
  */
 
 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 { CloudinaryEnvConfigCore } 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: CloudinaryEnvConfigCore,
-      args: objectOutputType<Args, ZodTypeAny>,
+      args: ShapeOutput<Args>,
       extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
     ) => GetPromptResult | Promise<GetPromptResult>;
   }
@@ -71,10 +62,10 @@ export function createRegisterPrompt(
   server: McpServer,
   getSDK: () => CloudinaryEnvConfigCore,
   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

@@ -1,5 +1,6 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: cb0c57ebeaea
  */
 
 import {
@@ -17,7 +18,7 @@ import {
 import { CloudinaryEnvConfigCore } 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: CloudinaryEnvConfigCore,
@@ -50,61 +51,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,

package/src/mcp-server/scopes.ts

@@ -1,5 +1,6 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 8966d24256b2
  */
 
 export const mcpScopes = [