@cloudgrid-io/mcp 0.20.21 → 0.20.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.20.21",
+  "version": "0.20.23",
   "description": "Use CloudGrid via MCP to brainstorm, build, deploy, and improve apps, games, websites, dashboards, and tools and get a live URL - templates, recipes, managed databases and AI, instant single-page publish, and full-app deploys, for developers and non-technical users. Three editions: local stdio (full toolset), hosted web (light, CLI-free), and a public docs-search server, over MCP.",
   "type": "module",
   "bin": {
@@ -30,6 +30,7 @@
     "test:plug-output-schema": "node test/plug-output-schema.test.mjs",
     "test:zip-deploy": "node test/zip-deploy.test.mjs",
     "test:create-gates": "node test/create-gates.test.mjs",
+    "test:create-project-args": "node test/create-project-args.test.mjs",
     "test:mcpb-boot": "node test/mcpb-boot.test.mjs",
     "test:plug-timeout": "node test/plug-timeout.test.mjs",
     "test:manifest-confirm": "node test/manifest-confirm.test.mjs",
@@ -49,7 +50,8 @@
     "snapshot:corpus": "node scripts/snapshot-corpus.mjs",
     "build:mcpb": "node scripts/build-mcpb.mjs",
     "test:widgets": "node test/apps-widgets.test.mjs",
-    "test:fork": "node test/fork.test.mjs"
+    "test:fork": "node test/fork.test.mjs",
+    "test:set-sharing": "node test/set-sharing.test.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",

package/src/tools/constants.js

@@ -68,7 +68,7 @@ export const CLI_NPX_PKG = "@cloudgrid-io/cli@latest";
 // server-side with HTTP 426) — a gate below the floor green-lights CLIs the API
 // rejects on every call (issue #59). Bump this in lockstep with every floor
 // raise (CLI release protocol checklist).
-export const MIN_CLI_VERSION = "0.15.2";
+export const MIN_CLI_VERSION = "0.15.14";
 
 // Upload/create POST budget. The build itself is async (server returns 202 +
 // poll_url); this bounds only the request→response, so a stalled server errors

package/src/tools/deploy.js

@@ -1398,6 +1398,9 @@ export async function runPlug(ctx, input, deps = {}) {
     ctx.state.lastDrop = {
       entity_id: data.entity_id ?? null,
       url: url ?? null,
+      // Kind lets grid_set_sharing route to the right visibility surface
+      // (inspirations vs runtime entities) without a re-detect round-trip.
+      kind: data.detection?.kind ?? data.kind ?? null,
       owner_token: useAnonWire ? (freshOwnerToken ?? ownerToken ?? null) : null,
     };
   }
@@ -1619,10 +1622,11 @@ export async function runDownload(ctx, { id, version }) {
   };
 }
 
