@cloudgrid-io/mcp 0.20.56 → 0.21.1

package/README.md

@@ -197,16 +197,16 @@ recording whether the user agreed to share the conversation (`deploy.js:544`),
 and a `context` object the model supplies — which by its declared shape
 (`register.js:964-975`) can carry the failing inputs (for example the HTML or
 args) and the original request. The transcript itself is not sent by this tool.
-The report scrub is **key-name-only**: a value is redacted only when its *key*
-matches a secret-looking name (`password`, `token`, `api_key`, …), so a secret
-embedded in a value — for example an API key inside HTML sent under
-`context.inputs` — is not redacted, and the error summary (`message`) is not
-scrubbed at all. This same key-name filter is applied client-side
-(`deploy.js:439-448`); the platform's error endpoint applies a key-name filter
-too, not a value-based one, so neither layer catches a secret that sits in a
-value. To keep a secret out of a report, do not place it in the `message` or
-`context` you send, or set `CLOUDGRID_TELEMETRY=off` to disable reporting
-entirely.
+The report scrub is **two-layer**: values AND the `message` field are scanned
+for known secret shapes (API key prefixes such as `sk-ant-`, `sk-proj-`,
+`AKIA…`; JWTs; PEM private-key blocks; Bearer tokens; basic-auth URL
+credentials) and matches are replaced with `[REDACTED]`. Arbitrary or
+unknown-shape secrets that do not match a known pattern still transit
+unredacted. The client-side scrub (`scrubReportContext` + `scrubSecretValues`
+in deploy.js) runs before the POST; the server endpoint applies a server-side
+key-name filter on top. To keep a secret out of a report, do not place it in
+the `message` or `context` you send, or set `CLOUDGRID_TELEMETRY=off` to
+disable reporting entirely.
 
 **Version check.** At startup the local edition makes one request to
 `https://registry.npmjs.org/@cloudgrid-io/mcp/latest` to detect a stale `.mcpb`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.20.56",
