@groundfloorcloud/mcp 0.2.3 → 0.2.5

package/README.md

@@ -82,7 +82,7 @@ Use the prefixed names: `GROUNDFLOOR_API_URL`, `GROUNDFLOOR_WORKSPACE_ID`, `GROU
 | `secrets_list` / `files_list` / `dataplane_status` | Inspect (no secrets values) |
 | `domains_list` | Custom domains of an App's Coderunner (`app_id` or `coderunner_id`). Domains exist on Apps, not standalone Coderunners |
 | `quota_get` / `billing_summary` | Plan quota and billing for the workspace's **account** (account id is not the workspace id; billing needs organization Owner, Admin or Billing admin) |
-| `docs_list` / `docs_get` | Product docs (`coderunner`, `coderunner-runtime`, `shell`, `design-standard`, `css-and-styling`, `databases`, `vault`, `feature-flags`, `authentication` are embedded; `access` and `m2m` are live pages, with an `offset` parameter to read past the 12,000-character page limit) |
+| `docs_list` / `docs_get` | Product docs (`coderunner`, `coderunner-runtime`, `shell`, `design-standard`, `css-and-styling`, `databases`, `vault`, `feature-flags`, `authentication`, `service-access` are embedded; `access` and `m2m` are live pages, with an `offset` parameter to read past the 12,000-character page limit) |
 | `suggest_cli` | Command to run: login, deploy, create_app, init_app, publish_app, m2m_token, … |
 
 Never create `app_kind=coderunner`. Deploy with `gf deploy`.

package/dist/index.js

@@ -179,12 +179,14 @@ async function getValidAccessToken() {
 
 // ../cli/src/cp.ts
 var CpError = class extends Error {
-  constructor(status, message) {
+  constructor(status, message, reason = null) {
     super(message);
     this.status = status;
+    this.reason = reason;
     this.name = "CpError";
   }
   status;
+  reason;
 };
 function formatCpErrorDetail(detail, fallback) {
   if (typeof detail === "string" && detail.trim()) return detail.trim();
@@ -204,6 +206,40 @@ function formatCpErrorDetail(detail, fallback) {
   }
   return fallback;
 }
+function parseRetryAfter(value, now = Date.now()) {
+  if (!value) return null;
+  const trimmed = value.trim();
+  if (/^\d+$/.test(trimmed)) return Number(trimmed);
+  const at = Date.parse(trimmed);
+  if (Number.isNaN(at)) return null;
+  return Math.max(0, Math.ceil((at - now) / 1e3));
+}
+function formatWait(seconds) {
+  if (seconds < 60) return `${seconds} second${seconds === 1 ? "" : "s"}`;
+  const minutes = Math.ceil(seconds / 60);
+  if (minutes < 60) return `${minutes} minute${minutes === 1 ? "" : "s"}`;
+  const hours = Math.ceil(minutes / 60);
+  return `${hours} hour${hours === 1 ? "" : "s"}`;
+}
+var REASON_HEADER = "x-groundfloor-reason";
+function formatCpErrorMessage(status, detail, retryAfterSeconds, reason = null) {
+  let message = `${status} ${detail}`;
+  const wait = retryAfterSeconds !== null ? `try again in ${formatWait(retryAfterSeconds)}` : "try again later";
+  if (status === 429 && reason === "sending_limited") {
+    message += ` (workspace sign-in email limit reached: ${wait}, or give access with a copy-link or temporary password instead)`;
+  } else if (status === 429) {
+    message += ` (rate limited: ${wait})`;
+  } else if (status === 423 && reason === "sending_paused") {
+    message += " (sign-in email is paused: only Groundfloor support can resume it; meanwhile give access with a copy-link or temporary password, or switch to your own email server)";
+  } else if (status === 423 && !/support/i.test(detail)) {
+    message += " (locked: Groundfloor has paused or frozen this; contact Groundfloor support)";
+  }
+  return message;
+}
+function reasonHeader(res) {
+  const value = res.headers?.get?.(REASON_HEADER);
+  return value ? value.trim() : null;
+}
 async function parseError(res) {
   let detail = res.statusText;
   try {
@@ -213,7 +249,12 @@ async function parseError(res) {
     }
   } catch {
   }
-  return `${res.status} ${detail}`;
+  return formatCpErrorMessage(
+    res.status,
+    detail,
+    parseRetryAfter(res.headers?.get?.("retry-after")),
+    reasonHeader(res)
+  );
 }
 async function cpGet(apiUrl, path2) {
   const token = await getValidAccessToken();
@@ -224,7 +265,7 @@ async function cpGet(apiUrl, path2) {
     }
   });
   if (!res.ok) {
-    throw new CpError(res.status, await parseError(res));
+    throw new CpError(res.status, await parseError(res), reasonHeader(res));
   }
   return await res.json();
 }
@@ -235,7 +276,7 @@ async function cpDelete(apiUrl, path2) {
     headers: { Authorization: `Bearer ${token}`, Accept: "application/json" }
   });
   if (!res.ok) {
-    throw new CpError(res.status, await parseError(res));
+    throw new CpError(res.status, await parseError(res), reasonHeader(res));
   }
 }
 function queryString(params) {
@@ -272,7 +313,7 @@ async function getDeployment(apiUrl, workspaceId, coderunnerId) {
   );
   if (res.status === 204) return null;
   if (!res.ok) {
-    throw new CpError(res.status, await parseError(res));
+    throw new CpError(res.status, await parseError(res), reasonHeader(res));
   }
   return await res.json();
 }
@@ -483,7 +524,16 @@ async function cpGetJson(apiUrl, token, path2) {
       }
     } catch {
     }
-    throw new CpError(res.status, `${res.status} ${detail}`);
+    throw new CpError(
+      res.status,
+      formatCpErrorMessage(
+        res.status,
+        detail,
+        parseRetryAfter(res.headers?.get?.("retry-after")),
+        reasonHeader(res)
+      ),
+      reasonHeader(res)
+    );
   }
   return await res.json();
 }
@@ -552,7 +602,13 @@ the provider.
   port 25, 465, 587 or 2525), then **Send test email** (goes to their own
   verified address). API: \`PUT /v1/workspaces/{id}/auth\` with
   \`mail: {mode: "custom", ...}\`; test with
-  \`POST /v1/workspaces/{id}/auth/mail/test\`.
+  \`POST /v1/workspaces/{id}/auth/mail/test\`. Over the sending limit it
+  returns 429 with \`Retry-After\`; while Groundfloor email is paused, 423. If
+  your own address is suppressed, or sending could not be checked, it returns
+  200 with \`ok: false\` and a sentence in \`error\`. These answers carry an
+  \`X-Groundfloor-Reason\` header (\`sending_limited\`, \`sending_paused\`,
+  \`recipient_suppressed\`, \`send_failed\`); the per-user rate limit's 429
+  does not.
 - A failing custom server does not fall back to Groundfloor email; the send
   fails. Changing host or port needs the password again.
 - **Warning:** saving a \`mail\` block with no \`host\` (or
@@ -569,7 +625,12 @@ reset responses, and every user in \`GET /v1/workspaces/{id}/users\`, carry:
 - \`email_skipped_reason\`: \`smtp_not_configured\` (no email server set up for
   the workspace's sign-in email), \`send_failed\` (the server refused or
   failed), \`delivery_unconfirmed\` (timed out; it may still arrive),
-  \`not_requested\` (sent with \`send_email: false\`), or \`null\`.
+  \`not_requested\` (sent with \`send_email: false\`), \`sending_limited\` (the
+  workspace or this address reached the sending limit; try later),
+  \`sending_paused\` (Groundfloor paused the workspace's sign-in email),
+  \`recipient_suppressed\` (the address bounced or reported spam), or \`null\`.
+  See "Email sending limits" below. Team invite responses carry the same
+  two fields.
   \`keycloak_smtp_missing\` is retired and no longer returned.
 - \`email_attempted_at\` (\`null\` = invited before delivery was recorded),
   \`invite_pending\`, \`password_change_required\`,
@@ -582,7 +643,10 @@ app-user tokens get 403):
 
 1. **Resend** (\`POST \u2026/users/{user_id}/resend-invite\`, pending users only):
    at most once per 60 s and 5 times per 24 h; re-inviting a pending user
-   counts against the same limit (429 with \`Retry-After\`). If the reason is
+   counts against the same limit (429 with \`Retry-After\`). Over the sending
+   limit resend also returns 429 with \`Retry-After\` (seconds), told apart by
+   the header \`X-Groundfloor-Reason: sending_limited\`: wait that long. When sending is paused or the address is suppressed it returns 200
+   with \`email_sent: false\` and the reason. If the reason is
    \`send_failed\` or \`smtp_not_configured\`, fix email first (Branding \u2192
    Email sending, Send test email) or resending will fail the same way.
 2. **Temp password** (\`POST \u2026/users/{user_id}/temporary-password\`, pending
@@ -601,6 +665,40 @@ person who asked for them, tell them to share privately, and never write them
 to files, commits, logs or chat with anyone else. Once a user has set their
 own password, none of these apply (409): use reset-password.
 
+## Email sending limits
+
+Workspace sign-in email (invite, resend, added-user and reset emails, the test
+email) is limited per workspace to 200 per hour and 1,000 per 24 hours, and per
+address to 5 per hour and 10 per 24 hours (rolling windows; Groundfloor can set
+other workspace limits). Limits apply with Groundfloor email and your own
+server. Portal Team invites are not limited.
+
+- **Limited** (\`sending_limited\`, or 429 with \`Retry-After\` and
+  \`X-Groundfloor-Reason: sending_limited\`): invite and add
+  still create the user, without email. Wait and resend, or give access now
+  with **Copy link** or **Temp password**.
+- **Paused** (\`sending_paused\`, test email 423): Groundfloor stopped the
+  workspace's Groundfloor email after too many bounces or spam reports. Only
+  Groundfloor support can resume it. Meanwhile use Copy link or Temp password,
+  or switch to **Your own email server** (pause applies to Groundfloor email
+  only).
+- **Suppressed** (\`recipient_suppressed\`): the address bounced or reported
+  spam, so Groundfloor email will not send to it. Check the address with the
+  user. A workspace Admin or Owner can list suppressed addresses (masked) with
+  \`GET /v1/workspaces/{id}/mail/suppressions\` and clear one with
+  \`DELETE \u2026/mail/suppressions/{suppression_id}\` (optional body
+  \`{"email": "<full address>"}\` to clear it from the mail provider's bounce
+  and block lists too; the response's \`provider\` says what happened). An
+  address that reported spam (\`provider: spam_report_kept\`) stays on the
+  provider's spam list until Groundfloor support removes it, so mail to it may
+  still be dropped. If the test email says your own address is suppressed,
+  clear it the same way. Only clear an address the user confirms is correct
+  and wants mail.
+- \`GET /v1/workspaces/{id}/mail/status\` (Admin or Owner) shows the mode,
+  \`state\` (\`active\` / \`paused\`), the limits, how many were sent in the
+  last hour and 24 hours, and the number of suppressed addresses.
+  \`workspace_context\` includes it as \`sign_in_email\`.
+
 ## Multi-tenant (customer companies inside one workspace)
 
 Turn on **Multi-tenant** in Settings to get a Tenants tab: one tenant per
@@ -627,8 +725,12 @@ with no role at all gets 403 too.
 ## In a Shell app
 
 The signed-in user's JWT comes from \`window.__GF_GET_ACCESS_TOKEN__()\`. See
-\`docs_get\` id \`shell\`. Unattended workloads use M2M instead (\`docs_get\` id
-\`m2m\`), not an end-user login.
+\`docs_get\` id \`shell\`. Roles are in the token's \`realm_access.roles\`
+(Groundfloor mode). A Shell app's backend Service is public and must verify
+that token itself (issuer and client ID from \`/v1/public/workspaces/by-host\`,
+JWKS, RS256): \`docs_get\` id \`service-access\`.
+Unattended workloads use M2M instead (\`docs_get\` id \`m2m\`), not an
+end-user login.
 `.trim();
 
 // src/coderunner-runtime.ts
