@cloudgrid-io/mcp 0.21.6 → 0.21.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.21.6",
+  "version": "0.21.8",
   "description": "MCP access to CloudGrid — the live runtime environment where the user's apps run WITH the infrastructure they need out of the box: managed MongoDB, Redis (cache/queues/pub-sub), a pgvector store, persistent disk, and built-in AI with no API keys, in any language or stack, no Docker or Kubernetes to manage. Brainstorm, build, plug, and improve apps, games, dashboards, and tools; instant single-page publishes and full runtime-app deploys with a live URL — for developers and non-technical users. Three editions: local stdio (full toolset), hosted web (light, CLI-free), and a public docs-search server.",
   "type": "module",
   "bin": {
@@ -36,6 +36,7 @@
     "test:mcpb-boot": "node test/mcpb-boot.test.mjs",
     "test:plug-timeout": "node test/plug-timeout.test.mjs",
     "test:manifest-confirm": "node test/manifest-confirm.test.mjs",
+    "test:inline-multifile-guard": "node test/inline-multifile-guard.test.mjs",
     "test:qa-courier": "node test/qa-courier.test.mjs",
     "test:drift-guard": "node test/drift-guard.mjs",
     "smoke:drop": "node test/smoke-drop.mjs",
@@ -68,15 +69,23 @@
     "test:web-identity": "node --test test/web-identity.test.mjs",
     "test:web-auth-integration": "node --test test/web-auth-integration.test.mjs",
     "test:web-restart-recovery": "node --test test/web-restart-recovery.test.mjs",
-    "test:web-capabilities-log": "node --test test/web-capabilities-log.test.mjs"
+    "test:web-capabilities-log": "node --test test/web-capabilities-log.test.mjs",
+    "test:internal-refs": "node --test test/no-internal-refs.test.mjs",
+    "test:login-app": "node test/login-app.test.mjs",
+    "test:login-poller": "node test/login-poller.test.mjs",
+    "build:login-widget": "node scripts/build-login-widget.mjs"
   },
   "dependencies": {
+    "@modelcontextprotocol/ext-apps": "^1.7.5",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "express": "^4.22.2",
     "fflate": "^0.8.3",
     "undici": "^8.10.0",
     "zod": "^3.23.0"
   },