+  "version": "0.21.1",
   "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": {
@@ -10,7 +10,7 @@
     "src"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22.19"
   },
   "scripts": {
     "start": "node src/index.js",
@@ -60,7 +60,10 @@
     "test:tool-titles-and-vocab": "node test/tool-titles-and-vocab.test.mjs",
     "test:visibility-mapping": "node test/visibility-mapping.test.mjs",
     "test:verb-distinction": "node test/verb-distinction.test.mjs",
-    "test:collab": "node test/collab.test.mjs"
+    "test:collab": "node test/collab.test.mjs",
+    "test:url-shape": "node test/url-shape-guard.test.mjs",
+    "test:pull-grid": "node test/pull-grid-param.test.mjs",
+    "test:pull-output-schema": "node test/pull-output-schema.test.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",

package/src/corpus/cli-reference.md

@@ -95,7 +95,7 @@ grid grid
 | `env` / `secrets` | Manage runtime env vars and secrets (secret values are never printed) |
 | `grid` / `list` | List what's on your hub / org |
 | `rename` / `delete` / `unplug` | Rename, archive, take off the grid |
-| `pull` / `clone` / `fork` | Download source; clone or fork an entity |
+| `collab` / `pull` / `pickup` | Grant push access (`collab`), continue in place (`pull`), or fork a copy (`pickup`) |
 | `feedback [message]` | Send feedback to the CloudGrid team |
 | `brain refresh <name>` | Re-run Grid Brain metadata (description, tags, diagram) |
 | `doctor` | Diagnostic checks (Node, Docker, API reachability, auth) |

package/src/corpus/rules/publish-fallbacks.md

@@ -14,8 +14,8 @@ loops forever.
 
 This is a known platform issue, not a mistake in your request. Do not retry with
 different flag or path permutations — they will all fail the same way. If a
-terminal is available, deploy from the CLI instead (`grid plug <path>`).
-If no terminal is available, stop and tell the user
+terminal is available, deploy from the CLI instead (`grid plug <path>` or
+`grid plug <url>`). If no terminal is available, stop and tell the user
 this is a known issue and needs the CLI.
 
 ## 429 anonymous cap

package/src/corpus/templates/semantic-search/services/backend/requirements.txt

@@ -3,5 +3,5 @@ uvicorn[standard]==0.30.1
 pymongo==4.8.0
 numpy==1.26.4
 httpx==0.27.0
-pypdf==6.14.2
+pypdf==6.15.0
 python-docx==1.1.2

package/src/corpus/templates/semantic-search/services/refresh/requirements.txt

@@ -5,5 +5,5 @@
 # pypdf / python-docx are imported lazily by source.extract_text for pdf/docx.
 pymongo==4.8.0
 httpx==0.27.0
-pypdf==6.14.2
+pypdf==6.15.0
 python-docx==1.1.2

package/src/corpus/troubleshooting/deploy-errors.md

@@ -10,7 +10,7 @@ Match the symptom to the row, apply the fix, and stop. Do not retry permutations
 
 | Symptom | Cause | Fix |
 | --- | --- | --- |
-| `SCOPE_INVALID` on deploy | Known platform issue, not your request | Deploy from a terminal with `grid plug <path>`. Do not retry flag or path permutations. If no terminal is available, tell the user it is a known issue that needs the CLI. |
+| `SCOPE_INVALID` on deploy | Known platform issue, not your request | Deploy from a terminal with `grid plug <path>` or `grid plug <url>`. Do not retry flag or path permutations. If no terminal is available, tell the user it is a known issue that needs the CLI. |
 | `429` anonymous cap reached | Anonymous deploy quota is exhausted | Stop. Do not log in to work around it and do not retry today. Tell the user the cap is reached; they can try later or sign in for a higher limit as a deliberate choice. |
 | `409 EDIT_REJECTED` on re-plug | The target entity is archived or expired | Do not silently create a new entity — that mints a new URL and orphans the shared one. Ask the user before creating a fresh entity. |
 | `401` on an anonymous edit | Missing or stale `owner_token` | Re-plug with the `owner_token` from the last deploy of that entity. Each anonymous edit returns a fresh token — store the new one and use it next time. |

package/src/tools/deploy.js

@@ -21,6 +21,45 @@ import {
 import { okResult } from "./util.js";
 import { runCloudgrid } from "./cli.js";
 
+/**
+ * The API refuses an infra-dependent write while a grid is still provisioning.
+ *
+ * The code is being renamed ORG_PROVISIONING -> GRID_PROVISIONING
+ * (cloudgrid-io/cloudgrid#2673, the org->grid retirement). This accepts BOTH,
+ * which is what makes the API-side rename safe: an mcp that understands both is
+ * version-independent from the API's side, so the rename can land the moment
+ * this ships rather than waiting for adoption.
+ *
+ * Keep both until the API no longer emits the old name AND the floor of
+ * installed mcp versions understands the new one. mcp is published to npm, so
+ * installed copies keep matching whatever they shipped with — dropping the old
+ * name early breaks plugs into brand-new grids, silently, by turning a
+ * retryable 409 into a hard failure.
+ *
+ * One predicate, two call sites, so they cannot drift.
+ */
+const PROVISIONING_CODES = new Set(["GRID_PROVISIONING", "ORG_PROVISIONING"]);
+function isProvisioningCode(code) {
+  return PROVISIONING_CODES.has(code);
+}
+
+// Same org->grid rename, same dual-accept safety (cloudgrid-io/cloudgrid#2673).
+// These two codes gate the first-time-user "no grid" path and the wrong-grid
+// path — if the MCP recognizes only the old ORG_* spelling, the API renaming it
+// silently darks those paths (the account-has-no-grid guidance and the typo
+// hint stop firing). NO_ACTIVE_GRID is ALREADY emitted by the API alongside
+// NO_ACTIVE_ORG; GRID_NOT_ACCESSIBLE is the anticipated rename of
+// ORG_NOT_ACCESSIBLE. Accept both spellings so the API rename can land anytime.
+const NO_ACTIVE_GRID_CODES = new Set(["NO_ACTIVE_GRID", "NO_ACTIVE_ORG"]);
+function isNoActiveGridCode(code) {
+  return NO_ACTIVE_GRID_CODES.has(code);
+}
+const GRID_NOT_ACCESSIBLE_CODES = new Set(["GRID_NOT_ACCESSIBLE", "ORG_NOT_ACCESSIBLE"]);
+function isGridNotAccessibleCode(code) {
+  return GRID_NOT_ACCESSIBLE_CODES.has(code);
+}
+
+
 // ── Org listing (bearer-authed, web edition) ──────────────────────────────────
 // Fetches the signed-in user's orgs via GET /api/v2/orgs. The JWT does not
 // carry orgs (claims: sub, email, name, iat, exp), so the API is the canonical
@@ -457,13 +496,51 @@ const REPORT_SECRET_KEY_PATTERNS = [
   /access[_-]?key/i,
 ];
 
-// Light client-side scrub of obviously secret-looking values in the report
-// context. Redacts values under secret-looking KEYS; leaves everything else
-// intact (the server applies the same key-name filter, not a value-based one —
-// a secret embedded in a value transits unredacted). Bounded depth so a
-// pathological object can't loop.
+// Value-level secret patterns — must stay in sync with TEXT_SECRET_PATTERNS
+// in session-logger.js (which scrubs free text for session logs). The lists are
+// separate because this module operates on structured object values via
+// scrubReportContext, while session-logger operates on free text via scrubText.
+// Both scan string content for the same secret shapes; if you add a pattern to
+// one, add it to the other.
+const REPORT_SECRET_VALUE_PATTERNS = [
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+  /eyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{0,}/g,
+  /sk-ant-[A-Za-z0-9_-]{16,}/g,
+  /sk-or-v1-[A-Za-z0-9]{16,}/g,
+  /sk-proj-[A-Za-z0-9_-]{16,}/g,
+  /\bsk-[A-Za-z0-9]{20,}/g,
+  /AIza[0-9A-Za-z_-]{30,}/g,
+  /ghp_[A-Za-z0-9]{30,}/g,
+  /github_pat_[A-Za-z0-9_]{30,}/g,
+  /AKIA[0-9A-Z]{16}/g,
+  /xox[baprs]-[A-Za-z0-9-]{10,}/g,
+  /\bsk_(?:live|test)_[0-9A-Za-z]{16,}\b/g,
+  /\bBearer\s+[A-Za-z0-9._-]{8,}/gi,
+];
+
+// Replace known secret shapes inside a string value with [REDACTED].
+// Complementary to the key-name check in scrubReportContext — this catches
+// secrets that live inside values (e.g. an API key pasted into HTML source).
+function scrubSecretValues(str) {
+  if (typeof str !== "string") return str;
+  let out = str;
+  for (const re of REPORT_SECRET_VALUE_PATTERNS) {
+    out = out.replace(re, "[REDACTED]");
+  }
+  out = out.replace(/([a-zA-Z][a-zA-Z0-9+.\-]*:\/\/)[^\s:@/]+:[^\s:@/]+@/g, "$1[REDACTED]@");
+  return out;
+}
+
+// Client-side scrub of the report context. Two layers:
+//   1. Key-name check: values under secret-looking KEYS are fully redacted.
+//   2. Value scan: string values in the tree (up to depth 5) are scanned for known
+//      secret shapes (API keys, Bearer tokens) and matches are replaced.
+// Bounded depth so a pathological object can't loop.
 export function scrubReportContext(obj, depth = 0) {
-  if (depth > 5 || obj === null || typeof obj !== "object") return obj;
+  if (depth > 5 || obj === null || typeof obj !== "object") {
+    // Leaf value — scrub known secret shapes from strings.
+    return typeof obj === "string" ? scrubSecretValues(obj) : obj;
+  }
   if (Array.isArray(obj)) return obj.map((item) => scrubReportContext(item, depth + 1));
   const out = {};
   for (const [key, value] of Object.entries(obj)) {
@@ -552,11 +629,11 @@ export async function runReport(
     // category: default "mcp" (or the failing tool name the agent passes).
     category: typeof category === "string" && category.trim() ? category.trim() : "mcp",
     app: "mcp",
-    message: summary.slice(0, 5000),
+    message: scrubSecretValues(summary).slice(0, 5000),
     context: safeContext,
     // Diagnostic pivots (match the CLI) — only when the agent forwards them.
     ...(typeof trace_id === "string" && trace_id ? { trace_id } : {}),
-    ...(typeof failed_step === "string" && failed_step ? { failed_step } : {}),
+    ...(typeof failed_step === "string" && failed_step ? { failed_step: scrubSecretValues(failed_step) } : {}),
     ...(typeof http_status === "number" && Number.isFinite(http_status) ? { http_status } : {}),
     // Attribution, ALSO top-level (persisted once the handler accepts these keys;
     // context.origin is the fallback until then).
@@ -638,7 +715,7 @@ export async function runReport(
 // or GET collaborator push access with grid_collab — grants permission
 // only, pull again once granted). A claim_token also
 // claims an anonymous drop into your account (ownership transfer).
-export async function runPull(ctx, { claim_token, claim_url, entity_id }) {
+export async function runPull(ctx, { claim_token, claim_url, entity_id, grid } = {}) {
   const token = await ctx.getToken();
   if (!token) {
     throw new Error("You are not signed in. Run grid_login first, then claim.");
@@ -685,8 +762,11 @@ export async function runPull(ctx, { claim_token, claim_url, entity_id }) {
   };
   // The claim re-homes the inspiration into the caller's grid; the platform
   // resolves the destination from the active-org context, so send the org
-  // header (the same header every other authed write uses).
-  const orgSlug = await ctx.getActiveGrid();
+  // header (the same header every other authed write uses). The `grid`
+  // parameter (added for #247: the hosted transport cannot set HTTP headers,
+  // so multi-grid users must pass the grid explicitly) takes precedence, then
+  // the session's active grid.
+  const orgSlug = grid || (await ctx.getActiveGrid());
   // Grid-native header + X-CloudGrid-Org alias (same slug) during the soak.
   if (orgSlug) {
     headers["X-CloudGrid-Grid"] = orgSlug;
@@ -724,6 +804,30 @@ export async function runPull(ctx, { claim_token, claim_url, entity_id }) {
       };
     }
     const code = data?.error?.code || null;
+    // ORG_NOT_ACCESSIBLE / GRID_NOT_ACCESSIBLE: the `grid` param has a typo or
+    // the user isn't a member of that grid. The server message already contains
+    // an "Available:" hint listing valid grid slugs — surface it so the agent
+    // can self-correct.
+    if (isGridNotAccessibleCode(code)) {
+      const serverMsg = data?.error?.message || "The specified grid is not accessible.";
+      const hint = data?.error?.details?.[0]?.hint || "";
+      return {
+        text:
+          `${serverMsg}${hint ? ` ${hint}` : ""} ` +
+          `Check the grid slug for typos and retry grid_pull with the correct \`grid\` parameter.`,
+        structured: { error: { code } },
+      };
+    }
+    // NO_ACTIVE_ORG / NO_ACTIVE_GRID: the account has no grid at all — route to
+    // in-flow grid creation instead of the misleading "no push access" advice.
+    if (isNoActiveGridCode(code)) {
+      return {
+        text:
+          "The account has no grid yet. Do not send the user to the console — create one from here: " +
+          "suggest a short slug, confirm it with the user, call grid_create_grid, then re-call grid_pull.",
+        structured: { needs_grid_create: true },
+      };
+    }
     // No push access → not an error to throw; tell the user their options.
     if (res.status === 403 || code === "NOT_ALLOWLISTED" || code === "PICKUP_DISABLED" || code === "FORBIDDEN_ROLE") {
       return {
@@ -735,7 +839,13 @@ export async function runPull(ctx, { claim_token, claim_url, entity_id }) {
         structured: { can_edit: false, owner_is_you: false, access: "view_only" },
       };
     }
-    const msg = data?.error?.message || data?.message || raw || `HTTP ${res.status}`;
+    let msg = data?.error?.message || data?.message || raw || `HTTP ${res.status}`;
+    // The API's "Set the X-CloudGrid-Grid header" error is unactionable for an
+    // MCP client (no client can set HTTP headers on a tool call). Rewrite it to
+    // name the tool parameter the caller CAN set (#247).
+    if (res.status === 400 && /X-CloudGrid-Grid/i.test(msg)) {
+      msg = "You belong to more than one grid. Pass the `grid` parameter to specify which grid to use.";
+    }
     throw new Error(`Pull failed (HTTP ${res.status}): ${msg}`);
   }
 
@@ -1277,7 +1387,7 @@ export function errorGuidance({ status, code, edition, isEdit, isAnon, signedIn
   // internally with a bounded budget; this guidance is the budget-exhausted tail,
   // so the wording tells the agent to wait and re-call rather than surface a raw
   // code. (Issue #235.)
-  if (status === 409 && code === "ORG_PROVISIONING") {
+  if (status === 409 && isProvisioningCode(code)) {
     return "The grid is still finishing setup — a brand-new grid provisions its infrastructure in the background (usually within ~30s). Wait ~15s and call grid_plug again with the SAME parameters; it deploys once the grid is ready. Do not switch to anonymous and do not send the user to the console.";
   }
   // 409 EDIT_REJECTED — an in-place re-plug the server won't take.
@@ -1291,13 +1401,13 @@ export function errorGuidance({ status, code, edition, isEdit, isAnon, signedIn
       : "Your sign-in is missing or expired. Run grid_login, then retry the same grid_plug. Do not offer anonymous publishing as a fix for a failed sign-in; anonymous is only for a user who explicitly asks to publish without attribution.";
   }
   if (status === 403) {
-    // NO_ACTIVE_ORG is not a role problem — the account has no grid at all.
-    // The generic pull/pickup hint here sent a first-time user in circles
-    // (field bug 2026-07-27); route them to in-flow grid creation instead.
-    if (code === "NO_ACTIVE_ORG") {
+    // NO_ACTIVE_ORG / NO_ACTIVE_GRID is not a role problem — the account has no
+    // grid at all. The generic pull/pickup hint here sent a first-time user in
+    // circles (field bug 2026-07-27); route them to in-flow grid creation instead.
+    if (isNoActiveGridCode(code)) {
       return "The account has no grid yet. Do not send the user to the console — create one from here: suggest a short slug, confirm it with the user, call grid_create_grid, then re-call grid_plug with grid: <slug>.";
     }
-    return "You lack the role to plug this target. To re-plug someone else's entity, pull it first (grid_pull), or make your own copy (grid_pickup).";
+    return "You lack the role to plug this target. To get push access to the SAME entity, use `grid_collab` — it grants permission only and fetches nothing, so run `grid_pull` again once it is granted (if the owner gates access, it becomes a request they approve). To make your own separate copy (a fork), use `grid_pickup`.";
   }
   // ── Consent-gated report offer (Task 34) ──────────────────────────────────
   // GENUINE bugs only: a build/deploy failure, any 5xx, INTERNAL_ERROR, or an
@@ -1754,7 +1864,7 @@ export async function runPlug(ctx, input, deps = {}) {
   for (;;) {
     ({ res, raw, data } = await sendPlug());
     if (res.ok) break;
-    if (res.status === 409 && data?.error?.code === "ORG_PROVISIONING") {
+    if (res.status === 409 && isProvisioningCode(data?.error?.code)) {
       const hint = data?.error?.details?.[0]?.hint || "";
       // Terminal failure — provisioning did not complete; retrying is futile.
       if (/did not (complete|finish)/i.test(hint)) {

package/src/tools/register.js

@@ -176,6 +176,7 @@ export function registerTools(server, ctx) {
       description: "Pull an app to continue/edit it IN PLACE — like `git clone` of the SAME entity: your next grid_plug (with its target_entity_id) updates that entity, and the team sees the new version. Requires PUSH ACCESS: you must own it or be a collaborator. If you can only view it, you CANNOT edit or plug it — say so, and offer the two real options: (1) make your own separate copy (a fork) with grid_pickup, or (2) GET push access to the SAME entity with grid_collab (or the CLI `grid collab <entity>`) — \"collab\" is a distinct access-control operation that grants permission only and fetches nothing, so once it is granted you run grid_pull again to get the code (and if the owner gates access, grid_collab becomes a request they approve). Passing an anonymous drop's `claim_token` claims it into your account. Requires sign-in. Calls the API directly (both editions).",
       inputSchema: {
         entity_id: z.string().optional().describe("The entity id to pull. Defaults to this session's last anonymous drop."),
+        grid: z.string().optional().describe("Grid to resolve a bare slug in. Required only when you belong to more than one grid."),
         claim_token: z.string().optional().describe("Anonymous drop only: its owner token — claims that drop into your account (ownership transfer)."),
         claim_url: z.string().optional().describe("Alternative to claim_token for an anonymous drop — the claim_url; the token is read from it."),
       },
@@ -186,6 +187,9 @@ export function registerTools(server, ctx) {
         url: z.string().optional().describe("Its public URL."),
         owner_is_you: z.boolean().optional().describe("True if you own it."),
         can_edit: z.boolean().optional().describe("True if you can plug/update it (owner or collaborator). False = view-only."),
+        access: z.string().optional().describe("Access level when can_edit is false (e.g. 'view_only')."),
+        error: z.object({ code: z.string() }).optional().describe("Error envelope when the grid slug is wrong or inaccessible. code is the server error code (e.g. ORG_NOT_ACCESSIBLE)."),
+        needs_grid_create: z.boolean().optional().describe("True when the account has no grid yet — route to grid_create_grid before retrying."),
       },
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
     },
@@ -448,6 +452,7 @@ export function registerTools(server, ctx) {
           is_active: z.boolean(),
         })).optional().describe("Alias of grids (legacy picker alias)."),
         via: z.string().optional().describe("Recovery marker: 'cli-fallback' when a signed-in create was published through the bundled CloudGrid CLI."),
+        needs_grid_create: z.boolean().optional().describe("Zero-grid ask: the account has no grid yet — suggest a slug, confirm with the user, call grid_create_grid, then re-call grid_plug with grid: <slug>."),
       },
       // destructiveHint (M3): a re-plug with target_entity_id REPLACES what is
       // live at a public URL in place. Versions + grid rollback exist, but the