@cloudgrid-io/mcp 0.20.56 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.20.56",
+  "version": "0.21.0",
   "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,29 @@ 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);
+}
+
+
 // ── 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
@@ -638,7 +661,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 +708,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 +750,29 @@ export async function runPull(ctx, { claim_token, claim_url, entity_id }) {
       };
     }
     const code = data?.error?.code || null;
+    // ORG_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 (code === "ORG_NOT_ACCESSIBLE") {
+      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: "ORG_NOT_ACCESSIBLE" } },
+      };
+    }
+    // NO_ACTIVE_ORG: the account has no grid at all — route to in-flow grid
+    // creation instead of the misleading "no push access" advice.
+    if (code === "NO_ACTIVE_ORG") {
+      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 +784,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 +1332,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.
@@ -1297,7 +1352,7 @@ export function errorGuidance({ status, code, edition, isEdit, isAnon, signedIn
     if (code === "NO_ACTIVE_ORG") {
       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 +1809,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