@groundfloorcloud/mcp 0.1.13 → 0.1.14

package/README.md

@@ -84,8 +84,9 @@ then `npm run release` and `gf apps publish --path release.zip`. Do not invent
 `App.tsx` / `vite.config`, zip `dist/`, or upload only `remoteEntry.js`.
 Own CSS framework: `docs_get` id `css-and-styling` (`FederatedStyleRoot`).
 
-**Databases:** `docs_get` id `databases`. Dataplane is not a database. ArangoDB
-is ready through Dataplane; Postgres is what you can deploy today.
+**Databases:** `docs_get` id `databases`. Dataplane is not a database. Shared
+PostgreSQL is ready through Dataplane; a dedicated PostgreSQL is what you can
+deploy today. No other engines are offered.
 
 **Coderunner how-to** is embedded: `docs_get` id `coderunner` (also
 `coderunner-overview`). That page covers:

package/dist/index.js

@@ -327,6 +327,12 @@ function listSecrets(apiUrl, workspaceId, environmentId) {
     })}`
   );
 }
+function listFlags(apiUrl, workspaceId, environmentId) {
+  return cpGet(
+    apiUrl,
+    `${wsPath(workspaceId, "/flags")}${queryString({ environment_id: environmentId })}`
+  );
+}
 function listFiles(apiUrl, workspaceId) {
   return cpGet(apiUrl, wsPath(workspaceId, "/files"));
 }
@@ -776,43 +782,40 @@ Dataplane is not a database. It is how Groundfloor talks to databases.
 When the user starts any data or database work, say this first. Do not mention
 infrastructure internals (cluster operators, installers, and the like):
 
-You have Postgres ready to use through Dataplane \u2014 a shared, platform-managed
-cluster, already there, no deploy step. If you want a different engine, or a
-database that is entirely your own (own scaling, own backups schedule), you
-can deploy one first.
+You have PostgreSQL ready to use through Dataplane \u2014 a shared,
+platform-managed cluster, already there, no deploy step. If you want a
+database that is entirely your own (own scaling, own backup schedule), you can
+deploy a dedicated PostgreSQL first.
 
 ## Options
 
-- Postgres (shared) \u2014 platform-managed, already there. Default for app data
+- 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
-- ArangoDB \u2014 also shared, managed, already there, no deploy step. Still fully
-  supported; just no longer the pre-selected engine for new collections.
-- A dedicated database you deploy and own (Postgres, Redis, ClickHouse,
-  Qdrant) \u2014 portal Data \u2192 Databases, or
-  POST /v1/workspaces/{id}/managed-databases. Heavier than the shared
-  default: you own its scaling, backups, and lifecycle. Use this when you
-  need a tier/engine the shared default doesn't offer (Redis, ClickHouse,
-  Qdrant) or want a database isolated to this workspace.
+- 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.
 
-Do not list other engines as available to deploy. Do not call Dataplane hosts
-from apps or embed service keys.
+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
+or embed service keys.
 
 ## Creating a collection / table
 
 Pass the engine explicitly \u2014 do not rely on Dataplane's default connector
 resolution. POST /v1/workspaces/{id}/vault/collections with
-\`"schema": {"engine": "postgresql", ...}\` for the shared default, or
-\`"engine": "arangodb"\` to use ArangoDB instead.
+\`"schema": {"engine": "postgresql", ...}\`.
 
 ## Paths
 
 - Browse / edit rows \u2192 Data Vault (portal or vault APIs)
-- Deploy your own database \u2192 Customer Portal Databases page, or
-  POST /v1/workspaces/{id}/managed-databases with engine postgres|redis|clickhouse|qdrant
+- Deploy your own PostgreSQL \u2192 Customer Portal Databases page, or
+  POST /v1/workspaces/{id}/managed-databases with engine postgres
 - Shell 403 / empty vault \u2192 collection Access for the site role
 
 docs_get id databases. Human docs: /docs/customer-portal/databases and /docs/customer-portal/data-vault
@@ -865,6 +868,112 @@ stay in Shadow DOM. Render modals inside that root, not document.body.
 Full steps: docs_get id css-and-styling.
 `;
 
