@cloudgrid-io/mcp 0.20.47 → 0.20.49

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.20.47",
+  "version": "0.20.49",
   "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/corpus/cli-reference.md

@@ -90,7 +90,7 @@ grid grid
 | `logs [name]` | Stream entity logs |
 | `open [name]` | Open the entity URL in the browser |
 | `info [name]` / `builds [name]` | Entity metadata; recent deploys |
-| `visibility set <slug> <mode>` | private \| authenticated \| org \| link |
+| `visibility set <slug> <mode>` | private \| grid \| link — or the axes: `--inside <private\|spaces\|grid> --outside <none\|link\|public>` (+ `--require-signin`, `--space <slug>`) |
 | `rollback` / `versions` | Roll back to a prior deploy; list/tag minted versions |
 | `env` / `secrets` | Manage runtime env vars and secrets (secret values are never printed) |
 | `grid` / `list` | List what's on your hub / org |

package/src/corpus/playbook.md

@@ -7,7 +7,7 @@ Operating rules:
 3b. No grid yet (first-time signed-in user): grid_plug returns needs_grid_create when the account has no grid, and a plug can fail with 403 NO_ACTIVE_ORG. Do NOT send the user to the console — suggest a short slug (3-40 lowercase letters/digits/hyphens, starting with a letter), confirm it with the user (it is permanent and appears in URLs), call grid_create_grid, then re-call grid_plug with grid: <slug>.
 3c. A failed runtime build never loses the work: the source was uploaded before the build ran and lives on the entity. Read the build log (grid_check_deploy) and fix; if it cannot be fixed from this session (hosted, no filesystem), hand the user their files — grid_get_app_source returns a source zip link (source_download_url), and `npx -y @cloudgrid-io/cli@latest pull <grid>/<slug>` downloads the project AND links the folder so the next plug updates the SAME entity locally. Offer one of these instead of abandoning the build or starting over.
 4. Load specifics on demand. Use grid_get_template({kind, name}) to pull the exact workflow, template, or example you need (kind ∈ workflow|template|example|rule|troubleshooting|doc).
-5. Always return the live share URL at the end — that is the deliverable. On a NEW plug, then ASK the user who should be able to open it — private (only you), a space, your grid, anyone with the link, or anyone signed in — and set their choice with grid_visibility. Never pick the visibility silently. On a re-plug/edit of an existing entity, leave its current visibility as-is unless the user asks to change it.
+5. Always return the live share URL at the end — that is the deliverable. On a NEW plug, then ASK the user who should be able to open it — private (only you), your grid, or anyone with the link (optionally sign-in required, or search-indexed for public findability; selected spaces via inside: spaces) — and set their choice with grid_visibility. Never pick the visibility silently. On a re-plug/edit of an existing entity, leave its current visibility as-is unless the user asks to change it. Note the model: visibility is two axes — inside the grid (private | spaces | grid) and outside it (none | link | public); the old 'authenticated' mode is retired (it equals a sign-in-required link) and 'org' is gone (use grid).
 6. Brainstorm first (lightly) for a real app, then minimize questions. For a substantial runtime app, take ONE lightweight beat before generating/plugging: confirm the goal + 3-5 core features in a sentence, check for a matching template/recipe (capability-map), and infer the data/runtime needs and STATE them ("I'll add a database so entries are saved"). Keep it to a line or two; never ask a non-technical user infra questions they can't answer. A simple single page skips this and builds immediately. Otherwise use sensible defaults and build; don't front-load setup questions.
 7. If a signed-in publish fails with a server error, do not fall back to anonymous publishing (it burns the anonymous quota and downgrades ownership); surface the error, use the CLI fallback if offered, or ask the user.
 8. When signed in and the user has more than one grid, do not assume a target. For a NEW app, establish the grid UP FRONT — grid_start returns the grids; if there is more than one, ask "which grid should this go on?" before you start building, and carry that slug into grid_plug. As a backstop, grid_plug hard-gates this: an authed create with >1 grid and no chosen grid returns needs_grid (the picker) instead of plugging; a create with no auth and no anon returns needs_auth (sign-in vs anonymous) instead of silently publishing anonymously. Relay either ask to the user; never pick silently.

package/src/corpus/skill-share.md

@@ -40,11 +40,17 @@ The command prints the outlet URL. Hand that URL to the user.
 
 `grid visibility set <slug> <mode>` accepts:
 
