create-multicast 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-multicast",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Create a Multicast MCP gateway — one command to scaffold, configure, and deploy your parallel MCP server.",
   "type": "module",
   "bin": "./dist/cli.js",

package/templates/default/migrations/0001_init.sql

@@ -28,6 +28,18 @@ CREATE TABLE IF NOT EXISTS tools (
     UNIQUE(server_name, tool_name)
 );
 
+-- Result cache: temporary storage for large tool results
+-- Used by the two-phase response pattern: multicast returns a reference,
+-- fetch_result retrieves the full data. Auto-cleaned after 1 hour.
+CREATE TABLE IF NOT EXISTS result_cache (
+    ref_id TEXT PRIMARY KEY,
+    server_name TEXT NOT NULL,
+    tool_name TEXT NOT NULL,
+    output TEXT NOT NULL,
+    created_at TEXT DEFAULT (datetime('now'))
+);
+
 -- Indexes for common queries
 CREATE INDEX IF NOT EXISTS idx_tools_server ON tools(server_name);
 CREATE INDEX IF NOT EXISTS idx_servers_status ON servers(status);
+CREATE INDEX IF NOT EXISTS idx_result_cache_created ON result_cache(created_at);

package/templates/default/src/index.ts

@@ -21,6 +21,9 @@ interface CallResult {
   tool: string;
   success: boolean;
   output?: unknown;
+  output_ref?: string;
+  output_summary?: string;
+  output_size?: string;
   error?: string;
   duration_ms: number;
 }
@@ -31,6 +34,10 @@ interface CachedTool {
   input_schema: string;
 }
 
+// Max size (in chars) for inline results. Larger results get stored in D1
+// and returned as a reference that can be fetched with fetch_result.
+const INLINE_RESULT_MAX_CHARS = 5000;
+
 // ── Server Registry ──────────────────────────────────────────
 // Parses MCP_SERVER_* and MCP_AUTH_* env vars at request time.
 // MCP_SERVER_CONTEXT_HUB=https://... → server name: "context-hub"
@@ -54,13 +61,21 @@ function getRegisteredServers(env: Env): Map<string, RegisteredServer> {
 }
 
 // ── Downstream MCP Client ────────────────────────────────────
-// Calls a single downstream MCP server via JSON-RPC over HTTP.
+// Calls a downstream MCP server via JSON-RPC over HTTP.
+// Supports optional "setup" steps that run sequentially on the same
+// session before the main tool call (e.g., select_workspace → list_services).
+
+interface ToolStep {
+  tool: string;
+  args: Record<string, unknown>;
+}
 
 async function callMcpServer(
   server: RegisteredServer,
   tool: string,
   args: Record<string, unknown>,
-  timeoutMs: number
+  timeoutMs: number,
+  setup?: ToolStep[]
 ): Promise<CallResult> {
   const start = Date.now();
   const controller = new AbortController();
@@ -110,7 +125,54 @@ async function callMcpServer(
       signal: controller.signal,
     });
 
