@cloudgrid-io/mcp 0.20.49 → 0.20.51

package/README.md

@@ -6,17 +6,17 @@ It ships in two editions from one codebase:
 
 - **Local (stdio)** — runs on your machine, full toolset including the CLI-wrapping
   tools. This README covers it. For Claude Code, Cursor, Claude Desktop.
-- **Web (hosted HTTP)** — a light, CLI-free toolset (drop, claim, login,
-  visibility) for web clients like claude.ai. See [REMOTE.md](REMOTE.md).
+- **Web (hosted HTTP)** — a lighter toolset (14 shared direct-API tools, no CLI
+  wrappers) for web clients like claude.ai. See [REMOTE.md](REMOTE.md).
 
 The local edition wraps the `grid` CLI for authenticated operations (the CLI
 handles auth, org context, and error formatting) and calls the API directly for the
-drop, claim, and login tools.
+plug, login, and visibility tools.
 
 ## CLI compatibility
 
 The MCP uses an installed CLI only when it meets the platform floor
-(`MIN_CLI_VERSION`, currently 0.15.2 - kept in lockstep with the API's live
+(`MIN_CLI_VERSION`, currently 0.15.14 — kept in lockstep with the API's live
 `cli_compat` floor, which rejects older CLIs with HTTP 426). Below the floor it
 skips the local/global CLI and lazily fetches `@cloudgrid-io/cli@latest` via
 npx instead. A CI drift guard (`npm run test:drift-guard`) asserts every
@@ -50,13 +50,27 @@ npx -y @cloudgrid-io/mcp
 Or from a clone:
 
 ```
-cd mcp-server
+cd mcp
 npm install
 npm start
 ```
 
 It speaks MCP over stdio. Point any MCP client at the `cloudgrid-mcp` command.
 
+### One CloudGrid server per client
+
+Run EITHER this local (stdio) server — standalone or via the Claude Code
+plugin, which bundles it — OR a hosted connector (`mcp.cloudgrid.io` /
+`mcp-connected.cloudgrid.io`) in a given client. Never both: each `grid_*`
+tool appears twice, the two servers hold separate sign-in state (the local
+edition shares the CLI's `~/.cloudgrid/credentials`; the connector holds an
+OAuth session), and they can disagree about whether you are signed in — the
+model may then act on whichever answered last. How to tell: duplicate
+`grid_*` entries in the client's tool list, or two CloudGrid servers in its
+MCP/connector settings. Which to keep: the local edition wherever you build
+runtime apps from folders (it has `path` + the CLI); the connector in
+chat-only clients where you publish single pages.
+
 ### QA session log (optional)
 
 Set `CLOUDGRID_QA_SLACK_WEBHOOK` to an **internal / private** Slack incoming-webhook
@@ -67,24 +81,29 @@ MUST be internal. Unset → the feature is fully dark (nothing captured, nothing
 posted). `CLOUDGRID_QA_IDLE_MS` overrides the abandoned-idle window (default
 900000 = 15 min).
 
+<!-- gen:tools -->
 ## Tools
 
+36 tools registered (14 shared across both editions, 22 local-only). No deprecated aliases. MIN_CLI_VERSION: 0.15.14.
+
 ### Direct-API tools (both editions)
 
-| Tool | Wraps | Notes |
+| Tool | Wraps | Summary |
 |---|---|---|
-| `grid_deploy` | `POST /api/v2/plug` | THE deploy/publish verb (CloudGrid calls it "plug"): create a new entity, or update the SAME entity in place with `target_entity_id` (same URL). Source via inline `html` (single page), local `path` (local edition), or inline `artifact_files` (both). Anonymous drops return an `entity_id` + `owner_token` re-plug/claim handle. |
-| `grid_claim_anonymous_deploy` | `POST /api/v2/entities/:id/pickup` | Claim an anonymous drop into the signed-in account (the claim token IS the drop's owner token). |
-| `grid_copy_app` | `POST /api/v2/runtimes/:id/fork` | Start a new entity from an existing runtime (lineage recorded). Needs sign-in. |
-| `grid_download_source` | `GET /api/v2/runtimes/:id/source` | Signed 15-minute source-bundle URLs. Needs sign-in. |
-| `grid_get_app_source` | `GET /api/v2/.../source` | Fetch a deployed entity's source (resolves entity_id from a URL). Read-only. |
-| `grid_login` | `GET /auth/login` | Start a CLI-free sign-in; returns a URL to open. |
-| `grid_login_status` | `GET /auth/status` | Finish the sign-in; saves the token to the shared CLI credentials. |
-| `grid_visibility` | `PATCH /api/v2/inspirations/<id>` | Change who can see a drop (private, space, authenticated, org, link). Needs sign-in. |
-| `grid_list_grids` | `GET /api/v2/orgs` | List the caller's grids. Read-only. |
-| `grid_start` | corpus | Orientation: the playbook + workflow index + live context. Call FIRST. Read-only. |
-| `grid_get_template` | corpus | Fetch a workflow / template / example / doc from the bundled corpus. Read-only. (`grid_fetch` is a kept deprecated alias.) |
-| `grid_note` / `grid_report` / `grid_feedback` | API | Session notes, consent-gated error reports, feedback feed. |
+| `grid_pickup` | API | Pick up an app: make your OWN COPY of any app you can see (like a git fork) into a grid you can build in. |
+| `grid_pull` | API | Pull an app to continue/edit it IN PLACE — like `git clone` of the SAME entity: your next grid_plug (with its target_... |
+| `grid_create_grid` | API | Create a new grid (workspace) for the signed-in user — they become its admin. |
+| `grid_note` | API | Optionally leave a one-paragraph summary of what you built this session and why. |
+| `grid_plug` | API | Plug an app, website, game, or single HTML page into CloudGrid — the live runtime that runs it and provides its infra... |
+| `grid_get_app_source` | API | Retrieve the CURRENT deployed HTML of an inspiration/drop inline as text, so you can edit it and re-plug the SAME URL... |
+| `grid_login` | API | Start a CLI-free CloudGrid sign-in. |
+| `grid_login_status` | API | Finish a sign-in started by grid_login. |
+| `grid_visibility` | API | Change who can see a CloudGrid inspiration OR runtime app/agent. |
+| `grid_check_deploy` | API | Check whether an async runtime-app build has finished and the app is live. |
+| `grid_list_grids` | API | List the signed-in user's grids, each with slug, name, role, and provisioning status. |
+| `grid_start` | API | Orient before building with CloudGrid — the live runtime environment where the user's apps run WITH the infrastructur... |
+| `grid_get_template` | corpus | Load a specific CloudGrid workflow, template, example, rule, or doc by name — deterministic retrieval from the bundle... |
+| `grid_report` | API | Report a genuine CloudGrid failure to the CloudGrid team — ONLY with the user's explicit consent. |
 
 The direct-API tools call the platform without the CLI, so they also work in
 the web edition. `grid_login` writes the same `~/.cloudgrid/credentials` the
@@ -92,40 +111,38 @@ CLI uses, so the two share one identity.
 
 ### CLI-wrapping tools (local edition only)
 
-| Tool | Wraps | Notes |
+| Tool | Wraps | Summary |
 |---|---|---|
-| `grid_create_project` | `grid new` | Scaffold an app or agent project; optionally seed a web service. |
-| `grid_view_logs` | `grid logs` | Snapshot of recent logs. Does not stream. Read-only. (`grid_logs` is a kept deprecated alias.) |
-| `grid_share` | `grid visibility set` | Set visibility, default link. |
-| `grid_whoami` | `grid whoami` | Show the signed-in user and active grid. Read-only. |
+| `grid_create_project` | `grid new` | Scaffold a new CloudGrid app or agent folder (cloudgrid.yaml + a web service), optionally pre-declaring resources. |
+| `grid_view_logs` | `grid logs` | Tail recent logs for an entity. |
+| `grid_share` | `grid visibility set` | Set an entity's visibility and print its URL. |
+| `grid_feedback` | `grid feedback list` | List recent feedback events for the active grid. |
+| `grid_whoami` | `grid whoami` | Show the signed-in user and active grid. |
 | `grid_switch_grid` | `grid use` | Switch the active grid. |
-| `grid_logout` | `grid logout` | Sign out and clear local credentials. Destructive. |
-| `grid_status` | `grid status` | Grid dashboard or entity detail. Read-only. |
-| `grid_info` | `grid info` | Entity metadata. Read-only. |
-| `grid_get` | `grid get grids\|entities\|spaces` | List grids, entities, or spaces. Read-only. |
-| `grid_describe_grid` | `grid describe grid <slug>` | Grid detail. Read-only. |
-| `grid_edit_existing_app` | `grid pickup <name>` | Download an entity's source and bind the folder. |
-| `grid_rename` | `grid rename` | Rename an entity's display name. |
-| `grid_take_offline` | `grid unplug` | Take an entity off the grid. Destructive; requires confirm. |
-| `grid_delete` | `grid delete entity` | Archive an inspiration. Destructive; requires confirm. |
-| `grid_rollback_deploy` | `grid rollback` | Rollback to a previous version. |
-| `grid_list_versions` | `grid versions` | List published versions. Read-only. |
-| `grid_set_env` | `grid env` | Get, set, or list environment variables. |
-| `grid_set_secret` | `grid secrets` | Set or list secret names. Never returns secret values. |
-| `grid_scaffold` | `grid scaffold` | Generate starter files. |
-| `grid_diagnose` | `grid doctor` | Run local diagnostics. Read-only. |
-| `grid_get_url` | `grid open --print` | Return the public URL. Does not open a browser. Read-only. |
+| `grid_logout` | `grid logout` | Sign out and clear local credentials. |
+| `grid_status` | `grid status` | Org dashboard, entity detail, or deploy snapshot. |
+| `grid_info` | `grid info` | Show metadata for a CloudGrid entity. |
+| `grid_get` | `grid get <grids|entities|spaces> --json` | List CloudGrid grids, entities, or spaces. |
+| `grid_describe_grid` | `grid describe grid <slug> --json` | Show a grid's detail: role, members, spaces, tier, wildcard-TLS state. |
+| `grid_edit_existing_app` | `grid pull` | Continue/edit an EXISTING entity locally: download its source + cloudgrid.yaml and link the folder so your next `grid... |
+| `grid_rename` | `grid rename` | Rename a CloudGrid entity's display name (slug stays the same). |
+| `grid_take_offline` | `grid unplug` | Take an entity off the grid. |
+| `grid_delete` | `grid delete entity` | Archive a CloudGrid inspiration. |
+| `grid_rollback_deploy` | `grid rollback` | Rollback an entity to a previous version. |
+| `grid_list_versions` | `grid versions` | List published versions for an entity. |
+| `grid_set_env` | `grid env` | Manage environment variables for an entity. |
+| `grid_set_secret` | `grid secrets` | Set or list secret names for an entity. |
+| `grid_scaffold` | `grid scaffold` | Scaffold service folders declared in cloudgrid.yaml (idempotent). |
+| `grid_diagnose` | `grid doctor` | Run CloudGrid diagnostics on the local environment. |
+| `grid_get_url` | `grid open --print` | Return the public URL for an entity. |
+
+<!-- /gen:tools -->
 
 `grid_share` and `grid_visibility` overlap on purpose: `grid_share`
 wraps the CLI and defaults to `link`; `grid_visibility` is direct API, takes an
-explicit scope, and defaults its target to the session's last drop -- it is the one
+explicit scope, and defaults its target to the session's last drop — it is the one
 the web edition gets.
 
-37 tool names are advertised in total: 35 canonical + 2 kept deprecated
-aliases (`grid_fetch`, `grid_logs`). The 0.20.8 alias diet dropped the other 16
-legacy aliases. Per-tool internals (signature, sketch, behavior):
-[docs/TOOL-INTERNALS.md](docs/TOOL-INTERNALS.md).
-
 All tools carry MCP annotations (`readOnlyHint`, `destructiveHint`,
 `openWorldHint`) for clients that support them.
 
@@ -135,7 +152,7 @@ A smoke test spawns the server with a real MCP client, lists the tools, and call
 the read-only `grid_feedback` tool end to end:
 
 ```
-cd mcp-server
+cd mcp
 npm install
 npm run smoke
 ```
@@ -146,5 +163,5 @@ It needs a logged-in CLI on `$PATH`.
 
 - Shells out with `execFile` and an argument array, so there is no shell and no
   injection surface.
-- `grid_logs` never uses `--follow`; a streaming call would never return.
+- `grid_view_logs` never uses `--follow`; a streaming call would never return.
 - Stateless. Each call is one CLI invocation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.20.49",
+  "version": "0.20.51",
   "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/auth.js

@@ -25,6 +25,13 @@ const PUBLIC_API_BASE = (
   process.env.CLOUDGRID_PUBLIC_API_URL || "https://api.cloudgrid.io"
 ).replace(/\/+$/, "");
 
+// The public URL of the connected (OAuth) MCP host, used in error guidance that
+// suggests the hosted connector as an alternative. Derived from MCP_PUBLIC_URL
+// (set on the deployment) with a fallback.
+const CONNECTED_MCP_HOST =
+  process.env.MCP_PUBLIC_URL?.replace(/\/+$/, "") ||
+  "https://mcp-connected.cloudgrid.io";
+
 export function cloudgridHome() {
   return process.env.CLOUDGRID_HOME || join(homedir(), ".cloudgrid");
 }
@@ -52,7 +59,7 @@ const CERT_ERROR_GUIDANCE =
   "- Install the root CA into your OS trust store (macOS Keychain, Windows " +
   "Certificate Manager, or /usr/local/share/ca-certificates on Linux), or\n" +
   "- Set NODE_EXTRA_CA_CERTS=/path/to/root-ca.pem before launching the MCP, or\n" +
-  "- Use the hosted MCP connector: https://mcp-connected.cloudgrid.io/mcp";
+  `- Use the hosted MCP connector: ${CONNECTED_MCP_HOST}/mcp`;
 
 function throwCertError() {
   const err = new Error(CERT_ERROR_GUIDANCE);
@@ -82,7 +89,7 @@ export async function pollStatusOnce(code) {
     throw new Error(
       `Can't reach api.cloudgrid.io (${cause}). ` +
         `If you are behind a proxy, set HTTPS_PROXY; or use the hosted connector ` +
-        `https://mcp-connected.cloudgrid.io/mcp.`,
+        `${CONNECTED_MCP_HOST}/mcp.`,
     );
   }
   if (res.status === 404) {

package/src/corpus/install.md

@@ -136,8 +136,13 @@ npx -y @cloudgrid-io/mcp
 ```
 
 It wraps the same `grid` CLI and uses the same credentials, so no extra login
-is needed. Remote-capable clients can point at `https://mcp.cloudgrid.io/mcp`
-instead. See [USAGE.md](USAGE.md) for per-client snippets.
+is needed. Remote-capable clients can point at one of two hosted endpoints:
+
+- `https://mcp.cloudgrid.io/mcp` — anonymous-first; no account needed to try it.
+- `https://mcp-connected.cloudgrid.io/mcp` — connected; native OAuth sign-in
+  when you add it (for claude.ai org connectors and clients that support OAuth).
+
+See [USAGE.md](USAGE.md) for per-client snippets.
 
 ### Claude Desktop — one-click install
 

package/src/tools/cli.js

@@ -68,7 +68,12 @@ export function resolveBundledCli(deps = {}) {
     const pkgPath = pathImpl.join(srcDir, "..", "node_modules", "@cloudgrid-io", "cli", "package.json");
     if (!fsExists(pkgPath)) return null;
     const pkg = JSON.parse(fsRead(pkgPath, "utf-8"));
-    const bin = pkg.bin && pkg.bin.cloudgrid;
+    // The CLI's bin renamed cloudgrid -> grid (the product verb). Accept both:
+    // current packages ship { grid: ... } only; the cloudgrid key covers a
+    // bundled pre-rename CLI. Without the grid key this rung was silently DEAD
+    // on every current install and everything fell through to npx (review L7 —
+    // the flagged future risk had already happened).
+    const bin = pkg.bin && (pkg.bin.grid || pkg.bin.cloudgrid);
     if (!bin) return null;
     return { entry: pathImpl.join(pathImpl.dirname(pkgPath), bin), version: pkg.version || null };
   } catch {
@@ -358,10 +363,13 @@ export async function runCloudgrid(args, opts = {}, deps = {}) {
     );
   }
 
-  // 2. Global `cloudgrid` on PATH — version-gated.
-  //    On Windows the bin is `cloudgrid.cmd`; run it via cmd.exe (execMaybeCmd).
-  {
-    const globalBin = IS_WIN ? "cloudgrid.cmd" : "cloudgrid";
+  // 2. Global CLI on PATH — version-gated. The bin renamed cloudgrid -> grid
+  //    (the product verb); try `grid` first, then the pre-rename `cloudgrid`.
+  //    The version gate doubles as an identity check: an unrelated `grid`
+  //    binary won't print a CloudGrid semver >= the floor, so it is skipped.
+  //    On Windows the bins are `.cmd` shims; run via cmd.exe (execMaybeCmd).
+  for (const name of ["grid", "cloudgrid"]) {
+    const globalBin = IS_WIN ? `${name}.cmd` : name;
     let useGlobal = false;
     try {
       const { stdout: vOut } = await execMaybeCmd(
@@ -379,11 +387,11 @@ export async function runCloudgrid(args, opts = {}, deps = {}) {
         useGlobal = true;
       } else {
         console.error(
-          `cloudgrid-mcp: global CLI ${ver || vOut.trim()} < ${MIN_CLI_VERSION}, skipping`,
+          `cloudgrid-mcp: global CLI (${name}) ${ver || vOut.trim()} < ${MIN_CLI_VERSION}, skipping`,
         );
       }
     } catch {
-      // Not on PATH or --version failed — skip
+      // Not on PATH or --version failed — try the next name
     }
     if (useGlobal) {
       try {

package/src/tools/deploy.js

@@ -1240,6 +1240,15 @@ export async function runPlug(ctx, input, deps = {}) {
         "may accompany a .zip `path` — it becomes the index.html over the archive's assets.",
     );
   }
+  // M3: a create/re-plug with NO source at all is a caller mistake — fail it
+  // here with the source list instead of letting it wander into an obscure
+  // downstream error.
+  if (!hasHtml && !hasArtifacts && !hasPath) {
+    throw new Error(
+      "No source to plug. Pass exactly one of: `html` (a single inline HTML document), " +
+        "`artifact_files` (multiple inline files), or `path` (a local file/folder/zip, local edition only).",
+    );
+  }
   if (ctx.edition === "web" && hasPath) {
     throw new Error(
       "The hosted server cannot read local files — pass the source inline via `html` or `artifact_files`.",

package/src/tools/register.js

@@ -398,7 +398,10 @@ export function registerTools(server, ctx) {
         })).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."),
       },
-      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+      // 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
+      // honest MCP annotation for overwrite-live-state is destructive.
+      annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
       ...(ctx.edition === "web" && APPS_WIDGETS_ENABLED ? {
         _meta: {
           ui: { resourceUri: LIVE_RESULT_URI, csp: WIDGET_CSP },