@cloudgrid-io/mcp 0.2.0

package/README.md

@@ -0,0 +1,83 @@
+# @cloudgrid-io/mcp
+
+An MCP server for CloudGrid. It exposes the CloudGrid actions as MCP tools.
+
+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) for
+  web clients like claude.ai. See [REMOTE.md](REMOTE.md).
+
+The local edition wraps the `cloudgrid` 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.
+
+## Prerequisite
+
+Install and log in to the CLI:
+
+```
+npm install -g @cloudgrid-io/cli
+cloudgrid login
+```
+
+The server reads no credentials directly. It runs `cloudgrid`, which uses its own
+stored credentials at `~/.cloudgrid/credentials`.
+
+## Run
+
+```
+npx -y @cloudgrid-io/mcp
+```
+
+Or from a clone:
+
+```
+cd mcp-server
+npm install
+npm start
+```
+
+It speaks MCP over stdio. Point any MCP client at the `cloudgrid-mcp` command.
+
+## Tools
+
+| Tool | Wraps | Notes |
+|---|---|---|
+| `cloudgrid_drop` | `POST /api/v2/drop/auto` | Artifact drop. Anonymous, or owned if signed in. No CLI. Direct API. |
+| `cloudgrid_claim` | `POST /api/v2/anon-claim` | Claim an anonymous drop into the signed-in account. Direct API. |
+| `cloudgrid_login` | `GET /auth/login` | Start a CLI-free sign-in; returns a URL to open. Calls the API directly. |
+| `cloudgrid_login_status` | `GET /auth/status` | Finish the sign-in; saves the token to the shared CLI credentials. |
+| `cloudgrid_init` | `cloudgrid init` | Register an app or agent; optionally seed a web service. |
+| `cloudgrid_plug` | `cloudgrid plug` | Deploy a directory or URL. |
+| `cloudgrid_logs` | `cloudgrid logs` | Snapshot of recent logs. Does not stream. |
+| `cloudgrid_share` | `cloudgrid visibility set` | Set visibility, default link. |
+| `cloudgrid_feedback` | `cloudgrid feedback list` | Read the org feedback feed. |
+| `cloudgrid_brain` | `cloudgrid brain refresh` | Re-run the Grid Brain hooks. |
+
+`cloudgrid_drop` and the two `cloudgrid_login` tools are the ones that do not wrap
+the CLI — both are about working without it. The anonymous drop has no identity to
+manage; login exists to get an identity without the CLI. Both call the API directly.
+`cloudgrid_login` writes the same `~/.cloudgrid/credentials` the CLI uses, so the two
+share one identity.
+
+## Test
+
+A smoke test spawns the server with a real MCP client, lists the tools, and calls
+the read-only `cloudgrid_feedback` tool end to end:
+
+```
+cd mcp-server
+npm install
+npm run smoke
+```
+
+It needs a logged-in CLI on `$PATH`.
+
+## Design
+
+- Shells out with `execFile` and an argument array, so there is no shell and no
+  injection surface.
+- `cloudgrid_logs` never uses `--follow`; a streaming call would never return.
+- Stateless. Each call is one CLI invocation.

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@cloudgrid-io/mcp",
+  "version": "0.2.0",
+  "description": "MCP server for CloudGrid. Two editions: a local stdio server (full toolset) and a hosted web server (light, CLI-free toolset) over MCP Streamable HTTP.",
+  "type": "module",
+  "bin": {
+    "cloudgrid-mcp": "src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "start:web": "node src/web.js",
+    "smoke": "node test/smoke.mjs",
+    "smoke:drop": "node test/smoke-drop.mjs",
+    "smoke:login": "node test/smoke-login.mjs",
+    "smoke:claim": "node test/smoke-claim.mjs",
+    "smoke:web": "node test/smoke-web.mjs",
+    "test:auth": "node test/auth.test.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "express": "^4.22.2",
+    "zod": "^3.23.0"
+  },
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/cloudgrid-io/skills/tree/main/mcp-server",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cloudgrid-io/skills.git",
+    "directory": "mcp-server"
+  }
+}

