@cloudgrid-io/mcp 0.20.34 → 0.20.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.20.34",
+  "version": "0.20.36",
   "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": {

package/src/tools/deploy.js

@@ -1438,7 +1438,8 @@ export async function runPlug(ctx, input, deps = {}) {
     } 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.`,
+        `Deploy failed (trace ${data.trace_id ?? "n/a"}): ${msg} The URL is NOT live — do not give it to the user as working.` +
+          formatFailureDetail(verdict),
       );
     }
     // Anything else (still building / poll unreachable): fall through to the
@@ -1452,6 +1453,7 @@ export async function runPlug(ctx, input, deps = {}) {
     ...(url ? { url } : {}),
     ...(data.poll_url ? { poll_url: data.poll_url } : {}),
     status: data.status ?? (isEdit ? "updated" : "created"),
+    source: hasPath ? "path" : hasHtml && !hasArtifacts ? "html" : "artifact_files",
     ...(data.claim_url ? { claim_url: data.claim_url } : {}),
     ...(data.claim_message ? { claim_message: data.claim_message } : {}),
     // Spec v2 omits owner_token from the output block — a spec bug (the anon
@@ -1480,6 +1482,39 @@ export async function runPlug(ctx, input, deps = {}) {
     detectedKind !== "agent" &&
     (inlineHtmlBytes != null || detectedKind === "inspiration");
 
+  // ── Source-transport disclosure (always) + CLI steer for multi-file apps ─────
+  // Two transports with very different reliability: INLINE (`html`/`artifact_files`
+  // — the source is copied THROUGH the tool call, so a large file like a lockfile
+  // or a binary can silently truncate and fail the build) vs DISK (`path`, or the
+  // CLI's folder plug — read straight from disk, no transcription risk). State
+  // which one ran so a watching user can see it, and for a multi-file inline
+  // deploy steer to the CLI, which reads from disk and cannot truncate.
+  const artifactCount = Array.isArray(artifacts) ? artifacts.length : 0;
+  let sourceLine;
+  let cliSteer = null;
+  if (hasPath) {
+    sourceLine = `Source: local folder \`${effectivePath}\`, read from disk (no truncation risk).`;
+  } else if (hasHtml && !hasArtifacts) {
+    sourceLine = "Source: inline `html` — a single self-contained document sent through the tool call.";
+  } else {
+    const kb = Math.round(artifacts.reduce((n, a) => n + (a.buffer?.byteLength ?? 0), 0) / 1024);
+    sourceLine = `Source: inline \`artifact_files\` — ${artifactCount} file${artifactCount === 1 ? "" : "s"}, ~${kb} KB copied through the tool call.`;
+    // A multi-file app (a real framework, a lockfile, or binary assets) is exactly
+    // where inline copying truncates. Steer to the CLI's disk-based plug.
+    const looksRuntime =
+      artifactCount > 1 ||
+      artifacts.some((a) => /(^|\/)(cloudgrid\.ya?ml|package-lock\.json|pnpm-lock\.yaml|yarn\.lock)$/i.test(a.path || ""));
+    if (looksRuntime) {
+      const gridSlug = data.grid ?? grid ?? null;
+      const eid = data.entity_id ?? targetEntityId ?? null;
+      cliSteer =
+        "For a multi-file app the local CLI is more reliable — it reads from disk, so lockfiles and binaries can't truncate the way inline copying can. " +
+        (eid
+          ? `If you have the folder: \`cd <app> && npx -y @cloudgrid-io/cli plug\`. If not, pick it up first: \`npx -y @cloudgrid-io/cli pickup ${gridSlug ? `${gridSlug}/` : ""}<slug> --force\` then \`cd <slug> && npx -y @cloudgrid-io/cli plug\`. Or re-plug directly: \`npx -y @cloudgrid-io/cli plug --existing ${eid}${gridSlug ? ` --grid ${gridSlug}` : ""} --verbose\`.`
+          : "Prefer `npx -y @cloudgrid-io/cli plug` from the app folder over inlining files.");
+    }
+  }
+
   const lines = [];
   if (isBuilding) {
     lines.push(
@@ -1507,6 +1542,10 @@ export async function runPlug(ctx, input, deps = {}) {
   } else {
     lines.push(`Live: ${url}`);
   }
+  // Suggestion 3: always disclose the transport; Suggestion 1: steer multi-file
+  // inline deploys to the CLI's disk-based plug.
+  lines.push(sourceLine);
+  if (cliSteer) lines.push(cliSteer);
   if (data.entity_id) {
     lines.push(
       `Re-plug handle: entity_id=${data.entity_id} — persist it (with the url) and pass it back as target_entity_id to update this entity later.`,
@@ -1854,12 +1893,41 @@ async function fetchDeployTrace(ctx, { pollUrl, grid }) {
   if (!res.ok) {
     throw new Error(`Deploy status check failed (HTTP ${res.status}): ${data?.error?.message || data?.error || raw || res.status}`);
   }
+  // Surface the real build failure, not just the generic floor message. A failed
+  // deploy trace carries a structured DeployEventError: message_user (the floor),
+  // build_log_excerpt.text (a sanitized ~50-line Cloud Build log tail — what the
+  // CLI's --verbose prints), a Cloud Build console_url, and suggested_fixes. Pull
+  // the log tail + first fix so grid_check_deploy stops dead-ending on "check the
+  // build logs" with no logs.
+  const e = data?.error && typeof data.error === "object" ? data.error : null;
+  const excerpt = e?.build_log_excerpt && typeof e.build_log_excerpt === "object" ? e.build_log_excerpt : null;
+  const logTail = (typeof excerpt?.text === "string" && excerpt.text.trim()) || (typeof excerpt?.summary === "string" && excerpt.summary.trim()) || null;
+  const fix = Array.isArray(e?.suggested_fixes) && typeof e.suggested_fixes[0]?.summary === "string"
+    ? e.suggested_fixes[0].summary
+    : (typeof e?.ai_explanation?.message_user === "string" ? e.ai_explanation.message_user : null);
   return {
     status: data?.status ?? "unknown",
-    error: data?.error?.message_user || data?.error?.message || null,
+    error: e?.message_user || e?.message || null,
+    logTail: logTail || null,
+    consoleUrl: (typeof excerpt?.console_url === "string" && excerpt.console_url) || null,
+    fix: fix || null,
   };
 }
 
+// Cap the log tail we echo into a tool result — enough to see the real error
+// (a few dozen lines) without flooding the model's context.
+const BUILD_LOG_TAIL_MAX = 1600;
+function formatFailureDetail({ logTail, consoleUrl, fix } = {}) {
+  const parts = [];
+  if (logTail) {
+    const t = logTail.length > BUILD_LOG_TAIL_MAX ? "…\n" + logTail.slice(-BUILD_LOG_TAIL_MAX) : logTail;
+    parts.push(`Build log (tail):\n${t}`);
+  }
+  if (fix) parts.push(`Suggested fix: ${fix}`);
+  if (consoleUrl) parts.push(`Full log: ${consoleUrl}`);
+  return parts.length ? "\n" + parts.join("\n") : "";
+}
+
 // 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).
@@ -1911,8 +1979,16 @@ export async function runCheckDeploy(ctx, { poll_url, grid } = {}) {
   }
   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 } : {}) },
+      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.` +
+        formatFailureDetail(verdict),
+      structured: {
+        status: "failed",
+        live: false,
+        ...(verdict.error ? { error: verdict.error } : {}),
+        ...(verdict.logTail ? { build_log_tail: verdict.logTail } : {}),
+        ...(verdict.fix ? { suggested_fix: verdict.fix } : {}),
+        ...(verdict.consoleUrl ? { build_log_url: verdict.consoleUrl } : {}),
+      },
     };
   }
   return {

package/src/tools/register.js

@@ -77,35 +77,20 @@ export function registerTools(server, ctx) {
     }
   };
 
-  // Every primary tool records its shape here so a deprecated alias can be
-  // registered under an OLD name with the same handler + schema but a
-  // redirect-only, keyword-free description (so the model never mis-selects it).
-  const registered = {};
+  // Every tool registers under its canonical grid_* name ONLY. Deprecated
+  // aliases were removed entirely (founder directive, 2026-07-22): each alias
+  // doubled the ListTools surface for pure clutter, clients enumerate tools
+  // dynamically, and the renames' old names (grid_deploy, grid_set_sharing,
+  // grid_copy_app, grid_claim_anonymous_deploy, grid_download_source,
+  // grid_fetch, grid_logs) are gone rather than advertised as redirects.
   const reg = (name, config, handler) => {
-    registered[name] = { kind: "reg", config, handler };
     server.registerTool(name, config, withCapture(name, handler));
   };
 
   const regTool = (name, description, schema, annotations, handler) => {
-    registered[name] = { kind: "tool", description, schema, annotations, handler };
     server.tool(name, description, schema, annotations, withCapture(name, handler));
   };
 
-  // Register OLD tool names as deprecated aliases of their new (clearer) names.
-  // Same handler/schema; description is redirect-only so it never wins selection.
-  // Skips silently if the primary isn't registered in this edition (e.g. a
-  // CLI-only tool on the web edition).
-  const registerAlias = (oldName, newName) => {
-    const r = registered[newName];
-    if (!r) return;
-    const redirect = `Deprecated alias of ${newName}. Always call ${newName} instead; this name is kept for backward compatibility.`;
-    if (r.kind === "reg") {
-      server.registerTool(oldName, { ...r.config, description: redirect }, withCapture(oldName, r.handler));
-    } else {
-      server.tool(oldName, redirect, r.schema, r.annotations, withCapture(oldName, r.handler));
-    }
-  };
-
   // ── Widget resources (web edition, ChatGPT Apps SDK) ──────────────────────
   if (ctx.edition === "web") {
     server.registerResource("cloudgrid-live-result", LIVE_RESULT_URI, {
@@ -289,7 +274,15 @@ export function registerTools(server, ctx) {
           ? " or `artifact_files` — a multi-file app inline. "
           : ", `path` — a local folder/file, or `artifact_files` — inline files. ") +
         "If you need to edit a page but don't have its HTML, call grid_get_app_source first, then deploy with " +
-        "target_entity_id. (CloudGrid calls this operation 'plug'.)",
+        "target_entity_id. " +
+        // Suggestion 1: steer multi-file runtime apps to the CLI up front — inline
+        // copying truncates large lockfiles/binaries and silently fails the build.
+        "RELIABILITY: `html` and `artifact_files` are sent INLINE (copied through this call), which can " +
+        "truncate large files (lockfiles, binaries) on a multi-file app. For a real framework (Next.js, etc.), " +
+        "a lockfile, or binary assets — and for re-plugging an existing runtime app — prefer the local CLI, " +
+        "which reads from disk: `npx -y @cloudgrid-io/cli plug` in the app folder (pick it up first with " +
+        "`npx -y @cloudgrid-io/cli pickup <grid>/<slug> --force` if you don't have it locally). Reserve inline " +
+        "for a single page or a few small text files. (CloudGrid calls this operation 'plug'.)",
       inputSchema: plugInputSchema,
       outputSchema: {
         entity_id: z.string().optional().describe("Globally unique — pass back as target_entity_id to re-plug."),
@@ -298,6 +291,7 @@ export function registerTools(server, ctx) {
         url: z.string().optional().describe("Canonical serving URL (stable across re-plugs; server-composed, flat-arch-aware)."),
         poll_url: z.string().optional().describe("Deploy status path while building (runtimes only)."),
         status: z.string().optional().describe("live | building | created | updated …"),
+        source: z.string().optional().describe("Transport used for this deploy: `path` (disk), `html`, or `artifact_files` (inline). Inline copies risk truncation on large files."),
         claim_url: z.string().optional().describe("Anon create only: sign-in link to claim ownership."),
         claim_message: z.string().optional().describe("Anon create only: the claim nudge to relay."),
         owner_token: z.string().optional().describe("Anonymous drops: the bearer owner token (re-plug + claim). Re-minted on every anonymous edit — persist the newest."),
@@ -430,11 +424,9 @@ export function registerTools(server, ctx) {
       }
   };
   reg("grid_plug", plugConfig, plugHandler);
-  // `grid_deploy` is kept as a deprecated back-compat alias that redirects to
-  // grid_plug (for any client still calling the old name). It is keyword-free so
-  // the model never selects it — "deploy"/"publish"/"ship"/"make live" live in
-  // grid_plug's own description, so deploy-intent routing lands on grid_plug.
-  registerAlias("grid_deploy", "grid_plug");
+  // NOTE: no `grid_deploy` alias — the tool is grid_plug only. "deploy"/
+  // "publish"/"ship"/"make live" live in grid_plug's description, so
+  // deploy-intent routing lands there without a second listed name.
 
   // ── grid_fork / grid_remix / grid_download — direct-API copy/source verbs ──────
   // fork = same-grid byte-carrying copy; remix = cross-grid copy with secrets
@@ -718,6 +710,9 @@ export function registerTools(server, ctx) {
         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."),
+        build_log_tail: z.string().optional().describe("Sanitized tail of the Cloud Build log (the real error), when the build failed."),
+        suggested_fix: z.string().optional().describe("A suggested fix for the failure, when the platform provides one."),
+        build_log_url: z.string().optional().describe("Cloud Build console URL for the full log, when available."),
       },
       annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
     },
@@ -972,26 +967,6 @@ export function registerTools(server, ctx) {
     },
   );
 
-  // ── Kept alias (both editions): grid_fetch has real muscle memory in saved
-  //    prompts and older docs. Every other legacy alias was dropped in 0.20.8 -
-  //    16 alias schemas were pure ListTools context weight on every session.
-  registerAlias("grid_fetch", "grid_get_template");
-  // grid_set_sharing → grid_visibility (2026-07-20, founder rename). Same handler
-  // and schema; old name kept as a redirect-only deprecated alias so any client
-  // still calling it works while the model prefers the new. MUST live here, above
-  // the local cutoff: grid_visibility is a both-editions tool, so the alias has
-  // to register on the web edition too (hosted callers keep back-compat).
-  registerAlias("grid_set_sharing", "grid_visibility");
-  // Copy/adopt verbs renamed to match the CLI (fork / remix / pickup / download).
-  // Old names kept as redirect-only deprecated aliases; all both-editions tools,
-  // so they must register above the local cutoff for hosted back-compat.
-  // grid_claim_anonymous_deploy → grid_pickup drops the "claim" naming; claiming
-  // an anonymous drop is now grid_pickup with a claim_token (mirrors the CLI's
-  // `grid pickup --claim-token`).
-  registerAlias("grid_copy_app", "grid_fork");
-  registerAlias("grid_claim_anonymous_deploy", "grid_pickup");
-  registerAlias("grid_download_source", "grid_download");
-
   if (ctx.edition !== "local") return; // web edition stops here — no CLI tools
 
   // ── CLI-wrapping tools (local edition only) ───────────────────────────────
@@ -1310,9 +1285,4 @@ export function registerTools(server, ctx) {
     }),
   );
 
-  // ── Deprecated aliases (tool-name cleanup): OLD CLI-tool names kept callable
-  //    (local edition) as redirect-only aliases of their new, clearer names.
-  // Kept alias (local): grid_logs - muscle memory. The other legacy CLI-tool
-  // aliases were dropped in 0.20.8 (see CHANGELOG).
-  registerAlias("grid_logs", "grid_view_logs");
 }