@cloudgrid-io/mcp 0.5.0 → 0.5.2

package/README.md

@@ -13,6 +13,13 @@ The local edition wraps the `cloudgrid` CLI for authenticated operations (the CL
 handles auth, org context, and error formatting) and calls the API directly for the
 drop, claim, and login tools.
 
+## CLI compatibility
+
+MCP 0.5.2 is tested against CLI 0.10.1. The lazy-npx fallback pins
+`@cloudgrid-io/cli@~0.10.1` so a future CLI major with renamed verbs cannot
+silently break a released MCP. A CI drift guard (`npm run test:drift-guard`)
+asserts every wrapped verb exists in the CLI help.
+
 ## Prerequisite
 
 Install and log in to the CLI:
@@ -67,24 +74,22 @@ also work in the web edition where no CLI exists. `cloudgrid_login` writes the s
 | `cloudgrid_logs` | `cloudgrid logs` | Snapshot of recent logs. Does not stream. Read-only. |
 | `cloudgrid_share` | `cloudgrid visibility set` | Set visibility, default link. |
 | `cloudgrid_feedback` | `cloudgrid feedback list` | Read the org feedback feed. Read-only. |
-| `cloudgrid_brain` | `cloudgrid brain refresh` | Re-run the Grid Brain hooks. |
 | `cloudgrid_whoami` | `cloudgrid whoami` | Show the signed-in user and active org. Read-only. |
 | `cloudgrid_use` | `cloudgrid use` | Switch the active org. |
 | `cloudgrid_logout` | `cloudgrid logout` | Sign out and clear local credentials. Destructive. |
 | `cloudgrid_status` | `cloudgrid status` | Org dashboard or entity detail. Read-only. |
 | `cloudgrid_info` | `cloudgrid info` | Entity metadata. Read-only. |
-| `cloudgrid_builds` | `cloudgrid builds` | Recent builds and deploys. Read-only. |
-| `cloudgrid_grid` | `cloudgrid grid` | List entities on the hub. Read-only. |
-| `cloudgrid_rename` | `cloudgrid rename` | Rename an entity. |
+| `cloudgrid_grid` | `cloudgrid get entities` | List entities on the grid. Read-only. |
+| `cloudgrid_rename` | `cloudgrid rename` | Rename an entity's display name. |
 | `cloudgrid_unplug` | `cloudgrid unplug` | Take an entity off the grid. Destructive; requires confirm. |
-| `cloudgrid_delete` | `cloudgrid delete` | Archive and delete an entity. Destructive; requires confirm. |
+| `cloudgrid_delete` | `cloudgrid delete entity` | Archive an inspiration. Destructive; requires confirm. |
 | `cloudgrid_rollback` | `cloudgrid rollback` | Rollback to a previous version. |
 | `cloudgrid_versions` | `cloudgrid versions` | List published versions. Read-only. |
 | `cloudgrid_env` | `cloudgrid env` | Get, set, or list environment variables. |
 | `cloudgrid_secrets` | `cloudgrid secrets` | Set or list secret names. Never returns secret values. |
 | `cloudgrid_scaffold` | `cloudgrid scaffold` | Generate starter files. |
 | `cloudgrid_doctor` | `cloudgrid doctor` | Run local diagnostics. Read-only. |
