@decocms/runtime 1.2.15 → 1.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/runtime",
-  "version": "1.2.15",
+  "version": "1.3.1",
   "type": "module",
   "scripts": {
     "check": "tsc --noEmit",
@@ -22,7 +22,9 @@
     "./bindings": "./src/bindings/index.ts",
     "./asset-server": "./src/asset-server/index.ts",
     "./tools": "./src/tools.ts",
-    "./decopilot": "./src/decopilot.ts"
+    "./decopilot": "./src/decopilot.ts",
+    "./triggers": "./src/triggers.ts",
+    "./trigger-storage": "./src/trigger-storage.ts"
   },
   "peerDependencies": {
     "ai": ">=6.0.0"

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/trigger-storage.ts

@@ -0,0 +1,195 @@
+/**
+ * Built-in TriggerStorage implementations.
+ *
+ * - StudioKV: Persists to Mesh/Studio's KV API (recommended for production)
+ * - JsonFileStorage: Persists to a local JSON file (for dev/simple deployments)
+ */
+
+import type { TriggerStorage } from "./triggers.ts";
+
+// ============================================================================
+// StudioKV — backed by Mesh's /api/kv endpoint
+// ============================================================================
+
+interface StudioKVOptions {
+  /** Mesh/Studio base URL (e.g., "https://studio.example.com") */
+  url: string;
+  /** API key created in the Studio org */
+  apiKey: string;
+  /** Key prefix to namespace trigger data (default: "triggers") */
+  prefix?: string;
+}
+
+/**
+ * TriggerStorage backed by Mesh/Studio's org-scoped KV API.
+ *
+ * @example
+ * ```typescript
+ * import { createTriggers } from "@decocms/runtime/triggers";
+ * import { StudioKV } from "@decocms/runtime/trigger-storage";
+ *
+ * const triggers = createTriggers({
+ *   definitions: [...],
+ *   storage: new StudioKV({
+ *     url: process.env.MESH_URL!,
+ *     apiKey: process.env.MESH_API_KEY!,
+ *   }),
+ * });
+ * ```
+ */
+export class StudioKV implements TriggerStorage {
+  private baseUrl: string;
+  private apiKey: string;
+  private prefix: string;
+
+  constructor(options: StudioKVOptions) {
+    this.baseUrl = options.url.replace(/\/$/, "");
+    this.apiKey = options.apiKey;
+    this.prefix = options.prefix ?? "triggers";
+  }
+
+  private key(connectionId: string): string {
+    return `${this.prefix}:${connectionId}`;
+  }
+
+  async get(connectionId: string) {
+    const res = await fetch(
+      `${this.baseUrl}/api/kv/${encodeURIComponent(this.key(connectionId))}`,
+      {
+        headers: { Authorization: `Bearer ${this.apiKey}` },
+      },
+    );
+
+    if (res.status === 404) return null;
+
+    if (!res.ok) {
+      console.error(`[StudioKV] GET failed: ${res.status} ${res.statusText}`);
+      return null;
+    }
+
+    const body = (await res.json()) as {
+      value?: {
+        credentials: { callbackUrl: string; callbackToken: string };
+        activeTriggerTypes: string[];
+      };
+    };
+    return body.value ?? null;
+  }
+
+  async set(
+    connectionId: string,
+    state: {
+      credentials: { callbackUrl: string; callbackToken: string };
+      activeTriggerTypes: string[];
+    },
+  ) {
+    const res = await fetch(
+      `${this.baseUrl}/api/kv/${encodeURIComponent(this.key(connectionId))}`,
+      {
+        method: "PUT",
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(state),
+      },
+    );
+
+    if (!res.ok) {
+      console.error(`[StudioKV] PUT failed: ${res.status} ${res.statusText}`);
+    }
+  }
+
+  async delete(connectionId: string) {
+    const res = await fetch(
+      `${this.baseUrl}/api/kv/${encodeURIComponent(this.key(connectionId))}`,
+      {
+        method: "DELETE",
+        headers: { Authorization: `Bearer ${this.apiKey}` },
+      },
+    );
+
+    if (!res.ok && res.status !== 404) {
+      console.error(
+        `[StudioKV] DELETE failed: ${res.status} ${res.statusText}`,
+      );
+    }
+  }
+}
+
+// ============================================================================
+// JsonFileStorage — backed by a local JSON file
+// ============================================================================
+
+interface JsonFileStorageOptions {
+  /** Path to the JSON file (will be created if it doesn't exist) */
+  path: string;
+}
+
+/**
+ * TriggerStorage backed by a local JSON file.
+ * Suitable for development and single-instance deployments.
+ *
+ * @example
+ * ```typescript
+ * import { createTriggers } from "@decocms/runtime/triggers";
+ * import { JsonFileStorage } from "@decocms/runtime/trigger-storage";
+ *
+ * const triggers = createTriggers({
+ *   definitions: [...],
+ *   storage: new JsonFileStorage({ path: "./trigger-state.json" }),
+ * });
+ * ```
+ */
+export class JsonFileStorage implements TriggerStorage {
+  private path: string;
+  private cache: Map<string, unknown> | null = null;
+
+  constructor(options: JsonFileStorageOptions) {
+    this.path = options.path;
+  }
+
+  private async load(): Promise<Map<string, unknown>> {
+    if (this.cache) return this.cache;
+    try {
+      const fs = await import("node:fs/promises");
+      const raw = await fs.readFile(this.path, "utf-8");
+      const data = JSON.parse(raw) as Record<string, unknown>;
+      this.cache = new Map(Object.entries(data));
+    } catch (err: unknown) {
+      if (
+        err instanceof Error &&
+        "code" in err &&
+        (err as NodeJS.ErrnoException).code === "ENOENT"
+      ) {
+        this.cache = new Map();
+      } else {
+        throw err;
+      }
+    }
+    return this.cache;
+  }
+
+  private async save(): Promise<void> {
+    const data = Object.fromEntries(this.cache ?? new Map());
+    const fs = await import("node:fs/promises");
+    await fs.writeFile(this.path, JSON.stringify(data, null, 2));
+  }
+
+  async get(connectionId: string) {
+    const map = await this.load();
+    return (map.get(connectionId) as any) ?? null;
+  }
+
+  async set(connectionId: string, state: unknown) {
+    const map = await this.load();
+    map.set(connectionId, state);
+    await this.save();
+  }
+
+  async delete(connectionId: string) {
+    const map = await this.load();
+    map.delete(connectionId);
+    await this.save();
+  }
+}