package/src/auth.js

@@ -0,0 +1,98 @@
+// CLI-free sign-in against CloudGrid's existing OAuth backend.
+//
+// The flow is the same one `cloudgrid login` uses, driven without the CLI:
+//   1. pick a UUID `code`
+//   2. user opens GET /auth/login?code=<code> and signs in with Google
+//   3. poll GET /auth/status?code=<code> until it returns the signed JWT (once)
+//   4. write the JWT to ~/.cloudgrid/credentials in the CLI's format, so the CLI
+//      and the MCP share one identity.
+//
+// No new identity provider, no localhost callback, no CLI dependency.
+
+import { randomUUID } from "node:crypto";
+import { mkdir, writeFile, chmod, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const API_BASE = (process.env.CLOUDGRID_API_URL || "https://api.cloudgrid.io").replace(/\/+$/, "");
+
+export function cloudgridHome() {
+  return process.env.CLOUDGRID_HOME || join(homedir(), ".cloudgrid");
+}
+
+export function credentialsPath() {
+  return join(cloudgridHome(), "credentials");
+}
+
+export function newLoginCode() {
+  return randomUUID();
+}
+
+export function buildLoginUrl(code) {
+  return `${API_BASE}/auth/login?code=${encodeURIComponent(code)}`;
+}
+
+// One poll. Returns { status: 'not_started' | 'pending' | 'authenticated' | 'expired', jwt? }.
+// A 404 means the session for this code does not exist yet — the user has not
+// opened the sign-in URL — so it is reported as 'not_started', not an error.
+export async function pollStatusOnce(code) {
+  const res = await fetch(`${API_BASE}/auth/status?code=${encodeURIComponent(code)}`);
+  if (res.status === 404) {
+    return { status: "not_started" };
+  }
+  if (!res.ok) {
+    throw new Error(`Sign-in status check failed: HTTP ${res.status}`);
+  }
+  return res.json();
+}
+
+// Read the stored credentials, or null if absent/unreadable. Same file the CLI
+// writes, so an MCP can reuse a CLI login (and vice versa).
+export async function readCredentials() {
+  try {
+    const creds = JSON.parse(await readFile(credentialsPath(), "utf8"));
+    return creds && creds.jwt ? creds : null;
+  } catch {
+    return null;
+  }
+}
+
+// The CLI's active org slug from ~/.cloudgrid/config.yaml, or null. A minimal
+// line parse — no YAML dependency for one field.
+export async function readActiveOrgSlug() {
+  try {
+    const raw = await readFile(join(cloudgridHome(), "config.yaml"), "utf8");
+    const m = raw.match(/^\s*active_org_slug:\s*(\S+)\s*$/m);
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+// Decode a JWT payload without verifying it — only to populate the credentials
+// file's email/user_id fields. The server verifies the token on every use.
+export function decodeJwt(jwt) {
+  try {
+    const part = jwt.split(".")[1];
+    const json = Buffer.from(part.replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf8");
+    return JSON.parse(json);
+  } catch {
+    return {};
+  }
+}
+
+// Write the JWT to ~/.cloudgrid/credentials in the CLI's exact shape and 0600.
+export async function writeCredentials(jwt) {
+  const claims = decodeJwt(jwt);
+  const creds = {
+    jwt,
+    issued_at: new Date().toISOString(),
+    email: claims.email ?? null,
+    user_id: claims.sub ?? null,
+  };
+  await mkdir(cloudgridHome(), { recursive: true });
+  const path = credentialsPath();
+  await writeFile(path, JSON.stringify(creds, null, 2) + "\n", { mode: 0o600 });
+  await chmod(path, 0o600); // enforce even if the file pre-existed
+  return creds;
+}

package/src/index.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// CloudGrid MCP server — local edition (stdio).
+//
+// Runs as a subprocess of a local MCP client (Claude Code, Cursor, Claude
+// Desktop). Full toolset, including the CLI-wrapping tools. Identity comes from
+// the shared ~/.cloudgrid/credentials file, so it interoperates with the CLI.
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerTools } from "./tools.js";
+import {
+  readCredentials,
+  readActiveOrgSlug,
+  writeCredentials,
+  credentialsPath,
+} from "./auth.js";
+
+const ctx = {
+  edition: "local",
+  state: { pendingLoginCode: null, lastAnonClaim: null },
+  canOpenBrowser: true,
+  getToken: async () => (await readCredentials())?.jwt ?? null,
+  getActiveOrg: async () => await readActiveOrgSlug(),
+  saveToken: async (jwt) => await writeCredentials(jwt),
+  savedLocationNote: () => `Credentials saved to ${credentialsPath()}.`,
+};
+
+const server = new McpServer({ name: "cloudgrid-mcp", version: "0.2.0" });
+registerTools(server, ctx);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/tools.js

@@ -0,0 +1,419 @@
+// Shared tool core for both editions of the CloudGrid MCP server.
+//
+// Two editions register from here:
+//   - local (stdio): full toolset, including the CLI-wrapping tools. Identity
+//     comes from ~/.cloudgrid/credentials.
+//   - web (HTTP, hosted): the light, CLI-free toolset (drop, claim, login).
+//     Identity is a per-session token held in memory.
+//
+// The difference is injected as a `ctx` object, so the tool logic is written once.
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { z } from "zod";
+import { newLoginCode, buildLoginUrl, pollStatusOnce, decodeJwt } from "./auth.js";
+
+const execFileAsync = promisify(execFile);
+
+export const API_BASE = (process.env.CLOUDGRID_API_URL || "https://api.cloudgrid.io").replace(
+  /\/+$/,
+  "",
+);
+
+const ANON_HTML_MAX_BYTES = 2_000_000;
+
+function ok(text) {
+  return { content: [{ type: "text", text }] };
+}
+function fail(text) {
+  return { content: [{ type: "text", text }], isError: true };
+}
+
+// ── CLI wrapping (local edition only) ──────────────────────────────────────────
+async function runCloudgrid(args) {
+  try {
+    const { stdout, stderr } = await execFileAsync("cloudgrid", args, {
+      maxBuffer: 16 * 1024 * 1024,
+      timeout: 10 * 60 * 1000,
+    });
+    return (stdout || stderr || "").trim() || "Done.";
+  } catch (err) {
+    if (err && err.code === "ENOENT") {
+      throw new Error(
+        "The cloudgrid CLI is not installed. Install it with: npm install -g @cloudgrid-io/cli",
+      );
+    }
+    const detail = [err && err.stdout, err && err.stderr, err && err.message]
+      .filter(Boolean)
+      .join("\n")
+      .trim();
+    throw new Error(detail || "cloudgrid command failed");
+  }
+}
+
+function cliTool(buildArgs) {
+  return async (input) => {
+    try {
+      return ok(await runCloudgrid(buildArgs(input || {})));
+    } catch (err) {
+      return fail(err.message);
+    }
+  };
+}
+
+function tryOpenBrowser(url) {
+  if (process.env.CLOUDGRID_NO_BROWSER === "1") return;
+  const cmd =
+    process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  try {
+    execFile(cmd, [url], () => {});
+  } catch {
+    // ignore — the URL is returned to the user anyway
+  }
+}
+
+// ── Direct-API tools (both editions) ───────────────────────────────────────────
+function looksLikeFullHtml(s) {
+  const head = s.replace(/^/, "").trimStart().slice(0, 256).toLowerCase();
+  return head.startsWith("<!doctype html") || head.startsWith("<html");
+}
+
+async function runDrop(ctx, { html, path: filePath, filename, anonymous, org }) {
+  let bytes;
+  let name;
+  let type;
+
+  if (filePath) {
+    bytes = await readFile(filePath);
+    name = filename || basename(filePath);
+    type = "application/octet-stream";
+  } else if (typeof html === "string" && html.length > 0) {
+    let content = html;
+    if (!looksLikeFullHtml(content)) {
+      content =
+        `<!doctype html>\n<html lang="en">\n<head><meta charset="utf-8">` +
+        `<title>Shared on CloudGrid</title></head>\n<body>\n${content}\n</body>\n</html>\n`;
+    }
+    bytes = Buffer.from(content, "utf8");
+    name = filename || "index.html";
+    type = "text/html";
+    if (bytes.byteLength > ANON_HTML_MAX_BYTES) {
+      throw new Error(
+        `This HTML is ${(bytes.byteLength / 1e6).toFixed(2)} MB. Anonymous drops are capped at 2 MB. ` +
+          `Trim it, or sign in to publish larger.`,
+      );
+    }
+  } else {
+    throw new Error("Provide either `html` (inline content) or `path` (a local file).");
+  }
+
+  const headers = {};
+  let orgSlug = null;
+  if (anonymous !== true) {
+    const token = await ctx.getToken();
+    if (token) {
+      headers["Authorization"] = `Bearer ${token}`;
+      orgSlug = org || (await ctx.getActiveOrg());
+      if (orgSlug) headers["X-CloudGrid-Org"] = orgSlug;
+    }
+  }
+
+  const form = new FormData();
+  form.append("artifact", new Blob([bytes], { type }), name);
+  if (orgSlug) form.append("org_slug", orgSlug);
+
+  let res;
+  try {
+    res = await fetch(`${API_BASE}/api/v2/drop/auto`, { method: "POST", headers, body: form });
+  } 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 || data?.message || raw || `HTTP ${res.status}`;
+    const hint = data?.error?.details?.[0]?.hint;
+    throw new Error(`Drop failed (HTTP ${res.status}): ${msg}${hint ? ` ${hint}` : ""}`);
+  }
+
+  if (data.owned_by === "authenticated") {
+    ctx.state.lastAnonClaim = null;
+    const lines = [`Published to your org: ${data.url}`, "Owned by you."];
+    if (data.expires_at) lines.push(`Expires ${data.expires_at}.`);
+    return lines.join("\n");
+  }
+
+  if (data.claim_url) {
+    try {
+      ctx.state.lastAnonClaim = {
+        token: new URL(data.claim_url).searchParams.get("token"),
+        entity_id: data.entity_id,
+        url: data.url,
+      };
+    } catch {
+      ctx.state.lastAnonClaim = null;
+    }
+  }
+  const lines = [`Live: ${data.url}`];
+  if (data.expires_at) lines.push(`Expires ${data.expires_at} — anonymous drops last 7 days.`);
+  if (data.claim_url) lines.push("Sign in, then run cloudgrid_claim to keep it past 7 days.");
+  return lines.join("\n");
+}
+
+async function runClaim(ctx, { claim_token, claim_url }) {
+  const token = await ctx.getToken();
+  if (!token) {
+    throw new Error("You are not signed in. Run cloudgrid_login first, then claim.");
+  }
+  let claimToken = claim_token;
+  if (!claimToken && claim_url) {
+    try {
+      claimToken = new URL(claim_url).searchParams.get("token");
+    } catch {
+      claimToken = null;
+    }
+  }
+  if (!claimToken && ctx.state.lastAnonClaim) claimToken = ctx.state.lastAnonClaim.token;
+  if (!claimToken) {
+    throw new Error("No claim token. Pass claim_token or claim_url from an anonymous drop.");
+  }
+
+  let res;
+  try {
+    res = await fetch(`${API_BASE}/api/v2/anon-claim`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+      body: JSON.stringify({ claim_token: claimToken }),
+    });
+  } 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 || data?.message || raw || `HTTP ${res.status}`;
+    throw new Error(`Claim failed (HTTP ${res.status}): ${msg}`);
+  }
+  const claimed = Array.isArray(data?.claimed) ? data.claimed : [];
+  if (claimed.length === 0) return "Nothing to claim — it may already be claimed or expired.";
+  ctx.state.lastAnonClaim = null;
+  const lines = [`Claimed ${claimed.length}, now yours:`];
+  for (const c of claimed) {
+    lines.push(`${c.url}${c.new_expires_at ? ` (expires ${c.new_expires_at})` : ""}`);
+  }
+  return lines.join("\n");
+}
+
+// ── Registration ───────────────────────────────────────────────────────────────
+// Registers the tools onto `server`. ctx.edition decides whether the CLI-wrapping
+// tools are included (they need a local machine).
+export function registerTools(server, ctx) {
+  // Drop — both editions.
+  server.tool(
+    "cloudgrid_drop",
+    "Publish an HTML page or file to CloudGrid and get a public shareable URL. Use when the user wants to share, publish, send, or 'deploy' an artifact, or wants a link to send a friend. If signed in, it publishes into the user's org as an owned inspiration (30-day expiry); if not, it drops anonymously (7-day expiry, claimable later). Calls the API directly.",
+    {
+      html: z.string().optional().describe("Inline HTML to publish. A fragment is wrapped into a full document."),
+      path: z.string().optional().describe("Path to a local file to upload instead of inline HTML."),
+      filename: z.string().optional().describe("Filename to present. Defaults to index.html for inline HTML."),
+      anonymous: z.boolean().optional().describe("Force an anonymous drop even if the user is signed in."),
+      org: z.string().optional().describe("Org slug to publish into when signed in. Defaults to the active org."),
+    },
+    async (input) => {
+      try {
+        return ok(await runDrop(ctx, input || {}));
+      } catch (err) {
+        return fail(err.message);
+      }
+    },
+  );
+
+  // Claim — both editions.
+  server.tool(
+    "cloudgrid_claim",
+    "Claim an anonymous drop into the signed-in account, so it becomes owned and stops expiring in 7 days. Use after the user signs in to keep something they dropped anonymously. The public URL does not change. Requires sign-in (cloudgrid_login). Calls the API directly.",
+    {
+      claim_token: z.string().optional().describe("The claim token from an anonymous drop."),
+      claim_url: z.string().optional().describe("The claim_url from an anonymous drop; the token is read from it."),
+    },
+    async (input) => {
+      try {
+        return ok(await runClaim(ctx, input || {}));
+      } catch (err) {
+        return fail(err.message);
+      }
+    },
+  );
+
+  // Login — both editions. Local opens a browser and saves to the credentials
+  // file; web returns the URL and saves to the session.
+  server.tool(
+    "cloudgrid_login",
+    "Start a CLI-free CloudGrid sign-in. Use when the user wants to log in, sign in, or authenticate, or to claim an anonymous drop. Returns a URL to open in the browser; then call cloudgrid_login_status to finish. Uses CloudGrid's existing OAuth.",
+    {},
+    async () => {
+      const code = newLoginCode();
+      ctx.state.pendingLoginCode = code;
+      const url = buildLoginUrl(code);
+      if (ctx.canOpenBrowser) tryOpenBrowser(url);
+      return ok(
+        `To sign in, open this URL in your browser and finish with Google:\n${url}\n\n` +
+          `After you complete it, run cloudgrid_login_status to finish signing in.`,
+      );
+    },
+  );
+
+  server.tool(
+    "cloudgrid_login_status",
+    "Finish a sign-in started by cloudgrid_login. Polls once: if you have completed the browser sign-in, it saves your session; otherwise it tells you to finish and try again.",
+    {
+      code: z.string().optional().describe("The sign-in code. Defaults to the most recent cloudgrid_login."),
+    },
+    async (input) => {
+      const code = input?.code || ctx.state.pendingLoginCode;
+      if (!code) return fail("No sign-in is in progress. Run cloudgrid_login first.");
+      let status;
+      try {
+        status = await pollStatusOnce(code);
+      } catch (err) {
+        return fail(err.message);
+      }
+      if (status.status === "authenticated" && status.jwt) {
+        let info;
+        try {
+          info = await ctx.saveToken(status.jwt);
+        } catch (err) {
+          return fail(`Signed in, but could not save credentials: ${err.message}`);
+        }
+        ctx.state.pendingLoginCode = null;
+        const who = info?.email ? ` as ${info.email}` : "";
+        return ok(`Signed in${who}. ${ctx.savedLocationNote()}`);
+      }
+      if (status.status === "pending" || status.status === "not_started") {
+        return ok(
+          "Still waiting for you to finish signing in. Open the URL from cloudgrid_login " +
+            "in your browser, complete it with Google, then run cloudgrid_login_status again.",
+        );
+      }
+      return fail("The sign-in window expired (5 minutes). Run cloudgrid_login to start again.");
+    },
+  );
+
+  if (ctx.edition !== "local") return; // web edition stops here — no CLI tools
+
+  // ── CLI-wrapping tools (local edition only) ──
+  server.tool(
+    "cloudgrid_init",
+    "Register a new CloudGrid app or agent, optionally seeding a web service. Wraps `cloudgrid init`.",
+    {
+      kind: z.enum(["app", "agent"]).describe("Entity kind."),
+      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 org for this init."),
+    },
+    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);
+      if (org) args.push("--org", org);
+      return args;
+    }),
+  );
+
+  server.tool(
+    "cloudgrid_plug",
+    "Build and deploy a directory or URL. Prints the live URL. Wraps `cloudgrid plug`.",
+    {
+      target: z.string().optional().describe("Path or URL. Omit to deploy the entity linked to the current directory."),
+      org: z.string().optional().describe("Pick or override the org."),
+      no_deploy: z.boolean().optional().describe("Register the entity but do not build or deploy."),
+    },
+    cliTool(({ target, org, no_deploy }) => {
+      const args = ["plug"];
+      if (target) args.push(target);
+      if (org) args.push("--org", org);
+      if (no_deploy) args.push("--no-deploy");
+      args.push("--no-clipboard", "--no-notify");
+      return args;
+    }),
+  );
+
+  server.tool(
+    "cloudgrid_logs",
+    "Tail recent logs for an entity. Does not stream; returns a snapshot. Wraps `cloudgrid logs`.",
+    {
+      name: z.string().optional().describe("Entity name. Omit to use the entity linked to the current directory."),
+      tail: z.number().int().positive().optional().describe("Number of recent lines. Default 100."),
+      since: z.string().optional().describe("Only logs newer than this, e.g. 5m, 1h, 2d."),
+    },
+    cliTool(({ name, tail, since }) => {
+      const args = ["logs"];
+      if (name) args.push(name);
+      args.push("--tail", String(tail ?? 100));
+      if (since) args.push("--since", since);
+      return args;
+    }),
+  );
+
+  server.tool(
+    "cloudgrid_share",
+    "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."),
+    },
+    cliTool(({ name, mode }) => ["visibility", "set", name, mode ?? "link"]),
+  );
+
+  server.tool(
+    "cloudgrid_feedback",
+    "List recent feedback events for the active org. Read-only. Wraps `cloudgrid feedback list`.",
+    {
+      since: z.string().optional().describe("Only events newer than this, e.g. 24h, 7d."),
+      limit: z.number().int().positive().max(200).optional().describe("Number of events. Default 50, max 200."),
+      org: z.string().optional().describe("Read another org's feed where you have access."),
+    },
+    cliTool(({ since, limit, org }) => {
+      const args = ["feedback", "list"];
+      if (since) args.push("--since", since);
+      if (limit) args.push("--limit", String(limit));
+      if (org) args.push("--org", org);
+      return args;
+    }),
+  );
+
+  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."),
+    },
+    cliTool(({ name, wait, org }) => {
+      const args = ["brain", "refresh", name];
+      if (wait !== false) args.push("--wait");
+      if (org) args.push("--org", org);
+      return args;
+    }),
+  );
+}
+
+export { decodeJwt };

