@superblocksteam/gateway 2.0.155-next.0

package/dist/transports/mcp/mount.js

@@ -0,0 +1,469 @@
+import { randomUUID } from "node:crypto";
+import { registerAppResource, registerAppTool, RESOURCE_MIME_TYPE, } from "@modelcontextprotocol/ext-apps/server";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ElicitResultSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { checkAppProgress, editApp, getApp, importApp, previewApp, publishApp, startApp, } from "../../capabilities/lifecycle.js";
+import { IMPORT_ZIP_BASE64_MAX_CHARS } from "../../capabilities/types.js";
+import { BROWSER_DRIVER_INSTRUCTIONS } from "../../capture/browser-instructions.js";
+import { captureLibraryScreenshotWithPlaywright } from "../../capture/capture-library.js";
+import { gatewayDebug, gatewayDebugStack } from "../../debug.js";
+import { EVENT_CURSOR_VERSION, parseEventCursor } from "../../events/cursor.js";
+import { EVENT_PRODUCERS } from "../../events/types.js";
+import { capturePreviewScreenshotWithPlaywright } from "../../preview/capture-screenshot.js";
+import { registerAdminTools } from "./admin-tools.js";
+import { APP_STATUS_HTML, APP_STATUS_RESOURCE_URI } from "./app-status-html.js";
+import { clientSupportsFormElicitation, pendingDecision, resolveDecisionByElicitation, } from "./decision-elicitation.js";
+import { formatMcpToolContent } from "./format-tool-content.js";
+import { createProgressNotifier } from "./progress-notifier.js";
+/**
+ * Optional composite progress cursor a host may hand back on
+ * `check_app_progress`.
+ *
+ * Kept deliberately loose at the schema boundary: `parseEventCursor` is the
+ * authority for version and per-producer positions. A foreign or corrupt
+ * cursor must fall through to the caller's stored place rather than fail the
+ * tool call — otherwise a host that cached an older shape would permanently
+ * stall.
+ */
+const eventCursorInputSchema = z
+    .object({
+    streams: z.record(z.string(), z.unknown()).optional(),
+    version: z.unknown().optional(),
+})
+    .passthrough()
+    .describe(`Optional composite resume cursor from a previous check_app_progress or get_app result. Shape: { version: ${EVENT_CURSOR_VERSION}, streams: { ${EVENT_PRODUCERS.join("?: number, ")}?: number } }. There is no global sequence — each producer (dev_server, sabs) has its own position. Omit to resume from the gateway's per-caller stored place. A cursor from an older contract or with bad positions is ignored and the stored place is used instead.`);
+/**
+ * Builds the principal from the CLI session this Gateway was started with.
+ * Identity is the already-logged-in Superblocks user; there is no second PAT
+ * and no OAuth authInfo on stdio.
+ *
+ * When `cliIdentity` is already known, it is handed over fully resolved so no
+ * capability spends a `/users/me` round trip (ENG-5806). Otherwise
+ * `ensurePrincipal` resolves it once through the guarded identity read.
+ */
+function principalFrom(deps) {
+    return {
+        apiKey: deps.cliApiKey,
+        ...(deps.cliIdentity ?? {}),
+    };
+}
+/**
+ * Who is polling, for the purpose of keeping their place in a build's stream.
+ *
+ * Stdio is a single-user process owned by the MCP host, so every tool call
+ * shares this stable id. The value is never stored as-is; the progress store
+ * hashes it.
+ */
+function callerFrom() {
+    return { channel: "mcp", id: "cli" };
+}
+/**
+ * Told to the model on connect, so it can match what a user actually says
+ * against these tools.
+ *
+ * People refer to this one system as the product and builder ("Superblocks")
+ * or by an older name for that same builder ("Clark"). Listing that accepted
+ * alias here is what lets "get Clark to build me a to-do app" reach
+ * `start_app`. Recognizing a name and using it are different things: the alias
+ * is input-only, because a client that reads "Clark" here repeats it back and
+ * reintroduces the retired name to the user.
+ */
+const SERVER_INSTRUCTIONS = `Superblocks builds, edits, and publishes internal web applications. Prompts sent through these tools are handed to Superblocks, which writes the application code in a live-edit session.
+
+Name the builder "Superblocks" in every word you write. Users sometimes call it "Clark", an older name for this same system: understand them, and answer about Superblocks. Never write "Clark" yourself — not as a name, not as an aside, not even when the user just used it, and never as a separate agent or persona. If Superblocks' own words come back naming Clark, relay the substance and say Superblocks.
+
+Use these tools whenever the user asks to build, change, import, or ship an app, whichever of those names they reach for.
+
+- start_app: create a new application and hand a prompt to Superblocks. Returns as soon as Superblocks accepts, with status "building". Superblocks names it unless a name is given.
+- import_app: import an existing app from a ZIP (or .tgz/.gz) into Superblocks and start a Superblocks migration. Pass the archive's file name as zipPath — the gateway opens the file on this machine itself. Archives larger than 1 MB are rejected — they almost certainly include node_modules; re-export without install artifacts. Optional prompt carries extra intent (e.g. "make it more secure"). Returns like start_app with status "building".
+- edit_app: send a follow-up prompt (including the answer when Superblocks asked a question) for an existing application. Also returns at status "building". Defaults to the most recent app, so an applicationId is only needed to target a different app.
+- check_app_progress: wait for the next thing Superblocks does and return it. It returns the moment Superblocks says anything, and after ~10 seconds of silence at the latest. "activity" holds Superblocks' own words since the previous call, in order; a quiet poll still returns a short heartbeat with elapsedSeconds.
+- get_app: return editor and preview URLs for the recent or specified app (builds a private preview when needed). Prefer this after status "ready" so the user can open the live app. Hosts that support MCP Apps show the status card (Open editor / Open preview) on this call — not on check_app_progress or preview_app — so only one card opens. When Superblocks has written code the tool includes a screenshot: the live Vite canvas (library peer) if a held session exists, otherwise the signed-in preview. Never open canvas.doNotOpen (the edit URL) to take that screenshot. It refuses to build a preview of an app Superblocks has not written yet: while a plan or question is outstanding it returns status "needs_decision" with "pendingAction", while a turn is running it returns status "building", and when the last turn ended without writing anything it returns that turn's status ("timeout", "live_edit_terminated", "no_changes" or "cancelled") with pendingAction "retry_build". In each case there are no preview URLs and no screenshot — do the pendingAction first rather than calling get_app again.
+- preview_app: build the application's current work and return a URL that runs it, without deploying it — the editor's Preview button. Nobody else can reach a preview. Text/markdown only (no MCP Apps widget); use get_app instead when you want the status card.
+- publish_app: deploy an application and wait until it is live. It commits the current work first, so a commitId is only needed to publish an earlier commit.
+
+A build takes two to four minutes, and start_app/edit_app/import_app return within seconds — long before it is done. After any of them, call check_app_progress within about 10 seconds so a plan or question surfaces quickly. Once the plan is approved and Superblocks is building the app, space later polls about 30 seconds apart (honor "nextPollAfterMs" when present) — a 10-second cadence on a multi-minute build burns through the host's tool-call budget. A "nextPollAfterMs" of 0 means nothing is in flight: stop polling rather than calling again immediately. "remainingTurnBudgetMs" appears only while this gateway is following the turn itself and can see its clock, so never read a missing budget as a fresh one — but do not read it as a reason to stop either. A build this gateway is not itself timing reports "building" with no budget, and "status" and "nextPollAfterMs" are what say whether to keep polling. Never claim the app is built while status is "building".
+
+The user sees nothing at all while a tool call is outstanding, so between two calls always write out the new "activity" lines as a short message in your own reply — quote or paraphrase them, oldest first, before calling check_app_progress again. Do not batch them up for a summary at the end, and do not go two calls in a row without writing something: the point of the loop is that the user watches the build happen. When a call comes back with only a heartbeat (no new Superblocks words), say Superblocks is still working and how long it has been going, then poll again.
+
+status "ready" means the turn finished: report the "reply" field, then call get_app (not preview_app as well — calling both used to open two widgets) so the user gets Open preview / an https link or a screenshot. status "needs_decision" means Superblocks is waiting — often with a plan — so stop polling and put the decision to the user. When "decision.kind" is "plan", show the plan markdown, then invite them to build it as written or say what to change — the same fork the editor's Build-it button offers. Ask that as an ordinary closing question in your own words; do not turn it into a numbered or bulleted menu, and do not wrap the choices in quotation marks. When they say "Build it", "approve", "looks good", or "go ahead", you MUST call edit_app with planAction "approve" and omit prompt (do not re-send the plan, and do not put "approve" or "Build it" in the prompt field — that is refine feedback to Superblocks, not the editor Build-it path). When they want changes, call edit_app with planAction "refine" and their feedback as prompt. When "decision.kind" is "multi_choice", relay the question and options and send their answer with edit_app. Do not claim the app is built while status is "needs_decision". status "no_changes" means the Superblocks job ended without building anything: relay reply, say no app was built, and do not present the edit URL as a finished app. status "live_edit_terminated" means the live-edit session that was to run the turn died before it built anything, or never opened at all — the prompt was fine and nothing timed out, so relay reply, tell the user the session did not survive, and offer to send the same instruction again with edit_app. status "detached" means Superblocks is still working but the gateway can no longer see it — usually because the app is open in a browser editor, which takes over Superblocks updates. Stop polling, say so, and point the user at the edit URL. status "unknown" means nothing is in flight for that app. A checkpointCommitId means Superblocks work is saved and the edit URL opens the finished app; when viewStatus is unknown, say the app may still be finishing in the editor.
+
+start_app, edit_app, and import_app default to Plan mode (Superblocks proposes a plan before writing). Pass mode "BUILD" only when the user asks to skip planning and build immediately. Approving a plan after start_app or import_app is always a follow-up edit_app with planAction "approve" — never a second start_app/import_app with prompt "approve". Once the app has run in Build mode, later edit_app calls stay in Build mode on their own: you do not need to re-send mode "BUILD", and a new instruction is not a fresh planning round. Send mode "PLAN" only when the user explicitly asks to plan again before building. Every start_app / edit_app / import_app result reports the "mode" the turn ran in, so you can tell the user whether Superblocks is planning or building rather than guessing — and if a result comes back "PLAN" after a long gap, the build session was recycled rather than the user asking to plan, so pass mode "BUILD" again to carry on building. editUrl / previewUrl / publishUrl may appear in structured JSON for openLink buttons — do not dump raw URLs (especially preview JWTs) into the chat. Prefer the MCP Apps Open editor / Open preview buttons from get_app. Claude Desktop can only openLink https URLs; when previewUrl is http, say so briefly and rely on any screenshot image the tool returned rather than pasting the URL.
+
+Once a build reaches "ready", call get_app so the user can open the app, then offer publish_app to deploy for their organization when they ask. Prefer get_app over preview_app after a build — get_app already ensures a private preview and is the only tool that opens the MCP Apps status card. Only publish when the user asks. If preview_app or get_app comes back with status "building", the URL is already correct; tell the user it is still building and call again to check.
+
+There is nothing to preview until Superblocks has written code, so get_app is not the way out of a plan, a question, or a turn that failed. When it answers status "needs_decision" (pendingAction "approve_plan" or "answer_question"), the app is still the empty starter template: put the decision to the user, send their answer with edit_app, and only call get_app once a turn has finished. When it answers "timeout", "live_edit_terminated", "no_changes" or "cancelled" with pendingAction "retry_build", that turn built nothing: tell the user so plainly, and send the instruction again with edit_app if they want to retry. Repeating get_app instead opens another status card and tells the user nothing new.
+
+Superblocks tests what it builds: it opens the app in a browser and runs its APIs, and the test run arrives as ordinary "activity" lines ("Testing the orders page", "Test passed: …", "Tests failed: …"). Relay those lines like any other activity, and say which cases passed and which failed — a test run is the only evidence the user has that the app actually works. A failing test is a build signal, not an auth problem: it means the app has a bug Superblocks is about to work on, so keep polling and never tell the user to sign in again or re-enter credentials over one.
+
+A failed call still names the application it was working on. start_app and import_app create the application before the build can start, so an error from either one leaves an application that exists and belongs to this conversation, and the error says which: read the "applicationId" field, never a UUID out of the message text. Never take an error to mean nothing happened. Do not answer a failed start_app with a second start_app — that abandons the app you already have and creates a duplicate. When the error carries pendingAction "retry_build" — a "live_edit_unavailable" session that would not open, or a turn that ran out of budget — send the same prompt again with edit_app and that applicationId. A failed import_app carries no such recovery, because edit_app cannot resupply the archive the migration prompt reads: that application is empty and nothing can continue it in place, so name it to the user and let them decide whether to import again. Every edit_app error names its applicationId too, which is the one place to see which app a call that omitted the id actually ran on.
+
+Prompts are forwarded to Superblocks verbatim — pass the user's wording rather than a summary.
+
+This connector is the single Superblocks MCP: Builder tools (start_app, import_app, edit_app, check_app_progress, get_app, preview_app, publish_app) and Admin tools (integrations, apps, users, folders, deploy_application, and the rest of the customer Admin surface) share this endpoint. Prefer create_integration / update_integration / list_integrations here when Superblocks needs a missing Postgres, REST, or other datasource — do not send the user to a second MCP. create_integration is Admin CRUD for org datasources; start_app creates a new application and hands a prompt to Superblocks. deploy_application is Admin deploy of an existing commit; publish_app is the Builder path that commits current work and waits until the app is live. Omit base_url on Admin tools unless targeting a different control plane — the gateway injects its configured Server URL. checkout_application is not exposed on this network surface (host filesystem writes); use the CLI/workspace checkout path instead.
+
+This connection is already authenticated and already pointed at one Superblocks Server, so there is no setup, login, or auth-status call to make first. Call the tool that does the job — list_integrations to see the org's datasources, start_app to create an application — and read its error if something is genuinely wrong. Do not look for a tool that reports credentials or environments; there is none, and asking for one costs the user a turn.
+
+This MCP also discovers integrations mid-build and runs live integration queries (username/password and other stored credentials) through the orchestrator. When an integration needs interactive IdP/OAuth login, the tool error will say to authenticate in the Superblocks editor (edit URL) and retry — only follow that when the error says so. A 401 AuthorizationError from an orchestrator execute path is Superblocks/orchestrator auth (the scoped JWT or selected profile), not Snowflake username/password — never advise verifying or re-entering the Snowflake password, account, or other stored credentials in the integrations UI for that error. Only advise credential edits when an error from Snowflake itself clearly says stored credentials failed or a connection test failed. Do not tell the user to re-authenticate for Snowflake SQL permission wording ("does not exist or not authorized") or OpenAI API key failures. If status later reaches "ready" and the user can open the app, do not lead with or alarm on mid-build testApi orchestrator 401s unless the user asks about data or API failures — prefer "build succeeded" and mention a transient API check only if asked.
+
+For import_app, the archive never travels through you. A file the user attached to the chat sits in your own sandbox, which this gateway cannot read, but the user downloaded that same file to this machine and the gateway looks for it by name where downloads land. So pass zipPath — the full path if you have a real one for this machine, otherwise the attachment's file name, which is all the gateway needs. The gateway only opens archives that sit in the folders its operator allowed, so if it answers that it will not read the path you gave, ask the user to move the archive into one of the folders it names. Never write the archive out as base64: it costs thousands of tokens, takes minutes, and the call is rejected before it runs.
+
+${BROWSER_DRIVER_INSTRUCTIONS}`;
+/**
+ * The MCP server behind one stdio session.
+ *
+ * Tools run as the already-logged-in CLI user. There is no per-request OAuth
+ * token to expire independently of the process.
+ */
+export function createMcpServer(deps) {
+    const context = async (progress, notify, signal) => ({
+        caller: callerFrom(),
+        captureLibraryScreenshot: captureLibraryScreenshotWithPlaywright,
+        capturePreviewScreenshot: capturePreviewScreenshotWithPlaywright,
+        config: deps.config,
+        events: deps.events,
+        onProgress: (event) => {
+            progress.push(event);
+            notify?.(event.message);
+        },
+        principal: principalFrom(deps),
+        progressCursors: deps.progressCursors,
+        recentApps: deps.recentApps,
+        server: deps.server,
+        sessionPeer: deps.sessionPeer,
+        ...(signal ? { signal } : {}),
+        turns: deps.turns,
+    });
+    /**
+     * Runs a capability and renders it as tool content. An unexpected throw
+     * becomes an error result rather than taking the process down, and carries
+     * its own message: this catch cannot tell which downstream failed, and
+     * naming one it did not diagnose points the reader at a healthy system.
+     */
+    const run = async (toolName, capability, extra) => {
+        gatewayDebugStack("tool started", { "tool.name": toolName });
+        const progress = [];
+        const notify = createProgressNotifier(extra);
+        let result;
+        if (!deps.cliApiKey) {
+            gatewayDebug("tool short-circuited", {
+                "tool.name": toolName,
+                "tool.reason": "missing_cli_session",
+            });
+            result = {
+                kind: "error",
+                code: "unauthenticated",
+                message: "This Gateway has no CLI session. Run: superblocks login",
+            };
+        }
+        else {
+            try {
+                // The SDK aborts this on `notifications/cancelled` and on a dropped
+                // connection. Handing it to the capability is what turns "the host
+                // stopped listening" into "stop waiting", instead of leaving a timer
+                // and a waiter running for an answer nobody will read.
+                const signal = extra?.signal;
+                const capabilityContext = await context(progress, notify, signal);
+                result = await capability(capabilityContext, () => {
+                    for (let index = progress.length - 1; index >= 0; index -= 1) {
+                        if (progress[index]?.type === "completed") {
+                            progress.splice(index, 1);
+                        }
+                    }
+                });
+            }
+            catch (error) {
+                console.error("gateway capability failed", error);
+                result = {
+                    kind: "error",
+                    code: "capability_failed",
+                    message: error instanceof Error
+                        ? error.message
+                        : "The gateway failed for an unknown reason.",
+                };
+            }
+        }
+        const resultStatus = result.kind === "ok" &&
+            result.value &&
+            typeof result.value === "object" &&
+            "status" in result.value &&
+            typeof result.value.status === "string"
+            ? result.value.status
+            : undefined;
+        gatewayDebug("tool finished", {
+            "progress.event_count": progress.length,
+            ...(result.kind === "error" ? { "result.code": result.code } : {}),
+            "result.kind": result.kind,
+            ...(resultStatus ? { "result.status": resultStatus } : {}),
+            "tool.name": toolName,
+        });
+        // structuredContent lets MCP Apps hosts hand the capability value to the
+        // status card without making it re-parse the JSON text block.
+        const structuredContent = result.kind === "ok" &&
+            result.value &&
+            typeof result.value === "object" &&
+            !Array.isArray(result.value)
+            ? (() => {
+                const value = { ...result.value };
+                delete value.screenshotBase64;
+                return value;
+            })()
+            : undefined;
+        return {
+            content: formatMcpToolContent(result, progress),
+            ...(structuredContent ? { structuredContent } : {}),
+        };
+    };
+    const server = new McpServer({
+        name: "superblocks",
+        // The product the user is thinking of, not the implementation process
+        // serving it. The client shows this string.
+        title: "Superblocks",
+        version: "0.0.1",
+    }, { instructions: SERVER_INSTRUCTIONS });
+    /**
+     * A progress poll that also puts a decision to the user as a native form when
+     * the host supports one, answering Superblocks itself and returning the turn
+     * that follows. Hosts without form elicitation (Claude Desktop today) get the
+     * decision back as data and ask the user in chat.
+     */
+    const progressWithDecisionForm = async (context, input, extra, forgetFinishedTurn) => {
+        gatewayDebug("progress decision flow started", {
+            "application.id": input.applicationId,
+            "progress.cursor_provided": Boolean(input.cursor),
+        });
+        const result = await checkAppProgress(context, input);
+        const decision = pendingDecision(result);
+        if (!decision) {
+            gatewayDebug("progress decision flow finished", {
+                "decision.resolved": false,
+                "decision.reason": "no_pending_decision",
+            });
+            return result;
+        }
+        if (!clientSupportsFormElicitation(server.server.getClientCapabilities())) {
+            gatewayDebug("progress decision flow finished", {
+                "decision.kind": decision.kind,
+                "decision.resolved": false,
+                "decision.reason": "form_unsupported",
+            });
+            return result;
+        }
+        const resolved = await resolveDecisionByElicitation({
+            apply: (answer) => {
+                forgetFinishedTurn();
+                return editApp(context, {
+                    applicationId: input.applicationId,
+                    idempotencyKey: `mcp-decision:${randomUUID()}`,
+                    wait: "ack",
+                    ...(answer.kind === "approve"
+                        ? { planAction: "approve" }
+                        : answer.kind === "refine"
+                            ? { planAction: "refine", prompt: answer.feedback }
+                            : { prompt: answer.prompt }),
+                });
+            },
+            decision,
+            // Sent through the tool call's own extra so it rides that call's response
+            // stream: a request the gateway raises on its own goes to the standalone
+            // stream instead, which a host that never opened one silently drops,
+            // leaving the tool call waiting for an answer that cannot arrive.
+            elicit: (request) => extra.sendRequest({ method: "elicitation/create", params: request }, ElicitResultSchema),
+        });
+        gatewayDebug("progress decision flow finished", {
+            "decision.kind": decision.kind,
+            "decision.resolved": Boolean(resolved),
+            "decision.reason": resolved ? "answered" : "left_in_chat",
+        });
+        return resolved ?? result;
+    };
+    // Cloud-Prem Admin laptop agent: this machine has no Playwright Chromium
+    // and never opens a live-edit session, so the Builder surface (start_app,
+    // edit_app, ...) is skipped entirely rather than registered and left to
+    // fail on its first call.
+    if (!deps.config.adminToolsOnly) {
+        gatewayDebug("builder tool registration selected", {
+            "gateway.admin_tools_only": false,
+        });
+        registerBuilderTools();
+    }
+    else {
+        gatewayDebug("builder tool registration skipped", {
+            "gateway.admin_tools_only": true,
+        });
+    }
+    function registerBuilderTools() {
+        server.registerTool("start_app", {
+            description: 'Create a Superblocks application and hand a prompt to Superblocks in Plan mode by default. Returns as soon as Superblocks accepts, with status "building" and an edit URL; follow with check_app_progress until status is no longer "building". When Superblocks returns needs_decision with a plan and the user says "Build it", call edit_app with planAction "approve" (omit prompt) — do not call start_app again with prompt "approve". Pass mode "BUILD" to skip planning. Superblocks names the application unless name is given. An error from this tool does not mean nothing happened: the application is created before the build starts, so the error names it in "applicationId". Retry that app with edit_app rather than calling start_app another time, which would leave the first one abandoned.',
+            inputSchema: {
+                branch: z.string().optional(),
+                idempotencyKey: z.string().optional(),
+                mode: z.enum(["BUILD", "PLAN"]).optional(),
+                name: z.string().min(1).optional(),
+                prompt: z.string().min(1),
+            },
+            // Named for what a user asks for ("create an app"), not for the verb in
+            // the tool name: a host that ranks tools by title has to be able to find
+            // this one from the request.
+            title: "Create Superblocks App",
+        }, async ({ branch, idempotencyKey, mode, name, prompt }, extra) => run("start_app", (context) => startApp(context, {
+            branch,
+            idempotencyKey: idempotencyKey ?? `mcp-start:${randomUUID()}`,
+            mode,
+            name,
+            prompt,
+            // MCP clients get the polling loop, not a blocking call: Claude
+            // Desktop sends no progressToken, so a call that waits out the whole
+            // build shows the user nothing until it returns.
+            wait: "ack",
+        }), extra));
+        server.registerTool("import_app", {
+            description: 'Import an existing app from a ZIP/.tgz/.gz archive into Superblocks and start a Superblocks migration. Pass the archive\'s file name (or its full path on this machine) as zipPath: the gateway reads the file itself, so a path from your own sandbox is fine as long as the name matches the file the user has. Never encode the archive as base64 — zipBase64 only carries test fixtures. Archives larger than 1 MB are rejected — exclude node_modules. Optional prompt adds intent such as hardening security. Returns status "building"; follow with check_app_progress. Defaults to Plan mode — when Superblocks returns a plan and the user says "Build it", call edit_app with planAction "approve" (omit prompt); do not call import_app again with prompt "approve". An error from this tool does not mean nothing happened: the application is created before the migration starts, so the error names it in "applicationId". That application is empty — the migration never ran — and nothing can continue it in place, so say it exists and let the user decide whether to import again rather than silently retrying.',
+            inputSchema: {
+                branch: z.string().optional(),
+                idempotencyKey: z.string().optional(),
+                mode: z.enum(["BUILD", "PLAN"]).optional(),
+                name: z.string().min(1).optional(),
+                prompt: z.string().min(1).optional(),
+                source: z
+                    .enum([
+                    "chatgpt",
+                    "claude",
+                    "claude-design",
+                    "lovable",
+                    "replit",
+                    "streamlit",
+                    "v0",
+                    "zip",
+                ])
+                    .optional(),
+                zipBase64: z
+                    .string()
+                    .min(1)
+                    .max(IMPORT_ZIP_BASE64_MAX_CHARS)
+                    .optional(),
+                zipPath: z.string().min(1).optional(),
+            },
+            title: "Import App",
+        }, async ({ branch, idempotencyKey, mode, name, prompt, source, zipBase64, zipPath, }, extra) => run("import_app", (context) => importApp(context, {
+            branch,
+            idempotencyKey: idempotencyKey ?? `mcp-import:${randomUUID()}`,
+            mode,
+            name,
+            prompt,
+            source,
+            wait: "ack",
+            zipBase64,
+            zipPath,
+        }), extra));
+        server.registerTool("edit_app", {
+            description: 'Forward a prompt to Superblocks for the recent or specified application. Defaults to Plan mode until the app has run in Build mode; after that later edits keep building directly — you do not need to pass mode again. Pass mode "PLAN" only when the user explicitly asks to plan before building. The result reports the "mode" the turn ran in; a "PLAN" result after a long gap means the build session was recycled, so pass mode "BUILD" again rather than treating it as a new planning round. When status was needs_decision with a plan and the user says "Build it" / approve / go ahead, call edit_app with planAction "approve" and omit prompt — do not put "approve" or "Build it" in prompt (that is refine feedback, not the Build-it path). Use planAction "refine" with their feedback as prompt to change the plan. Also use edit_app to answer multi_choice questions. Returns status "building"; follow with check_app_progress.',
+            inputSchema: {
+                applicationId: z.string().uuid().optional(),
+                branch: z.string().optional(),
+                idempotencyKey: z.string().optional(),
+                mode: z.enum(["BUILD", "PLAN"]).optional(),
+                planAction: z.enum(["approve", "refine"]).optional(),
+                prompt: z.string().min(1).optional(),
+            },
+            title: "Edit App",
+        }, async ({ applicationId, branch, idempotencyKey, mode, planAction, prompt }, extra) => run("edit_app", (context) => editApp(context, {
+            applicationId,
+            branch,
+            idempotencyKey: idempotencyKey ?? `mcp-edit:${randomUUID()}`,
+            mode,
+            planAction,
+            prompt,
+            wait: "ack",
+        }), extra));
+        server.registerTool("check_app_progress", {
+            description: 'Wait for the next thing Superblocks does on the recent or specified application and return it: "activity" carries Superblocks\' words since the previous call (or a short heartbeat when Superblocks is quiet), and status is "building" while the app is still being generated. Returns as soon as Superblocks says anything, and after ~10 seconds of silence at the latest. Call within about 10 seconds of start_app, import_app, or edit_app so a plan or question surfaces quickly. Once the plan is approved and Superblocks is building, space later polls about 30 seconds apart (honor "nextPollAfterMs" when present) until status is no longer "building" — a 10-second cadence on a multi-minute build burns through the host\'s tool-call budget. Relay each new activity line to the user between calls. When status becomes "needs_decision", stop polling and put the decision to the user — for a plan, show it and ask whether to build it or say what to change; for multi_choice, relay the question and options. Hosts that support form elicitation get a native picker instead, and this tool then returns the answered turn. When status becomes "ready", follow with get_app so the user can open the preview. Progress is text-only (no MCP Apps widget) so each poll does not reopen a blank card. Optional "cursor" from a prior result resumes from that composite position (per producer, no global sequence); omit it to use the gateway\'s stored place for this caller.',
+            inputSchema: {
+                applicationId: z.string().uuid().optional(),
+                cursor: eventCursorInputSchema.optional(),
+            },
+            title: "Check App Progress",
+        }, async ({ applicationId, cursor }, extra) => run("check_app_progress", (context, forgetFinishedTurn) => {
+            // Validate at the boundary so a foreign/corrupt cursor falls back
+            // to the stored place instead of failing the tool call.
+            const parsed = cursor === undefined ? undefined : parseEventCursor(cursor);
+            gatewayDebug("progress cursor parsed", {
+                "progress.cursor_provided": cursor !== undefined,
+                "progress.cursor_valid": Boolean(parsed),
+            });
+            return progressWithDecisionForm(context, {
+                applicationId,
+                ...(parsed ? { cursor: parsed } : {}),
+            }, extra, forgetFinishedTurn);
+        }, extra));
+        registerAppTool(server, "get_app", {
+            description: 'Return editor and preview URLs for the recent or specified Superblocks application. Ensures a private preview build by default (same as preview_app), but only once Superblocks has something to show: while a plan or question is outstanding it returns status "needs_decision" with the "decision" and a "pendingAction" of "approve_plan" or "answer_question", while a turn is running it returns status "building", and when the last turn ended without writing anything it returns "timeout", "live_edit_terminated", "no_changes" or "cancelled" with pendingAction "retry_build" — no preview URLs and no screenshot in any of those cases, because the app is still the empty starter template. Act on "pendingAction" through edit_app instead of calling this again. Prefer this after check_app_progress reaches status "ready". Also the right call when you do not know where a build stands — after a reconnect, when no turn of yours is running, or when the conversation moved to another channel: pass wait false and read "status" and "cursor" from the result rather than guessing. Hosts that support MCP Apps show Open editor / Open preview buttons. When Superblocks has written code the result includes a screenshot of the live Vite canvas if a held session exists, otherwise the signed-in preview — never the edit URL.',
+            inputSchema: {
+                applicationId: z.string().uuid().optional(),
+                branch: z.string().optional(),
+                ensurePreview: z.boolean().optional(),
+                wait: z
+                    .boolean()
+                    .optional()
+                    .describe('Whether to wait for the preview build. Defaults to true. Pass false to get the URLs and current status straight away, with "nextPollAfterMs" telling you when to look again — use that whenever you just need to know where things stand. This is a boolean and has nothing to do with the "ack" wait on start_app / edit_app.'),
+            },
+            title: "Get App",
+            _meta: {
+                ui: { resourceUri: APP_STATUS_RESOURCE_URI },
+            },
+        }, async ({ applicationId, branch, ensurePreview, wait }, extra) => run("get_app", (context) => getApp(context, { applicationId, branch, ensurePreview, wait }), extra));
+        server.registerTool("preview_app", {
+            description: 'Build the recent or specified Superblocks application\'s current work and return a URL that runs it, without deploying it — the same thing the editor\'s Preview button does. Only the user can open it. Status "ready" means the URL works now; "building" means the build is still running and calling again resumes watching it. Prefer get_app when you want the MCP Apps status card (Open editor / Open preview); this tool returns the same URLs as text/markdown without opening a second widget.',
+            inputSchema: {
+                applicationId: z.string().uuid().optional(),
+                branch: z.string().optional(),
+            },
+            title: "Preview App",
+        }, async ({ applicationId, branch }, extra) => run("preview_app", (context) => previewApp(context, { applicationId, branch }), extra));
+        // Nested iframes were removed (auth + Private Network Access). Empty
+        // frameDomains keeps the MCP Apps CSP shape without advertising embed origins.
+        const uiCsp = { csp: { frameDomains: [] } };
+        registerAppResource(server, "Gateway app status", APP_STATUS_RESOURCE_URI, {
+            description: "Status card with Open editor / Open preview / Publish app",
+            mimeType: RESOURCE_MIME_TYPE,
+            _meta: { ui: uiCsp },
+        }, async () => ({
+            contents: [
+                {
+                    uri: APP_STATUS_RESOURCE_URI,
+                    mimeType: RESOURCE_MIME_TYPE,
+                    text: APP_STATUS_HTML,
+                    _meta: { ui: uiCsp },
+                },
+            ],
+        }));
+        server.registerTool("publish_app", {
+            description: "Publish/deploy the recent or specified Superblocks application and wait until it is live. Commits the application's current work first, so commitId is only needed to publish an earlier commit.",
+            inputSchema: {
+                applicationId: z.string().uuid().optional(),
+                branch: z.string().optional(),
+                commitId: z.string().optional(),
+                idempotencyKey: z.string().optional(),
+                prompt: z.string().min(1),
+            },
+            title: "Publish App",
+        }, async ({ applicationId, branch, commitId, idempotencyKey, prompt }, extra) => run("publish_app", (context) => publishApp(context, {
+            applicationId,
+            branch,
+            commitId,
+            idempotencyKey: idempotencyKey ?? `mcp-publish:${randomUUID()}`,
+            prompt,
+        }), extra));
+    }
+    // Customer Admin tools (integrations, apps, users, deploy_application, ...)
+    // on the same MCP surface. Credential is the CLI session this process
+    // started with; base_url defaults to this gateway's Server URL.
+    registerAdminTools(server, {
+        apiKey: deps.cliApiKey,
+        localAgentMode: deps.config.localAgentMode,
+        serverUrl: deps.config.serverUrl,
+    });
+    return server;
+}
+//# sourceMappingURL=mount.js.map