@@ -868,6 +970,11 @@ CMD ["npm", "start"]
 
 - Services follow the \`npm start\` / \`PORT\` contract: Node needs \`scripts.start\` if CMD is \`npm start\`.
 - Prefer curling the Deployment URL (\`/health\`) over \`\u2026/run\`.
+- **The Deployment URL (and any App domain on it) is public.** Groundfloor
+  checks no identity. A Service that is a Shell app's backend must verify the
+  user's token itself, and allow the Shell origin for CORS. Off-the-shelf
+  images (port 80 defaults, MySQL, local uploads, sessions): \`docs_get\` id
+  \`service-access\`.
 
 ## Latest deploy rules (all types)
 
@@ -965,10 +1072,14 @@ An M2M client can also read secret **values** directly at runtime instead
 of (or alongside) \`--secret\` deploy-time injection: grant it the
 **\`secrets:read\`** scope (same Portal **Administer \u2192 M2M tokens** screen,
 per-client toggle), then call
-\`GET {CONTROLPLANE_URL}/v1/workspaces/{workspace_id}/secrets/{key}\` with
-\`Authorization: Bearer\` from \`gf m2m token\` locally, or the deployed
+\`GET {CONTROLPLANE_URL}/v1/workspaces/{workspace_id}/secrets/{key}?environment_id=$GROUNDFLOOR_ENVIRONMENT_ID\`
+with \`Authorization: Bearer\` from \`gf m2m token\` locally, or the deployed
 workload's injected \`GROUNDFLOOR_M2M_CLIENT_ID\`/\`GROUNDFLOOR_M2M_CLIENT_SECRET\`
-exchanged the same way. This path is:
+exchanged the same way. **Always pass \`environment_id\`**
+(\`GROUNDFLOOR_ENVIRONMENT_ID\` is injected on deploy for a Coderunner bound to
+an environment) to choose which environment's value is read: omitted or
+empty, it resolves to the workspace's \`dev\` environment (or its only active
+one), so a prod workload silently reads dev secrets. This path is:
 
 - **Read-only** \u2014 \`secrets:read\` never grants \`upsert\`/\`delete\`, regardless
   of the client's writer relation on Vault/Files.
@@ -977,7 +1088,9 @@ exchanged the same way. This path is:
 - **Workspace-wide, not per-key or per-environment** \u2014 granting the scope
   exposes every secret in the workspace across all environments to that
   client's code, same class of trade as the existing Vault/Files writer
-  grant. Not a fit for isolating one secret to one Coderunner.
+  grant. \`environment_id\` only selects which environment's value is
+  returned; it is not an access boundary. Not a fit for isolating one secret
+  (or one environment) to one Coderunner.
 
 Prefer it over \`--secret\` injection when you want live rotation and can
 do the fetch yourself; keep using \`--secret\` injection for SDKs that only
@@ -1258,6 +1371,113 @@ active environments \xB7 400 bad or reserved key \xB7 422 value/value_type misma
 423 workspace frozen (writes).
 `.trim();
 