-    // Step 3: Call the tool with the session
+    // Step 3: Run setup commands sequentially on the same session
+    // (e.g., select_workspace before list_services)
+    if (setup && setup.length > 0) {
+      for (const step of setup) {
+        const setupResponse = await fetch(server.url, {
+          method: "POST",
+          headers: callHeaders,
+          body: JSON.stringify({
+            jsonrpc: "2.0",
+            method: "tools/call",
+            params: { name: step.tool, arguments: step.args },
+            id: "setup-" + crypto.randomUUID(),
+          }),
+          signal: controller.signal,
+        });
+
+        if (!setupResponse.ok) {
+          return {
+            server: server.name,
+            tool,
+            success: false,
+            error: `setup step "${step.tool}" failed: HTTP ${setupResponse.status}`,
+            duration_ms: Date.now() - start,
+          };
+        }
+
+        const setupData = (await setupResponse.json()) as {
+          result?: { content?: Array<{ text?: string }>; isError?: boolean };
+          error?: { message?: string };
+        };
+
+        if (setupData.error || setupData.result?.isError) {
+          const errMsg =
+            setupData.error?.message ||
+            setupData.result?.content?.[0]?.text ||
+            `setup step "${step.tool}" failed`;
+          return {
+            server: server.name,
+            tool,
+            success: false,
+            error: `setup step "${step.tool}": ${errMsg}`,
+            duration_ms: Date.now() - start,
+          };
+        }
+      }
+    }
+
+    // Step 4: Call the actual tool on the same session
     const response = await fetch(server.url, {
       method: "POST",
       headers: callHeaders,
@@ -175,6 +237,46 @@ async function callMcpServer(
   }
 }
 
+// ── Summary Generator ────────────────────────────────────────
+// Creates a brief summary of large results so Claude can decide
+// whether to fetch the full data.
+
+function generateSummary(output: unknown, server: string, tool: string): string {
+  try {
+    // Handle MCP tool result format: { content: [{ type: "text", text: "..." }] }
+    const result = output as { content?: Array<{ text?: string }> };
+    const text = result?.content?.[0]?.text;
+
+    if (!text) return `Large result from ${server}/${tool}`;
+
+    // Try to parse as JSON array (common for list responses)
+    try {
+      const parsed = JSON.parse(text);
+      if (Array.isArray(parsed)) {
+        const names = parsed
+          .slice(0, 8)
+          .map((item: Record<string, unknown>) =>
+            (item.name as string) || (item.title as string) || (item.id as string) || "unnamed"
+          );
+        const suffix = parsed.length > 8 ? `, ... +${parsed.length - 8} more` : "";
+        return `${parsed.length} items: ${names.join(", ")}${suffix}`;
+      }
+
+      if (typeof parsed === "object" && parsed !== null) {
+        const keys = Object.keys(parsed).slice(0, 5);
+        return `Object with keys: ${keys.join(", ")}${Object.keys(parsed).length > 5 ? " ..." : ""}`;
+      }
+    } catch {
+      // Not JSON — use text preview
+    }
+
+    // Plain text — return first 200 chars
+    return text.slice(0, 200) + (text.length > 200 ? "..." : "");
+  } catch {
+    return `Large result from ${server}/${tool}`;
+  }
+}
+
 // ── Tool Discovery ───────────────────────────────────────────
 // Calls tools/list on a downstream MCP server and caches results in D1.
 
@@ -429,13 +531,42 @@ Always returns partial results even if some calls fail.
 
 Use list_servers first to discover available servers and their tools.
 
-Example:
+For stateful servers that need setup steps (e.g., Render's select_workspace),
+use the "setup" field to chain commands that run sequentially on the same
+session BEFORE the main tool call.
+
+Example — simple parallel calls:
 {
   "calls": [
     { "server": "context-hub", "tool": "search_memories", "args": { "query": "project ideas" } },
     { "server": "supabase", "tool": "execute_sql", "args": { "sql": "SELECT count(*) FROM users" } }
   ]
-}`,
+}
+
+Example — with setup steps for stateful servers:
+{
+  "calls": [
+    {
+      "server": "render",
+      "tool": "list_services",
+      "args": {},
+      "setup": [
+        { "tool": "select_workspace", "args": { "workspace_id": "tea-xxx" } }
+      ]
+    },
+    {
+      "server": "render-personal",
+      "tool": "list_services",
+      "args": {},
+      "setup": [
+        { "tool": "select_workspace", "args": { "workspace_id": "tea-yyy" } }
+      ]
+    }
+  ]
+}
+
+Setup steps run sequentially on the same session, then the main tool executes.
+Different servers still run in parallel with each other.`,
       {
         calls: z
           .array(
@@ -447,6 +578,19 @@ Example:
                 .optional()
                 .default({})
                 .describe("Arguments to pass to the tool"),
+              setup: z
+                .array(
+                  z.object({
+                    tool: z.string().describe("Setup tool to call first (e.g., select_workspace)"),
+                    args: z
+                      .record(z.string(), z.unknown())
+                      .optional()
+                      .default({})
+                      .describe("Arguments for the setup tool"),
+                  })
+                )
+                .optional()
+                .describe("Sequential setup steps to run on the same session before the main call"),
             })
           )
           .min(1)
@@ -468,6 +612,7 @@ Example:
           server: RegisteredServer;
           tool: string;
           args: Record<string, unknown>;
+          setup?: ToolStep[];
         }> = [];
 
         for (const call of calls) {
@@ -485,18 +630,32 @@ Example:
               server,
               tool: call.tool,
               args: (call.args || {}) as Record<string, unknown>,
+              setup: call.setup?.map((s) => ({
+                tool: s.tool,
+                args: (s.args || {}) as Record<string, unknown>,
+              })),
             });
           }
         }
 
         // Execute all valid calls in parallel