-// Change an inspiration's visibility. Authed, direct API — works on the hosted
-// edition where the CLI-wrapping share tool is unavailable. Defaults to the drop
-// made in this session, so "make it private" needs no ids.
-export async function runVisibility(ctx, { target, visibility, org }) {
+// Change an entity's visibility — inspiration OR runtime app/agent. Authed,
+// 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 }) {
   const token = await ctx.getToken();
   if (!token) {
     throw new Error("Changing visibility needs an owner. Run grid_login first.");
@@ -1638,33 +1642,86 @@ export async function runVisibility(ctx, { target, visibility, org }) {
     headers["X-CloudGrid-Grid"] = orgSlug;
     headers["X-CloudGrid-Org"] = orgSlug;
   }
-  let res;
-  try {
-    res = await fetch(`${API_BASE}/api/v2/inspirations/${encodeURIComponent(id)}`, {
-      method: "PATCH",
-      headers,
-      body: JSON.stringify({ visibility }),
-    });
-  } catch (err) {
-    throw new Error(`Could not reach CloudGrid at ${API_BASE}: ${err.message}`);
-  }
-  const raw = await res.text();
-  let data = null;
-  try { data = JSON.parse(raw); } catch { /* handled below */ }
-  if (!res.ok) {
-    const msg = data?.error?.message || raw || `HTTP ${res.status}`;
-    const hint = data?.error?.details?.[0]?.hint;
-    throw new Error(`Visibility change failed (HTTP ${res.status}): ${msg}${hint ? ` ${hint}` : ""}`);
+
+  // 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
+
+  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 lines = [`Visibility is now ${visibility}.`];
-  if (data?.url) lines.push(data.url);
-  return {
-    text: lines.join("\n"),
-    structured: {
-      visibility,
-      ...(data?.url ? { url: data.url } : {}),
-    },
+
+  const patch = async (pathName, value) => {
+    let res;
+    try {
+      res = await fetch(`${API_BASE}${pathName}`, {
+        method: "PATCH",
+        headers,
+        body: JSON.stringify({ visibility: value }),
+      });
+    } catch (err) {
+      throw new Error(`Could not reach CloudGrid at ${API_BASE}: ${err.message}`);
+    }
+    const raw = await res.text();
+    let data = null;
+    try { data = JSON.parse(raw); } catch { /* handled by caller */ }
+    return { res, data, raw };
   };
+
+  const runtimePath = `/api/v2/entities/${encodeURIComponent(id)}/visibility`;
+  const inspirationPath = `/api/v2/inspirations/${encodeURIComponent(id)}`;
+
+  // 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 runFork).
+  let order;
+  if (vis === "space") order = ["inspiration"];
+  else 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);
+    if (last.res.ok) {
+      const lines = [`Visibility is now ${vis}.`];
+      if (last.data?.url) lines.push(last.data.url);
+      return {
+        text: lines.join("\n"),
+        structured: {
+          visibility: vis,
+          ...(last.data?.url ? { url: last.data.url } : {}),
+        },
+      };
+    }
+    // Fall back runtime→inspiration only when the id isn't a runtime entity
+    // (a genuine 4xx like NOT_OWNER must surface, not silently re-route).
+    const code = last.data?.error?.code;
+    const canFallback =
+      route === "runtime" &&
+      i < order.length - 1 &&
+      (last.res.status === 404 || code === "NOT_FOUND" || code === "NOT_A_RUNTIME");
+    if (!canFallback) break;
+  }
+
+  const msg = last?.data?.error?.message || last?.raw || `HTTP ${last?.res?.status}`;
+  const hint = last?.data?.error?.details?.[0]?.hint;
+  throw new Error(`Visibility change failed (HTTP ${last?.res?.status}): ${msg}${hint ? ` ${hint}` : ""}`);
 }
 
 // Max HTML we'll return inline from runSource. Past this, we return the first

package/src/tools/register.js

@@ -28,6 +28,21 @@ import {
   runSource,
 } from "./deploy.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
+// `--agent` for agents (NOT the legacy `init <kind> <slug>` positional). The
+// old `--description` flag was removed from the CLI, so it is gone here too.
+// Exported pure so the argv is unit-tested without spawning a CLI.
+export function buildCreateProjectArgs({ kind, name, type, needs, dir, org } = {}) {
+  const args = ["new", name];
+  if (kind === "agent") args.push("--agent");
+  if (type) args.push("--type", type);
+  if (Array.isArray(needs) && needs.length) args.push("--needs", needs.join(","));
+  if (dir) args.push("--dir", dir);
+  if (org) args.push("--grid", org); // CLI 0.12 dropped --org for --grid (same slug)
+  return args;
+}
+
 // ── Registration ───────────────────────────────────────────────────────────────
 // Registers the tools onto `server`. ctx.edition decides whether the CLI-wrapping
 // tools are included (they need a local machine).
@@ -605,10 +620,11 @@ export function registerTools(server, ctx) {
   reg(
     "grid_set_sharing",
     {
-      description: "Change who can see a CloudGrid inspiration: private, space, authenticated, org, or link (anyone with the URL). Use when the user wants to make a drop private, restrict who sees it, or open it up — including right after a drop, with no target id needed. 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: 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.",
       inputSchema: {
-        visibility: z.enum(["private", "space", "authenticated", "org", "link"]).describe("The new scope."),
+        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."),
         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: {
@@ -861,26 +877,19 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_create_project",
-    "Register a new CloudGrid app or agent, optionally seeding a web service. Wraps `grid new` (`init` remains an alias).",
+    "Scaffold a new CloudGrid app or agent folder (cloudgrid.yaml + a web service), optionally pre-declaring resources. Wraps `grid new` (scaffolds locally; no server entity until you grid_deploy).",
     {
-      kind: z.enum(["app", "agent"]).describe("Entity kind."),
+      kind: z.enum(["app", "agent"]).describe("Entity kind. 'agent' scaffolds an agent: block."),
       name: z.string().describe("Slug: 3-40 lowercase alphanumerics and hyphens."),
       type: z.enum(["node", "nextjs", "python", "static"]).optional().describe("Seed a web service of this type."),
-      description: z.string().optional().describe("Initial one-line description."),
-      dir: z.string().optional().describe("Target directory. Defaults to ./<name>."),
-      org: z.string().optional().describe("Override the active grid for this project."),
+      needs: z.array(z.enum(["database", "cache", "kv", "queue", "pubsub", "vector", "ai", "disk"])).optional()
+        .describe("Pre-declare infrastructure needs in the scaffolded cloudgrid.yaml (e.g. [\"database\",\"ai\"])."),
+      dir: z.string().optional().describe("Target directory. Defaults to the current folder."),
+      org: z.string().optional().describe("Override the active grid this project will target."),
       cwd: z.string().optional().describe("Working directory. The CLI runs in this directory. Defaults to the MCP server's working directory."),
     },
     { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
-    cliTool(({ kind, name, type, description, dir, org }) => {
-      const args = ["init", kind, name];
-      if (type) args.push("--type", type);
-      if (description) args.push("--description", description);
-      if (dir) args.push("--dir", dir);
-      // CLI 0.12 dropped `--org` in favour of `--grid` (same slug).
-      if (org) args.push("--grid", org);
-      return args;
-    }, { cwdParam: true }),
+    cliTool((input) => buildCreateProjectArgs(input), { cwdParam: true }),
   );
 
   // NOTE: grid_deploy is no longer CLI-wrapping — the unified direct-API verb

package/src/tools.js

@@ -35,6 +35,7 @@ export {
   runPlug,
   runFork,
   runSource,
+  runVisibility,
 } from "./tools/deploy.js";
-export { registerTools } from "./tools/register.js";
+export { registerTools, buildCreateProjectArgs } from "./tools/register.js";
 export { decodeJwt } from "./auth.js";