+// src/service-access-guide.ts
+var SERVICE_ACCESS_GUIDE = `
+# Who can reach a Service (and checking Shell tokens in a backend)
+
+## The rule
+
+Every Coderunner Service is public. Its Deployment URL, and an App's domain
+routed to it, accept requests from anyone. Groundfloor routes the request but
+signs nobody in and checks no token. The Service decides who gets in.
+
+| Service is\u2026 | Example | Do |
+|---|---|---|
+| Open to everyone | website, docs, public API, webhook receiver | Nothing (default) |
+| An app with its own logins | WordPress, Ghost, Metabase | Nothing from Groundfloor; its own login applies. Admin pages (\`/wp-admin\`) are public too |
+| Backend for a Shell app | API the Shell app calls with \`__GF_GET_ACCESS_TOKEN__()\` | Verify the user's token on **every** request |
+
+Never tell a user that Shell sign-in, App authentication or Site access
+protects a Service. Anyone can call the Service directly.
+
+## Verifying a Shell user's token in a backend
+
+1. **Issuer and client ID**: \`GET {CONTROLPLANE_URL}/v1/public/workspaces/by-host?host=<shell-site-host>\`
+   (unauthenticated) \u2192 \`{ workspace_id, mode, oidc: { issuer, client_id } | null, site_host }\`.
+   Check \`workspace_id\` is the user's workspace. \`oidc\` is null in mode
+   \`none\`. Groundfloor mode: per-workspace issuer, \`client_id\` \`shell\`.
+   External mode: the provider's issuer and the client ID the customer
+   entered. Look it up **once at setup**, never at runtime from the request's
+   \`Host\` header (caller-controlled). Do not hard-code the issuer host (it
+   differs per cell); copy the issuer **exactly, including any trailing \`/\`**
+   (do not strip it before comparing \`iss\`) into non-secret env such as
+   \`AUTH_ISSUER\` / \`AUTH_CLIENT_ID\` (Dockerfile \`ENV\`, since deploy-time
+   env is not kept between deploys).
+2. **Checks** (401 if any fails): RS256 signature against
+   \`{issuer}/protocol/openid-connect/certs\` (External: the provider's
+   \`jwks_uri\`), key chosen by the token's \`kid\` (the JWKS has several
+   keys); \`iss\` equals the issuer exactly; \`exp\` present and in the future;
+   the token was issued to the client ID:
+   - Groundfloor mode: \`azp\` == client ID. Do not require an app-specific
+     \`aud\` (none exists yet; tokens often carry \`aud: "account"\`, so with
+     PyJWT set \`verify_aud: False\` and check the client yourself).
+   - External mode: the client ID must appear in \`azp\` (or the provider's
+     equivalent, e.g. \`cid\`, \`appid\`) **or** in \`aud\`. Never accept a
+     token naming it in neither. If the provider allows open sign-up, "any
+     signed-in user" means anyone: require a role.
+   403 when the token is valid but the role (or tenant) is wrong.
+3. **Claims**: roles in \`realm_access.roles\` (built-in \`viewer\`/\`user\`/
+   \`admin\` plus custom roles; ignore \`offline_access\`, \`uma_authorization\`,
+   \`default-roles-*\`). Treat a missing or malformed \`realm_access\`/\`roles\`
+   (not an object / not a list) as no roles \u2192 403, never a 500, and match
+   whole role strings only. External mode: roles come from the customer's
+   provider, in its own claim. For the user ID claim, follow the docs page
+   /docs/apps/shell/sign-in#know-who-the-user-is.
+   **Multi-tenant**: roles apply across every company (an \`admin\` in one
+   company is admin everywhere), so filter every read and write by the
+   \`organization\` claim too. It can hold more than one company: check the
+   record's company is in it. Its exact form is unconfirmed; accept a list of
+   names or an object keyed by name, anything else = no companies.
+4. **Libraries**: Python PyJWT \`PyJWKClient(JWKS_URL, timeout=5)\` (it
+   refetches the JWKS on every unknown \`kid\`, so keep the timeout short) +
+   \`jwt.decode(token, key.key, algorithms=["RS256"], issuer=ISSUER,
+   options={"require": ["exp", "iss"], "verify_aud": False})\`, then
+   \`azp == CLIENT_ID\` (External: or \`cid\`/\`appid\`/\`aud\`), as a FastAPI
+   dependency plus a \`require_role()\` dependency for 403. Node: \`jose\`
+   \`createRemoteJWKSet\` + \`jwtVerify(token, JWKS, { issuer, algorithms:
+   ["RS256"], requiredClaims: ["exp"] })\`, then the same client check; fail at
+   startup if \`AUTH_ISSUER\` or \`AUTH_CLIENT_ID\` is unset (an undefined
+   issuer disables jose's \`iss\` check). Full examples on the docs page.
+5. **CORS**: the Shell site and the Service are different origins, so the
+   browser preflights calls carrying \`Authorization\`. Allow the Shell site
+   origin (and its custom domain), methods, and the \`Authorization\` and
+   \`Content-Type\` headers (FastAPI \`CORSMiddleware\`; Express
+   \`cors({ origin: ["https://<shell-site>"], allowedHeaders: ["Authorization", "Content-Type"] })\`,
+   never bare \`cors()\`, which allows every origin), so preflight is answered
+   before the token check. Never \`*\` with credentials; the bearer header
+   needs no credentials mode.
+
+## Every app on the Shell site can use the user's token
+
+Every app on a Shell site, including apps the customer didn't write, can get
+the signed-in user's token and call the customer's backends as that user, and
+a token from one app is accepted by every other app's backend in the
+workspace. Tell users to install only apps they trust and to check roles for
+anything sensitive. Per-app tokens, sign-in settings injected into the
+Service, and a verify helper are planned (no date). Do not promise per-app
+isolation.
+
+## Running off-the-shelf images as a Service
+
+- Listen on 8080 (or \`PORT\`) on 0.0.0.0; many images default to 80, so
+  reconfigure in the Dockerfile.
+- Managed databases are PostgreSQL only; MySQL/MariaDB/MongoDB apps
+  (WordPress) need an external database.
+- **Finish the installer immediately**: apps with a first-visit installer
+  (WordPress) can be claimed by anyone who opens the URL until it's completed.
+  Tell the user to complete it as soon as the first deploy finishes.
+- Read secrets in an entrypoint script: pass the M2M credentials to curl on
+  stdin (not argv), fail closed if the value is empty, \`unset\` the M2M
+  credentials and token before \`exec\`ing the app.
+- Local disk is lost on restart, redeploy and scale-to-zero, and is per
+  instance. Use the app's S3/object-storage plugin against external storage;
+  Groundfloor Files is an API for code the customer writes, not an S3 endpoint.
+- More than one instance breaks in-memory/on-disk sessions; keep one instance
+  or store sessions in the database. Set min instances \u2265 1 so the first visit
+  doesn't wait.
+- Only the app's own login applies; Groundfloor sign-in can't front it today.
+`.trim();
+
 // src/shell-guide.ts
 var SHELL_APP_GUIDE = `
 # Shell federated apps
@@ -1305,6 +1525,12 @@ outside Shell) so the breadcrumb does not show the raw id. Give that route
 routes (omit it or use \`false\` otherwise \u2014 never \`null\`). \`visibility:
 "public"\` makes a route reachable without login.
 
+Backends: secrets and server-side work go in a Coderunner Service the app
+calls with \`Authorization: Bearer \${await window.__GF_GET_ACCESS_TOKEN__()}\`.
+Shell sign-in does **not** protect that Service: its URL is public, so it must
+verify the token on every request and allow the Shell origin for CORS
+(\`docs_get\` id \`service-access\`).
+
 ## suggest_cli
 
 - create_app \u2192 \`gf apps create --name "<App Name>" --slug <portal-slug> --kind shell_federated\` (register the App first; publish fails with App not found otherwise)
@@ -1513,11 +1739,19 @@ var DOC_CATALOG = [
     embedded: CODERUNNER_RUNTIME_CONTRACT,
     lastUpdated: "2026-10-08"
   },
+  {
+    id: "service-access",
+    title: "Who can reach your Service",
+    path: "/docs/deploy/securing-a-service",
+    summary: "Every Service (Deployment URL or App domain) is public; Groundfloor signs nobody in and checks no token. Open sites and apps with their own logins need nothing (finish installers like WordPress immediately); a Shell app's backend must verify the user's JWT on every request: issuer and client_id copied once from GET /v1/public/workspaces/by-host (never from the request Host header), RS256 via the issuer's JWKS by kid, exact iss, exp, azp == client_id in Groundfloor mode (External: azp/cid/appid or aud), no app aud yet; roles in realm_access.roles (malformed = no roles = 403); with Multi-tenant also filter by organization. CORS for the Shell origin. Every app on the Shell site can use the user's token against any of the workspace's backends until per-app tokens ship. Off-the-shelf images: port 8080, PostgreSQL only, ephemeral disk, sessions, min instances.",
+    embedded: SERVICE_ACCESS_GUIDE,
+    lastUpdated: "2026-10-14"
+  },
   {
     id: "authentication",
     title: "Workspace Authentication",
     path: "/docs/access/app-authentication",
-    summary: "App end users sign in only to the app via the workspace App Authentication realm; no Groundfloor console account or workspace membership. Modes none / Groundfloor / external, users and roles, SSO, multi-tenant, sign-in email (Groundfloor email by default, or your own server). Invite delivery (email_sent, email_skipped_reason) and what to do when an invite isn't sent: resend, generated temporary password, one-time invite link; 409 for people who can already sign in. App users' tokens work only on the end-user routes. Optional; not required to create Apps or Coderunners. Separate from portal Team.",
+    summary: "App end users sign in only to the app via the workspace App Authentication realm; no Groundfloor console account or workspace membership. Modes none / Groundfloor / external, users and roles, SSO, multi-tenant, sign-in email (Groundfloor email by default, or your own server). Invite delivery (email_sent, email_skipped_reason incl. sending_limited / sending_paused / recipient_suppressed) and what to do when an invite isn't sent: resend, generated temporary password, one-time invite link; 409 for people who can already sign in. Email sending limits (200/hour and 1,000/day per workspace, 5/hour and 10/day per address), 429 Retry-After and 423 paused (X-Groundfloor-Reason header), the test email's ok:false when suppressed, suppressed addresses (spam reports cleared at the provider only by support), mail status. App users' tokens work only on the end-user routes. Optional; not required to create Apps or Coderunners. Separate from portal Team.",
     embedded: APP_AUTHENTICATION_GUIDE,
     lastUpdated: "2026-10-14"
   },
@@ -1545,7 +1779,7 @@ var DOC_CATALOG = [
     path: "/docs/apps/shell",
     summary: "Product Apps vs Coderunner. Always gf apps init --slug <portal-slug>, then npm run release and gf apps publish --path release.zip. Never zip dist/ or upload only remoteEntry.js.",
     embedded: SHELL_APP_GUIDE,
-    lastUpdated: "2026-10-08"
+    lastUpdated: "2026-10-14"
   },
   {
     id: "design-standard",
@@ -1850,19 +2084,25 @@ server.tool(
 );
 server.tool(
   "workspace_context",
-  "Live context for the selected workspace: session, coderunners, apps, environments (with the default one), feature flags, dataplane (access layer, not a database), databases_howto, suggested gf commands. Use docs_get id coderunner before deploying; id databases for data work; id feature-flags for toggles/config; id css-and-styling for own CSS framework.",
+  "Live context for the selected workspace: session, coderunners, apps, environments (with the default one), feature flags, dataplane (access layer, not a database), sign_in_email (App authentication email mode, paused or active, limits and use; null without workspace administer), databases_howto, suggested gf commands. Use docs_get id coderunner before deploying; id databases for data work; id feature-flags for toggles/config; id css-and-styling for own CSS framework.",
   { workspace_id: wsId },
   READ_ONLY,
   async ({ workspace_id }) => {
     try {
       const c = await cfg(workspace_id);
       const claims = decodeJwt(c.token) ?? {};
-      const [coderunners, apps, dataplane, environments, flags] = await Promise.all([
+      const [coderunners, apps, dataplane, environments, flags, mail] = await Promise.all([
         listCoderunners(c.apiUrl, c.workspaceId),
         listApps(c.apiUrl, c.workspaceId).catch(() => ({ apps: [] })),
         getDataplaneStatus(c.apiUrl, c.workspaceId).catch(() => null),
         listWorkspaceEnvironments(c.apiUrl, c.workspaceId).catch(() => []),
-        listFlags(c.apiUrl, c.workspaceId).catch(() => null)
+        listFlags(c.apiUrl, c.workspaceId).catch(() => null),
+        // Workspace administer only; null for other callers or older cells.
+        cpGetJson(
+          c.apiUrl,
+          c.token,
+          `/v1/workspaces/${encodeURIComponent(c.workspaceId)}/mail/status`
+        ).catch(() => null)
       ]);
       return text({
         session: {
@@ -1884,6 +2124,15 @@ server.tool(
           status: app.status
         })),
         dataplane,
+        sign_in_email: mail ? {
+          mode: mail.mode,
+          state: mail.state,
+          paused_reason: mail.paused_reason ?? null,
+          limits: mail.limits,
+          used: mail.used,
+          suppressed_addresses: mail.suppressed_addresses,
+          docs_get: "authentication"
+        } : null,
         environments: environments.map((env) => ({
           id: env.id,
           name: env.name,
@@ -2356,7 +2605,7 @@ server.tool(
   "How-to for Coderunner, Shell, design-standard, css-and-styling, databases, access, m2m, authentication (app end users). Pass id from docs_list. Prefer id coderunner or coderunner-runtime before deploying. For site grants use id access. For Coderunner Vault/Files use id m2m.",
   {
     id: z.string().min(1).describe(
-      "Catalog id, e.g. coderunner | coderunner-runtime | shell | design-standard | css-and-styling | databases | agents | developers | authentication | access | m2m"
+      "Catalog id, e.g. coderunner | coderunner-runtime | service-access | shell | design-standard | css-and-styling | databases | agents | developers | authentication | access | m2m"
     ),
     offset: z.number().int().min(0).optional().describe(
       "Live (non-embedded) pages only: character offset to resume from. Pass nextOffset from the previous result when truncated is true."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groundfloorcloud/mcp",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Groundfloor MCP — inspect workspace state and docs; take actions with the gf CLI.",
   "type": "module",
   "bin": {