+        // Each call gets its own session; setup steps run sequentially within that session
         const promises = validCalls.map((call) =>
-          callMcpServer(call.server, call.tool, call.args, timeout)
+          callMcpServer(call.server, call.tool, call.args, timeout, call.setup)
         );
 
         const settled = await Promise.allSettled(promises);
 
-        const results: CallResult[] = [
+        const db = this.env.DB;
+
+        // Clean expired cache entries (older than 1 hour)
+        await db
+          .prepare(
+            "DELETE FROM result_cache WHERE created_at < datetime('now', '-1 hour')"
+          )
+          .run();
+
+        const rawResults: CallResult[] = [
           ...validationErrors,
           ...settled.map((result, i) => {
             if (result.status === "fulfilled") {
@@ -512,23 +671,68 @@ Example:
           }),
         ];
 
+        // Two-phase response: inline small results, store large ones in D1
+        const results: CallResult[] = [];
+        let hasRefs = false;
+
+        for (const r of rawResults) {
+          if (!r.success || !r.output) {
+            results.push(r);
+            continue;
+          }
+
+          const outputStr = JSON.stringify(r.output);
+
+          if (outputStr.length <= INLINE_RESULT_MAX_CHARS) {
+            // Small result — include inline
+            results.push(r);
+          } else {
+            // Large result — store in D1, return reference
+            const refId = `ref_${crypto.randomUUID().replace(/-/g, "").slice(0, 12)}`;
+            hasRefs = true;
+
+            await db
+              .prepare(
+                "INSERT INTO result_cache (ref_id, server_name, tool_name, output) VALUES (?, ?, ?, ?)"
+              )
+              .bind(refId, r.server, r.tool, outputStr)
+              .run();
+
+            // Generate a brief summary from the output
+            const summary = generateSummary(r.output, r.server, r.tool);
+
+            results.push({
+              server: r.server,
+              tool: r.tool,
+              success: true,
+              output_ref: refId,
+              output_summary: summary,
+              output_size: `${Math.round(outputStr.length / 1024)}KB`,
+              duration_ms: r.duration_ms,
+            });
+          }
+        }
+
         const completed = results.filter((r) => r.success).length;
         const failed = results.filter((r) => !r.success).length;
 
+        const response: Record<string, unknown> = {
+          results,
+          total_ms: Date.now() - totalStart,
+          completed,
+          failed,
+        };
+
+        if (hasRefs) {
+          response.note =
+            "Some results were too large to include inline. Use fetch_result with the output_ref to retrieve full data.";
+        }
+
         return {
           content: [
             {
               type: "text" as const,
-              text: JSON.stringify(
-                {
-                  results,
-                  total_ms: Date.now() - totalStart,
-                  completed,
-                  failed,
-                },
-                null,
-                2
-              ),
+              text: JSON.stringify(response, null, 2),
             },
           ],
         };
@@ -573,6 +777,74 @@ Clears the cache and re-fetches tools/list from every registered server.`,
         };
       }
     );
+
+    // ── Tool: fetch_result ──────────────────────────────────
+
+    this.server.tool(
+      "fetch_result",
+      `Retrieve the full output of a large result that was stored by reference.
+When multicast returns an output_ref instead of inline output, call this
+tool with the ref ID to get the complete data. Results expire after 1 hour.`,
+      {
+        ref: z
+          .string()
+          .describe("The output_ref ID from a multicast result (e.g., ref_abc123def456)"),
+      },
+      async ({ ref }) => {
+        const db = this.env.DB;
+
+        const row = await db
+          .prepare(
+            "SELECT server_name, tool_name, output, created_at FROM result_cache WHERE ref_id = ?"
+          )
+          .bind(ref)
+          .first<{
+            server_name: string;
+            tool_name: string;
+            output: string;
+            created_at: string;
+          }>();
+
+        if (!row) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: JSON.stringify({
+                  error: `Result not found for ref "${ref}". It may have expired (results are kept for 1 hour).`,
+                }),
+              },
+            ],
+          };
+        }
+
+        // Parse the stored output back
+        let parsedOutput: unknown;
+        try {
+          parsedOutput = JSON.parse(row.output);
+        } catch {
+          parsedOutput = row.output;
+        }
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify(
+                {
+                  server: row.server_name,
+                  tool: row.tool_name,
+                  output: parsedOutput,
+                  cached_at: row.created_at,
+                },
+                null,
+                2
+              ),
+            },
+          ],
+        };
+      }
+    );
   }
 }