-| `cloudgrid_open` | `cloudgrid open` | Return the public URL. Does not open a browser. Read-only. |
+| `cloudgrid_open` | `cloudgrid open --print` | Return the public URL. Does not open a browser. Read-only. |
 
 `cloudgrid_share` and `cloudgrid_visibility` overlap on purpose: `cloudgrid_share`
 wraps the CLI and defaults to `link`; `cloudgrid_visibility` is direct API, takes an

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "MCP server for CloudGrid. Three editions: a local stdio server (full toolset), a hosted web server (light, CLI-free toolset), and a public docs server (search_cloudgrid_documentation) over MCP Streamable HTTP.",
   "type": "module",
   "bin": {
@@ -16,6 +16,7 @@
     "start": "node src/index.js",
     "start:web": "node src/web.js",
     "smoke": "node test/smoke.mjs",
+    "test:drift-guard": "node test/drift-guard.mjs",
     "smoke:drop": "node test/smoke-drop.mjs",
     "smoke:login": "node test/smoke-login.mjs",
     "smoke:claim": "node test/smoke-claim.mjs",

package/src/tools.js

@@ -9,7 +9,6 @@
 // The difference is injected as a `ctx` object, so the tool logic is written once.
 
 import { execFile } from "node:child_process";
-import { createRequire } from "node:module";
 import { promisify } from "node:util";
 import { readFile } from "node:fs/promises";
 import { readFileSync, existsSync, statSync } from "node:fs";
@@ -75,24 +74,69 @@ function resolveCwd(cwd) {
   return abs;
 }
 
-// Resolve the bundled CLI entry point from this package's own node_modules.
-// Returns the absolute path to the JS entry, or null if unresolvable.
+// Pin the CLI version for the lazy npx fallback so behaviour is reproducible.
+// MCP 0.5.2 is tested against CLI 0.10.1.
+const CLI_NPX_PKG = "@cloudgrid-io/cli@~0.10.1";
+
+// Minimum CLI version that supports the verbs and flags the MCP passes.
+const MIN_CLI_VERSION = "0.10.1";
+
+// Verb map for the drift guard: each CLI-wrapping tool's top-level verb(s).
+// The drift-guard test imports this and asserts every verb exists in `cloudgrid --help`.
+export const CLI_TOOL_VERBS = {
+  cloudgrid_init:     ["init"],
+  cloudgrid_plug:     ["plug"],
+  cloudgrid_logs:     ["logs"],
+  cloudgrid_share:    ["visibility"],
+  cloudgrid_feedback: ["feedback"],
+  cloudgrid_whoami:   ["whoami"],
+  cloudgrid_use:      ["use"],
+  cloudgrid_logout:   ["logout"],
+  cloudgrid_status:   ["status"],
+  cloudgrid_info:     ["info"],
+  cloudgrid_grid:     ["get"],
+  cloudgrid_rename:   ["rename"],
+  cloudgrid_unplug:   ["unplug"],
+  cloudgrid_delete:   ["delete"],
+  cloudgrid_rollback: ["rollback"],
+  cloudgrid_versions: ["versions"],
+  cloudgrid_env:      ["env"],
+  cloudgrid_secrets:  ["secrets"],
+  cloudgrid_scaffold: ["scaffold"],
+  cloudgrid_doctor:   ["doctor"],
+  cloudgrid_open:     ["open"],
+};
+
+// Simple semver comparison: true when `version` >= MIN_CLI_VERSION.
+function meetsMinVersion(version) {
+  if (!version) return false;
+  const parse = (s) => s.replace(/^v/, "").split(".").map((p) => parseInt(p, 10) || 0);
+  const v = parse(version);
+  const m = parse(MIN_CLI_VERSION);
+  for (let i = 0; i < 3; i++) {
+    if ((v[i] || 0) > (m[i] || 0)) return true;
+    if ((v[i] || 0) < (m[i] || 0)) return false;
+  }
+  return true;
+}
+
+// Resolve the bundled CLI from this package's OWN node_modules only — never
+// walk up to parent directories (which may contain stale CLI versions).
+// Returns { entry, version } or null.
 function resolveBundledCli() {
   try {
-    const require = createRequire(import.meta.url);
-    const pkgPath = require.resolve("@cloudgrid-io/cli/package.json");
+    const srcDir = dirname(new URL(import.meta.url).pathname);
+    const pkgPath = join(srcDir, "..", "node_modules", "@cloudgrid-io", "cli", "package.json");
+    if (!existsSync(pkgPath)) return null;
     const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
     const bin = pkg.bin && pkg.bin.cloudgrid;
     if (!bin) return null;
-    return join(dirname(pkgPath), bin);
+    return { entry: join(dirname(pkgPath), bin), version: pkg.version || null };
   } catch {
     return null;
   }
 }
 
-// Pin the CLI version for the lazy npx fallback so behaviour is reproducible.
-const CLI_NPX_PKG = "@cloudgrid-io/cli@^0.9.20";
-
 async function runCloudgrid(args, opts = {}) {
   const cwd = resolveCwd(opts.cwd);
   const execOpts = {
@@ -110,28 +154,52 @@ async function runCloudgrid(args, opts = {}) {
     return new Error(detail || "cloudgrid command failed");
   };
 
-  // 1. Bundled CLI (the .mcpb ships it in its node_modules)
+  // 1. Bundled CLI — own node_modules only, version-gated
   const bundled = resolveBundledCli();
-  if (bundled) {
+  if (bundled && meetsMinVersion(bundled.version)) {
     try {
       const { stdout, stderr } = await execFileAsync(
         process.execPath,
-        [bundled, ...args],
+        [bundled.entry, ...args],
         execOpts,
       );
       return (stdout || stderr || "").trim() || "Done.";
     } catch (err) {
       throw extract(err);
     }
+  } else if (bundled) {
+    console.error(
+      `cloudgrid-mcp: bundled CLI ${bundled.version} < ${MIN_CLI_VERSION}, skipping`,
+    );
   }
 
-  // 2. Global `cloudgrid` on PATH
-  try {
-    const { stdout, stderr } = await execFileAsync("cloudgrid", args, execOpts);
-    return (stdout || stderr || "").trim() || "Done.";
-  } catch (err) {
-    if (!(err && err.code === "ENOENT")) throw extract(err);
-    // Not found — fall through to lazy npx fetch
+  // 2. Global `cloudgrid` on PATH — version-gated
+  {
+    let useGlobal = false;
+    try {
+      const { stdout: vOut } = await execFileAsync("cloudgrid", ["--version"], {
+        timeout: 5_000,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+      const ver = vOut.trim().match(/(\d+\.\d+\.\d+)/)?.[1];
+      if (meetsMinVersion(ver)) {
+        useGlobal = true;
+      } else {
+        console.error(
+          `cloudgrid-mcp: global CLI ${ver || vOut.trim()} < ${MIN_CLI_VERSION}, skipping`,
+        );
+      }
+    } catch {
+      // Not on PATH or --version failed — skip
+    }
+    if (useGlobal) {
+      try {
+        const { stdout, stderr } = await execFileAsync("cloudgrid", args, execOpts);
+        return (stdout || stderr || "").trim() || "Done.";
+      } catch (err) {
+        throw extract(err);
+      }
+    }
   }
 
   // 3. Lazy fetch: npx -y @cloudgrid-io/cli@<pinned> <args>
@@ -965,7 +1033,7 @@ export function registerTools(server, ctx) {
     "Set an entity's visibility and print its URL. Defaults to link (anyone with the URL). Wraps `cloudgrid visibility set`.",
     {
       name: z.string().describe("Entity slug."),
-      mode: z.enum(["link", "private", "authenticated", "org", "space"]).optional().describe("Visibility mode. Default link."),
+      mode: z.enum(["link", "private", "authenticated", "grid"]).optional().describe("Visibility mode. Default link."),
     },
     { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
     cliTool(({ name, mode }) => ["visibility", "set", name, mode ?? "link"]),
@@ -989,23 +1057,6 @@ export function registerTools(server, ctx) {
     }),
   );
 
-  server.tool(
-    "cloudgrid_brain",
-    "Re-run an entity's Grid Brain hooks to re-classify its description, tags, and diagram. Wraps `cloudgrid brain refresh`.",
-    {
-      name: z.string().describe("Entity slug."),
-      wait: z.boolean().optional().describe("Wait for the refresh to finish. Default true."),
-      org: z.string().optional().describe("Target an entity in another org."),
-    },
-    { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
-    cliTool(({ name, wait, org }) => {
-      const args = ["brain", "refresh", name];
-      if (wait !== false) args.push("--wait");
-      if (org) args.push("--org", org);
-      return args;
-    }),
-  );
-
   // ── New CLI-wrapping tools (local edition only) ───────────────────────────
 
   server.tool(
@@ -1052,36 +1103,20 @@ export function registerTools(server, ctx) {
     }),
   );
 
-  server.tool(
-    "cloudgrid_builds",
-    "List recent builds and deploys for an entity. Wraps `cloudgrid builds`.",
-    {
-      name: z.string().optional().describe("Entity name. Omit for the entity linked to the current directory."),
-      limit: z.number().int().positive().optional().describe("Number of builds to show."),
-    },
-    { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
-    cliTool(({ name, limit }) => {
-      const args = ["builds"];
-      if (name) args.push(name);
-      if (limit) args.push("--limit", String(limit));
-      return args;
-    }),
-  );
-
   server.tool(
     "cloudgrid_grid",
-    "List entities on the hub or org. Wraps `cloudgrid grid`.",
-    { org: z.string().optional().describe("Org slug. Omit for the active org.") },
+    "List entities on the grid. Wraps `cloudgrid get entities`.",
+    { grid: z.string().optional().describe("Grid slug. Omit for the active grid.") },
     { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
-    cliTool(({ org }) => (org ? ["grid", "--org", org] : ["grid"])),
+    cliTool(({ grid }) => (grid ? ["get", "entities", "--grid", grid] : ["get", "entities"])),
   );
 
   server.tool(
     "cloudgrid_rename",
-    "Rename a CloudGrid entity. Wraps `cloudgrid rename`.",
+    "Rename a CloudGrid entity's display name (slug stays the same). Wraps `cloudgrid rename`.",
     {
-      name: z.string().describe("Current entity slug."),
-      new_name: z.string().describe("New slug."),
+      name: z.string().describe("Entity slug."),
+      new_name: z.string().describe("New display name."),
     },
     { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
     cliTool(({ name, new_name }) => ["rename", name, new_name]),
@@ -1100,13 +1135,13 @@ export function registerTools(server, ctx) {
 
   server.tool(
     "cloudgrid_delete",
-    "Archive and delete a CloudGrid entity. Destructive. Wraps `cloudgrid delete`.",
+    "Archive a CloudGrid inspiration. Destructive. Wraps `cloudgrid delete entity`.",
     {
       name: z.string().describe("Entity slug to delete (required)."),
       confirm: z.literal(true).describe("Must be true to proceed."),
     },
     { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
-    cliTool(({ name }) => ["delete", name, "--yes"]),
+    cliTool(({ name }) => ["delete", "entity", name, "--yes"]),
   );
 
   server.tool(
@@ -1118,7 +1153,7 @@ export function registerTools(server, ctx) {
     },
     { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
     cliTool(({ name, to }) => {
-      const args = ["rollback", name];
+      const args = ["rollback", name, "--yes"];
       if (to) args.push("--to", to);
       return args;
     }),
@@ -1174,7 +1209,7 @@ export function registerTools(server, ctx) {
     cliTool(({ action, name, key, value }) => {
       if (action === "set") {
         if (!key || value === undefined) throw new Error("key and value are required for set");
-        return ["secrets", "set", name, key, value];
+        return ["secrets", "set", name, `${key}=${value}`];
       }
       return ["secrets", "list", name];
     }, { cwdParam: true }),
@@ -1182,19 +1217,12 @@ export function registerTools(server, ctx) {
 
   server.tool(
     "cloudgrid_scaffold",
-    "Generate starter files for a CloudGrid entity. Wraps `cloudgrid scaffold`.",
+    "Scaffold service folders declared in cloudgrid.yaml (idempotent). Wraps `cloudgrid scaffold`.",
     {
-      template: z.string().optional().describe("Template name."),
-      dir: z.string().optional().describe("Target directory."),
       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(({ template, dir }) => {
-      const args = ["scaffold"];
-      if (template) args.push(template);
-      if (dir) args.push("--dir", dir);
-      return args;
-    }, { cwdParam: true }),
+    cliTool(() => ["scaffold"], { cwdParam: true }),
   );
 
   server.tool(
@@ -1207,11 +1235,11 @@ export function registerTools(server, ctx) {
 
   server.tool(
     "cloudgrid_open",
-    "Return the public URL for an entity. Does not open a browser. Wraps `cloudgrid open --url`.",
+    "Return the public URL for an entity. Does not open a browser. Wraps `cloudgrid open --print`.",
     { name: z.string().optional().describe("Entity name. Omit for the entity linked to the current directory.") },
     { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
     cliTool(({ name }) => {
-      const args = ["open", "--url"];
+      const args = ["open", "--print"];
       if (name) args.push(name);
       return args;
     }),