@groundfloorcloud/mcp 0.2.4 → 0.2.5

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
@@ -1653,7 +1751,7 @@ var DOC_CATALOG = [
     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"
   },
@@ -1986,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: {
@@ -2020,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,

package/package.json

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