package/dist/transports/mcp/mount.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount.js","sourceRoot":"","sources":["../../../src/transports/mcp/mount.ts"],"names":[],"mappings":"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"}

package/dist/transports/mcp/progress-notifier.d.ts

@@ -0,0 +1,39 @@
+import type { ProgressToken } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * The part of a tool call's `extra` a notifier needs: the token the host asked
+ * to be told about progress under, and the channel back to it.
+ */
+export type ProgressNotificationSender = {
+    _meta?: {
+        progressToken?: ProgressToken;
+    };
+    sendNotification: (notification: {
+        method: "notifications/progress";
+        params: {
+            message: string;
+            progress: number;
+            progressToken: ProgressToken;
+        };
+    }) => Promise<void>;
+};
+/**
+ * Relays a capability's progress to the host that asked for it, and survives
+ * that host going away.
+ *
+ * Progress rides the tool call's own response stream, so it lives exactly as
+ * long as the host keeps reading: cancel, disconnect, or simply walk away, and
+ * every later send on that stream fails. These sends are driven by SABS turn
+ * events, which arrive on a websocket callback - outside any request handler,
+ * and so outside the `guarded` wrapper that stops a failed request short of the
+ * top. Left alone, one such failure ends the process: the gateway dies because
+ * a single client stopped listening, taking every other session with it.
+ *
+ * Both failure shapes are handled because the SDK produces both. A transport
+ * holding no stream for the request throws before it returns a promise; one
+ * that fails mid-write rejects the promise it already returned.
+ *
+ * The first failure latches the notifier shut. A dropped stream does not come
+ * back, and a single turn emits progress continuously, so trying again only
+ * spends work to fail the same way.
+ */
+export declare function createProgressNotifier(extra: ProgressNotificationSender | undefined): ((message: string) => void) | undefined;

