create-multicast 0.2.1 → 0.4.0

package/dist/cli.js

@@ -7,6 +7,8 @@ import { existsSync } from "node:fs";
 import { resolve, join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const TEMPLATES_DIR = resolve(__dirname, "..", "templates", "default");
@@ -70,6 +72,189 @@ async function processTemplates(targetDir, replacements) {
         await unlink(tmplPath);
     }
 }
+// ── OAuth Flow ───────────────────────────────────────────────
+// Discovers OAuth metadata, registers client, opens browser for auth,
+// receives callback with code, exchanges for tokens.
+async function discoverOAuthMetadata(serverUrl) {
+    const baseUrl = new URL(serverUrl);
+    const wellKnownPaths = [
+        `${baseUrl.origin}/.well-known/oauth-authorization-server`,
+        `${baseUrl.origin}/.well-known/openid-configuration`,
+    ];
+    for (const path of wellKnownPaths) {
+        try {
+            const res = await fetch(path, { signal: AbortSignal.timeout(5000) });
+            if (res.ok) {
+                const metadata = (await res.json());
+                if (metadata.authorization_endpoint && metadata.token_endpoint) {
+                    return metadata;
+                }
+            }
+        }
+        catch {
+            // Try next
+        }
+    }
+    return null;
+}
+async function registerOAuthClient(registrationEndpoint, redirectUri) {
+    try {
+        const res = await fetch(registrationEndpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                client_name: "Multicast MCP Gateway",
+                redirect_uris: [redirectUri],
+                grant_types: ["authorization_code", "refresh_token"],
+                response_types: ["code"],
+                token_endpoint_auth_method: "none",
+            }),
+            signal: AbortSignal.timeout(10000),
+        });
+        if (!res.ok)
+            return null;
+        return (await res.json());
+    }
+    catch {
+        return null;
+    }
+}
+function generateCodeVerifier() {
+    return randomBytes(32).toString("base64url");
+}
+async function generateCodeChallenge(verifier) {
+    const { createHash } = await import("node:crypto");
+    return createHash("sha256").update(verifier).digest("base64url");
+}
+function openBrowser(url) {
+    const cmd = process.platform === "darwin"
+        ? "open"
+        : process.platform === "win32"
+            ? "cmd"
+            : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    try {
+        spawnSync(cmd, args, { stdio: "ignore" });
+    }
+    catch {
+        // Browser open failed silently — URL is shown in terminal
+    }
+}
+async function runOAuthFlow(serverUrl, metadata) {
+    const port = 9876 + Math.floor(Math.random() * 100);
+    const redirectUri = `http://localhost:${port}/oauth/callback`;
+    // Dynamic Client Registration
+    let clientId = "multicast-mcp-gateway";
+    let clientSecret;
+    if (metadata.registration_endpoint) {
+        const reg = await registerOAuthClient(metadata.registration_endpoint, redirectUri);
+        if (reg) {
+            clientId = reg.client_id;
+            clientSecret = reg.client_secret;
+        }
+    }
+    // PKCE
+    const codeVerifier = generateCodeVerifier();
+    const codeChallenge = await generateCodeChallenge(codeVerifier);
+    const state = randomBytes(16).toString("hex");
+    // Build authorization URL
+    const authUrl = new URL(metadata.authorization_endpoint);
+    authUrl.searchParams.set("response_type", "code");
+    authUrl.searchParams.set("client_id", clientId);
+    authUrl.searchParams.set("redirect_uri", redirectUri);
+    authUrl.searchParams.set("code_challenge", codeChallenge);
+    authUrl.searchParams.set("code_challenge_method", "S256");
+    authUrl.searchParams.set("state", state);
+    authUrl.searchParams.set("scope", "mcp");
+    authUrl.searchParams.set("resource", serverUrl);
+    return new Promise((resolve) => {
+        let resolved = false;
+        const timer = setTimeout(() => {
+            if (!resolved) {
+                resolved = true;
+                httpServer.close();
+                resolve(null);
+            }
+        }, 120000);
+        const httpServer = createServer(async (req, res) => {
+            const url = new URL(req.url || "/", `http://localhost:${port}`);
+            if (url.pathname !== "/oauth/callback") {
+                res.writeHead(404);
+                res.end("Not found");
+                return;
+            }
+            const code = url.searchParams.get("code");
+            const returnedState = url.searchParams.get("state");
+            const error = url.searchParams.get("error");
+            if (error || !code || returnedState !== state) {
+                res.writeHead(400, { "Content-Type": "text/html" });
+                res.end("<html><body><h2>Authorization failed</h2><p>You can close this window.</p></body></html>");
+                if (!resolved) {
+                    resolved = true;
+                    clearTimeout(timer);
+                    httpServer.close();
+                    resolve(null);
+                }
+                return;
+            }
+            try {
+                const tokenParams = new URLSearchParams({
+                    grant_type: "authorization_code",
+                    code,
+                    redirect_uri: redirectUri,
+                    client_id: clientId,
+                    code_verifier: codeVerifier,
+                });
+                if (clientSecret)
+                    tokenParams.set("client_secret", clientSecret);
+                const tokenRes = await fetch(metadata.token_endpoint, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                    body: tokenParams.toString(),
+                });
+                if (!tokenRes.ok) {
+                    res.writeHead(500, { "Content-Type": "text/html" });
+                    res.end("<html><body><h2>Token exchange failed</h2><p>You can close this window.</p></body></html>");
+                    if (!resolved) {
+                        resolved = true;
+                        clearTimeout(timer);
+                        httpServer.close();
+                        resolve(null);
+                    }
+                    return;
+                }
+                const tokenData = (await tokenRes.json());
+                res.writeHead(200, { "Content-Type": "text/html" });
+                res.end("<html><body><h2>Authorized!</h2><p>You can close this window and return to the terminal.</p></body></html>");
+                if (!resolved) {
+                    resolved = true;
+                    clearTimeout(timer);
+                    httpServer.close();
+                    resolve({
+                        access_token: tokenData.access_token,
+                        refresh_token: tokenData.refresh_token,
+                        token_endpoint: metadata.token_endpoint,
+                        client_id: clientId,
+                        expires_at: Math.floor(Date.now() / 1000) + (tokenData.expires_in || 3600),
+                    });
+                }
+            }
+            catch {
+                res.writeHead(500, { "Content-Type": "text/html" });
+                res.end("<html><body><h2>Error</h2><p>You can close this window.</p></body></html>");
+                if (!resolved) {
+                    resolved = true;
+                    clearTimeout(timer);
+                    httpServer.close();
+                    resolve(null);
+                }
+            }
+        });
+        httpServer.listen(port, () => {
+            openBrowser(authUrl.toString());
+        });
+    });
+}
 // ── MCP Config Discovery ─────────────────────────────────────
 // Scans known locations for existing MCP server configurations.
 function getMcpConfigPaths() {
@@ -270,13 +455,17 @@ async function main() {
             if (auth) {
                 // Auth found in existing config — use it
                 authStatus = "credentials found in config";
+                selectedServers.push({ name, url: server.url, auth });
             }
             else {
                 // No auth in config — probe the server
                 try {
                     const probe = await fetch(server.url, {
                         method: "POST",
-                        headers: { "Content-Type": "application/json" },
+                        headers: {
+                            "Content-Type": "application/json",
+                            "Accept": "application/json, text/event-stream",
+                        },
                         body: JSON.stringify({
                             jsonrpc: "2.0",
                             method: "initialize",
@@ -290,43 +479,61 @@ async function main() {
                         signal: AbortSignal.timeout(5000),
                     });
                     if (probe.status === 401 || probe.status === 403) {
-                        // Server requires auth but we don't have it — need to ask
+                        // Server requires auth — check if it's OAuth
                         authStatus = "needs-auth";
                     }
                     else {
                         // Server responded without auth — no auth needed
                         authStatus = "no auth required";
+                        selectedServers.push({ name, url: server.url });
                     }
                 }
                 catch {
-                    // Can't reach server — assume no auth (will fail later with clear error)
                     authStatus = "unreachable (skipping auth)";
+                    selectedServers.push({ name, url: server.url });
                 }
             }
             if (authStatus === "needs-auth") {
-                // Only ask when we KNOW the server needs auth but we don't have it
-                authSpinner.stop(`${pc.yellow("!")} ${name} requires authentication.`);
-                const authResult = await p.text({
-                    message: `Enter auth header for ${pc.bold(name)}:`,
-                    placeholder: "Bearer your-token-here",
-                    validate: (v) => {
-                        if (!v.trim())
-                            return "Auth header is required — server returned 401";
-                        return undefined;
-                    },
-                });
-                if (p.isCancel(authResult)) {
-                    p.cancel("Setup cancelled.");
-                    process.exit(0);
+                // Check if server supports OAuth
+                authSpinner.stop(`${pc.yellow("!")} ${name} requires authentication. Checking for OAuth...`);
+                const oauthMetadata = await discoverOAuthMetadata(server.url);
+                if (oauthMetadata) {
+                    // OAuth server — run the authorization flow
+                    p.log.info(`${pc.bold(name)} uses OAuth. Opening browser for authorization...`);
+                    p.log.info(pc.dim(`Authorization URL: ${oauthMetadata.authorization_endpoint}`));
+                    const oauthResult = await runOAuthFlow(server.url, oauthMetadata);
+                    if (oauthResult) {
+                        p.log.success(`${name} authorized via OAuth.`);
+                        selectedServers.push({
+                            name,
+                            url: server.url,
+                            oauth: oauthResult,
+                        });
+                    }
+                    else {
+                        p.log.warn(`OAuth authorization failed for ${name}. Skipping.\n` +
+                            `  ${pc.dim("You can add it manually later or re-run the installer.")}`);
+                    }
+                }
+                else {
+                    // Not OAuth — ask for static auth header
+                    const authResult = await p.text({
+                        message: `Enter auth header for ${pc.bold(name)}:`,
+                        placeholder: "Bearer your-token-here",
+                        validate: (v) => {
+                            if (!v.trim())
+                                return "Auth header is required — server returned 401";
+                            return undefined;
+                        },
+                    });
+                    if (p.isCancel(authResult)) {
+                        p.cancel("Setup cancelled.");
+                        process.exit(0);
+                    }
+                    selectedServers.push({ name, url: server.url, auth: authResult });
                 }
-                auth = authResult;
                 authSpinner.start("Detecting authentication requirements...");
             }
-            selectedServers.push({
-                name,
-                url: server.url,
-                auth: auth || undefined,
-            });
         }
         authSpinner.stop("Authentication configured.");
         // Show auth summary
@@ -509,8 +716,35 @@ async function main() {
             else {
                 p.log.success(`${server.name} URL set.`);
             }
-            // Set auth if present
-            if (server.auth) {
+            // Set auth: static header OR OAuth tokens
+            if (server.oauth) {
+                // OAuth server — store tokens in D1 and set MCP_OAUTH_ flag
+                const oauthFlag = spawnSync("npx", ["wrangler", "secret", "put", `MCP_OAUTH_${envName}`], {
+                    cwd: targetDir,
+                    input: "true\n",
+                    stdio: ["pipe", "inherit", "inherit"],
+                    encoding: "utf-8",
+                });
+                if (oauthFlag.status !== 0) {
+                    p.log.warn(`Failed to set OAuth flag for ${server.name}.`);
+                }
+                // Insert tokens into D1
+                const sql = `INSERT OR REPLACE INTO oauth_tokens (server_name, access_token, refresh_token, token_endpoint, client_id, expires_at) VALUES ('${server.name}', '${server.oauth.access_token}', ${server.oauth.refresh_token ? `'${server.oauth.refresh_token}'` : "NULL"}, '${server.oauth.token_endpoint}', '${server.oauth.client_id}', ${server.oauth.expires_at})`;
+                const dbInsert = spawnSync("npx", ["wrangler", "d1", "execute", `${projectName}-db`, "--remote", `--command=${sql}`], {
+                    cwd: targetDir,
+                    stdio: ["inherit", "inherit", "inherit"],
+                    encoding: "utf-8",
+                });
+                if (dbInsert.status !== 0) {
+                    p.log.warn(`Failed to store OAuth tokens for ${server.name} in D1.\n` +
+                        `  ${pc.dim("You may need to re-run the installer to authorize again.")}`);
+                }
+                else {
+                    p.log.success(`${server.name} OAuth tokens stored.`);
+                }
+            }
+            else if (server.auth) {
+                // Static auth header
                 const authResult = spawnSync("npx", ["wrangler", "secret", "put", `MCP_AUTH_${envName}`], {
                     cwd: targetDir,
                     input: server.auth + "\n",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-multicast",
-  "version": "0.2.1",
+  "version": "0.4.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,31 @@ 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'))
+);
+
+-- OAuth tokens: cached access/refresh tokens for OAuth-based MCP servers
+-- Installer stores initial tokens during setup. Worker refreshes automatically
+-- when access_token expires using the refresh_token + token_endpoint.
+CREATE TABLE IF NOT EXISTS oauth_tokens (
+    server_name TEXT PRIMARY KEY,
+    access_token TEXT NOT NULL,
+    refresh_token TEXT,
+    token_endpoint TEXT NOT NULL,
+    client_id TEXT NOT NULL,
+    expires_at INTEGER NOT NULL,         -- unix timestamp (seconds)
+    updated_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

@@ -14,6 +14,16 @@ interface RegisteredServer {
   name: string;
   url: string;
   auth?: string;
+  isOAuth?: boolean; // true if server uses OAuth (tokens in D1)
+}
+
+interface OAuthTokenRow {
+  server_name: string;
+  access_token: string;
+  refresh_token: string | null;
+  token_endpoint: string;
+  client_id: string;
+  expires_at: number;
 }
 
 interface CallResult {
@@ -21,6 +31,9 @@ interface CallResult {
   tool: string;
   success: boolean;
   output?: unknown;
+  output_ref?: string;
+  output_summary?: string;
+  output_size?: string;
   error?: string;
   duration_ms: number;
 }
@@ -31,10 +44,15 @@ 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.
+// Parses MCP_SERVER_*, MCP_AUTH_*, and MCP_OAUTH_* env vars at request time.
 // MCP_SERVER_CONTEXT_HUB=https://... → server name: "context-hub"
-// MCP_AUTH_CONTEXT_HUB=Bearer key... → auth header for "context-hub"
+// MCP_AUTH_CONTEXT_HUB=Bearer key... → static auth header
+// MCP_OAUTH_NEOSAPIEN=true → OAuth server (tokens managed in D1)
 
 function getRegisteredServers(env: Env): Map<string, RegisteredServer> {
   const servers = new Map<string, RegisteredServer>();
@@ -44,23 +62,108 @@ function getRegisteredServers(env: Env): Map<string, RegisteredServer> {
       const rawName = key.replace("MCP_SERVER_", "");
       const name = rawName.toLowerCase().replace(/_/g, "-");
       const authKey = `MCP_AUTH_${rawName}`;
+      const oauthKey = `MCP_OAUTH_${rawName}`;
       const auth = typeof env[authKey] === "string" ? (env[authKey] as string) : undefined;
+      const isOAuth = typeof env[oauthKey] === "string" && env[oauthKey] === "true";
 
-      servers.set(name, { name, url: value, auth });
+      servers.set(name, { name, url: value, auth, isOAuth });
     }
   }
 
   return servers;
 }
 
+// ── OAuth Token Management ───────────────────────────────────
+// Resolves auth for OAuth servers: checks D1 for cached token,
+// refreshes if expired, returns a valid Bearer header.
+
+async function resolveOAuthToken(
+  serverName: string,
+  db: D1Database
+): Promise<{ auth: string; error?: undefined } | { auth?: undefined; error: string }> {
+  const row = await db
+    .prepare("SELECT * FROM oauth_tokens WHERE server_name = ?")
+    .bind(serverName)
+    .first<OAuthTokenRow>();
+
+  if (!row) {
+    return { error: `no OAuth tokens found for "${serverName}". Re-run npx create-multicast to authorize.` };
+  }
+
+  const nowSeconds = Math.floor(Date.now() / 1000);
+
+  // Token still valid (with 60s buffer)
+  if (row.expires_at > nowSeconds + 60) {
+    return { auth: `Bearer ${row.access_token}` };
+  }
+
+  // Token expired — try to refresh
+  if (!row.refresh_token) {
+    return { error: `OAuth token expired for "${serverName}" and no refresh token available. Re-run npx create-multicast to re-authorize.` };
+  }
+
+  try {
+    const refreshResponse = await fetch(row.token_endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: row.refresh_token,
+        client_id: row.client_id,
+      }).toString(),
+    });
+
+    if (!refreshResponse.ok) {
+      return { error: `OAuth token refresh failed for "${serverName}": HTTP ${refreshResponse.status}. Re-run npx create-multicast to re-authorize.` };
+    }
+
+    const tokenData = (await refreshResponse.json()) as {
+      access_token: string;
+      refresh_token?: string;
+      expires_in?: number;
+    };
+
+    const newExpiresAt = nowSeconds + (tokenData.expires_in || 3600);
+
+    // Update D1 with new tokens
+    await db
+      .prepare(
+        `UPDATE oauth_tokens
+         SET access_token = ?, refresh_token = ?, expires_at = ?, updated_at = datetime('now')
+         WHERE server_name = ?`
+      )
+      .bind(
+        tokenData.access_token,
+        tokenData.refresh_token || row.refresh_token,
+        newExpiresAt,
+        serverName
+      )
+      .run();
+
+    return { auth: `Bearer ${tokenData.access_token}` };
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : "unknown error";
+    return { error: `OAuth token refresh failed for "${serverName}": ${message}` };
+  }
+}
+
 // ── 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[],
+  db?: D1Database
 ): Promise<CallResult> {
   const start = Date.now();
   const controller = new AbortController();
@@ -71,7 +174,21 @@ async function callMcpServer(
       "Content-Type": "application/json",
       "Accept": "application/json, text/event-stream",
     };
-    if (server.auth) {
+
+    // Resolve auth: static header OR OAuth token from D1
+    if (server.isOAuth && db) {
+      const oauthResult = await resolveOAuthToken(server.name, db);
+      if (oauthResult.error) {
+        return {
+          server: server.name,
+          tool,
+          success: false,
+          error: oauthResult.error,
+          duration_ms: Date.now() - start,
+        };
+      }
+      baseHeaders["Authorization"] = oauthResult.auth!;
+    } else if (server.auth) {
       baseHeaders["Authorization"] = server.auth;
     }
 
@@ -110,7 +227,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 +339,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 +633,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 +680,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 +714,7 @@ Example:
           server: RegisteredServer;
           tool: string;
           args: Record<string, unknown>;
+          setup?: ToolStep[];
         }> = [];
 
         for (const call of calls) {
@@ -485,18 +732,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
+        // Pass db for OAuth token resolution
+        const db = this.env.DB;
         const promises = validCalls.map((call) =>
-          callMcpServer(call.server, call.tool, call.args, timeout)
+          callMcpServer(call.server, call.tool, call.args, timeout, call.setup, db)
         );
 
         const settled = await Promise.allSettled(promises);
 
-        const results: CallResult[] = [
+        // 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 +773,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 +879,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
+              ),
+            },
+          ],
+        };
+      }
+    );
   }
 }