@cloudgrid-io/mcp 0.20.27 → 0.20.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.20.27",
+  "version": "0.20.28",
   "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": {
@@ -51,7 +51,9 @@
     "build:mcpb": "node scripts/build-mcpb.mjs",
     "test:widgets": "node test/apps-widgets.test.mjs",
     "test:fork": "node test/fork.test.mjs",
-    "test:set-sharing": "node test/set-sharing.test.mjs"
+    "test:set-sharing": "node test/set-sharing.test.mjs",
+    "test:check-deploy": "node test/check-deploy.test.mjs",
+    "test:staleness": "node test/staleness.test.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",

package/src/index.js

@@ -19,6 +19,7 @@ import { randomUUID } from "node:crypto";
 import { createSessionLogger } from "./session-logger.js";
 import { createSink } from "./log-sink.js";
 import { INSTRUCTIONS_LOCAL } from "./playbook.js";
+import { checkForNewerVersion } from "./staleness.js";
 
 const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url)));
 
@@ -32,6 +33,24 @@ const ctx = {
   savedLocationNote: () => `Credentials saved to ${credentialsPath()}.`,
 };
 
+// Boot-time staleness self-check (local edition only — hosted auto-updates on
+// cutover). Fire-and-forget with a short timeout: offline or slow → stays null.
+// Surfaced in grid_start's live context so the model relays the reinstall note
+// in-session; also logged to stderr for the Desktop MCP log.
+ctx.staleness = null;
+checkForNewerVersion(version)
+  .then((info) => {
+    if (info?.behind) {
+      ctx.staleness = info;
+      console.error(
+        `cloudgrid-mcp: this MCP is v${info.current}; latest is v${info.latest}. ` +
+          `The .mcpb Desktop extension never auto-updates — reinstall the latest from ` +
+          `https://github.com/cloudgrid-io/mcp/releases/latest`,
+      );
+    }
+  })
+  .catch(() => {});
+
 // QA session log (dark by default: no CLOUDGRID_QA_SLACK_WEBHOOK → null → no-op).
 // The stdio process IS the session. user_request is forwarded by Claude Code via
 // CLOUDGRID_USER_REQUEST when present.

package/src/staleness.js

@@ -0,0 +1,71 @@
+// Boot-time staleness self-check for the LOCAL edition.
+//
+// The .mcpb Desktop extension is a frozen snapshot: it never auto-updates, so
+// an installed bundle silently rots (a pre-0.20.17 bundle crashed on boot for a
+// week; stale installs pinned old CLIs that the API rejects). The hosted
+// edition auto-updates on cutover and never needs this.
+//
+// The check is strictly best-effort: one fetch to the npm registry with a short
+// timeout, fire-and-forget at boot. Offline, slow, or erroring → null, silently.
+// The result is surfaced in TWO places: stderr (Desktop MCP logs) and the
+// grid_start live context, where the model can relay it to the user in-session
+// — turning silent rot into a one-line user action.
+
+const REGISTRY_LATEST_URL = "https://registry.npmjs.org/@cloudgrid-io/mcp/latest";
+const CHECK_TIMEOUT_MS = 2500;
+
+// Compare two semver strings (no prerelease handling — releases are plain
+// X.Y.Z). Returns -1 / 0 / 1 for a < b / a == b / a > b; null if unparsable.
+export function compareSemver(a, b) {
+  const pa = String(a ?? "").split(".").map((n) => Number.parseInt(n, 10));
+  const pb = String(b ?? "").split(".").map((n) => Number.parseInt(n, 10));
+  if (pa.length !== 3 || pb.length !== 3 || pa.some(Number.isNaN) || pb.some(Number.isNaN)) return null;
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] < pb[i]) return -1;
+    if (pa[i] > pb[i]) return 1;
+  }
+  return 0;
+}
+
+/**
+ * One best-effort registry check. Resolves { current, latest, behind } when the
+ * registry answered and `current` is older than `latest`; resolves null in every
+ * other case (up to date, ahead, offline, timeout, bad payload). Never throws.
+ */
+export async function checkForNewerVersion(current, { fetchImpl = fetch, timeoutMs = CHECK_TIMEOUT_MS } = {}) {
+  try {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), timeoutMs);
+    let res;
+    try {
+      res = await fetchImpl(REGISTRY_LATEST_URL, { signal: ac.signal });
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!res?.ok) return null;
+    const data = await res.json();
+    const latest = data?.version;
+    if (typeof latest !== "string") return null;
+    if (compareSemver(current, latest) === -1) {
+      return { current, latest, behind: true };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The one-line, model-relayable note grid_start appends when the local MCP is
+ * stale. Kept short and §23-plain; names the .mcpb non-auto-update property so
+ * the model explains WHY a reinstall is needed.
+ */
+export function stalenessNote(staleness) {
+  if (!staleness?.behind) return null;
+  return (
+    `Note: this local CloudGrid MCP is v${staleness.current}; the latest is v${staleness.latest}. ` +
+    `If it is installed as the Claude Desktop extension (.mcpb), it never auto-updates — ` +
+    `tell the user to reinstall the latest cloudgrid.mcpb from https://github.com/cloudgrid-io/mcp/releases/latest ` +
+    `(npx installs pick up the latest on their next cold start).`
+  );
+}

package/src/tools/deploy.js

@@ -1401,6 +1401,10 @@ export async function runPlug(ctx, input, deps = {}) {
       // Kind lets grid_visibility route to the right visibility surface
       // (inspirations vs runtime entities) without a re-detect round-trip.
       kind: data.detection?.kind ?? data.kind ?? null,
+      // poll_url lets grid_check_deploy default to this session's build with
+      // no arguments ("is it live yet?" needs no ids).
+      poll_url: data.poll_url ?? null,
+      grid: data.grid ?? null,
       owner_token: useAnonWire ? (freshOwnerToken ?? ownerToken ?? null) : null,
     };
   }
