@groundfloorcloud/mcp 0.2.1 → 0.2.3

package/README.md

@@ -81,7 +81,7 @@ Use the prefixed names: `GROUNDFLOOR_API_URL`, `GROUNDFLOOR_WORKSPACE_ID`, `GROU
 | `apps_list` / `apps_get` | Inspect product Apps |
 | `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 Owner or Billing admin) |
+| `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) |
 | `suggest_cli` | Command to run: login, deploy, create_app, init_app, publish_app, m2m_token, … |
 

package/dist/index.js

@@ -516,8 +516,20 @@ the provider.
 
 ## Users and roles (Groundfloor mode)
 
-- **Invite user**: they set their own password (email needs Branding set up).
-- **Add user**: you set a password now; no email is sent.
+- **Invite user**: they set their own password from an emailed invitation
+  (the link works for 72 hours).
+- **Add user**: they can sign in straight away. Prefer **Generate a temporary
+  password** (API: \`POST /v1/workspaces/{id}/users/add\` with
+  \`generate_password: true\`): it is returned once in \`temporary_password\`
+  with \`sign_in_url\`, never stored or emailed, and must be changed at first
+  sign-in. They also get an email with their sign-in address and role (never
+  the password).
+- Invite and add take an optional \`app_id\` so the email's sign-in link opens
+  that app.
+- Inviting or adding someone who can already sign in (a password, another
+  credential or single sign-on) returns 409 and sends nothing. Use
+  \`POST \u2026/users/{user_id}/reset-password\` for them instead.
+- App users never appear on the portal **Team** page.
 - Each user has a role: built-in \`viewer\`, \`user\`, \`admin\`, or a custom role
   created on the **Roles** tab. Roles here are unrelated to Portal team roles.
 - The role decides what the user reaches once granted on **Site access**
@@ -530,6 +542,65 @@ the provider.
 - SSO (OIDC or SAML) can be connected per workspace; role names in the
   provider's tokens must match the roles granted on Site access.
 
+## Sign-in email (invites, password resets, email verification)
+
+- Sent by **Groundfloor email** by default in every workspace: a Groundfloor
+  no-reply address with the organization's name as sender. Nothing to set up;
+  do not tell the user to configure email before inviting.
+- To use their own mail server, the user chooses **Your own email server**
+  under **Branding \u2192 Email sending** (host, port and from address required;
+  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\`.
+- 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
+  \`mode: "groundfloor"\`) switches back to Groundfloor email and deletes the
+  stored custom server settings and password. Only send \`mail\` when the user
+  means to change email settings.
+
+## When an invite email isn't sent
+
+Never report an invite as delivered without checking. Invite, add, resend and
+reset responses, and every user in \`GET /v1/workspaces/{id}/users\`, carry:
+
+- \`email_sent\`: \`true\` sent, \`false\` not sent, \`null\` unknown.
+- \`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\`.
+  \`keycloak_smtp_missing\` is retired and no longer returned.
+- \`email_attempted_at\` (\`null\` = invited before delivery was recorded),
+  \`invite_pending\`, \`password_change_required\`,
+  \`temporary_password_set_at\`, \`invite_link_expires_at\`.
+
+If \`email_sent\` is not \`true\` for a pending user, tell the user plainly
+and offer the fallbacks. In the Portal they are on the user's row under
+**App authentication \u2192 Users**; all need workspace \`administer\` (M2M and
+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
+   \`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
+   or still on an unused temporary password): returns \`temporary_password\`
+   and \`sign_in_url\` once; no email is sent; same user id and roles; must be
+   changed at first sign-in. 504 = it may or may not be set, retry.
+3. **Copy link** (\`POST \u2026/users/{user_id}/invite-link\`, pending and enabled
+   users only): returns a one-time \`url\` (the portal's \`/join\` page) and
+   \`expires_at\` (24 h), once. The user opens it and chooses their own
+   password. Each call cancels the previous link; \`DELETE\` cancels it;
+   at most 10 per user per hour. Anyone holding the link can set the
+   password.
+
+Temporary passwords and invite links are credentials. Show them only to the
+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.
+
 ## Multi-tenant (customer companies inside one workspace)
 
 Turn on **Multi-tenant** in Settings to get a Tenants tab: one tenant per
@@ -544,6 +615,15 @@ Switching to None or External keeps users, roles and settings (switch back and
 they return). To remove them, turn sign-in off first, then **Delete Groundfloor
 login**. Access grants and M2M tokens are kept.
 
+## What app users' tokens can call
+
+App users' tokens work only on: app list and by-slug, Data Vault collection
+list/schema and record query/count/create/update/delete (per collection
+grants), Files list/upload/download/delete (per Files grants) and
+\`GET \u2026/flags/runtime\`. Everything else returns 403 "This API is not
+available to app end users", whatever their role, \`admin\` included. A user
+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
@@ -798,6 +878,11 @@ CMD ["npm", "start"]
   \`externalEndpoint\` and status 4 means the container never became ready.
   \`gf deploy\` prints the last Process Log lines, ids, and a Portal link on
   failure. Fetch more with \`gf coderunner logs -c <id|slug>\`.
+- \`coderunner_get_status\` (\`GET \u2026/coderunners/{id}/status\`) returns
+  \`deployment_status\` (same 1\u20137 codes) and \`deployment_status_message\` for
+  the current deployment. While it is 4 (Failed), an App address or custom
+  domain routed to it answers 503, and the Portal app page shows "Deployment
+  failed".
 - Strip \`.env*\`, \`.git\`, \`node_modules\` from ZIPs. Put secrets in
   \`gf secrets\` / deploy \`-e\`, never in the archive.
 - Zip **contents** at root, not a wrapping folder.
@@ -914,8 +999,9 @@ documented limit.
 Plan quota and usage are account-scoped, not workspace-scoped. The **account
 id is not the workspace id**: read \`account_id\` from \`workspaces_list\`. If a
 deploy is refused or you need to know what is in use, call \`quota_get\`.
-\`billing_summary\` shows spend, and only Owners and Billing admins can read it
-(others get 403).
+\`billing_summary\` shows spend, and only organization Owners, Admins and
+Billing admins can read it (others get 403). A Billing admin has no workspace
+access at all.
 
 ## Agent actions
 
@@ -975,16 +1061,26 @@ deploy a dedicated PostgreSQL first.
 ## Options
 
 - PostgreSQL (shared) \u2014 platform-managed, already there. Default for app data
-  and Vault. No deploy step. This is NOT a workspace-owned resource: it does
-  not appear on the customer Databases page, and there is nothing to scale,
-  back up, or delete yourself \u2014 it's offered, not provisioned. Query via
-  Control Plane vault: POST /v1/workspaces/{id}/vault/collections/{name}/query
+  and Vault. No deploy step. The portal Databases page lists it first as
+  "Shared PostgreSQL" (Default, connected as \`postgresql\`), but it is NOT a
+  workspace-owned resource: no credentials, and nothing to scale, back up, or
+  delete yourself \u2014 it's offered, not provisioned. Query via Control Plane
+  vault: POST /v1/workspaces/{id}/vault/collections/{name}/query
 - Dedicated PostgreSQL you deploy and own \u2014 portal Data \u2192 Databases, or
   POST /v1/workspaces/{id}/managed-databases with engine postgres. Heavier
   than the shared default: you own its scaling, backups, and lifecycle. Use it
   when you want a database isolated to this workspace.
 - A database they already run \u2014 through Dataplane if they wire it, or direct.
 
+A dedicated PostgreSQL is usable through Vault only once Dataplane has it:
+\`GET /v1/workspaces/{id}/managed-databases\` returns \`dataplane_status\`
+(\`connected\` | \`not_connected\` | null while not up) and
+\`dataplane_connection_name\` (pass it as Vault \`connection\`). If it is
+\`not_connected\`, retry with
+\`POST \u2026/managed-databases/{managed_database_id}/dataplane/register\` (write; the
+portal's Retry button), or tell the user to. New dedicated databases get a
+daily backup schedule (30-day retention) where the cell has backup storage.
+
 PostgreSQL is the only engine offered today, shared or dedicated. Do not offer
 other engines (ArangoDB, MongoDB, Redis, ClickHouse, Qdrant, \u2026) as available,
 even if you see them mentioned elsewhere. Do not call Dataplane hosts from apps
@@ -1100,9 +1196,10 @@ with no role gets 403.
 ### Shell federated app (browser)
 
 - **Token**: the Shell end-user JWT, \`await window.__GF_GET_ACCESS_TOKEN__()\`.
-- **Permission**: workspace \`read\`. Site users get it from a recognised site
-  role (member/admin); self-registered users with no role get 403 (same rule
-  as Vault). No per-flag Access grant exists or is needed.
+- **Permission**: any role from the workspace's App authentication (built-in
+  or custom); a signed-in user with no role gets 403 (same rule as Vault).
+  App users are not workspace members. No per-flag Access grant exists or is
+  needed.
 - **Environment**: \`window.__GF_ENVIRONMENT_ID__\` \u2014 the environment the app is
   bound to, published by the Shell before your remote mounts. Unset in local
   Dev Shell \u2192 server default (dev); \`VITE_GF_ENVIRONMENT_ID\` pins one.
@@ -1406,7 +1503,7 @@ var DOC_CATALOG = [
     path: "/docs/deploy",
     summary: "Workload types (function, job, schedule, service/Deployment), runtime contract (handler.js for function/job/schedule; npm start, PORT 8080 for service), Dockerfile for services, Coderunner identities for Vault, App authentication optional, local live data, gf deploy.",
     embedded: CODERUNNER_GUIDE,
-    lastUpdated: "2026-10-08"
+    lastUpdated: "2026-10-14"
   },
   {
     id: "coderunner-runtime",
@@ -1420,9 +1517,9 @@ 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. 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) 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.",
     embedded: APP_AUTHENTICATION_GUIDE,
-    lastUpdated: "2026-10-12"
+    lastUpdated: "2026-10-14"
   },
   {
     id: "access",
@@ -1470,9 +1567,9 @@ var DOC_CATALOG = [
     id: "databases",
     title: "Databases",
     path: "/docs/data/databases",
-    summary: "Dataplane is not a database. PostgreSQL (shared, platform-managed) is ready through Dataplane with no deploy step. A dedicated PostgreSQL you deploy and own is a separate, heavier path. PostgreSQL is the only engine offered.",
+    summary: "Dataplane is not a database. PostgreSQL (shared, platform-managed) is ready through Dataplane with no deploy step. A dedicated PostgreSQL you deploy and own is a separate, heavier path; check its dataplane_status before using it in Vault. PostgreSQL is the only engine offered.",
     embedded: DATABASES_GUIDE,
-    lastUpdated: "2026-09-26"
+    lastUpdated: "2026-10-14"
   },
   {
     id: "vault",
@@ -1488,7 +1585,7 @@ var DOC_CATALOG = [
     path: "/docs/configure/feature-flags",
     summary: "Built-in per-environment feature flags (toggles / config values) \u2014 use these, not a Vault collection. gf flags ls|set|compare|promote. Apps read GET \u2026/flags/runtime: Shell apps with the end-user JWT + window.__GF_ENVIRONMENT_ID__ (starter-kit useFlag), Coderunners with gf m2m token + GROUNDFLOOR_ENVIRONMENT_ID. Default environment is dev.",
     embedded: FLAGS_GUIDE,
-    lastUpdated: "2026-10-08"
+    lastUpdated: "2026-10-14"
   },
   {
     id: "flags-api",
@@ -1496,7 +1593,7 @@ var DOC_CATALOG = [
     path: "/docs/api/flags",
     summary: "REST reference for flags: list/get/put/delete per environment_id (omitted \u2192 workspace default, dev), compare, promote, runtime read. Key format, value_type validation, auth per method (M2M read-only), error codes.",
     embedded: FLAGS_GUIDE,
-    lastUpdated: "2026-10-08"
+    lastUpdated: "2026-10-14"
   },
   {
     id: "scheduled-jobs",
@@ -1504,7 +1601,7 @@ var DOC_CATALOG = [
     path: "/docs/deploy/schedules",
     summary: "workload_type=schedule plus cron. gf coderunner status shows type/schedule/last_job. Use Process Log, not a public URL.",
     embedded: CODERUNNER_GUIDE,
-    lastUpdated: "2026-10-08"
+    lastUpdated: "2026-10-14"
   }
 ];
 function docUrl(entry) {
@@ -1799,7 +1896,7 @@ server.tool(
           default_environment_id: flags?.environment_id ?? null,
           default_environment_flags: flags ? flags.flags.map((f) => ({ key: f.key, value_type: f.value_type, value: f.value })) : null,
           manage: "gf flags ls|get|set|rm|compare|promote -e <env id or name>. Omitting -e uses the default environment (dev).",
-          shell_app: "Starter-kit src/lib/flags.ts: useFlag('key', fallback). Calls GET /v1/workspaces/{id}/flags/runtime?environment_id=window.__GF_ENVIRONMENT_ID__ with the Shell end-user JWT (needs a site role \u2192 workspace read).",
+          shell_app: "Starter-kit src/lib/flags.ts: useFlag('key', fallback). Calls GET /v1/workspaces/{id}/flags/runtime?environment_id=window.__GF_ENVIRONMENT_ID__ with the Shell end-user JWT (needs any App authentication role; app users are not workspace members).",
           coderunner: "GET \u2026/flags/runtime?environment_id=$GROUNDFLOOR_ENVIRONMENT_ID with an M2M token (gf m2m token). M2M is read-only on flags; workload-identity tokens are rejected."
         },
         coderunner_howto: {
@@ -2210,7 +2307,7 @@ server.tool(
 );
 server.tool(
   "billing_summary",
-  "Compute-unit usage and billing estimate for the organization that owns the workspace (account-scoped, not workspace-scoped). Only Owners and Billing admins may read it; others get 403. The response notes whether it is an estimate.",
+  "Compute-unit usage and billing estimate for the organization that owns the workspace (account-scoped, not workspace-scoped). Only organization Owners, Admins and Billing admins may read it; others get 403. The response notes whether it is an estimate.",
   {
     workspace_id: wsId,
     account_id: accountId,

package/package.json

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