@decocms/runtime 1.3.0 → 1.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/runtime",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "type": "module",
   "scripts": {
     "check": "tsc --noEmit",

package/src/tools.ts

@@ -9,6 +9,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebStandardStreamableHTTPServerTransport as HttpServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import type {
   GetPromptResult,
+  Implementation,
   ToolAnnotations,
 } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
@@ -485,6 +486,7 @@ export interface CreateMCPServerOptions<
   State extends
     TEnv["MESH_REQUEST_CONTEXT"]["state"] = TEnv["MESH_REQUEST_CONTEXT"]["state"],
 > {
+  serverInfo?: Partial<Implementation> & { instructions?: string };
   before?: (env: TEnv) => Promise<void> | void;
   oauth?: OAuthConfig;
   events?: {
@@ -711,14 +713,21 @@ const toolsFor = <TSchema extends ZodTypeAny = never>({
     ...(workflows?.length
       ? workflows.map((wf) => {
           const id = wf.toolId ?? workflowToolId(wf.title);
+          const baseDescription = [
+            wf.description
+              ? `Run workflow: ${wf.description}`
+              : `Start the "${wf.title}" workflow.`,
+            "Returns an execution_id immediately. Use COLLECTION_WORKFLOW_EXECUTION_GET to track progress.",
+          ].join(" ");
           return createTool({
             id,
-            description: [
-              wf.description
-                ? `Run workflow: ${wf.description}`
-                : `Start the "${wf.title}" workflow.`,
-              "Returns an execution_id immediately. Use COLLECTION_WORKFLOW_EXECUTION_GET to track progress.",
-            ].join(" "),
+            description: (() => {
+              if (!wf.inputSchema) return baseDescription;
+              const schemaStr = JSON.stringify(wf.inputSchema, null, 2);
+              return schemaStr.length <= 2048
+                ? `${baseDescription}\n\nInput schema:\n${schemaStr}`
+                : `${baseDescription}\n\nThis workflow expects structured input. Use COLLECTION_WORKFLOW_GET to inspect the full input schema.`;
+            })(),
             inputSchema: z.object({
               input: z
                 .record(z.string(), z.unknown())
@@ -808,44 +817,118 @@ export const createMCPServer = <
 >(
   options: CreateMCPServerOptions<TEnv, TSchema, TBindings>,
 ): MCPServer<TEnv, TSchema, TBindings> => {
-  const createServer = async (bindings: TEnv) => {
-    await options.before?.(bindings);
+  // Tool/prompt/resource definitions are resolved once on first request and
+  // cached for the lifetime of the process. Tool *execution* reads per-request
+  // context from State (AsyncLocalStorage), so reusing definitions is safe.
+  type Registrations = {
+    tools: CreatedTool[];
+    prompts: CreatedPrompt[];
+    resources: CreatedResource[];
+    workflows?: WorkflowDefinition[];
+  };
 
-    const server = new McpServer(
-      { name: "@deco/mcp-api", version: "1.0.0" },
-      { capabilities: { tools: {}, prompts: {}, resources: {} } },
-    );
+  let cached: Registrations | null = null;
+  let inflightResolve: Promise<Registrations> | null = null;
 
-    const toolsFn =
-      typeof options.tools === "function"
-        ? options.tools
-        : async (bindings: TEnv) => {
-            if (typeof options.tools === "function") {
-              return await options.tools(bindings);
-            }
-            return await Promise.all(
-              options.tools?.flatMap(async (tool) => {
-                const toolResult = tool(bindings);
-                const awaited = await toolResult;
-                if (Array.isArray(awaited)) {
-                  return awaited;
-                }
-                return [awaited];
-              }) ?? [],
-            ).then((t) => t.flat());
-          };
-    const tools = await toolsFn(bindings);
+  const resolveRegistrations = async (
+    bindings: TEnv,
+  ): Promise<Registrations> => {
+    if (cached) return cached;
+    if (inflightResolve) return inflightResolve;
 
-    const resolvedWorkflows =
-      typeof options.workflows === "function"
-        ? await options.workflows(bindings)
-        : options.workflows;
+    inflightResolve = (async (): Promise<Registrations> => {
+      try {
+        const toolsFn =
+          typeof options.tools === "function"
+            ? options.tools
+            : async (bindings: TEnv) => {
+                if (typeof options.tools === "function") {
+                  return await options.tools(bindings);
+                }
+                return await Promise.all(
+                  options.tools?.flatMap(async (tool) => {
+                    const toolResult = tool(bindings);
+                    const awaited = await toolResult;
+                    if (Array.isArray(awaited)) {
+                      return awaited;
+                    }
+                    return [awaited];
+                  }) ?? [],
+                ).then((t) => t.flat());
+              };
+        const tools = await toolsFn(bindings);
+
+        const resolvedWorkflows =
+          typeof options.workflows === "function"
+            ? await options.workflows(bindings)
+            : options.workflows;
+
+        tools.push(
+          ...toolsFor<TSchema>({ ...options, workflows: resolvedWorkflows }),
+        );
+
+        const promptsFn =
+          typeof options.prompts === "function"
+            ? options.prompts
+            : async (bindings: TEnv) => {
+                if (typeof options.prompts === "function") {
+                  return await options.prompts(bindings);
+                }
+                return await Promise.all(
+                  options.prompts?.flatMap(async (prompt) => {
+                    const promptResult = prompt(bindings);
+                    const awaited = await promptResult;
+                    if (Array.isArray(awaited)) {
+                      return awaited;
+                    }
+                    return [awaited];
+                  }) ?? [],
+                ).then((p) => p.flat());
+              };
+        const prompts = await promptsFn(bindings);
+
+        const resourcesFn =
+          typeof options.resources === "function"
+            ? options.resources
+            : async (bindings: TEnv) => {
+                if (typeof options.resources === "function") {
+                  return await options.resources(bindings);
+                }
+                return await Promise.all(
+                  options.resources?.flatMap(async (resource) => {
+                    const resourceResult = resource(bindings);
+                    const awaited = await resourceResult;
+                    if (Array.isArray(awaited)) {
+                      return awaited;
+                    }
+                    return [awaited];
+                  }) ?? [],
+                ).then((r) => r.flat());
+              };
+        const resources = await resourcesFn(bindings);
+
+        const result = {
+          tools,
+          prompts,
+          resources,
+          workflows: resolvedWorkflows,
+        };
+        cached = result;
+        return result;
+      } catch (err) {
+        inflightResolve = null;
+        throw err;
+      }
+    })();
 
-    tools.push(
-      ...toolsFor<TSchema>({ ...options, workflows: resolvedWorkflows }),
-    );
+    return inflightResolve;
+  };
 
-    for (const tool of tools) {
+  const registerAll = (
+    server: McpServer,
+    registrations: Registrations,
+  ) => {
+    for (const tool of registrations.tools) {
       server.registerTool(
         tool.id,
         {
@@ -873,9 +956,8 @@ export const createMCPServer = <
             runtimeContext: createRuntimeContext(),
           });
 
-          // For streamable tools, the Response is handled at the transport layer
-          // Do NOT call result.bytes() - it buffers the entire response in memory
-          // causing massive memory leaks (2GB+ Uint8Array accumulation)
+          // For streamable tools, the Response is handled at the transport layer.
+          // Do NOT call result.bytes() — it buffers the entire body in memory.
           if (isStreamableTool(tool) && result instanceof Response) {
             return {
               structuredContent: {
@@ -904,28 +986,7 @@ export const createMCPServer = <
       );
     }
 
-    // Resolve and register prompts
-    const promptsFn =
-      typeof options.prompts === "function"
-        ? options.prompts
-        : async (bindings: TEnv) => {
-            if (typeof options.prompts === "function") {
-              return await options.prompts(bindings);
-            }
-            return await Promise.all(
-              options.prompts?.flatMap(async (prompt) => {
-                const promptResult = prompt(bindings);
-                const awaited = await promptResult;
-                if (Array.isArray(awaited)) {
-                  return awaited;
-                }
-                return [awaited];
-              }) ?? [],
-            ).then((p) => p.flat());
-          };
-    const prompts = await promptsFn(bindings);
-
-    for (const prompt of prompts) {
+    for (const prompt of registrations.prompts) {
       server.registerPrompt(
         prompt.name,
         {
@@ -944,28 +1005,7 @@ export const createMCPServer = <
       );
     }
 
-    // Resolve and register resources
-    const resourcesFn =
-      typeof options.resources === "function"
-        ? options.resources
-        : async (bindings: TEnv) => {
-            if (typeof options.resources === "function") {
-              return await options.resources(bindings);
-            }
-            return await Promise.all(
-              options.resources?.flatMap(async (resource) => {
-                const resourceResult = resource(bindings);
-                const awaited = await resourceResult;
-                if (Array.isArray(awaited)) {
-                  return awaited;
-                }
-                return [awaited];
-              }) ?? [],
-            ).then((r) => r.flat());
-          };
-    const resources = await resourcesFn(bindings);
-
-    for (const resource of resources) {
+    for (const resource of registrations.resources) {
       server.resource(
         resource.name,
         resource.uri,
@@ -978,19 +1018,7 @@ export const createMCPServer = <
             uri,
             runtimeContext: createRuntimeContext(),
           });
-          // Build content object based on what's provided (text or blob, not both)
-          const content: {
-            uri: string;
-            mimeType?: string;
-            text?: string;
-            blob?: string;
-          } = { uri: result.uri };
-
-          if (result.mimeType) {
-            content.mimeType = result.mimeType;
-          }
 
-          // MCP SDK expects either text or blob content, not both
           const meta =
             (result as { _meta?: Record<string, unknown> | null })._meta ??
             undefined;
@@ -1018,7 +1046,6 @@ export const createMCPServer = <
             };
           }
 
-          // Fallback to empty text if neither provided
           return {
             contents: [
               { uri: result.uri, mimeType: result.mimeType, text: "" },
@@ -1027,8 +1054,28 @@ export const createMCPServer = <
         },
       );
     }
+  };
+
+  const createServer = async (bindings: TEnv) => {
+    await options.before?.(bindings);
+
+    const { instructions, ...serverInfoOverrides } = options.serverInfo ?? {};
+    const server = new McpServer(
+      {
+        ...serverInfoOverrides,
+        name: serverInfoOverrides.name ?? "@deco/mcp-api",
+        version: serverInfoOverrides.version ?? "1.0.0",
+      },
+      {
+        capabilities: { tools: {}, prompts: {}, resources: {} },
+        ...(instructions && { instructions }),
+      },
+    );
 
-    return { server, tools, prompts, resources };
+    const registrations = await resolveRegistrations(bindings);
+    registerAll(server, registrations);
+
+    return { server, ...registrations };
   };
 
   const fetch = async (req: Request, env: TEnv) => {
@@ -1037,34 +1084,45 @@ export const createMCPServer = <
 
     await server.connect(transport);
 
+    const cleanup = () => {
+      try {
+        transport.close?.();
+      } catch {
+        /* ignore */
+      }
+      try {
+        server.close?.();
+      } catch {
+        /* ignore */
+      }
+    };
+
     try {
       const response = await transport.handleRequest(req);
 
-      // Check if this is a streaming response (SSE or streamable tool)
-      // SSE responses have text/event-stream content-type
-      // Note: response.body is always non-null for all HTTP responses, so we can't use it to detect streaming
       const contentType = response.headers.get("content-type");
       const isStreaming =
         contentType?.includes("text/event-stream") ||
         contentType?.includes("application/json-rpc");
 
-      // Only close transport for non-streaming responses
-      if (!isStreaming) {
-        try {
-          await transport.close?.();
-        } catch {
-          // Ignore close errors
-        }
+      if (!isStreaming || !response.body) {
+        cleanup();
+        return response;
       }
 
-      return response;
+      // Pipe the SSE body through a passthrough so that when the stream
+      // finishes (server sent the response) or the client disconnects
+      // (cancel), the server and transport are always cleaned up.
+      const { readable, writable } = new TransformStream();
+      response.body.pipeTo(writable).catch(() => {}).finally(cleanup);
+
+      return new Response(readable, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+      });
     } catch (error) {
-      // On error, always try to close transport to prevent leaks
-      try {
-        await transport.close?.();
-      } catch {
-        // Ignore close errors
-      }
+      cleanup();
       throw error;
     }
   };
@@ -1075,7 +1133,9 @@ export const createMCPServer = <
       throw new Error("Missing state, did you forget to call State.bind?");
     }
     const env = currentState?.env;
-    const { tools } = await createServer(env as TEnv & DefaultEnv<TSchema>);
+    const { tools } = await resolveRegistrations(
+      env as TEnv & DefaultEnv<TSchema>,
+    );
     const tool = tools.find((t) => t.id === toolCallId);
     const execute = tool?.execute;
     if (!execute) {

package/src/workflows.ts

@@ -24,6 +24,12 @@ export interface WorkflowDefinition {
    * Defaults to START_WORKFLOW_<TITLE_SLUG> (e.g. START_WORKFLOW_FETCH_USERS).
    */
   toolId?: string;
+  /**
+   * JSON Schema describing the expected input for this workflow.
+   * When set, the mesh validates execution input against this schema
+   * before creating an execution.
+   */
+  inputSchema?: Record<string, unknown> | null;
 }
 
 interface WorkflowCollectionItem {
@@ -67,6 +73,7 @@ interface MeshWorkflowClient {
       description?: string;
       virtual_mcp_id?: string;
       steps: Step[];
+      input_schema?: Record<string, unknown> | null;
     };
   }) => Promise<{ item: WorkflowCollectionItem }>;
   COLLECTION_WORKFLOW_UPDATE: (input: {
@@ -76,6 +83,7 @@ interface MeshWorkflowClient {
       description?: string;
       virtual_mcp_id?: string;
       steps?: Step[];
+      input_schema?: Record<string, unknown> | null;
     };
   }) => Promise<{ success: boolean; error?: string }>;
   COLLECTION_WORKFLOW_DELETE: (input: {
@@ -254,10 +262,11 @@ function fingerprintWorkflows(declared: WorkflowDefinition[]): string {
   return JSON.stringify(
     declared.map((w) => ({
       title: w.title,
-      description: w.description ?? null,
-      virtual_mcp_id: w.virtual_mcp_id ?? null,
+      description: w.description ?? undefined,
+      virtual_mcp_id: w.virtual_mcp_id ?? undefined,
       steps: w.steps,
-      toolId: w.toolId ?? null,
+      toolId: w.toolId ?? undefined,
+      inputSchema: w.inputSchema ?? undefined,
     })),
   );
 }
@@ -383,6 +392,10 @@ async function doSyncWorkflows(
                 virtual_mcp_id: resolvedVmcpId,
               }),
               steps: wf.steps,
+              input_schema:
+                wf.inputSchema === undefined
+                  ? undefined
+                  : (wf.inputSchema ?? null),
             },
           });
           if (!result.success) {
@@ -402,6 +415,7 @@ async function doSyncWorkflows(
               description: wf.description,
               virtual_mcp_id: resolvedVmcpId,
               steps: wf.steps,
+              input_schema: wf.inputSchema ?? null,
             },
           });
           console.log(`${tag} CREATE "${wf.title}" OK`);
@@ -596,8 +610,30 @@ type InputForTool<
     : StepInput<TSteps>
   : StepInput<TSteps>;
 
-type BaseStepFields = Omit<Step, "name" | "input" | "action">;
-type BaseForEachFields = Omit<Step, "name" | "forEach" | "input" | "action">;
+/**
+ * Typed bail condition with @ref autocomplete.
+ * Self-references (e.g. `@thisStep.field` on step "thisStep") are valid for
+ * bail — the condition is evaluated after the step completes — but the current
+ * step name isn't in TSteps yet. Use the `(string & {})` escape hatch.
+ */
+type TypedBail<TSteps extends string> =
+  | true
+  | {
+      ref: KnownRefs<TSteps>;
+      eq?: unknown;
+      neq?: unknown;
+      gt?: number;
+      lt?: number;
+    };
+
+type BaseStepFields<TSteps extends string> = Omit<
+  Step,
+  "name" | "input" | "action" | "bail"
+> & { bail?: TypedBail<TSteps> };
+type BaseForEachFields<TSteps extends string> = Omit<
+  Step,
+  "name" | "forEach" | "input" | "action" | "bail"
+> & { bail?: TypedBail<TSteps> };
 
 /**
  * Tool-call variants of StepOpts — one discriminated member per tool ID so
@@ -608,12 +644,12 @@ type ToolCallStepOpts<
   TSteps extends string,
   TTools extends readonly ToolLike[],
 > = [TTools[number]] extends [never]
-  ? BaseStepFields & {
+  ? BaseStepFields<TSteps> & {
       action: { toolName: string & {}; transformCode?: string };
       input?: StepInput<TSteps>;
     }
   : {
-      [TId in TTools[number]["id"]]: BaseStepFields & {
+      [TId in TTools[number]["id"]]: BaseStepFields<TSteps> & {
         action: { toolName: TId; transformCode?: string };
         input?: InputForTool<TTools, TId, TSteps>;
       };
@@ -621,19 +657,22 @@ type ToolCallStepOpts<
 
 type StepOpts<TSteps extends string, TTools extends readonly ToolLike[]> =
   | ToolCallStepOpts<TSteps, TTools>
-  | (BaseStepFields & { action: { code: string }; input?: StepInput<TSteps> });
+  | (BaseStepFields<TSteps> & {
+      action: { code: string };
+      input?: StepInput<TSteps>;
+    });
 
 type ToolCallForEachOpts<
   TSteps extends string,
   TTools extends readonly ToolLike[],
 > = [TTools[number]] extends [never]
-  ? BaseForEachFields & {
+  ? BaseForEachFields<TSteps> & {
       action: { toolName: string & {}; transformCode?: string };
       input?: StepInput<TSteps>;
       concurrency?: number;
     }
   : {
-      [TId in TTools[number]["id"]]: BaseForEachFields & {
+      [TId in TTools[number]["id"]]: BaseForEachFields<TSteps> & {
         action: { toolName: TId; transformCode?: string };
         input?: InputForTool<TTools, TId, TSteps>;
         concurrency?: number;
@@ -645,7 +684,7 @@ type ForEachItemOpts<
   TTools extends readonly ToolLike[],
 > =
   | ToolCallForEachOpts<TSteps, TTools>
-  | (BaseForEachFields & {
+  | (BaseForEachFields<TSteps> & {
       action: { code: string };
       input?: StepInput<TSteps>;
       concurrency?: number;