@cloudgrid-io/mcp 0.5.1 → 0.5.3

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,24 @@ 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_get` | `cloudgrid get grids\|entities\|spaces` | List grids, entities, or spaces. Read-only. |
+| `cloudgrid_describe_grid` | `cloudgrid describe grid <slug>` | Grid detail. Read-only. |
+| `cloudgrid_pickup` | `cloudgrid pickup <name>` | Download an entity's source and bind the folder. |
+| `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.1",
+  "version": "0.5.3",
   "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

@@ -75,10 +75,39 @@ function resolveCwd(cwd) {
 }
 
 // Pin the CLI version for the lazy npx fallback so behaviour is reproducible.
-const CLI_NPX_PKG = "@cloudgrid-io/cli@^0.9.20";
-
-// Minimum CLI version that supports the flags the MCP passes (--auto etc.).
-const MIN_CLI_VERSION = "0.9.20";
+// 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_get:          ["get"],
+  cloudgrid_describe_grid: ["describe"],
+  cloudgrid_pickup:        ["pickup"],
+  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) {
@@ -1006,7 +1035,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"]),
@@ -1030,23 +1059,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(
@@ -1093,36 +1105,77 @@ export function registerTools(server, ctx) {
     }),
   );
 
+  // cloudgrid_get is the single canonical lister for grids, entities, and spaces
+  // (wraps `cloudgrid get <resource> --json`). It replaces the former
+  // cloudgrid_grid (which wrapped only `get entities`) — retired here so there is
+  // exactly one way to list entities. resource="entities" reproduces the old
+  // cloudgrid_grid behaviour with `grid` mapping to the CLI's `--grid` flag.
   server.tool(
-    "cloudgrid_builds",
-    "List recent builds and deploys for an entity. Wraps `cloudgrid builds`.",
+    "cloudgrid_get",
+    "List CloudGrid grids, entities, or spaces. Wraps `cloudgrid get <grids|entities|spaces> --json`.",
     {
-      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."),
+      resource: z.enum(["grids", "entities", "spaces"]).describe("What to list: grids, entities, or spaces."),
+      grid: z.string().optional().describe("Grid slug (entities/spaces only). Omit for the active grid."),
+      kind: z.enum(["app", "agent", "inspiration"]).optional().describe("Filter by kind (entities only)."),
+      status: z.enum(["charged", "live", "dark", "archived"]).optional().describe("Filter by status (entities only)."),
+      space: z.string().optional().describe("Only entities scoped to this space slug (entities only)."),
+      archived: z.boolean().optional().describe("Include archived entities (entities only)."),
     },
     { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
-    cliTool(({ name, limit }) => {
-      const args = ["builds"];
-      if (name) args.push(name);
-      if (limit) args.push("--limit", String(limit));
+    cliTool(({ resource, grid, kind, status, space, archived }) => {
+      const args = ["get", resource];
+      // --grid applies to entities and spaces; grids has no such flag.
+      if (grid && resource !== "grids") args.push("--grid", grid);
+      if (resource === "entities") {
+        if (kind) args.push("--kind", kind);
+        if (status) args.push("--status", status);
+        if (space) args.push("--space", space);
+        if (archived) args.push("--archived");
+      }
+      args.push("--json");
       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.") },
+    "cloudgrid_describe_grid",
+    "Show a grid's detail: role, members, spaces, tier, wildcard-TLS state. Wraps `cloudgrid describe grid <slug> --json`.",
+    { grid: z.string().describe("Grid slug to describe.") },
     { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
-    cliTool(({ org }) => (org ? ["grid", "--org", org] : ["grid"])),
+    cliTool(({ grid }) => ["describe", "grid", grid, "--json"]),
+  );
+
+  server.tool(
+    "cloudgrid_pickup",
+    "Download an entity's source + cloudgrid.yaml and link the folder to it. Overwrites with --force. Wraps `cloudgrid pickup`.",
+    {
+      name: z.string().describe("Entity slug or id to pick up."),
+      target_dir: z.string().optional().describe("Directory to pick up into (relative to cwd). Defaults to the entity name."),
+      grid: z.string().optional().describe("Grid to resolve the entity in. Defaults to the active grid."),
+      version: z.string().optional().describe("Pick up an older version's source instead of HEAD."),
+      force: z.boolean().optional().describe("Pick up into a non-empty directory."),
+      no_bind: z.boolean().optional().describe("Download source only — skip cloudgrid.yaml and the link."),
+      cwd: z.string().optional().describe("Working directory the CLI runs in. The download lands here; pass an explicit, writable directory."),
+    },
+    { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    cliTool(({ name, target_dir, grid, version, force, no_bind }) => {
+      const args = ["pickup", name];
+      if (target_dir) args.push(target_dir);
+      // The CLI's pickup --help exposes `--org <slug>` (legacy naming) for the grid.
+      if (grid) args.push("--org", grid);
+      if (version) args.push("--version", version);
+      if (force) args.push("--force");
+      if (no_bind) args.push("--no-bind");
+      return args;
+    }, { cwdParam: true }),
   );
 
   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]),
@@ -1141,13 +1194,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(
@@ -1159,7 +1212,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;
     }),
@@ -1215,7 +1268,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 }),
@@ -1223,19 +1276,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(
@@ -1248,11 +1294,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;
     }),