@cloudgrid-io/mcp 0.3.1 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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": {

package/src/tools.js

@@ -23,6 +23,14 @@ export const API_BASE = (process.env.CLOUDGRID_API_URL || "https://api.cloudgrid
 );
 
 const ANON_HTML_MAX_BYTES = 2_000_000;
+const CONSOLE_URL = "https://console.cloudgrid.io/";
+const VISIBILITY_LABELS = {
+  private: "Only you",
+  org: "Your org",
+  authenticated: "Anyone signed in",
+  space: "A space",
+  link: "Anyone with the link",
+};
 
 function ok(text) {
   return { content: [{ type: "text", text }] };
@@ -30,6 +38,9 @@ function ok(text) {
 function fail(text) {
   return { content: [{ type: "text", text }], isError: true };
 }
+function okResult({ text, structured }) {
+  return { content: [{ type: "text", text }], structuredContent: structured };
+}
 
 // ── CLI wrapping (local edition only) ──────────────────────────────────────────
 async function runCloudgrid(args) {
@@ -74,6 +85,28 @@ function tryOpenBrowser(url) {
   }
 }
 
+// ── Org listing (bearer-authed, web edition) ──────────────────────────────────
+// Fetches the signed-in user's orgs via GET /api/v2/orgs. The JWT does not
+// carry orgs (claims: sub, email, name, iat, exp), so the API is the canonical
+// source. Returns [{slug, name, role}].
+async function fetchUserOrgs(token) {
+  try {
+    const res = await fetch(`${API_BASE}/api/v2/orgs`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!res.ok) return [];
+    const data = await res.json();
+    const orgs = Array.isArray(data?.orgs) ? data.orgs : Array.isArray(data) ? data : [];
+    return orgs.map((o) => ({
+      slug: o.slug ?? "",
+      name: o.name ?? o.slug ?? "",
+      role: o.role ?? "member",
+    }));
+  } catch {
+    return [];
+  }
+}
+
 // ── Direct-API tools (both editions) ───────────────────────────────────────────
 function looksLikeFullHtml(s) {
   const head = s.replace(/^/, "").trimStart().slice(0, 256).toLowerCase();
@@ -185,23 +218,61 @@ async function runDrop(ctx, { html, path: filePath, filename, anonymous, org, fr
 
   if (res.status === 202) {
     // Idempotent no-op — the bytes matched the live version exactly.
-    return `No change — this exact content is already live: ${data.url ?? ctx.state.lastDrop?.url ?? ""}`.trim();
+    const url = (data.url ?? ctx.state.lastDrop?.url ?? "").trim();
+    return {
+      text: `No change — this exact content is already live: ${url}`,
+      structured: { url, status: "unchanged" },
+    };
   }
 
   if (res.status === 200) {
     // Updated in place: same URL, new version, views/reactions intact.
-    const lines = [`Updated in place — same link: ${data.url ?? ctx.state.lastDrop?.url ?? ""}`.trim()];
-    if (data.owned_by === "authenticated") lines.push("Owned by you.");
+    const url = (data.url ?? ctx.state.lastDrop?.url ?? "").trim();
+    const lines = ctx.edition === "web"
+      ? [`Your app is live: ${url}`]
+      : [`Updated in place — same link: ${url}`];
+    if (ctx.edition !== "web" && data.owned_by === "authenticated") lines.push("Owned by you.");
     if (data.expires_at) lines.push(`Expires ${data.expires_at}.`);
-    return lines.join("\n");
+    const structured = {
+      url,
+      status: "updated",
+      ...(data.owned_by ? { owned_by: data.owned_by } : {}),
+      ...(data.expires_at ? { expires_at: data.expires_at } : {}),
+    };
+    if (ctx.edition === "web") {
+      lines.push(`See and manage all your apps in your grid: ${CONSOLE_URL}`);
+      const vis = data.visibility || "link";
+      lines.push(`Visible to: ${VISIBILITY_LABELS[vis] || vis}. Want to change who can see it? I can set it to only you, your org, or anyone with the link.`);
+      structured.console_url = CONSOLE_URL;
+      structured.current_visibility = vis;
+      structured.visibility_options = Object.entries(VISIBILITY_LABELS).map(([v, l]) => ({ value: v, label: l }));
+    }
+    return { text: lines.join("\n"), structured };
   }
 
   if (data.owned_by === "authenticated") {
     ctx.state.lastAnonClaim = null;
-    const lines = [`Published to your org: ${data.url}`, "Owned by you."];
+    const lines = ctx.edition === "web"
+      ? [`Your app is live: ${data.url}`]
+      : [`Published to your org: ${data.url}`, "Owned by you."];
     if (data.expires_at) lines.push(`Expires ${data.expires_at}.`);
-    lines.push("Drop again in this session to update it in place (same link); pass fresh to start a new one.");
-    return lines.join("\n");
+    const structured = {
+      url: data.url,
+      status: "created",
+      owned_by: "authenticated",
+      ...(data.expires_at ? { expires_at: data.expires_at } : {}),
+    };
+    if (ctx.edition === "web") {
+      lines.push(`See and manage all your apps in your grid: ${CONSOLE_URL}`);
+      const vis = data.visibility || "link";
+      lines.push(`Visible to: ${VISIBILITY_LABELS[vis] || vis}. Want to change who can see it? I can set it to only you, your org, or anyone with the link.`);
+      structured.console_url = CONSOLE_URL;
+      structured.current_visibility = vis;
+      structured.visibility_options = Object.entries(VISIBILITY_LABELS).map(([v, l]) => ({ value: v, label: l }));
+    } else {
+      lines.push("Drop again in this session to update it in place (same link); pass fresh to start a new one.");
+    }
+    return { text: lines.join("\n"), structured };
   }
 
   // 201 — created new (first drop, fresh: true, or the server fell back to create).
@@ -216,11 +287,18 @@ async function runDrop(ctx, { html, path: filePath, filename, anonymous, org, fr
       ctx.state.lastAnonClaim = null;
     }
   }
-  const lines = [`Live: ${data.url}`];
+  const lines = [ctx.edition === "web" ? `Your app is live: ${data.url}` : `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.");
   lines.push("Drop again in this session to update it in place (same link); pass fresh to start a new one.");
-  return lines.join("\n");
+  return {
+    text: lines.join("\n"),
+    structured: {
+      url: data.url,
+      status: "created",
+      ...(data.expires_at ? { expires_at: data.expires_at } : {}),
+    },
+  };
 }
 
 async function runClaim(ctx, { claim_token, claim_url }) {
@@ -264,13 +342,24 @@ async function runClaim(ctx, { claim_token, claim_url }) {
     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.";
+  if (claimed.length === 0) {
+    return {
+      text: "Nothing to claim — it may already be claimed or expired.",
+      structured: { claimed: 0, urls: [] },
+    };
+  }
   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");
+  return {
+    text: lines.join("\n"),
+    structured: {
+      claimed: claimed.length,
+      urls: claimed.map((c) => c.url),
+    },
+  };
 }
 
 
@@ -309,7 +398,13 @@ async function runVisibility(ctx, { target, visibility, org }) {
   }
   const lines = [`Visibility is now ${visibility}.`];
   if (data?.url) lines.push(data.url);
-  return lines.join("\n");
+  return {
+    text: lines.join("\n"),
+    structured: {
+      visibility,
+      ...(data?.url ? { url: data.url } : {}),
+    },
+  };
 }
 
 // ── Registration ───────────────────────────────────────────────────────────────
@@ -319,24 +414,73 @@ export function registerTools(server, ctx) {
   // ── Direct-API tools (both editions) ──────────────────────────────────────
 
   // Drop — both editions.
-  server.tool(
+  server.registerTool(
     "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. Re-drops in the same session update the existing drop in place — same link, new version; pass fresh: true to force a new one. 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."),
-      fresh: z
-        .boolean()
-        .optional()
-        .describe("Force a new drop even if you already dropped in this session (default: update in place)."),
+      description: "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. Re-drops in the same session update the existing drop in place — same link, new version; pass fresh: true to force a new one. 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.",
+      inputSchema: {
+        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."),
+        fresh: z
+          .boolean()
+          .optional()
+          .describe("Force a new drop even if you already dropped in this session (default: update in place)."),
+      },
+      outputSchema: {
+        url: z.string().optional().describe("The public URL of the drop."),
+        status: z.enum(["created", "updated", "unchanged"]).optional().describe("What happened to the drop."),
+        owned_by: z.string().optional().describe("Ownership class, e.g. 'authenticated'."),
+        expires_at: z.string().optional().describe("Expiry timestamp, if any."),
+        console_url: z.string().optional().describe("URL to manage all apps in the grid."),
+        current_visibility: z.string().optional().describe("Current visibility of the drop."),
+        visibility_options: z.array(z.object({
+          value: z.string().describe("Visibility value to pass to cloudgrid_visibility."),
+          label: z.string().describe("Human-readable label."),
+        })).optional().describe("Available visibility levels."),
+        needs_org: z.boolean().optional().describe("True when the user must choose an org before dropping."),
+        orgs: z.array(z.object({
+          slug: z.string().describe("Org slug to pass as the org parameter."),
+          name: z.string().describe("Human-readable org name."),
+          role: z.string().describe("User's role in the org."),
+        })).optional().describe("The user's orgs, when org choice is needed."),
+        needs_sign_in: z.boolean().optional().describe("True when sign-in is needed before dropping."),
+        login_url: z.string().optional().describe("Sign-in URL when authentication is needed."),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
     },
-    { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
     async (input) => {
       try {
-        return ok(await runDrop(ctx, input || {}));
+        // Web edition: sign-in guidance when unauthenticated.
+        if (ctx.edition === "web" && input?.anonymous !== true) {
+          const token = await ctx.getToken();
+          if (!token) {
+            const url = buildLoginUrl(newLoginCode());
+            return okResult({
+              text: `Sign in to publish to your org.\n${url}`,
+              structured: { needs_sign_in: true, login_url: url },
+            });
+          }
+          // Org disambiguation: if signed in, no org arg, list the user's orgs.
+          if (!input?.org) {
+            const orgs = await fetchUserOrgs(token);
+            if (orgs.length > 1) {
+              const lines = ["Which org should this be published to?"];
+              for (const o of orgs) lines.push(`  ${o.slug} — ${o.name} (${o.role})`);
+              lines.push("Pass the org slug in the org parameter to publish.");
+              return okResult({
+                text: lines.join("\n"),
+                structured: { needs_org: true, orgs },
+              });
+            }
+            if (orgs.length === 1) {
+              input = { ...(input || {}), org: orgs[0].slug };
+            }
+          }
+        }
+        return okResult(await runDrop(ctx, input || {}));
       } catch (err) {
         return fail(err.message);
       }
@@ -344,17 +488,23 @@ export function registerTools(server, ctx) {
   );
 
   // Claim — both editions.
-  server.tool(
+  server.registerTool(
     "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."),
+      description: "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.",
+      inputSchema: {
+        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."),
+      },
+      outputSchema: {
+        claimed: z.number().describe("Number of drops claimed."),
+        urls: z.array(z.string()).describe("URLs of the claimed drops."),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
     },
-    { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
     async (input) => {
       try {
-        return ok(await runClaim(ctx, input || {}));
+        return okResult(await runClaim(ctx, input || {}));
       } catch (err) {
         return fail(err.message);
       }
@@ -363,30 +513,44 @@ export function registerTools(server, ctx) {
 
   // Login — both editions. Local opens a browser and saves to the credentials
   // file; web returns the URL and saves to the session.
-  server.tool(
+  server.registerTool(
     "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.",
-    {},
-    { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    {
+      description: "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.",
+      inputSchema: {},
+      outputSchema: {
+        login_url: z.string().describe("URL to open in a browser to complete sign-in."),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    },
     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` +
+      return {
+        content: [{ type: "text", text:
+          `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.`,
-      );
+        }],
+        structuredContent: { login_url: url },
+      };
     },
   );
 
-  server.tool(
+  server.registerTool(
     "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."),
+      description: "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.",
+      inputSchema: {
+        code: z.string().optional().describe("The sign-in code. Defaults to the most recent cloudgrid_login."),
+      },
+      outputSchema: {
+        status: z.enum(["authenticated", "pending"]).describe("Current sign-in state."),
+        email: z.string().optional().describe("Signed-in email, when authenticated."),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
     },
-    { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
     async (input) => {
       const code = input?.code || ctx.state.pendingLoginCode;
       if (!code) return fail("No sign-in is in progress. Run cloudgrid_login first.");
@@ -405,36 +569,79 @@ export function registerTools(server, ctx) {
         }
         ctx.state.pendingLoginCode = null;
         const who = info?.email ? ` as ${info.email}` : "";
-        return ok(`Signed in${who}. ${ctx.savedLocationNote()}`);
+        return {
+          content: [{ type: "text", text: `Signed in${who}. ${ctx.savedLocationNote()}` }],
+          structuredContent: { status: "authenticated", ...(info?.email ? { email: info.email } : {}) },
+        };
       }
       if (status.status === "pending" || status.status === "not_started") {
-        return ok(
-          "Still waiting for you to finish signing in. Open the URL from cloudgrid_login " +
+        return {
+          content: [{ type: "text", text:
+            "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.",
-        );
+          }],
+          structuredContent: { status: "pending" },
+        };
       }
       return fail("The sign-in window expired (5 minutes). Run cloudgrid_login to start again.");
     },
   );
 
-  server.tool(
+  server.registerTool(
     "cloudgrid_visibility",
-    "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. Defaults to the drop made in this session. Requires sign-in. Calls the API directly.",
     {
-      visibility: z.enum(["private", "space", "authenticated", "org", "link"]).describe("The new scope."),
-      target: z.string().optional().describe("Entity id. Defaults to this session's last drop."),
-      org: z.string().optional().describe("Org of the entity. Defaults to the active org."),
+      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.",
+      inputSchema: {
+        visibility: z.enum(["private", "space", "authenticated", "org", "link"]).describe("The new scope."),
+        target: z.string().optional().describe("Entity id. Defaults to this session's last drop."),
+        org: z.string().optional().describe("Org of the entity. Defaults to the active org."),
+      },
+      outputSchema: {
+        visibility: z.string().describe("The visibility that was set."),
+        url: z.string().optional().describe("URL of the entity, if returned."),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
     },
-    { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
     async (input) => {
       try {
-        return ok(await runVisibility(ctx, input || {}));
+        return okResult(await runVisibility(ctx, input || {}));
       } catch (err) {
         return fail(err.message);
       }
     },
   );
 
+  // Org listing — web edition only (local edition uses cloudgrid_whoami).
+  if (ctx.edition === "web") {
+    server.registerTool(
+      "cloudgrid_orgs",
+      {
+        description: "List the signed-in user's organizations. Returns each org's slug, name, and the user's role. Use to discover which org to publish to. Requires sign-in.",
+        inputSchema: {},
+        outputSchema: {
+          orgs: z.array(z.object({
+            slug: z.string().describe("Org slug."),
+            name: z.string().describe("Human-readable org name."),
+            role: z.string().describe("User's role in the org."),
+          })).describe("The user's org memberships."),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+      },
+      async () => {
+        const token = await ctx.getToken();
+        if (!token) {
+          return fail("You are not signed in. Run cloudgrid_login first.");
+        }
+        const orgs = await fetchUserOrgs(token);
+        if (orgs.length === 0) {
+          return okResult({ text: "No organizations found.", structured: { orgs: [] } });
+        }
+        const lines = orgs.map((o) => `${o.slug} — ${o.name} (${o.role})`);
+        return okResult({ text: lines.join("\n"), structured: { orgs } });
+      },
+    );
+  }
+
   if (ctx.edition !== "local") return; // web edition stops here — no CLI tools
 
   // ── CLI-wrapping tools (local edition only) ───────────────────────────────