package/src/web.js

@@ -0,0 +1,95 @@
+// CloudGrid MCP server — web edition (HTTP, hosted).
+//
+// The same tool core as the local edition, served over the MCP Streamable HTTP
+// transport so web clients (claude.ai) can connect by URL with nothing installed.
+// The light, CLI-free toolset only: drop, claim, login. Identity is a per-session
+// token held in memory for the life of the MCP session (no local files on a
+// shared host).
+//
+// Run: PORT=8080 node src/web.js     Health: GET /healthz
+
+import { randomUUID } from "node:crypto";
+import express from "express";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { registerTools, decodeJwt } from "./tools.js";
+
+const PORT = Number(process.env.PORT || 8080);
+
+// A web session: identity lives in memory for the session's lifetime only.
+function makeWebContext() {
+  let sessionToken = null;
+  return {
+    edition: "web",
+    state: { pendingLoginCode: null, lastAnonClaim: null },
+    canOpenBrowser: false,
+    getToken: async () => sessionToken,
+    // No local config on a shared host. The user passes `org`, or the API returns
+    // the list of orgs to choose from.
+    getActiveOrg: async () => null,
+    saveToken: async (jwt) => {
+      sessionToken = jwt;
+      return decodeJwt(jwt);
+    },
+    savedLocationNote: () => "You are signed in for this session.",
+  };
+}
+
+const app = express();
+app.use(express.json({ limit: "8mb" }));
+
+app.get("/healthz", (_req, res) => res.json({ ok: true, edition: "web" }));
+
+// One transport per MCP session, keyed by the session id.
+const transports = Object.create(null);
+
+app.post("/mcp", async (req, res) => {
+  const sessionId = req.headers["mcp-session-id"];
+  let transport = sessionId ? transports[sessionId] : undefined;
+
+  if (!transport) {
+    if (sessionId || !isInitializeRequest(req.body)) {
+      res.status(400).json({
+        jsonrpc: "2.0",
+        error: { code: -32000, message: "No valid session. Send an initialize request first." },
+        id: null,
+      });
+      return;
+    }
+    // New session: fresh server + per-session identity context.
+    transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => randomUUID(),
+      onsessioninitialized: (sid) => {
+        transports[sid] = transport;
+      },
+    });
+    transport.onclose = () => {
+      if (transport.sessionId) delete transports[transport.sessionId];
+    };
+    const server = new McpServer({ name: "cloudgrid-mcp-web", version: "0.2.0" });
+    registerTools(server, makeWebContext());
+    await server.connect(transport);
+  }
+
+  await transport.handleRequest(req, res, req.body);
+});
+
+// SSE stream (GET) and session close (DELETE) reuse the same transport.
+async function handleSessionRequest(req, res) {
+  const sessionId = req.headers["mcp-session-id"];
+  const transport = sessionId ? transports[sessionId] : undefined;
+  if (!transport) {
+    res.status(400).send("Invalid or missing session id");
+    return;
+  }
+  await transport.handleRequest(req, res);
+}
+
+app.get("/mcp", handleSessionRequest);
+app.delete("/mcp", handleSessionRequest);
+
+app.listen(PORT, () => {
+  // eslint-disable-next-line no-console
+  console.error(`cloudgrid-mcp web edition listening on :${PORT} (POST /mcp, GET /healthz)`);
+});