@cloudgrid-io/mcp 0.20.52 → 0.20.54

package/src/tools/register.js

@@ -35,13 +35,14 @@ import { stalenessNote } from "../staleness.js";
 // `--agent` for agents (NOT the legacy `init <kind> <slug>` positional). The
 // old `--description` flag was removed from the CLI, so it is gone here too.
 // Exported pure so the argv is unit-tested without spawning a CLI.
-export function buildCreateProjectArgs({ kind, name, type, needs, dir, org } = {}) {
+export function buildCreateProjectArgs({ kind, name, type, needs, dir, grid, org } = {}) {
   const args = ["new", name];
   if (kind === "agent") args.push("--agent");
   if (type) args.push("--type", type);
   if (Array.isArray(needs) && needs.length) args.push("--needs", needs.join(","));
   if (dir) args.push("--dir", dir);
-  if (org) args.push("--grid", org); // CLI 0.12 dropped --org for --grid (same slug)
+  const gridSlug = grid || org;
+  if (gridSlug) args.push("--grid", gridSlug);
   return args;
 }
 
@@ -86,8 +87,8 @@ export function registerTools(server, ctx) {
     server.registerTool(name, config, withCapture(name, handler));
   };
 
-  const regTool = (name, description, schema, annotations, handler) => {
-    server.tool(name, description, schema, annotations, withCapture(name, handler));
+  const regTool = (name, title, description, schema, annotations, handler) => {
+    server.registerTool(name, { title, description, inputSchema: schema, annotations }, withCapture(name, handler));
   };
 
   // ── Widget resources (web edition, ChatGPT Apps SDK) ──────────────────────
@@ -130,10 +131,13 @@ export function registerTools(server, ctx) {
   reg(
     "grid_pickup",
     {
+      title: "Copy an app into your grid",
       description: "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. It mints a NEW entity with lineage back to the source and WITHOUT the source's secrets (set your own before you plug). Plugging your copy creates/updates YOUR entity — the original is never touched. Requires sign-in. To edit the ORIGINAL entity in place (as its owner or a collaborator), use grid_pull instead.",
       inputSchema: {
-        id: z.string().describe("The source app to copy: a canonical UUID or <grid-slug>/<entity-slug>."),
-        into_org_slug: z.string().optional().describe("Grid to create your copy in. Required only when you belong to more than one grid."),
+        entity_id: z.string().describe("The source app to copy: a canonical UUID or <grid-slug>/<entity-slug>."),
+        grid: z.string().optional().describe("Grid to create your copy in. Required only when you belong to more than one grid."),
+        id: z.string().optional().describe("Alias of entity_id (legacy). Prefer entity_id."),
+        into_org_slug: z.string().optional().describe("Alias of grid (legacy). Prefer grid."),
         name: z.string().optional().describe("Slug for your copy. Omit to derive one from the source."),
         source_version_id: z.string().optional().describe("Copy an older version instead of HEAD, e.g. v_a1b2c3d."),
       },
@@ -150,8 +154,13 @@ export function registerTools(server, ctx) {
     },
     async (input) => {
       try {
-        if (!input?.id) return fail("`id` is required (a canonical UUID or <grid-slug>/<entity-slug>).");
-        return okResult(await runPickup(ctx, input));
+        const resolved = {
+          ...input,
+          id: input?.entity_id || input?.id,
+          into_org_slug: input?.grid || input?.into_org_slug,
+        };
+        if (!resolved.id) return fail("`entity_id` is required (a canonical UUID or <grid-slug>/<entity-slug>).");
+        return okResult(await runPickup(ctx, resolved));
       } catch (err) {
         return fail(err.message);
       }
@@ -162,6 +171,7 @@ export function registerTools(server, ctx) {
   reg(
     "grid_pull",
     {
+      title: "Pull an app to edit in place",
       description: "Pull an app to continue/edit it IN PLACE — like `git clone` of the SAME entity: your next grid_plug (with its target_entity_id) updates that entity, and the team sees the new version. Requires PUSH ACCESS: you must own it or be a collaborator. If you can only view it, you CANNOT edit or plug it — say so and tell the user they can make their own copy with grid_pickup, or request collaborator access with the CLI `grid collab <entity>` (rolling out soon). Passing an anonymous drop's `claim_token` claims it into your account. Requires sign-in. Calls the API directly (both editions).",
       inputSchema: {
         entity_id: z.string().optional().describe("The entity id to pull. Defaults to this session's last anonymous drop."),
@@ -194,13 +204,15 @@ export function registerTools(server, ctx) {
   reg(
     "grid_create_grid",
     {
-      description: "Create a new grid (workspace) for the signed-in user — they become its admin. Use when the account has no grid yet (grid_plug returns needs_grid_create, or a plug fails with NO_ACTIVE_ORG): suggest a short slug from the user's name or app, CONFIRM it with the user (the slug is permanent and appears in URLs), create, then re-call grid_plug with grid: <slug>. Never send the user to the console to create a grid by hand. Requires sign-in. Calls the API directly (both editions).",
+      title: "Create a new grid",
+      description: "Create a new grid (workspace) for the signed-in user — they become its admin. Use when the account has no grid yet (grid_plug returns needs_grid_create, or a plug fails with NO_ACTIVE_ORG): suggest a short slug from the user's name or app, CONFIRM it with the user (the slug is permanent and appears in URLs), create, then call grid_plug with grid: <slug>. A brand-new grid provisions in the background (~30s); grid_plug waits for readiness before deploying, so call it right away — no manual delay or polling needed. Never send the user to the console to create a grid by hand. Requires sign-in. Calls the API directly (both editions).",
       inputSchema: {
         slug: z.string().describe("The grid slug: 3-40 lowercase letters, digits, or hyphens, starting with a letter. Permanent — confirm with the user before creating."),
         name: z.string().optional().describe("Display name (defaults to the slug)."),
       },
       outputSchema: {
         created: z.boolean().optional().describe("True when the grid was created."),
+        provisioning: z.boolean().optional().describe("True when the grid is still finishing setup in the background. grid_plug waits for readiness before deploying, so call it right away — no manual polling needed."),
         grid: z.object({
           slug: z.string().describe("The new grid's slug — pass it to grid_plug as `grid`."),
           name: z.string().optional().describe("Its display name."),
@@ -227,6 +239,7 @@ export function registerTools(server, ctx) {
   // acknowledgement.
   regTool(
     "grid_note",
+    "Leave a session build note",
     "Optionally leave a one-paragraph summary of what you built this session and why. Call it BEFORE a plug, or in a session that ends without one — a successful plug has already posted the QA log, so pass grid_plug's session_note instead. The summary is recorded with the CloudGrid team for QA review.",
     { summary: z.string().describe("A short plain-language summary of what was built and why.") },
     { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
@@ -328,6 +341,7 @@ export function registerTools(server, ctx) {
   };
 
   const plugConfig = {
+      title: "Plug an app into the grid",
       description:
         "Plug an app, website, game, or single HTML page into CloudGrid — the live runtime that runs it and provides its infrastructure — and get a live public URL. " +
         "Use for any request to deploy, publish, host, ship, launch, go live, or share a working link — " +
@@ -530,6 +544,7 @@ export function registerTools(server, ctx) {
   reg(
     "grid_get_app_source",
     {
+      title: "Get deployed app source",
       description:
         "Retrieve the CURRENT deployed HTML of an inspiration/drop inline as text, so you can edit it and " +
         "re-plug the SAME URL when you no longer have its source in context (e.g. the user asks to 'change the " +
@@ -583,6 +598,7 @@ export function registerTools(server, ctx) {
   reg(
     "grid_login",
     {
+      title: "Sign in to CloudGrid",
       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 grid_login_status to finish. Uses CloudGrid's existing OAuth.",
       inputSchema: {},
       outputSchema: {
@@ -613,6 +629,7 @@ export function registerTools(server, ctx) {
   reg(
     "grid_login_status",
     {
+      title: "Check sign-in status",
       description: "Finish a sign-in started by grid_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 grid_login."),
@@ -662,7 +679,8 @@ export function registerTools(server, ctx) {
   reg(
     "grid_visibility",
     {
-      description: "Change who can see a CloudGrid inspiration OR runtime app/agent. Simple modes: private (only the user), grid (everyone in their grid), link (anyone with the URL — add indexed: true to be findable by search engines). Finer control via the TWO AXES instead: inside (who in the grid: private | spaces | grid) and outside (reach beyond it: none | link | public), with require_signin for a members-only link and `spaces` for selected spaces. 'authenticated' is retired (it maps to a sign-in-required link); 'org' is gone — use grid. Use when the user wants to make something private, restrict who sees it, or open it up — including right after a drop, with no target id needed. Kind-aware routing across both surfaces. Defaults to the drop made in this session. Requires sign-in. Calls the API directly.",
+      title: "Change app visibility",
+      description: "Change who can see a CloudGrid inspiration OR runtime app/agent. Simple modes: private (only the user), grid (everyone in their grid), link (anyone with the URL — add indexed: true to be findable by search engines). Finer control via the TWO AXES instead: inside (who in the grid: private | spaces | grid) and outside (reach beyond it: none | link | public), with require_signin for a members-only link and `spaces` for selected spaces. 'authenticated' is retired (it maps to a sign-in-required link). Use when the user wants to make something private, restrict who sees it, or open it up — including right after a drop, with no target id needed. Kind-aware routing across both surfaces. Defaults to the drop made in this session. Requires sign-in. Calls the API directly.",
       inputSchema: {
         visibility: z.enum(["private", "grid", "link", "public", "authenticated", "space"]).optional().describe("Simple mode: private | grid | link ('public' is an alias of link — pass indexed: true for search-findable; 'authenticated' is the retired alias for a sign-in-required link; 'space' needs the `spaces` list). Pass either this OR the inside/outside axes."),
         inside: z.enum(["private", "spaces", "grid"]).optional().describe("Axis 1 — who in the grid can see it: private (only the user), spaces (selected spaces — pass `spaces`), or grid (everyone in the grid). Use together with `outside`, instead of `visibility`."),
@@ -670,9 +688,11 @@ export function registerTools(server, ctx) {
         require_signin: z.boolean().optional().describe("With outside: link (or visibility: link) — the link requires a signed-in CloudGrid account."),
         spaces: z.array(z.string()).optional().describe("Space slugs, for inside: spaces (or the legacy space/grid modes)."),
         indexed: z.boolean().optional().describe("With visibility: link — make the page search-engine indexable."),
-        target: z.string().optional().describe("Entity id. Defaults to this session's last drop."),
+        entity_id: z.string().optional().describe("Entity id. Defaults to this session's last drop."),
         kind: z.enum(["inspiration", "app", "agent"]).optional().describe("Entity kind. Omit to auto-detect from this session's last drop (falls back to trying the runtime surface, then the inspiration surface)."),
-        org: z.string().optional().describe("Grid of the entity. Defaults to the active grid."),
+        grid: z.string().optional().describe("Grid of the entity. Defaults to the active grid."),
+        target: z.string().optional().describe("Alias of entity_id (legacy). Prefer entity_id."),
+        org: z.string().optional().describe("Alias of grid (legacy). Prefer grid."),
       },
       outputSchema: {
         visibility: z.string().optional().describe("The legacy mode that was set, when a simple mode was used."),
@@ -687,7 +707,12 @@ export function registerTools(server, ctx) {
     },
     async (input) => {
       try {
-        return okResult(await runVisibility(ctx, input || {}));
+        const resolved = {
+          ...(input || {}),
+          target: input?.entity_id || input?.target,
+          org: input?.grid || input?.org,
+        };
+        return okResult(await runVisibility(ctx, resolved));
       } catch (err) {
         return fail(err.message);
       }
@@ -701,6 +726,7 @@ export function registerTools(server, ctx) {
   reg(
     "grid_check_deploy",
     {
+      title: "Check deploy status",
       description:
         "Check whether an async runtime-app build has finished and the app is live. Call this after grid_plug returns status \"building\" — repeat every ~15s until it reports success or failed, and do NOT tell the user the app is live until it does. Defaults to this session's last deploy; pass poll_url from a grid_plug result to check another. Requires sign-in (builds are owned). Calls the API directly — works on every edition, including hosted.",
       inputSchema: {
@@ -731,6 +757,7 @@ export function registerTools(server, ctx) {
   reg(
     "grid_list_grids",
     {
+      title: "List your grids",
       description: "List the signed-in user's grids, each with slug, name, role, and provisioning status. A grid that is still provisioning (render_ready false) may not serve pages yet — prefer a ready grid, and if the user insists on a not-ready one, warn them that pages may not load. Requires sign-in.",
       inputSchema: {},
       outputSchema: {
@@ -784,12 +811,12 @@ export function registerTools(server, ctx) {
   // ── Agent Core orientation tools (authed editions: local + web) ───────────
   // These serve the delivery ladder's Orient + Load rungs. They are registered
   // before the local-only cutoff below, so BOTH the local and web (hosted-auth)
-  // editions expose them. The anon docs edition (src/docs.js) does NOT call
-  // registerTools, so it never gets them (spec F3).
+  // editions expose them.
 
   reg(
     "grid_start",
     {
+      title: "Orient before building",
       description:
         "Orient before building with CloudGrid — the live runtime environment where the user's apps run WITH the infrastructure they need (managed database, cache, persistent disk, AI with no API keys), any language or stack. Call this FIRST when the user wants to build, create, make, deploy, publish, or generate something. Returns the CloudGrid playbook (operating rules + golden path) and the index of available workflows (presentation, …). After this, match the user's intent to a workflow and call grid_get_template to load it.",
       inputSchema: {},
@@ -889,6 +916,7 @@ export function registerTools(server, ctx) {
   reg(
     "grid_get_template",
     {
+      title: "Load a workflow or template",
       description:
         "Load a specific CloudGrid workflow, template, example, rule, or doc by name — deterministic retrieval from the bundled corpus. Use after grid_start to pull the exact recipe/template you need, e.g. grid_get_template({kind:\"workflow\", name:\"presentation\"}) then grid_get_template({kind:\"template\", name:\"deck\"}).",
       inputSchema: {
@@ -927,8 +955,9 @@ export function registerTools(server, ctx) {
   reg(
     "grid_report",
     {
+      title: "Report a failure",
       description:
-        "Report a genuine CloudGrid failure to the CloudGrid team — ONLY with the user's explicit consent. When a build/deploy or platform call fails unexpectedly, ASK the user first; call this only after they say yes. Send a short `message` (what failed) plus `context` (the tool, inputs, grid, original request, error code/detail). By default it does NOT include the conversation — set include_conversation:true ONLY if the user explicitly agreed to send the chat. Obvious secrets in context are scrubbed before sending. Never sends anything the user didn't agree to.",
+        "Report a genuine CloudGrid failure to the CloudGrid team — ONLY with the user's explicit consent. When a build/deploy or platform call fails unexpectedly, ASK the user first; call this only after they say yes. Send a short `message` (what failed) plus `context` (the tool, inputs, grid, original request, error code/detail). By default it does NOT include the conversation — set include_conversation:true ONLY if the user explicitly agreed to send the chat. Redaction is key-name-only: a value is dropped only when its KEY looks secret, so a secret embedded in a value (e.g. inside HTML) is NOT redacted — do not put secrets in `message` or `context`. Never sends anything the user didn't agree to.",
       inputSchema: {
         message: z
           .string()
@@ -936,7 +965,7 @@ export function registerTools(server, ctx) {
         context: z
           .object({
             tool: z.string().optional().describe("The CloudGrid tool that failed, e.g. grid_plug."),
-            inputs: z.any().optional().describe("The failing inputs (e.g. the HTML/args). Keep it minimal; secrets are scrubbed."),
+            inputs: z.any().optional().describe("The failing inputs (e.g. the HTML/args). Keep it minimal and do NOT include secrets — a secret embedded in a value here is not redacted."),
             grid: z.string().optional().describe("The grid/org slug involved, if any."),
             original_request: z.string().optional().describe("What the user asked for, in one line."),
             error_code: z.string().optional().describe("The server error code, e.g. INTERNAL_ERROR."),
@@ -944,7 +973,7 @@ export function registerTools(server, ctx) {
           })
           .partial()
           .optional()
-          .describe("The failed-request context. Secret-looking values are scrubbed client-side and again server-side."),
+          .describe("The failed-request context. Redaction is key-name-only (a value is dropped only when its KEY looks secret) client-side, and the server applies the same key-name filter — a secret embedded in a value is not redacted by either."),
         include_conversation: z
           .boolean()
           .optional()
@@ -1000,6 +1029,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_create_project",
+    "Scaffold a new project",
     "Scaffold a new CloudGrid app or agent folder (cloudgrid.yaml + a web service), optionally pre-declaring resources. Wraps `grid new` (scaffolds locally; no server entity until you grid_plug). Language note: the nextjs starter is TypeScript (writes tsconfig.json + app/*.tsx), but CloudGrid templates are plain JavaScript. When you fill a template, treat the template's files as the source of truth — delete the scaffolded tsconfig.json and app/*.tsx, then write the template's .js files. Never leave both .tsx and .js for the same route.",
     {
       kind: z.enum(["app", "agent"]).describe("Entity kind. 'agent' scaffolds an agent: block."),
@@ -1008,7 +1038,8 @@ export function registerTools(server, ctx) {
       needs: z.array(z.enum(["database", "cache", "kv", "queue", "pubsub", "vector", "ai", "disk"])).optional()
         .describe("Pre-declare infrastructure needs in the scaffolded cloudgrid.yaml (e.g. [\"database\",\"ai\"])."),
       dir: z.string().optional().describe("Target directory. Defaults to the current folder."),
-      org: z.string().optional().describe("Override the active grid this project will target."),
+      grid: z.string().optional().describe("Override the active grid this project will target."),
+      org: z.string().optional().describe("Alias of grid (legacy). Prefer grid."),
       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 },
@@ -1021,6 +1052,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_view_logs",
+    "View entity logs",
     "Tail recent logs for an entity. Does not stream; returns a snapshot. Wraps `grid logs`.",
     {
       name: z.string().optional().describe("Entity name. Omit to use the entity linked to the current directory."),
@@ -1039,6 +1071,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_share",
+    "Set visibility via CLI",
     "Set an entity's visibility and print its URL. Defaults to link (anyone with the URL). Wraps `grid visibility set`.",
     {
       name: z.string().describe("Entity slug."),
@@ -1050,19 +1083,21 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_feedback",
+    "List feedback events",
     "List recent feedback events for the active grid. Read-only. Wraps `grid 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 grid's feed where you have access."),
+      grid: z.string().optional().describe("Read another grid's feed where you have access."),
+      org: z.string().optional().describe("Alias of grid (legacy). Prefer grid."),
     },
     { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
-    cliTool(({ since, limit, org }) => {
+    cliTool(({ since, limit, grid, org }) => {
       const args = ["feedback", "list"];
       if (since) args.push("--since", since);
       if (limit) args.push("--limit", String(limit));
-      // CLI 0.12 dropped `--org` in favour of `--grid` (same slug).
-      if (org) args.push("--grid", org);
+      const gridSlug = grid || org;
+      if (gridSlug) args.push("--grid", gridSlug);
       return args;
     }),
   );
@@ -1071,6 +1106,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_whoami",
+    "Show current user and grid",
     "Show the signed-in user and active grid. Wraps `grid whoami`.",
     {},
     { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
@@ -1079,14 +1115,23 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_switch_grid",
+    "Switch the active grid",
     "Switch the active grid. Wraps `grid use`.",
-    { org: z.string().describe("Org slug to switch to.") },
+    {
+      grid: z.string().optional().describe("Grid slug to switch to."),
+      org: z.string().optional().describe("Alias of grid (legacy). Prefer grid."),
+    },
     { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
-    cliTool(({ org }) => ["use", org]),
+    cliTool(({ grid, org }) => {
+      const slug = grid || org;
+      if (!slug) throw new Error("`grid` is required.");
+      return ["use", slug];
+    }),
   );
 
   regTool(
     "grid_logout",
+    "Sign out",
     "Sign out and clear local credentials. Wraps `grid logout`.",
     {},
     { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
@@ -1095,7 +1140,8 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_status",
-    "Org dashboard, entity detail, or deploy snapshot. Wraps `grid status`.",
+    "Show grid or entity status",
+    "Grid dashboard, entity detail, or deploy snapshot. Wraps `grid status`.",
     { name: z.string().optional().describe("Entity name or trace id. Omit for the org dashboard.") },
     { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
     cliTool(({ name }) => (name ? ["status", name] : ["status"])),
@@ -1103,6 +1149,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_info",
+    "Show entity metadata",
     "Show metadata for a CloudGrid entity. Wraps `grid info`.",
     { name: z.string().optional().describe("Entity name. Omit for the entity linked to the current directory.") },
     { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
@@ -1120,6 +1167,7 @@ export function registerTools(server, ctx) {
   // cloudgrid_grid behaviour with `grid` mapping to the CLI's `--grid` flag.
   regTool(
     "grid_get",
+    "List grids, entities, or spaces",
     "List CloudGrid grids, entities, or spaces. Wraps `grid get <grids|entities|spaces> --json`.",
     {
       resource: z.enum(["grids", "entities", "spaces"]).describe("What to list: grids, entities, or spaces."),
@@ -1147,6 +1195,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_describe_grid",
+    "Describe a grid",
     "Show a grid's detail: role, members, spaces, tier, wildcard-TLS state. Wraps `grid describe grid <slug> --json`.",
     { grid: z.string().describe("Grid slug to describe.") },
     { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
@@ -1160,6 +1209,7 @@ export function registerTools(server, ctx) {
   // pulled — use grid_pickup to copy it, or `grid collab` to request access.
   regTool(
     "grid_edit_existing_app",
+    "Pull app source to edit locally",
     "Continue/edit an EXISTING entity locally: download its source + cloudgrid.yaml and link the folder so your next `grid plug` updates it IN PLACE. Requires push access (owner or collaborator). Wraps `grid pull`. To make your own separate copy instead, use grid_pickup.",
     {
       name: z.string().describe("Entity slug or id to pull."),
@@ -1184,6 +1234,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_rename",
+    "Rename an entity",
     "Rename a CloudGrid entity's display name (slug stays the same). Wraps `grid rename`.",
     {
       name: z.string().describe("Entity slug."),
@@ -1195,6 +1246,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_take_offline",
+    "Take an entity offline",
     "Take an entity off the grid. Destructive. Wraps `grid unplug`.",
     {
       name: z.string().describe("Entity slug to take down (required)."),
@@ -1206,6 +1258,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_delete",
+    "Delete an entity",
     "Archive a CloudGrid inspiration. Destructive. Wraps `grid delete entity`.",
     {
       name: z.string().describe("Entity slug to delete (required)."),
@@ -1217,6 +1270,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_rollback_deploy",
+    "Roll back to a previous version",
     "Rollback an entity to a previous version. Wraps `grid rollback`.",
     {
       name: z.string().describe("Entity slug."),
@@ -1232,6 +1286,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_list_versions",
+    "List entity versions",
     "List published versions for an entity. Wraps `grid versions`.",
     { name: z.string().optional().describe("Entity name. Omit for the entity linked to the current directory.") },
     { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
@@ -1244,6 +1299,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_set_env",
+    "Manage environment variables",
     "Manage environment variables for an entity. Wraps `grid env`.",
     {
       action: z.enum(["get", "set", "list"]).describe("get, set, or list."),
@@ -1268,6 +1324,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_set_secret",
+    "Manage secrets",
     "Set or list secret names for an entity. Never returns secret values. Wraps `grid secrets`.",
     {
       action: z.enum(["set", "list"]).describe("set or list (names only)."),
@@ -1288,6 +1345,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_scaffold",
+    "Scaffold service folders",
     "Scaffold service folders declared in cloudgrid.yaml (idempotent). Wraps `grid scaffold`.",
     {
       cwd: z.string().optional().describe("Working directory. The CLI runs in this directory. Defaults to the MCP server's working directory."),
@@ -1298,6 +1356,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_diagnose",
+    "Run local diagnostics",
     "Run CloudGrid diagnostics on the local environment. Wraps `grid doctor`.",
     {},
     { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
@@ -1306,6 +1365,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_get_url",
+    "Get entity URL",
     "Return the public URL for an entity. Does not open a browser. Wraps `grid open --print`.",
     { name: z.string().optional().describe("Entity name. Omit for the entity linked to the current directory.") },
     { readOnlyHint: true, destructiveHint: false, openWorldHint: true },

package/src/web.js

@@ -25,6 +25,7 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { registerTools, decodeJwt } from "./tools.js";
 import { mountOAuth, bearerChallenge } from "./oauth.js";
+import { mountLanding } from "./landing.js";
 import { createSessionLogger } from "./session-logger.js";
 import { createSink } from "./log-sink.js";
 import { INSTRUCTIONS_WEB } from "./playbook.js";
@@ -98,6 +99,10 @@ app.use(express.urlencoded({ extended: false })); // OAuth token exchange is for
 
 app.get("/healthz", (_req, res) => res.json({ ok: true, edition: "web" }));
 
+// The human-facing root page and favicon. Mounted on both postures; the auth line
+// it renders is driven by the same REQUIRE_AUTH flag used below.
+mountLanding(app, PUBLIC_BASE, { requireAuth: REQUIRE_AUTH });
+
 mountOAuth(app, PUBLIC_BASE, { requireAuth: REQUIRE_AUTH });
 
 // One transport per MCP session, keyed by the session id.

package/src/docs.js

@@ -1,147 +0,0 @@
-// CloudGrid MCP server — docs edition (public, read-only, no auth).
-//
-// A public documentation search server exposing search_cloudgrid_documentation
-// (and an optional cloudgrid_quickstart_guide) over MCP Streamable HTTP. The
-// same Express + StreamableHTTP pattern as the web edition (src/web.js),
-// stripped to the minimum: no auth, no OAuth, no session identity, no secrets.
-// Safe to expose anonymously.
-//
-// The corpus (src/corpus/*.md) is indexed at startup with BM25 keyword search.
-// The search backend is behind a clean interface so it can be swapped to
-// semantic/embedding search later without changing the tool contract.
-//
-// Run: PORT=8080 node src/docs.js     Health: GET /healthz
-
-import { readFileSync } from "node:fs";
-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 { z } from "zod";
-import { DocsSearch, loadCorpus } from "./docs-search.js";
-
-const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url)));
-
-const PORT = Number(process.env.PORT || 8080);
-
-// Build the search index once at startup.
-const search = loadCorpus(new DocsSearch());
-
-// Load the quickstart guide verbatim.
-const QUICKSTART = readFileSync(new URL("./corpus/cookbook.md", import.meta.url), "utf-8");
-
-// ── Tool helpers (same convention as tools.js) ────────────────────────────────
-function ok(text) {
-  return { content: [{ type: "text", text }] };
-}
-
-function createDocsServer() {
-  const server = new McpServer({ name: "cloudgrid-docs", version });
-
-  // Naming cleanup (spec §6): the docs tools move to the grid_* family. Both
-  // legacy names stay registered as deprecated aliases (same handler) so nothing
-  // breaks mid-migration; aliases are removed in a later major.
-  //   search_cloudgrid_documentation → grid_search_docs
-  //   cloudgrid_quickstart_guide     → grid_quickstart
-  const dual = (name, alias, description, schema, handler) => {
-    server.tool(name, description, schema, handler);
-    server.tool(alias, `(deprecated: use ${name}) ${description}`, schema, handler);
-  };
-
-  dual(
-    "grid_search_docs",
-    "search_cloudgrid_documentation",
-    "Search CloudGrid documentation — guides, tutorials, CLI reference, MCP setup, and skill descriptions. Returns the most relevant doc chunks with title, snippet, and source path.",
-    {
-      query: z
-        .string()
-        .describe(
-          "The search query, e.g. 'deploy a database app' or 'add the MCP to Cursor'",
-        ),
-    },
-    async ({ query }) => {
-      const results = search.search(query, 5);
-      if (results.length === 0) {
-        return ok("No documentation matched your query. Try different keywords.");
-      }
-      const text = results
-        .map(
-          (r, i) => `### ${i + 1}. ${r.title}\n${r.snippet}\n_Source: ${r.source}_`,
-        )
-        .join("\n\n---\n\n");
-      return ok(text);
-    },
-  );
-
-  dual(
-    "grid_quickstart",
-    "cloudgrid_quickstart_guide",
-    "Get the CloudGrid quickstart guide — the canonical build-and-ship loop from scaffold to deploy to feedback.",
-    {},
-    async () => ok(QUICKSTART),
-  );
-
-  return server;
-}
-
-// ── HTTP server (mirrors src/web.js, no auth) ─────────────────────────────────
-const app = express();
-app.use(express.json());
-
-app.get("/healthz", (_req, res) => res.json({ ok: true, edition: "docs" }));
-
-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) {
-    await transport.handleRequest(req, res, req.body);
-    return;
-  }
-
-  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;
-  }
-
-  const newSessionId = randomUUID();
-  transport = new StreamableHTTPServerTransport({
-    sessionIdGenerator: () => newSessionId,
-    onsessioninitialized: (sid) => {
-      transports[sid] = transport;
-    },
-  });
-  transport.onclose = () => {
-    if (transport.sessionId) delete transports[transport.sessionId];
-  };
-  const server = createDocsServer();
-  await server.connect(transport);
-  await transport.handleRequest(req, res, req.body);
-});
-
-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-docs edition listening on :${PORT} (POST /mcp, GET /healthz) — ${search.size} chunks indexed`,
-  );
-});