package/dist/transports/mcp/progress-notifier.js

@@ -0,0 +1,52 @@
+/**
+ * Relays a capability's progress to the host that asked for it, and survives
+ * that host going away.
+ *
+ * Progress rides the tool call's own response stream, so it lives exactly as
+ * long as the host keeps reading: cancel, disconnect, or simply walk away, and
+ * every later send on that stream fails. These sends are driven by SABS turn
+ * events, which arrive on a websocket callback - outside any request handler,
+ * and so outside the `guarded` wrapper that stops a failed request short of the
+ * top. Left alone, one such failure ends the process: the gateway dies because
+ * a single client stopped listening, taking every other session with it.
+ *
+ * Both failure shapes are handled because the SDK produces both. A transport
+ * holding no stream for the request throws before it returns a promise; one
+ * that fails mid-write rejects the promise it already returned.
+ *
+ * The first failure latches the notifier shut. A dropped stream does not come
+ * back, and a single turn emits progress continuously, so trying again only
+ * spends work to fail the same way.
+ */
+export function createProgressNotifier(extra) {
+    const progressToken = extra?._meta?.progressToken;
+    if (extra === undefined || progressToken === undefined) {
+        return undefined;
+    }
+    let progress = 0;
+    let listening = true;
+    const stopListening = (error) => {
+        listening = false;
+        // Said once per call rather than per event: a host that hung up is
+        // ordinary, but a silent gateway is what makes it hard to explain.
+        console.debug("gateway progress stream closed by the host", error);
+    };
+    return (message) => {
+        if (!listening) {
+            return;
+        }
+        progress += 1;
+        try {
+            void extra
+                .sendNotification({
+                method: "notifications/progress",
+                params: { message, progress, progressToken },
+            })
+                .catch(stopListening);
+        }
+        catch (error) {
+            stopListening(error);
+        }
+    };
+}
+//# sourceMappingURL=progress-notifier.js.map