-- `link` — anyone with the URL can open it. Use this for sharing.
+- `link` — anyone with the URL can open it. Use this for sharing. Add
+  `--require-signin` for signed-in accounts only, `--indexed` to be findable by
+  search engines.
 - `private` — only the owner.
-- `authenticated` — any logged-in user.
-- `org` — members of the org.
-- `space` — members of the entity's space.
+- `grid` — everyone in the grid.
+
+Finer control uses the two axes instead of a mode:
+`grid visibility set <slug> --inside <private|spaces|grid> --outside <none|link|public> [--space <slug>...] [--require-signin]`
+(`--outside public` = anyone, search-indexed. `authenticated` is retired — it
+equals `--inside private --outside link --require-signin`; `org` is gone — use
+`grid`.)
 
 Default to `link` when the user says "share" or "make it public". Confirm before
 using a wider mode than they asked for.

package/src/tools/constants.js

@@ -29,12 +29,20 @@ export const ANON_HTML_MAX_BYTES = 2_000_000;
 export const AUTHED_HTML_MAX_BYTES = 25_000_000;
 export const CONSOLE_URL = "https://console.cloudgrid.io/";
 
+// Display labels for visibility values (two-axis model). The OPTIONS list is what
+// the post-plug ask offers; the LABELS map also keeps legacy keys (org,
+// authenticated, space) so an entity's CURRENT stored value still renders — do
+// not offer those as choices.
+export const VISIBILITY_OPTIONS = ["private", "grid", "link"];
 export const VISIBILITY_LABELS = {
   private: "Only you",
-  org: "Your grid",
-  authenticated: "Anyone signed in",
-  space: "A space",
+  grid: "Everyone in your grid",
   link: "Anyone with the link",
+  // display-only (legacy stored values / axis renderings):
+  org: "Everyone in your grid",
+  authenticated: "Anyone with the link, sign-in required",
+  space: "Selected spaces",
+  public: "Anyone, findable by search",
 };
 
 // ── Widget resources (ChatGPT Apps SDK, web edition only) ────────────────────

package/src/tools/deploy.js