+// src/flags-guide.ts
+var FLAGS_GUIDE = `
+# Feature Flags
+
+Groundfloor has built-in feature flags: per-environment key \u2192 value toggles
+(boolean, string, number or JSON) stored in Control Plane. **Use them instead
+of building a flags table in a Vault collection or reading \`.env\`.** Each
+environment (dev / staging / prod) has its own values; \`promote\` copies
+between them.
+
+## Manage (builder)
+
+\`\`\`bash
+gf flags ls -e dev                       # -e takes an environment id or name
+gf flags set new-checkout true -e dev    # type inferred; --type json for objects
+gf flags compare dev prod
+gf flags promote dev prod --dry-run
+gf flags rm new-checkout -e dev
+\`\`\`
+
+Or the Portal: Workspace \u2192 Feature Flags. API (builder \`gf token\`):
+\`GET|PUT|DELETE /v1/workspaces/{id}/flags[/{key}]?environment_id=\`,
+\`GET \u2026/flags/compare\`, \`POST \u2026/flags/promote\` \u2014 docs_get id \`flags-api\`.
+
+- **Keys**: trimmed + lowercased, then \`^[a-z][a-z0-9_.-]{0,62}$\` (\`new-checkout\`,
+  \`ui.dark_mode\`). \`compare\`, \`promote\`, \`runtime\` are reserved.
+- **Values**: \`value_type\` defaults to \`boolean\`; a mismatched value is 422.
+- **Default environment**: omit \`environment_id\` \u2192 the active env named
+  \`dev\` (or the only active env). The response echoes the resolved
+  \`environment_id\`. Pass it explicitly for anything prod-facing.
+
+## Read at runtime (apps)
+
+One endpoint for every runtime:
+
+\`GET /v1/workspaces/{workspace_id}/flags/runtime?environment_id=<env>\`
+\u2192 \`{ "workspace_id", "environment_id", "flags": { "new-checkout": true, \u2026 } }\`
+
+Weak \`ETag\` + \`Cache-Control: private, no-cache\`. Send \`If-None-Match\` \u2192 304.
+Poll no faster than every 30s (the kit uses 60s). No push channel yet.
+Flag values are not secrets \u2014 every signed-in end user can read them.
+
+### 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.
+- **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.
+- **Code**: the starter kit ships \`src/lib/flags.ts\`. Do not hand-roll it.
+
+\`\`\`tsx
+import { useFlag, useFlags } from './lib/flags';
+
+export function Checkout() {
+  const newCheckout = useFlag('new-checkout', false);
+  const maxItems = useFlag('max-items', 10);
+  return newCheckout ? <NewCheckout max={maxItems} /> : <LegacyCheckout />;
+}
+// Many flags: const { flags, loading, error } = useFlags();
+\`\`\`
+
+### Coderunner (server)
+
+- **Token**: M2M \u2014 \`gf m2m token\` locally, or exchange
+  \`GROUNDFLOOR_M2M_CLIENT_ID\`/\`_SECRET\` at \`POST \u2026/m2m/token\` in code. M2M is
+  **read-only** on flags (PUT/DELETE/promote \u2192 403). Workload-identity Vault
+  JWTs cannot read flags (403).
+- **Environment**: \`GROUNDFLOOR_ENVIRONMENT_ID\` is injected on deploy (the
+  Coderunner's bound environment). \`GROUNDFLOOR_WORKSPACE_ID\`,
+  \`CONTROLPLANE_URL\` and the M2M client id/secret are injected when an M2M
+  client is attached. Redeploy once to pick up the variable on older deploys.
+
+\`\`\`js
+const CP = process.env.CONTROLPLANE_URL;
+const WS = process.env.GROUNDFLOOR_WORKSPACE_ID;
+const ENV = process.env.GROUNDFLOOR_ENVIRONMENT_ID;
+let cache = { etag: null, flags: {} };
+
+export async function getFlags(token) {
+  const qs = ENV ? \`?environment_id=\${encodeURIComponent(ENV)}\` : '';
+  const res = await fetch(\`\${CP}/v1/workspaces/\${WS}/flags/runtime\${qs}\`, {
+    headers: {
+      Authorization: \`Bearer \${token}\`,
+      ...(cache.etag ? { 'If-None-Match': cache.etag } : {}),
+    },
+  });
+  if (res.status === 304) return cache.flags;
+  if (!res.ok) throw new Error(\`flags \${res.status}: \${await res.text()}\`);
+  const body = await res.json();
+  cache = { etag: res.headers.get('etag'), flags: body.flags };
+  return cache.flags;
+}
+// Call per request with a cached M2M token; refresh at most every 30\u201360s.
+\`\`\`
+
+## Errors
+
+401 bad/missing token \xB7 403 no workspace read, M2M write, or workload identity \xB7
+404 unknown workspace/environment/flag \xB7 409 environment not active, or no
+active environments \xB7 400 bad or reserved key \xB7 422 value/value_type mismatch \xB7
+423 workspace frozen (writes).
+`.trim();
+
 // src/shell-guide.ts
 var SHELL_APP_GUIDE = `
 # Shell federated apps
@@ -899,10 +1008,9 @@ remoteEntry.js. Header logos: manifest \`theme.logoUrl\` (absolute https).
 UI look: \`docs_get\` id \`design-standard\`. CSS: Tailwind by default;
 own framework uses FederatedStyleRoot (Shadow DOM) \u2014 \`docs_get\` id
 \`css-and-styling\`. Data: Dataplane is not a database. Say first: you have
-Postgres (shared, platform-managed, no deploy step) ready through Dataplane
-by default; ArangoDB is also ready the same way. Deploy your own dedicated
-database only if you need a different engine or workspace-owned isolation
-(\`docs_get\` id \`databases\`). Local UI without live vault:
+PostgreSQL (shared, platform-managed, no deploy step) ready through Dataplane.
+Deploy a dedicated PostgreSQL only if you want workspace-owned isolation.
+No other engines are offered (\`docs_get\` id \`databases\`). Local UI without live vault:
 \`npm run dev:fixtures\`.
 
 Detail routes (e.g. \`records/:id\`): once the record loads, call
@@ -934,12 +1042,14 @@ POST \`/v1/workspaces/{id}/vault/collections\` with a **JSON Schema** object
 **400** with a field error \u2014 not a 500.
 
 Pass \`engine\` explicitly \u2014 don't rely on Dataplane's default connector.
-\`"postgresql"\` is the platform default (shared, no deploy step);
-\`"arangodb"\` is also available the same way.
+\`"postgresql"\` is the platform default (shared, no deploy step) and the only
+engine offered today. \`?connection=\` must be \`postgresql\` or the name of a dedicated
+PostgreSQL in this workspace \u2014 another engine or an unknown name is **400**.
 
-\`id\` and \`tenant_id\` are reserved field names on Postgres (and any SQL-shaped
-engine) \u2014 Dataplane adds them automatically as system columns on every table.
-Declaring either as a property is a **400**, not a 500. Not reserved on ArangoDB.
+\`id\`, \`tenant_id\`, and \`gf_extra\` are reserved field names \u2014 Dataplane adds
+them automatically as system columns on every Postgres table. Declaring any of
+them as a property is a **400**, not a 500. Undeclared record fields are kept in \`gf_extra\` and
+merged back on read, so extra keys are not lost.
 
 Example:
 
@@ -1028,7 +1138,7 @@ var DOC_CATALOG = [
     id: "developers",
     title: "Developers (gf CLI)",
     path: "/docs/customer-portal/developers",
-    summary: "gf login, workspaces, deploy, secrets, files, apps, gf m2m token. Coderunner types: function, job, schedule, service (also called Deployment). App authentication optional."
+    summary: "gf login, workspaces, deploy, secrets, feature flags (gf flags), files, apps, gf m2m token. Coderunner types: function, job, schedule, service (also called Deployment). App authentication optional."
   },
   {
     id: "coderunner",
@@ -1084,7 +1194,7 @@ var DOC_CATALOG = [
     path: "/docs/integrations/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-09-24"
+    lastUpdated: "2026-09-26"
   },
   {
     id: "design-standard",
@@ -1106,9 +1216,9 @@ var DOC_CATALOG = [
     id: "databases",
     title: "Databases",
     path: "/docs/customer-portal/databases",
-    summary: "Dataplane is not a database. Postgres (shared, platform-managed) is the default, ready through Dataplane with no deploy step. ArangoDB is also ready the same way. A dedicated database you deploy and own is a separate, heavier path.",
+    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.",
     embedded: DATABASES_GUIDE,
-    lastUpdated: "2026-09-22"
+    lastUpdated: "2026-09-26"
   },
   {
     id: "vault",
@@ -1116,7 +1226,23 @@ var DOC_CATALOG = [
     path: "/docs/api/vault",
     summary: "Create collections with JSON Schema, query totals vs limit, ACLs, implicit tables, nested filters, identities vs M2M.",
     embedded: VAULT_GUIDE,
-    lastUpdated: "2026-09-22"
+    lastUpdated: "2026-09-26"
+  },
+  {
+    id: "feature-flags",
+    title: "Feature Flags",
+    path: "/docs/customer-portal/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-09-26"
+  },
+  {
+    id: "flags-api",
+    title: "Feature flags API",
+    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-09-26"
   },
   {
     id: "scheduled-jobs",
@@ -1252,6 +1378,12 @@ function suggestCli(intent, args) {
         why: "Mutations: gf secrets set|get|rm. MCP only lists keys.",
         docs: "https://docs.groundfloor.cloud/docs/customer-portal/developers"
       };
+    case "flags":
+      return {
+        command: `gf flags ls${ws}`,
+        why: "Feature flags per environment. Mutations: gf flags set|rm|compare|promote (-e <id|name>). Apps read GET \u2026/flags/runtime (docs_get id feature-flags). Do not build flags in a Vault collection.",
+        docs: "https://docs.groundfloor.cloud/docs/customer-portal/feature-flags"
+      };
     case "dataplane":
       return {
         command: `gf dataplane status${ws}  # provision: gf dataplane provision`,