@@ -1414,6 +1418,32 @@ export async function runPlug(ctx, input, deps = {}) {
     ctx.state.lastAnonClaim = null;
   }
 
+  // Confirm-before-claiming-live: a runtime build is async (status "building" +
+  // poll_url). Rather than returning immediately — which trained models to
+  // promise URLs that then 502'd — poll the deploy trace server-side for a short
+  // budget. Fast builds come back "live" in this same tool call; a build that
+  // outlives the budget returns "building" with explicit do-not-claim-live copy;
+  // a failed build surfaces the platform's user-language error instead of a URL.
+  if ((data.status === "building" || data.poll_url) && data.poll_url && !useAnonWire) {
+    const verdict = await pollDeployTrace(ctx, {
+      pollUrl: data.poll_url,
+      grid: data.grid,
+      budgetMs: ctx.deployPollBudgetMs ?? DEPLOY_POLL_BUDGET_MS,
+      intervalMs: ctx.deployPollIntervalMs ?? DEPLOY_POLL_INTERVAL_MS,
+    });
+    if (verdict.status === "success") {
+      data.status = "live";
+      data.poll_url = undefined;
+    } else if (verdict.status === "failed") {
+      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.`,
+      );
+    }
+    // Anything else (still building / poll unreachable): fall through to the
+    // building wording below — the do-not-claim-live path.
+  }
+
   const structured = {
     ...(data.entity_id ? { entity_id: data.entity_id } : {}),
     ...(data.slug ? { slug: data.slug } : {}),
@@ -1456,10 +1486,16 @@ export async function runPlug(ctx, input, deps = {}) {
         ? `Building (async): ${url} — the update is deploying, not live yet.`
         : `Building (async): ${url} — the deploy is in progress, not live yet.`,
     );
+    // Point at a tool that exists on THIS edition. grid_status is CLI-wrapping,
+    // local-only — telling a hosted (ChatGPT/claude.ai) model to "run
+    // grid_status" dead-ends (observed live: a hosted session had no status
+    // tool and blind-polled the public URL into a 502). grid_check_deploy is
+    // direct-API and registered on both editions.
+    const checkHint = ctx.edition === "web" ? "grid_check_deploy" : "grid_check_deploy (or grid_status)";
     lines.push(
       data.poll_url
-        ? `Poll ${data.poll_url} or run grid_status until it is ready (trace ${data.trace_id ?? "n/a"}). Do not report it as live until then.`
-        : "Run grid_status until it is ready. Do not report it as live until then.",
+        ? `Call ${checkHint} until status is "success" (trace ${data.trace_id ?? "n/a"}). Do NOT tell the user it is live until then.`
+        : `Call ${checkHint} until it is ready. Do NOT tell the user it is live until then.`,
     );
   } else if (isEdit) {
     lines.push(`Updated in place: ${url}`);
@@ -1724,6 +1760,91 @@ export async function runVisibility(ctx, { target, visibility, kind, org }) {
   throw new Error(`Visibility change failed (HTTP ${last?.res?.status}): ${msg}${hint ? ` ${hint}` : ""}`);
 }
 
+// ── Deploy-trace polling (confirm-before-claiming-live) ─────────────────────
+// A runtime build is async: POST /api/v2/plug answers 202 { status: "building",
+// poll_url: "/deploys/<trace_id>" } and GET {API}/deploys/<trace_id> (org-authed)
+// reports { status, error } until a terminal "success" | "failed". Budget below
+// is deliberately under typical host tool timeouts; slower builds fall back to
+// the explicit do-not-claim-live wording + grid_check_deploy.
+const DEPLOY_POLL_BUDGET_MS = 45_000;
+const DEPLOY_POLL_INTERVAL_MS = 3_000;
+const sleepMs = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// GET one deploy-trace snapshot. Returns { status, error } — status is the
+// server's word ("queued"/"building"/"success"/"failed"), error is the
+// user-language message when failed. Throws only on a non-OK HTTP response.
+async function fetchDeployTrace(ctx, { pollUrl, grid }) {
+  const token = await ctx.getToken();
+  const headers = {};
+  if (token) headers.Authorization = `Bearer ${token}`;
+  const orgSlug = grid || (await ctx.getActiveGrid());
+  if (orgSlug) {
+    headers["X-CloudGrid-Grid"] = orgSlug;
+    headers["X-CloudGrid-Org"] = orgSlug;
+  }
+  const path = pollUrl.startsWith("http") ? pollUrl : `${API_BASE}${pollUrl.startsWith("/") ? "" : "/"}${pollUrl}`;
+  const res = await fetch(path, { headers });
+  const raw = await res.text();
+  let data = null;
+  try { data = JSON.parse(raw); } catch { /* handled below */ }
+  if (!res.ok) {
+    throw new Error(`Deploy status check failed (HTTP ${res.status}): ${data?.error?.message || data?.error || raw || res.status}`);
+  }
+  return {
+    status: data?.status ?? "unknown",
+    error: data?.error?.message_user || data?.error?.message || null,
+  };
+}
+
+// Poll until terminal or the budget runs out. Never throws — an unreachable
+// poll endpoint degrades to { status: "unknown" } and the caller keeps the
+// do-not-claim-live wording (the safe direction).
+export async function pollDeployTrace(ctx, { pollUrl, grid, budgetMs = DEPLOY_POLL_BUDGET_MS, intervalMs = DEPLOY_POLL_INTERVAL_MS }) {
+  const start = Date.now();
+  let last = { status: "unknown", error: null };
+  for (;;) {
+    try {
+      last = await fetchDeployTrace(ctx, { pollUrl, grid });
+    } catch {
+      // transient/unauthorized/network — keep last, retry within budget
+    }
+    if (last.status === "success" || last.status === "failed") return last;
+    if (Date.now() - start + intervalMs > budgetMs) return last;
+    await sleepMs(intervalMs);
+  }
+}
+
+// grid_check_deploy — one authed status check for an async build. Direct API,
+// both editions: this is the status verb hosted (ChatGPT/claude.ai) sessions
+// were missing — they had no way to confirm a runtime build came live and
+// blind-polled the public URL into 502s.
+export async function runCheckDeploy(ctx, { poll_url, grid } = {}) {
+  const pollUrl = poll_url || ctx.state.lastDrop?.poll_url;
+  if (!pollUrl) {
+    throw new Error(
+      "No build to check. Pass poll_url from a grid_deploy result, or deploy something first in this session. (Instant inspiration deploys are live on return and have no poll_url.)",
+    );
+  }
+  const verdict = await fetchDeployTrace(ctx, { pollUrl, grid: grid || ctx.state.lastDrop?.grid });
+  const url = ctx.state.lastDrop?.url;
+  if (verdict.status === "success") {
+    return {
+      text: `Live${url ? `: ${url}` : ""} — the build finished. Give the user the URL.`,
+      structured: { status: "success", live: true, ...(url ? { url } : {}) },
+    };
+  }
+  if (verdict.status === "failed") {
+    return {
+      text: `The build FAILED: ${verdict.error || "no reason reported"}. The URL is not live — do not give it to the user as working. Fix the app (or re-deploy) and try again.`,
+      structured: { status: "failed", live: false, ...(verdict.error ? { error: verdict.error } : {}) },
+    };
+  }
+  return {
+    text: `Still ${verdict.status === "unknown" ? "building (status unavailable)" : verdict.status} — NOT live yet. Do not tell the user it is live. Wait ~15s and call grid_check_deploy again.`,
+    structured: { status: verdict.status, live: false },
+  };
+}
+
 // Max HTML we'll return inline from runSource. Past this, we return the first
 // slice with truncated:true — a re-plug needs the complete document, so a
 // truncated body is a signal the drop is likely multi-file rather than a single

package/src/tools/register.js

@@ -26,7 +26,9 @@ import {
   runDownload,
   runVisibility,
   runSource,
+  runCheckDeploy,
 } from "./deploy.js";
+import { stalenessNote } from "../staleness.js";
 
 // Build the argv for grid_create_project → `grid new` (CLI >= 0.15.14; `init`
 // is a deprecated alias we no longer author). Modern shape: `new <slug>` with
@@ -643,6 +645,36 @@ export function registerTools(server, ctx) {
     },
   );
 
+  // Deploy-status check — both editions. The status verb hosted sessions were
+  // missing: grid_status wraps the CLI (local-only), so a ChatGPT/claude.ai
+  // session had NO way to confirm an async runtime build came live and
+  // blind-polled the public URL into 502s. Direct API, no CLI.
+  reg(
+    "grid_check_deploy",
+    {
+      description:
+        "Check whether an async runtime-app build has finished and the app is live. Call this after grid_deploy returns status \"building\" — repeat every ~15s until it reports success or failed, and do NOT tell the user the app is live until it does. Defaults to this session's last deploy; pass poll_url from a grid_deploy result to check another. Requires sign-in (builds are owned). Calls the API directly — works on every edition, including hosted.",
+      inputSchema: {
+        poll_url: z.string().optional().describe("The poll_url from a grid_deploy result. Defaults to this session's last deploy."),
+        grid: z.string().optional().describe("Grid of the entity. Defaults to the deploy's grid, then the active grid."),
+      },
+      outputSchema: {
+        status: z.string().describe("The build status: success | failed | building | queued | unknown."),
+        live: z.boolean().describe("True only when the build finished successfully and the URL serves."),
+        url: z.string().optional().describe("The live URL, when known."),
+        error: z.string().optional().describe("User-language failure reason, when the build failed."),
+      },
+      annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+    },
+    async (input) => {
+      try {
+        return okResult(await runCheckDeploy(ctx, input || {}));
+      } catch (err) {
+        return fail(err.message);
+      }
+    },
+  );
+
   // Org listing — both editions.
   reg(
     "grid_list_grids",
@@ -724,6 +756,13 @@ export function registerTools(server, ctx) {
           .object({
             active_grid: z.string().nullable().describe("The user's active grid/org slug, or null."),
             signed_in: z.boolean().describe("Whether the current session is signed in."),
+            update_available: z
+              .object({
+                current: z.string().describe("This MCP's version."),
+                latest: z.string().describe("Latest published version."),
+              })
+              .optional()
+              .describe("Present when this local MCP is behind the latest release — relay the reinstall note to the user."),
           })
           .optional()
           .describe("Live context from the current session."),
@@ -744,17 +783,28 @@ export function registerTools(server, ctx) {
       } catch {
         activeGrid = null;
       }
+      // Staleness (local edition): populated fire-and-forget at boot. The
+      // .mcpb never auto-updates, so this is where silent rot becomes a
+      // one-line user action — the model relays the note in-session.
+      const stale = stalenessNote(ctx.staleness);
       const structured = {
         playbook: PLAYBOOK,
         workflows,
-        context: { active_grid: activeGrid, signed_in: signedIn },
+        context: {
+          active_grid: activeGrid,
+          signed_in: signedIn,
+          ...(ctx.staleness?.behind
+            ? { update_available: { current: ctx.staleness.current, latest: ctx.staleness.latest } }
+            : {}),
+        },
       };
       const wfLines = workflows.length
         ? workflows.map((w) => `  - ${w.name}: ${w.when || w.summary}`).join("\n")
         : "  (none available)";
       const text =
         `${PLAYBOOK}\n\nAvailable workflows:\n${wfLines}\n\n` +
-        `Next: match the intent to a workflow and call grid_get_template({kind:"workflow", name}).`;
+        `Next: match the intent to a workflow and call grid_get_template({kind:"workflow", name}).` +
+        (stale ? `\n\n${stale}` : "");
       return okResult({ text, structured });
     },
   );

package/src/tools.js

@@ -36,6 +36,8 @@ export {
   runFork,
   runSource,
   runVisibility,
+  runCheckDeploy,
+  pollDeployTrace,
 } from "./tools/deploy.js";
 export { registerTools, buildCreateProjectArgs } from "./tools/register.js";
 export { decodeJwt } from "./auth.js";