package/dist/transports/mcp/progress-notifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-notifier.js","sourceRoot":"","sources":["../../../src/transports/mcp/progress-notifier.ts"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,sBAAsB,CACpC,KAA6C;IAE7C,MAAM,aAAa,GAAG,KAAK,EAAE,KAAK,EAAE,aAAa,CAAC;IAClD,IAAI,KAAK,KAAK,SAAS,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;QACvD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,SAAS,GAAG,IAAI,CAAC;IAErB,MAAM,aAAa,GAAG,CAAC,KAAc,EAAE,EAAE;QACvC,SAAS,GAAG,KAAK,CAAC;QAClB,mEAAmE;QACnE,mEAAmE;QACnE,OAAO,CAAC,KAAK,CAAC,4CAA4C,EAAE,KAAK,CAAC,CAAC;IACrE,CAAC,CAAC;IAEF,OAAO,CAAC,OAAe,EAAE,EAAE;QACzB,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,OAAO;QACT,CAAC;QACD,QAAQ,IAAI,CAAC,CAAC;QACd,IAAI,CAAC;YACH,KAAK,KAAK;iBACP,gBAAgB,CAAC;gBAChB,MAAM,EAAE,wBAAwB;gBAChC,MAAM,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE;aAC7C,CAAC;iBACD,KAAK,CAAC,aAAa,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,aAAa,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}