@@ -1268,7 +1400,7 @@ function suggestCli(intent, args) {
     default:
       return {
         command: "gf --help",
-        why: `Unknown intent "${intent}". Use login | switch_workspace | deploy | run | status | logs | environments | cancel_deployment | init_app | publish_app | secrets | dataplane | vault_token.`,
+        why: `Unknown intent "${intent}". Use login | switch_workspace | deploy | run | status | logs | environments | cancel_deployment | init_app | publish_app | secrets | flags | dataplane | vault_token.`,
         docs: "https://docs.groundfloor.cloud/docs/customer-portal/developers"
       };
   }
@@ -1339,16 +1471,18 @@ server.tool(
 );
 server.tool(
   "workspace_context",
-  "Live context for the selected workspace: session, coderunners, apps, dataplane (access layer, not a database), databases_howto, suggested gf commands. Use docs_get id coderunner before deploying; id databases for data work; 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), 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 },
   async ({ workspace_id }) => {
     try {
       const c = await cfg(workspace_id);
       const claims = decodeJwt(c.token) ?? {};
-      const [coderunners, apps, dataplane] = await Promise.all([
+      const [coderunners, apps, dataplane, environments, flags] = await Promise.all([
         listCoderunners(c.apiUrl, c.workspaceId),
         listApps(c.apiUrl, c.workspaceId).catch(() => ({ apps: [] })),
-        getDataplaneStatus(c.apiUrl, c.workspaceId).catch(() => null)
+        getDataplaneStatus(c.apiUrl, c.workspaceId).catch(() => null),
+        listWorkspaceEnvironments(c.apiUrl, c.workspaceId).catch(() => []),
+        listFlags(c.apiUrl, c.workspaceId).catch(() => null)
       ]);
       return text({
         session: {
@@ -1370,6 +1504,21 @@ server.tool(
           status: app.status
         })),
         dataplane,
+        environments: environments.map((env) => ({
+          id: env.id,
+          name: env.name,
+          status: env.status,
+          default: flags ? env.id === flags.environment_id : void 0
+        })),
+        feature_flags_howto: {
+          docs_get: "feature-flags",
+          rule: "Groundfloor has built-in per-environment feature flags. Use them; never build a flags collection in Vault or read toggles from .env.",
+          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).",
+          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: {
           docs_get: "coderunner",
           runtime_contract: "coderunner-runtime",
@@ -1393,10 +1542,10 @@ server.tool(
         databases_howto: {
           docs_get: "databases",
           dataplane: "Dataplane is not a database. It is how Groundfloor talks to databases.",
-          say_first: "You have Postgres ready to use through Dataplane \u2014 shared, platform-managed, already there, no deploy step. ArangoDB is also available the same way. If you want your own dedicated database instead, deploy it first.",
+          say_first: "You have PostgreSQL ready to use through Dataplane \u2014 shared, platform-managed, already there, no deploy step. If you want your own dedicated database instead, deploy a dedicated PostgreSQL first.",
           shared_postgres: 'Default for app data and Vault. Platform-managed, not workspace-owned \u2014 nothing to scale/backup/delete yourself. Pass engine "postgresql" explicitly when creating a collection.',
-          arango: "Also shared, managed, already there, no deploy step. Still fully supported; just no longer pre-selected.",
-          deploy: "A dedicated Postgres/Redis/ClickHouse/Qdrant you own is what you can deploy today (portal Data \u2192 Databases)."
+          deploy: "A dedicated PostgreSQL you own is what you can deploy today (portal Data \u2192 Databases).",
+          engines: "PostgreSQL only, shared or dedicated. Do not offer ArangoDB, MongoDB, Redis, ClickHouse, Qdrant or other engines."
         },
         actions: {
           deploy: suggestCli("deploy"),
@@ -1404,6 +1553,7 @@ server.tool(
           run: suggestCli("run"),
           logs: suggestCli("logs"),
           environments: suggestCli("environments"),
+          flags: suggestCli("flags"),
           cancel_deployment: suggestCli("cancel_deployment"),
           vault_token: suggestCli("m2m_token"),
           init_app: suggestCli("init_app"),
@@ -1641,6 +1791,21 @@ server.tool(
     }
   }
 );
+server.tool(
+  "flags_list",
+  "List feature flags and values in one environment (omit environment_id \u2192 workspace default, dev; response echoes the resolved id). To set/delete/promote, use `gf flags`. docs_get id feature-flags for runtime use.",
+  { workspace_id: wsId, environment_id: z.string().optional() },
+  async (args) => {
+    try {
+      const c = await cfg(args.workspace_id);
+      return text(
+        await listFlags(c.apiUrl, c.workspaceId, args.environment_id)
+      );
+    } catch (e) {
+      return errText(e);
+    }
+  }
+);
 server.tool(
   "files_list",
   "List workspace files (read-only). Upload/download with `gf files`.",
@@ -1674,7 +1839,7 @@ server.tool(
 );
 server.tool(
   "dataplane_status",
-  "Dataplane setup status (Dataplane is how Groundfloor talks to databases, not a database itself). Postgres (shared, platform-managed) is ready through it by default; ArangoDB is also ready. Provision with `gf dataplane provision`.",
+  "Dataplane setup status (Dataplane is how Groundfloor talks to databases, not a database itself). PostgreSQL (shared, platform-managed) is ready through it by default. Provision with `gf dataplane provision`.",
   { workspace_id: wsId },
   async ({ workspace_id }) => {
     try {
@@ -1744,6 +1909,7 @@ server.tool(
       "init_app",
       "publish_app",
       "secrets",
+      "flags",
       "dataplane",
       "vault_token",
       "m2m_token"

package/package.json

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