+  "devDependencies": {
+    "esbuild": "^0.25.0"
+  },
   "license": "Apache-2.0",
   "homepage": "https://github.com/cloudgrid-io/mcp",
   "repository": {

package/src/tools/constants.js

@@ -53,17 +53,44 @@ export const VISIBILITY_LABELS = {
 // optional. Flip MCP_APPS_WIDGETS=1 in the platform manifest to re-enable once
 // the widget HTML is verified to render. The resources stay registered either
 // way (harmless when no tool references them via outputTemplate).
+//
+// 2026-08-25 (#308): the black frame was diagnosed as a MIME mismatch. ChatGPT
+// discovers an Apps-SDK widget by a tool carrying openai/outputTemplate PLUS a
+// ui:// resource whose mimeType is `text/html+skybridge` (verified against
+// OpenAI's shipped example servers — openai/openai-apps-sdk-examples
+// solar-system/shopping_cart/kitchen_sink main.py). Our two ChatGPT widgets
+// declared `text/html;profile=mcp-app` — the SEP-1865/MCP-Apps MIME that CLAUDE
+// reads (RESOURCE_MIME_TYPE in @modelcontextprotocol/ext-apps). ChatGPT saw the
+// outputTemplate pointer, opened the skybridge iframe (dark chrome), but the
+// resource was not a skybridge document, so the HTML/bridge never populated —
+// the empty dark frame covering the text. CHATGPT_WIDGET_MIME below is the
+// correct type. The flag STAYS OFF until a card is seen rendering in real
+// ChatGPT (Developer Mode custom connector against staging); this only makes the
+// machinery correct for that verification.
 export const APPS_WIDGETS_ENABLED = process.env.MCP_APPS_WIDGETS === "1";
+// The mimeType ChatGPT's Apps-SDK renderer requires for a ui:// widget resource.
+// Distinct from RESOURCE_MIME_TYPE (`text/html;profile=mcp-app`, the SEP-1865
+// key Claude reads) — the two hosts key off different MIME types, so the ChatGPT
+// widgets and the Claude sign-in card must NOT share one.
+export const CHATGPT_WIDGET_MIME = "text/html+skybridge";
 export const LIVE_RESULT_URI = "ui://cloudgrid/live-result.html";
 // URI/resource-name/filename stay `org-picker` — that's the stable contract the
 // web card is registered under; only the JS identifier moves toward grid.
 export const GRID_PICKER_URI = "ui://cloudgrid/org-picker.html";
 export const LIVE_RESULT_HTML = readFileSync(new URL("../widgets/live-result.html", import.meta.url), "utf-8");
 export const GRID_PICKER_HTML = readFileSync(new URL("../widgets/org-picker.html", import.meta.url), "utf-8");
-export const WIDGET_CSP = {
-  connectDomains: ["https://*.cloudgrid.io"],
-  resourceDomains: ["https://*.cloudgrid.io"],
-};
+
+// ── grid_login MCP App (SEP-1865, Claude web) ────────────────────────────────
+// A SECOND, independent UI mechanism from the ChatGPT Apps-SDK widgets above.
+// It is NOT gated behind MCP_APPS_WIDGETS: that flag controls only the
+// openai/outputTemplate key ChatGPT reads, and it must stay exactly as it is.
+// The login card binds via _meta.ui.resourceUri (the SEP-1865 key Claude reads),
+// which ChatGPT ignores — so shipping it does not touch the ChatGPT path. A
+// client without the UI extension ignores _meta.ui and still gets the text-first
+// sign-in URL. The HTML is the self-contained bundle from
+// scripts/build-login-widget.mjs (App class + card inlined; deny-by-default CSP).
+export const GRID_LOGIN_APP_URI = "ui://grid-login/mcp-app.html";
+export const GRID_LOGIN_APP_HTML = readFileSync(new URL("../widgets/grid-login.html", import.meta.url), "utf-8");
 
 // The lazy npx fallback always fetches the LATEST published CLI, so the MCP is
 // never left behind the platform's required CLI version (a pinned range went

package/src/tools/deploy.js

@@ -1480,6 +1480,51 @@ function plugErrorMessage(status, code, msg, ctxFlags = {}) {
   return guidance ? `${base} — ${guidance}` : base;
 }
 
+// ── WORKAROUND(#311): inline multi-file re-plug guard + FETCHSOURCE handoff ───
+// WHAT IS BROKEN: the hosted (web) server materializes the uploaded multipart
+// parts into a source tarball SERVER-SIDE; for a MULTI-FILE runtime app
+// re-plugged INLINE it emits a non-gzip stream that dies at the build container's
+// FETCHSOURCE with "gzip: stdin: not in gzip format / tar: Child returned status
+// 1" — raw, unactionable output that stranded a real user (natalys-grid). This
+// client never gzips/tars anything (it uploads each file as an octet-stream part
+// — see buildForm; byte-exactness proven in test), so the corruption is a
+// SERVER-SIDE defect downstream of this process; the disk-based CLI uploads the
+// same files and works.
+// WHAT WOULD LET THIS BE REMOVED: the API-side fix to tarball materialization for
+// this shape (tracked on #311). Until then, two defenses live here:
+//   1. detect the shape BEFORE upload (the gate in runPlug) and hand over the
+//      CLI commands with the real entity handle — never fail at the build.
+//   2. if a corrupt-archive build failure still slips through, rewrite the raw
+//      tar/gzip log to the same actionable handoff (archiveCorruptionSignature).
+
+// The "continue this exact entity from a terminal" CLI commands, with the real
+// handle substituted. Prefers grid/slug (what `pull` takes, human-readable);
+// falls back to the entity id. Same entity, same URL.
+export function cliContinueHandoff({ entityId, grid, slug } = {}) {
+  const target = grid && slug ? `${grid}/${slug}` : slug || entityId || "<grid>/<app>";
+  const dir = slug || entityId || "<app>";
+  return (
+    "Continue from a terminal with the CLI — it uploads the files from disk and updates the SAME entity (same URL):\n" +
+    "  npx -y @cloudgrid-io/cli@latest login\n" +
+    `  npx -y @cloudgrid-io/cli@latest pull ${target}\n` +
+    `  cd ${dir}\n` +
+    "  npx -y @cloudgrid-io/cli@latest plug"
+  );
+}
+
+// True when a build failure is the #311 corrupt-archive signature (a FETCHSOURCE
+// gunzip/tar failure), as opposed to a genuine app build error the developer can
+// act on (a missing dependency, a syntax error) — those keep their real log tail.
+export function archiveCorruptionSignature(text) {
+  const hay = String(text || "").toLowerCase();
+  return (
+    /not in gzip format/.test(hay) ||
+    /gzip:\s*stdin/.test(hay) ||
+    /tar:\s*child returned status/.test(hay) ||
+    /invalid gzip/.test(hay)
+  );
+}
+
 // Parse the live URL the CLI prints on a successful `plug`. The CLI prints the
 // canonical https://…cloudgrid.io URL somewhere in stdout (labelled "Outlet"
 // / "Live" / bare); take the last cloudgrid.io URL it emits — the final line is
@@ -1557,6 +1602,7 @@ export async function runPlug(ctx, input, deps = {}) {
     target_entity_id,
     grid,
     slug,
+    url: targetUrl,
     hints,
     anon,
     owner_token,
@@ -1676,20 +1722,68 @@ export async function runPlug(ctx, input, deps = {}) {
     );
   }
 
-  // grid+slug re-plug handle (the pickup contract's `replug_handle`): when no
-  // explicit target_entity_id was given but a grid+slug pair is, resolve it to
-  // an existing entity_id and re-plug that in place. A slug that does NOT resolve
-  // to an existing entity → targetEntityId stays empty → this is a CREATE (no
-  // false-positive re-plug). target_entity_id remains the primary/documented
-  // handle. Best-effort resolve (pickup contract); never fetches the public URL.
+  // Re-plug handle resolution (the pickup contract's `replug_handle`): when no
+  // explicit target_entity_id was given, resolve one from an alternative target
+  // the caller DID name — a grid+slug pair, or a CloudGrid `url` — so an edge
+  // identified only by its public URL re-plugs the SAME entity in place instead
+  // of minting a new one. A target that does NOT resolve to an existing entity →
+  // targetEntityId stays empty → this is a CREATE (no false-positive re-plug).
+  // target_entity_id remains the primary/documented handle. Best-effort resolve
+  // (pickup contract); never fetches the public URL.
+  //
+  // #296: a `url` is only trusted as a re-plug target when its host is a real
+  // CloudGrid grid apex (gridFromCloudgridUrl != null) — a foreign or malformed
+  // host is NOT sent to the resolver, so an untrusted URL can never redirect a
+  // write to another entity. `pickupData` is reused below to header the write
+  // without a second round-trip.
   let targetEntityId = target_entity_id;
-  if ((typeof targetEntityId !== "string" || targetEntityId.length === 0) && grid && slug) {
-    const resolved = await resolveEntityViaPickup(ctx, { target: slug, grid });
-    if (resolved?.entity_id) targetEntityId = resolved.entity_id;
+  const urlGrid = gridFromCloudgridUrl(targetUrl);
+  let pickupData = null;
+  if (typeof targetEntityId !== "string" || targetEntityId.length === 0) {
+    if (grid && slug) {
+      pickupData = await resolveEntityViaPickup(ctx, { target: slug, grid });
+    } else if (urlGrid) {
+      pickupData = await resolveEntityViaPickup(ctx, { url: targetUrl, grid: urlGrid });
+    }
+    if (pickupData?.entity_id) targetEntityId = pickupData.entity_id;
   }
 
   const isEdit = typeof targetEntityId === "string" && targetEntityId.length > 0;
 
+  // ── WORKAROUND(#311): pre-upload gate for inline multi-file runtime RE-PLUG ──
+  // WHAT IS BROKEN: the hosted server's tarball materialization corrupts the
+  // source archive for a multi-file runtime app re-plugged INLINE — it emits a
+  // non-gzip stream that dies at the build container's FETCHSOURCE with
+  // "gzip: stdin: not in gzip format / tar: Child returned status 1". This client
+  // uploads byte-exact octet-stream parts (proven in test), so the defect is
+  // SERVER-SIDE, not here. It stranded a real user (natalys-grid) twice.
+  // WHAT WOULD LET THIS BE REMOVED: the API-side fix to tarball materialization
+  // for this shape (tracked on #311). Once hosted rebuilds a multi-file inline
+  // re-plug reliably, delete this gate — the inline path would just work.
+  // Until then, detect the shape BEFORE uploading and hand over the CLI, which
+  // uploads from disk and updates the SAME entity. NARROW by design so it never
+  // touches the cases that work today: hosted (web) only, RE-PLUG only (a real
+  // entity id in hand to substitute), MULTIPLE files, and a ROOT cloudgrid.yaml
+  // that DECLARES services (i.e. a runtime app, not a static bundle). A single
+  // HTML page, or a few small text files with no service manifest, are untouched
+  // and still plug inline. Multi-file runtime CREATES are also untouched (issue
+  // #48 aligned that bundle) — only the re-plug shape that failed twice is gated.
+  if (ctx.edition === "web" && isEdit && hasArtifacts && artifacts.length > 1) {
+    const manifest = detectSourceManifest(input);
+    if (manifest && manifest.services.length > 0) {
+      const slugForMsg = pickupData?.slug || (typeof slug === "string" && slug ? slug : null);
+      const gridForMsg = pickupData?.grid || (typeof grid === "string" && grid ? grid : null);
+      throw new Error(
+        `This is a multi-file runtime app (${artifacts.length} files + a cloudgrid.yaml declaring ` +
+          `services: ${manifest.services.join(", ")}) being re-plugged inline on the hosted server. ` +
+          "The hosted server can't reliably rebuild a multi-file app from an inline upload — the source " +
+          "archive arrives corrupt at build (#311), which is why the identical source plugs fine from the " +
+          "CLI. " +
+          cliContinueHandoff({ entityId: targetEntityId, grid: gridForMsg, slug: slugForMsg }),
+      );
+    }
+  }
+
   // An inspiration edit content-versions the FIRST uploaded artifact — when a
   // multi-file folder rides a re-plug, put the primary entry first so the edit
   // swaps the right file (index.html > any .html > everything else).
@@ -1771,17 +1865,26 @@ export async function runPlug(ctx, input, deps = {}) {
     // the caller's membership from this header and requires it to MATCH the
     // entity's grid, so pass `grid` here too when the target lives outside the
     // active grid.
-    orgSlug = grid || (await ctx.getActiveGrid());
     // #296: an EDIT's destination is NOT ambiguous — the entity already lives in
-    // exactly one grid. When neither an explicit `grid` nor active-grid session
-    // state resolves one (the common hosted case, where active-grid is often
-    // unset), derive the home grid from the target entity itself so the write
-    // never depends on session state the API would otherwise reject for
-    // (GRID_HEADER_REQUIRED). Best-effort metadata resolve via the pickup
-    // contract (no claim); a null result simply falls back to today's behaviour.
-    if (!orgSlug && isEdit && targetEntityId) {
-      const resolved = await resolveEntityViaPickup(ctx, { target: targetEntityId });
-      if (resolved?.grid) orgSlug = resolved.grid;
+    // exactly one grid, and every way of naming that entity carries the grid.
+    // Resolve it in a deliberate order, cheapest reliable source first, so the
+    // write never depends on session state the API would otherwise reject for
+    // (GRID_HEADER_REQUIRED):
+    //   1. explicit `grid` param        — the caller said so.
+    //   2. active grid                   — session state, no network.
+    //   3. the URL host                  — FREE: the grid is the subdomain of a
+    //      CloudGrid `url` the user pasted; read it before any round-trip. A
+    //      foreign/malformed host yields null (gridFromCloudgridUrl) and we fall
+    //      through — never a silent redirect.
+    //   4. the target entity itself      — a pickup round-trip, only if 1–3 all
+    //      came up empty. Reuse a pickup already done above to resolve the id.
+    orgSlug = grid || (await ctx.getActiveGrid());
+    if (!orgSlug) orgSlug = gridFromCloudgridUrl(targetUrl);
+    if (!orgSlug && isEdit) {
+      if (!pickupData && targetEntityId) {
+        pickupData = await resolveEntityViaPickup(ctx, { target: targetEntityId });
+      }
+      if (pickupData?.grid) orgSlug = pickupData.grid;
     }
     // Grid-native header + X-CloudGrid-Org alias (same slug) during the soak.
     if (orgSlug) {
@@ -2024,6 +2127,21 @@ export async function runPlug(ctx, input, deps = {}) {
       data.status = "live";
       data.poll_url = undefined;
     } else if (verdict.status === "failed") {
+      // WORKAROUND(#311): a corrupt-archive FETCHSOURCE failure is unactionable
+      // as raw tar output — never surface it verbatim. WHAT IS BROKEN: the
+      // server-side tarball materialization corrupts the archive for a multi-file
+      // runtime re-plug; WHAT WOULD LET THIS BE REMOVED: the API-side fix (#311),
+      // after which no corrupt-archive verdict reaches here. Name the CLI path
+      // with the real handle instead (defense-in-depth behind the pre-upload gate
+      // above; this catches any shape the gate didn't). Genuine app build errors
+      // keep their real log tail — those the developer CAN act on.
+      if (archiveCorruptionSignature(`${verdict.error || ""}\n${verdict.logTail || ""}`)) {
+        throw new Error(
+          "The uploaded source could not be read by the build (its archive was corrupt) — the URL is NOT " +
+            "live. This is a known limitation of inline multi-file uploads on the hosted server (#311). " +
+            cliContinueHandoff({ entityId: data.entity_id, grid: data.grid, slug: data.slug }),
+        );
+      }
       const msg = verdict.error || "The build failed.";
       throw new Error(
         `Deploy failed (trace ${data.trace_id ?? "n/a"}): ${msg} The URL is NOT live — do not give it to the user as working.` +
@@ -2651,6 +2769,25 @@ export async function runCheckDeploy(ctx, { poll_url, grid } = {}) {
     // the source zip (grid_get_app_source → source_download_url) or the
     // pull command that downloads + links the folder so the SAME entity
     // continues locally.
+    // WORKAROUND(#311): a corrupt-archive FETCHSOURCE failure is unactionable raw
+    // tar output — do NOT echo it. WHAT IS BROKEN: server-side tarball
+    // materialization corrupts the archive for a multi-file runtime re-plug;
+    // WHAT WOULD LET THIS BE REMOVED: the API-side fix (#311). Name the CLI
+    // continue-path with the real handle instead.
+    if (archiveCorruptionSignature(`${verdict.error || ""}\n${verdict.logTail || ""}`)) {
+      return {
+        text: "The uploaded source could not be read by the build (its archive was corrupt) — the URL is " +
+          "not live. This is a known limitation of inline multi-file uploads on the hosted server (#311); the " +
+          "project files are NOT lost — they are saved on the entity. " +
+          cliContinueHandoff({ entityId, grid: gridSlug, slug: ctx.state.lastDrop?.slug }),
+        structured: {
+          status: "failed",
+          live: false,
+          reason: "archive_corrupt",
+          ...(ctx.edition === "web" && entityId ? { source_recovery: { entity_id: entityId, via: ["grid_get_app_source", "grid pull"] } } : {}),
+        },
+      };
+    }
     const handoff = ctx.edition === "web" && entityId
       ? `\nThe project files are NOT lost — they are saved on the entity. If it can't be fixed from this chat, hand the user their work: call grid_get_app_source for the source zip (source_download_url), or give them the local continue command: npx -y @cloudgrid-io/cli@latest pull ${gridSlug ? `${gridSlug}/` : ""}${ctx.state.lastDrop?.slug || entityId} — it downloads the project and links the folder so their next plug updates this same entity.`
       : "";
@@ -2688,6 +2825,42 @@ function isCloudgridHost(hostname) {
   return h === "cloudgrid.io" || h.endsWith(".cloudgrid.io");
 }
 
+// Derive the home grid slug from a CloudGrid URL (or a bare host). The grid is
+// the subdomain: `<grid>.cloudgrid.io/<slug>` (inspiration/path form) and
+// `<slug>--<grid>.cloudgrid.io` (runtime/flat form — grid is the label after
+// `--`), matching composePlugUrl's two serving shapes.
+//
+// SECURITY (#296): this derives a WRITE DESTINATION from user-supplied input, so
+// it is deliberately strict — it reuses `isCloudgridHost` (the single host check,
+// SSRF-shaped) rather than string-matching, and returns null for anything that is
+// not a trusted grid apex: a foreign or lookalike host, a malformed URL, the bare
+// apex `cloudgrid.io`, a deeper host (`a.b.cloudgrid.io`), or the anonymous
+// `guest` apex (never an authed write destination). A null result means "I could
+// not name the grid" → the caller falls through to today's behaviour and NEVER
+// silently redirects the write to a grid the user did not mean.
+export function gridFromCloudgridUrl(input) {
+  const raw = String(input ?? "").trim();
+  if (!raw) return null;
+  let parsed;
+  try {
+    // Accept a bare host (`shoobi.cloudgrid.io/x`) by supplying a scheme; a
+    // string that is already a URL keeps its own scheme.
+    parsed = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(raw) ? raw : `https://${raw}`);
+  } catch {
+    return null;
+  }
+  if (!isCloudgridHost(parsed.hostname)) return null;
+  const host = parsed.hostname.toLowerCase();
+  const labels = host.split(".");
+  // Exactly `<sub>.cloudgrid.io`. The apex (`cloudgrid.io`, 2 labels) and any
+  // deeper host (`a.b.cloudgrid.io`, 4+) name no single grid apex we trust.
+  if (labels.length !== 3) return null;
+  const sub = labels[0];
+  const grid = sub.includes("--") ? sub.split("--").pop() : sub;
+  if (!grid || grid === GUEST_ORG_SLUG) return null;
+  return grid;
+}
+
 // Shape an HTML string into the grid_get_app_source result (shared by the API-read
 // and the public-fetch paths). Caps the body at SOURCE_MAX_BYTES. `extra` carries
 // optional edition metadata resolved from the pickup contract (kind, single_html,
@@ -2837,10 +3010,10 @@ export async function runSource(ctx, { entity_id, url, grid, slug } = {}) {
   const resolvedUrl = parsed.toString();
   let eid = entity_id ?? (last && (!entity_id || last.entity_id === entity_id) ? last.entity_id : null);
 
-  // Derive the grid/slug hint from the inspiration path URL (`grid.cloudgrid.io/slug`).
-  const host = parsed.hostname;
-  const gridHint = grid ?? (host.endsWith(".cloudgrid.io") && !host.includes("--") && host.split(".").length === 3
-    ? host.split(".")[0] : null);
+  // Derive the grid/slug hint from the URL. gridFromCloudgridUrl is the single
+  // host→grid parser (it also handles the flat `<slug>--<grid>` form the old
+  // inline check missed); the slug is the first path segment.
+  const gridHint = grid ?? gridFromCloudgridUrl(resolvedUrl);
   const slugHint = slug ?? (parsed.pathname.replace(/^\/+/, "").split("/")[0] || null);
 
   // ── URL → entity_id (fresh chat, no session) via the pickup contract ──────

package/src/tools/register.js

@@ -3,15 +3,18 @@
 // Extracted verbatim from src/tools.js (refactor: split tools.js into modules).
 
 import { z } from "zod";
+import { registerAppResource, RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";
 import { newLoginCode, buildLoginUrl, pollStatusOnce, checkApiConnectivity, decodeJwt as decodeJwtAuth } from "../auth.js";
 import { PLAYBOOK, fetchCorpus, listWorkflows } from "../playbook.js";
 import {
   APPS_WIDGETS_ENABLED,
+  CHATGPT_WIDGET_MIME,
   LIVE_RESULT_URI,
   GRID_PICKER_URI,
   LIVE_RESULT_HTML,
   GRID_PICKER_HTML,
-  WIDGET_CSP,
+  GRID_LOGIN_APP_URI,
+  GRID_LOGIN_APP_HTML,
 } from "./constants.js";
 import { fail, okResult } from "./util.js";
 import { cliTool, tryOpenBrowser } from "./cli.js";
@@ -121,27 +124,50 @@ export function registerTools(server, ctx) {
 
   // ── Widget resources (web edition, ChatGPT Apps SDK) ──────────────────────
   if (ctx.edition === "web") {
+    // ChatGPT Apps-SDK widgets. mimeType MUST be text/html+skybridge
+    // (CHATGPT_WIDGET_MIME) — NOT the MCP-Apps `text/html;profile=mcp-app` the
+    // Claude card uses; that mismatch was the black frame (#308). widgetAccessible
+    // lets the widget call tools back over window.openai.callTool (the visibility
+    // pills call grid_visibility). These make no direct network requests, so no
+    // openai/widgetCSP is declared — the default deny is correct.
     server.registerResource("cloudgrid-live-result", LIVE_RESULT_URI, {
       description: "Live result card after a CloudGrid drop — shows URL, grid link, and visibility controls.",
-      mimeType: "text/html;profile=mcp-app",
+      mimeType: CHATGPT_WIDGET_MIME,
     }, async () => ({
       contents: [{
         uri: LIVE_RESULT_URI,
-        mimeType: "text/html;profile=mcp-app",
+        mimeType: CHATGPT_WIDGET_MIME,
         text: LIVE_RESULT_HTML,
-        _meta: { ui: { csp: WIDGET_CSP } },
+        _meta: { "openai/widgetAccessible": true },
       }],
     }));
 
     server.registerResource("cloudgrid-org-picker", GRID_PICKER_URI, {
       description: "Grid picker card — lets the user choose which grid to plug into.",
-      mimeType: "text/html;profile=mcp-app",
+      mimeType: CHATGPT_WIDGET_MIME,
     }, async () => ({
       contents: [{
         uri: GRID_PICKER_URI,
-        mimeType: "text/html;profile=mcp-app",
+        mimeType: CHATGPT_WIDGET_MIME,
         text: GRID_PICKER_HTML,
-        _meta: { ui: { csp: WIDGET_CSP } },
+        _meta: { "openai/widgetAccessible": true },
+      }],
+    }));
+
+    // grid_login MCP App (SEP-1865). Registered via the official ext-apps
+    // helper, which defaults the MIME type to RESOURCE_MIME_TYPE
+    // (text/html;profile=mcp-app) — the type Claude web looks for. NO csp
+    // domains: the card makes no network requests of its own (it only asks the
+    // host to open the sign-in URL and calls grid_login_status back over the
+    // bridge), so deny-by-default is exactly right. Independent of
+    // APPS_WIDGETS_ENABLED by design (see constants.js).
+    registerAppResource(server, "cloudgrid-grid-login", GRID_LOGIN_APP_URI, {
+      description: "CloudGrid sign-in card — opens the sign-in URL and confirms when you return.",
+    }, async () => ({
+      contents: [{
+        uri: GRID_LOGIN_APP_URI,
+        mimeType: RESOURCE_MIME_TYPE,
+        text: GRID_LOGIN_APP_HTML,
       }],
     }));
   }
@@ -380,6 +406,13 @@ export function registerTools(server, ctx) {
       "raw entity_id. target_entity_id takes precedence. A grid+slug that does NOT resolve to an existing " +
       "entity is treated as a CREATE (never a false-positive re-plug).",
     ),
+    url: z.string().optional().describe(
+      "Alternative RE-PLUG handle: the entity's public CloudGrid URL (e.g. https://<grid>.cloudgrid.io/<slug>) " +
+      "— use it to edit in place when you have the URL but no target_entity_id (the common \"change the color of " +
+      "this page\" flow after grid_get_app_source). The grid is read from the host and the entity is resolved via " +
+      "the pickup contract, so no `grid` param is needed. target_entity_id and grid+slug take precedence. A " +
+      "non-CloudGrid host is ignored (never redirects the write); a URL that does not resolve is treated as a CREATE.",
+    ),
     hints: z.object({
       kind: z.enum(["inspiration", "app", "agent"]).optional().describe("Force the detected kind; omit to let the server auto-detect."),
       yaml: z.string().optional().describe("An inline cloudgrid.yaml override used as a detection hint."),
@@ -485,11 +518,13 @@ export function registerTools(server, ctx) {
       // live at a public URL in place. Versions + grid rollback exist, but the
       // honest MCP annotation for overwrite-live-state is destructive.
       annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+      // ChatGPT-only binding: openai/outputTemplate points at the skybridge
+      // widget. Deliberately NOT the MCP-Apps `ui.resourceUri` key — that is
+      // Claude's, and the live-result resource is now text/html+skybridge, which
+      // Claude cannot render; carrying it here would regress the Claude path when
+      // this flag is flipped. The two mechanisms stay independent (#308/#303).
       ...(ctx.edition === "web" && APPS_WIDGETS_ENABLED ? {
-        _meta: {
-          ui: { resourceUri: LIVE_RESULT_URI, csp: WIDGET_CSP },
-          "openai/outputTemplate": LIVE_RESULT_URI,
-        },
+        _meta: { "openai/outputTemplate": LIVE_RESULT_URI },
       } : {}),
   };
   const plugHandler = async (input) => {
@@ -662,6 +697,14 @@ export function registerTools(server, ctx) {
         login_url: z.string().describe("URL to open in a browser to complete sign-in."),
       },
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+      // Bind the SEP-1865 sign-in card on the web edition (Claude web). This is
+      // the SEP-1865 key (_meta.ui.resourceUri); ChatGPT reads openai/outputTemplate
+      // and ignores it, and a client without the UI extension ignores it too and
+      // gets the text-first result below. NOT gated behind MCP_APPS_WIDGETS — a
+      // second, independent mechanism (see constants.js). The result shape is
+      // unchanged: content[0] stays the sign-in URL text so the link is never
+      // unreachable if the card does not render.
+      ...(ctx.edition === "web" ? { _meta: { ui: { resourceUri: GRID_LOGIN_APP_URI } } } : {}),
     },
     async () => {
       try {
@@ -764,6 +807,11 @@ export function registerTools(server, ctx) {
         url: z.string().optional().describe("URL of the entity, if returned."),
       },
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+      // The live-result widget's visibility pills call this back over
+      // window.openai.callTool; ChatGPT only permits that when the target tool
+      // is marked openai/widgetAccessible. ChatGPT-only key, inert on Claude and
+      // when the widget is disabled. (#308)
+      ...(ctx.edition === "web" ? { _meta: { "openai/widgetAccessible": true } } : {}),
     },
     async (input) => {
       try {

package/src/tools.js

@@ -31,6 +31,8 @@ export {
   errorGuidance,
   REPORT_OFFER,
   parseCliPlugUrl,
+  cliContinueHandoff,
+  archiveCorruptionSignature,
   plugViaCliFallback,
   runPlug,
   runPickup,

package/src/widgets/grid-login/mcp-app.css

@@ -0,0 +1,57 @@
+:root { color-scheme: light dark; }
+* { box-sizing: border-box; }
+body {
+  margin: 0;
+  font-family: var(--font-sans, Inter, system-ui, -apple-system, sans-serif);
+  background: transparent;
+  color: light-dark(#0d0d0f, #fafafa);
+}
+#card {
+  max-width: 420px;
+  margin: 0 auto;
+  padding: 1.5rem;
+}
+h1 {
+  font-size: 1.15rem;
+  margin: 0 0 0.5rem;
+}
+.lede {
+  margin: 0 0 1rem;
+  font-size: 0.9rem;
+  line-height: 1.45;
+  opacity: 0.85;
+}
+.status {
+  margin: 0 0 1rem;
+  font-size: 0.85rem;
+  opacity: 0.7;
+  min-height: 1.2em;
+}
+.actions {
+  display: flex;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+}
+button {
+  font: inherit;
+  font-weight: 600;
+  padding: 0.6rem 1.1rem;
+  border-radius: 8px;
+  border: 1px solid transparent;
+  cursor: pointer;
+  background: light-dark(#0d0d0f, #fafafa);
+  color: light-dark(#fafafa, #0d0d0f);
+}
+button:disabled { opacity: 0.5; cursor: default; }
+button.secondary {
+  background: transparent;
+  color: inherit;
+  border-color: light-dark(rgba(13,13,15,0.25), rgba(250,250,250,0.3));
+}
+.fallback {
+  margin: 1rem 0 0;
+  font-size: 0.8rem;
+  opacity: 0.7;
+  word-break: break-all;
+}
+.fallback a { color: inherit; }

package/src/widgets/grid-login/mcp-app.html

@@ -0,0 +1,26 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="color-scheme" content="light dark">
+<title>Sign in to CloudGrid</title>
+<style>/* __CSS__ */</style>
+</head>
+<body>
+<main id="card">
+  <h1>Sign in to CloudGrid</h1>
+  <p class="lede">CloudGrid runs your apps with the infrastructure they need. Sign in to plug to your grid.</p>
+  <p class="status" id="status">Preparing the sign-in link.</p>
+  <div class="actions">
+    <button id="signin" type="button" disabled>Open sign-in</button>
+    <button id="check" type="button" class="secondary" hidden>Check sign-in</button>
+  </div>
+  <p class="fallback" id="fallback" hidden>
+    Or open this link yourself:
+    <a id="fallback-url" href="#" target="_blank" rel="noopener noreferrer"></a>
+  </p>
+</main>
+<script type="module">/* __JS__ */</script>
+</body>
+</html>