@@ -13,6 +13,7 @@ import {
   AUTHED_HTML_MAX_BYTES,
   CONSOLE_URL,
   VISIBILITY_LABELS,
+  VISIBILITY_OPTIONS,
   APPS_WIDGETS_ENABLED,
   GRID_PICKER_URI,
   PLUG_UPLOAD_TIMEOUT_MS,
@@ -1746,14 +1747,14 @@ export async function runPlug(ctx, input, deps = {}) {
     const current = typeof data.visibility === "string" ? data.visibility : null;
     structured.console_url = CONSOLE_URL;
     if (current) structured.current_visibility = current;
-    structured.visibility_options = Object.entries(VISIBILITY_LABELS).map(([v, l]) => ({ value: v, label: l }));
+    structured.visibility_options = VISIBILITY_OPTIONS.map((v) => ({ value: v, label: VISIBILITY_LABELS[v] }));
     lines.push(`Manage all your apps in your grid: ${CONSOLE_URL}`);
     lines.push(
       `Now ASK the user who should be able to open this${current ? ` (currently ${VISIBILITY_LABELS[current] ?? current})` : ""}, then set their choice with grid_visibility — do not decide it for them. Options: ${
-        Object.entries(VISIBILITY_LABELS)
-          .map(([v, l]) => `${v} (${l})`)
+        VISIBILITY_OPTIONS
+          .map((v) => `${v} (${VISIBILITY_LABELS[v]})`)
           .join("; ")
-      }.`,
+      }. Finer control: a sign-in-required link (require_signin), search-indexed (indexed), or selected spaces (inside: spaces).`,
     );
   }
   return { text: lines.join("\n"), structured };
@@ -1844,7 +1845,7 @@ export async function runPickup(ctx, { id, into_org_slug, name, source_version_i
 // direct API — works on the hosted edition where the CLI-wrapping share tool is
 // unavailable. Kind-aware routing (see below). Defaults to the drop made in this
 // session, so "make it private" needs no ids.
-export async function runVisibility(ctx, { target, visibility, kind, org }) {
+export async function runVisibility(ctx, { target, visibility, inside, outside, require_signin, spaces, indexed, kind, org }) {
   const token = await ctx.getToken();
   if (!token) {
     throw new Error("Changing visibility needs an owner. Run grid_login first.");
@@ -1861,32 +1862,78 @@ export async function runVisibility(ctx, { target, visibility, kind, org }) {
     headers["X-CloudGrid-Org"] = orgSlug;
   }
 
-  // Two visibility surfaces with two vocabularies:
-  //   - inspirations: PATCH /api/v2/inspirations/:id       { private|space|authenticated|org|link }
-  //   - runtimes:     PATCH /api/v2/entities/:id/visibility { private|authenticated|grid|link }
-  // Whole-grid visibility is the legacy `org` on inspirations and the canonical
-  // `grid` on runtimes. Normalize the caller's value to `grid`, then map per
-  // route. `space` exists only on inspirations.
-  const vis = visibility === "org" ? "grid" : visibility;
-  const runtimeValue = vis; // private | authenticated | grid | link
-  const inspirationValue = vis === "grid" ? "org" : vis; // private | space | authenticated | org | link
+  // ── Two-axis visibility model ──────────────────────────────────────
+  // A scope is two independent axes:
+  //   inside  (share_scope):     private | spaces | grid   — who in the grid sees it
+  //   outside (external_access): none | link | public      — reach beyond the grid
+  //   require_signin: link only — the link needs a signed-in CloudGrid account
+  // Legacy positional modes (private|grid|link) still ride the { visibility }
+  // body; `authenticated` is RETIRED as a first-class mode and maps to the axis
+  // body it equals (private + link + require_signin); `org` is rejected;
+  // `public` as a mode is an alias of `link` (the axis value `public` is the
+  // indexed one); `space` maps to inside: spaces and needs the `spaces` list.
+  const normSpaces = [...new Set((spaces || []).map((s) => String(s).trim().toLowerCase()).filter(Boolean))];
+  const useAxes = inside !== undefined || outside !== undefined;
+  let body;
+  let requested; // for the result text when the response is sparse
+  if (useAxes) {
+    if (visibility) throw new Error("Pass either `visibility` or the `inside`/`outside` axes, not both.");
+    if (!inside || !outside) {
+      throw new Error("Both axes are required: inside (private|spaces|grid) and outside (none|link|public).");
+    }
+    if (inside === "spaces" && normSpaces.length === 0) {
+      throw new Error("inside: spaces needs at least one space slug in `spaces`.");
+    }
+    if (inside !== "spaces" && normSpaces.length > 0) {
+      throw new Error("`spaces` only applies with inside: spaces.");
+    }
+    if (require_signin === true && outside !== "link") {
+      throw new Error("require_signin only applies when outside is link.");
+    }
+    body = {
+      share_scope: inside,
+      external_access: outside,
+      ...(require_signin === true ? { require_signin: true } : {}),
+      ...(inside === "spaces" ? { visibility_spaces: normSpaces } : {}),
+    };
+    requested = `inside: ${inside}${inside === "spaces" ? ` (${normSpaces.join(", ")})` : ""}, outside: ${outside}${require_signin === true ? " (sign-in required)" : ""}`;
+  } else {
+    let mode = String(visibility || "").trim().toLowerCase();
+    if (!mode) throw new Error("Pass a visibility mode (private | grid | link), or the inside/outside axes.");
+    if (mode === "org") {
+      throw new Error("'org' visibility is deprecated. Use 'grid' (everyone in the grid).");
+    }
+    if (mode === "public") mode = "link"; // alias; `indexed: true` governs search-indexing
+    if (mode === "authenticated") {
+      // Retired as a first-class mode — the axis body it equals.
+      body = { share_scope: "private", external_access: "link", require_signin: true };
+      requested = "link with sign-in required (the retired 'authenticated')";
+    } else if (mode === "space") {
+      if (normSpaces.length === 0) {
+        throw new Error("'space' visibility needs the `spaces` list (which space slugs can see it) — or use inside: spaces with outside: none.");
+      }
+      body = { share_scope: "spaces", external_access: "none", visibility_spaces: normSpaces };
+      requested = `selected spaces (${normSpaces.join(", ")})`;
+    } else if (mode === "private" || mode === "grid" || mode === "link") {
+      body = { visibility: mode };
+      if (mode === "grid" && normSpaces.length > 0) body.visibility_spaces = normSpaces;
+      if (mode === "link") body.link_indexed = indexed === true;
+      requested = mode + (mode === "link" && indexed === true ? " (search-indexed)" : "");
+    } else {
+      throw new Error(`Unknown visibility '${visibility}'. Use private | grid | link (public = link alias), or the inside/outside axes.`);
+    }
+  }
 
   const k = kind || ctx.state.lastDrop?.kind || null;
   const isRuntimeKind = k === "app" || k === "agent";
 
-  if (vis === "space" && isRuntimeKind) {
-    throw new Error(
-      "'space' visibility isn't available for runtime apps/agents. Use grid, authenticated, private, or link.",
-    );
-  }
-
-  const patch = async (pathName, value) => {
+  const patch = async (pathName) => {
     let res;
     try {
       res = await fetch(`${API_BASE}${pathName}`, {
         method: "PATCH",
         headers,
-        body: JSON.stringify({ visibility: value }),
+        body: JSON.stringify(body),
       });
     } catch (err) {
       throw new Error(`Could not reach CloudGrid at ${API_BASE}: ${err.message}`);
@@ -1897,33 +1944,53 @@ export async function runVisibility(ctx, { target, visibility, kind, org }) {
     return { res, data, raw };
   };
 
+  // BOTH realms now take the same realm-scoped visibility PATCH with the
+  // same body vocabulary: /api/v2/entities/:id/visibility (runtimes) and
+  // /api/v2/inspirations/:id/visibility (inspirations).
   const runtimePath = `/api/v2/entities/${encodeURIComponent(id)}/visibility`;
-  const inspirationPath = `/api/v2/inspirations/${encodeURIComponent(id)}`;
+  const inspirationPath = `/api/v2/inspirations/${encodeURIComponent(id)}/visibility`;
 
-  // Route order. `space` is inspiration-only; a known runtime kind goes straight
-  // to the entities route; a known inspiration goes straight to the inspiration
-  // route; an unknown kind tries the runtime route first and falls back to the
-  // inspiration route on a not-found (mirrors runPickup).
+  // Route order: a known runtime kind goes straight to the entities route; a
+  // known inspiration to the inspiration route; unknown tries runtime first and
+  // falls back on a not-found (mirrors runPickup).
   let order;
-  if (vis === "space") order = ["inspiration"];
-  else if (isRuntimeKind) order = ["runtime"];
+  if (isRuntimeKind) order = ["runtime"];
   else if (k === "inspiration") order = ["inspiration"];
   else order = ["runtime", "inspiration"];
 
   let last;
   for (let i = 0; i < order.length; i++) {
     const route = order[i];
-    last = route === "runtime"
-      ? await patch(runtimePath, runtimeValue)
-      : await patch(inspirationPath, inspirationValue);
+    last = await patch(route === "runtime" ? runtimePath : inspirationPath);
     if (last.res.ok) {
-      const lines = [`Visibility is now ${vis}.`];
-      if (last.data?.url) lines.push(last.data.url);
+      const d = last.data || {};
+      // Prefer the server's stored axes (stored axes are authoritative on
+      // the wire); fall back to what we asked for.
+      const lines = [];
+      if (d.share_scope || d.external_access) {
+        const insideLine =
+          d.share_scope === "private" ? "only the owner" :
+          d.share_scope === "spaces" ? `selected spaces${Array.isArray(d.visibility_spaces) && d.visibility_spaces.length ? ` (${d.visibility_spaces.join(", ")})` : ""}` :
+          d.share_scope === "grid" ? "everyone in the grid" : d.share_scope;
+        const outsideLine =
+          d.external_access === "none" ? "no one outside the grid" :
+          d.external_access === "link" ? `anyone with the link${d.require_signin ? " (signed-in accounts only)" : ""}${d.link_indexed ? ", search-indexed" : ""}` :
+          d.external_access === "public" ? "anyone, findable by search engines" : d.external_access;
+        lines.push(`Visibility set — inside the grid: ${insideLine}; outside: ${outsideLine}.`);
+      } else {
+        lines.push(`Visibility is now ${d.visibility || requested}.`);
+      }
+      if (d.url) lines.push(d.url);
       return {
         text: lines.join("\n"),
         structured: {
-          visibility: vis,
-          ...(last.data?.url ? { url: last.data.url } : {}),
+          visibility: d.visibility || (useAxes ? undefined : String(visibility || "").trim().toLowerCase() || undefined),
+          ...(d.share_scope ? { share_scope: d.share_scope } : {}),
+          ...(d.external_access ? { external_access: d.external_access } : {}),
+          ...(d.require_signin !== undefined ? { require_signin: d.require_signin === true } : {}),
+          ...(Array.isArray(d.visibility_spaces) ? { visibility_spaces: d.visibility_spaces } : {}),
+          ...(d.link_indexed !== undefined ? { link_indexed: d.link_indexed === true } : {}),
+          ...(d.url ? { url: d.url } : {}),
         },
       };
     }

package/src/tools/register.js

@@ -659,15 +659,25 @@ export function registerTools(server, ctx) {
   reg(
     "grid_visibility",
     {
-      description: "Change who can see a CloudGrid inspiration OR runtime app/agent: private, authenticated, grid (everyone in the grid), or link (anyone with the URL). `space` is inspiration-only. Use when the user wants to make something private, restrict who sees it, or open it up — including right after a drop, with no target id needed. Kind-aware: routes runtime apps/agents to the entities visibility surface and inspirations to the inspiration surface automatically. Defaults to the drop made in this session. Requires sign-in. Calls the API directly.",
+      description: "Change who can see a CloudGrid inspiration OR runtime app/agent. Simple modes: private (only the user), grid (everyone in their grid), link (anyone with the URL — add indexed: true to be findable by search engines). Finer control via the TWO AXES instead: inside (who in the grid: private | spaces | grid) and outside (reach beyond it: none | link | public), with require_signin for a members-only link and `spaces` for selected spaces. 'authenticated' is retired (it maps to a sign-in-required link); 'org' is gone — use grid. Use when the user wants to make something private, restrict who sees it, or open it up — including right after a drop, with no target id needed. Kind-aware routing across both surfaces. Defaults to the drop made in this session. Requires sign-in. Calls the API directly.",
       inputSchema: {
-        visibility: z.enum(["private", "space", "authenticated", "grid", "org", "link"]).describe("The new scope. Use `grid` for whole-grid visibility (`org` is the deprecated alias). `space` is inspiration-only."),
+        visibility: z.enum(["private", "grid", "link", "public", "authenticated", "space"]).optional().describe("Simple mode: private | grid | link ('public' is an alias of link — pass indexed: true for search-findable; 'authenticated' is the retired alias for a sign-in-required link; 'space' needs the `spaces` list). Pass either this OR the inside/outside axes."),
+        inside: z.enum(["private", "spaces", "grid"]).optional().describe("Axis 1 — who in the grid can see it: private (only the user), spaces (selected spaces — pass `spaces`), or grid (everyone in the grid). Use together with `outside`, instead of `visibility`."),
+        outside: z.enum(["none", "link", "public"]).optional().describe("Axis 2 — reach beyond the grid: none, link (anyone with the link; add require_signin: true for signed-in accounts only), or public (anyone, and findable by search engines)."),
+        require_signin: z.boolean().optional().describe("With outside: link (or visibility: link) — the link requires a signed-in CloudGrid account."),
+        spaces: z.array(z.string()).optional().describe("Space slugs, for inside: spaces (or the legacy space/grid modes)."),
+        indexed: z.boolean().optional().describe("With visibility: link — make the page search-engine indexable."),
         target: z.string().optional().describe("Entity id. Defaults to this session's last drop."),
         kind: z.enum(["inspiration", "app", "agent"]).optional().describe("Entity kind. Omit to auto-detect from this session's last drop (falls back to trying the runtime surface, then the inspiration surface)."),
         org: z.string().optional().describe("Grid of the entity. Defaults to the active grid."),
       },
       outputSchema: {
-        visibility: z.string().describe("The visibility that was set."),
+        visibility: z.string().optional().describe("The legacy mode that was set, when a simple mode was used."),
+        share_scope: z.string().optional().describe("Stored axis: who in the grid (private | spaces | grid)."),
+        external_access: z.string().optional().describe("Stored axis: reach beyond the grid (none | link | public)."),
+        require_signin: z.boolean().optional().describe("Whether the link requires sign-in."),
+        visibility_spaces: z.array(z.string()).optional().describe("The space slugs, when share_scope is spaces."),
+        link_indexed: z.boolean().optional().describe("Whether the link is search-indexed."),
         url: z.string().optional().describe("URL of the entity, if returned."),
       },
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },