@groundfloorcloud/mcp 0.1.7 → 0.1.8

package/README.md

@@ -74,8 +74,8 @@ The `command` must be your Node (from `which node`), not `npx` and not Cursor’
 | `coderunner_cancel_deployment` | Delete current (or given) deployment |
 | `apps_list` / `apps_get` | Inspect product Apps |
 | `secrets_list` / `files_list` / `domains_list` / `dataplane_status` | Inspect (no secrets values) |
-| `docs_list` / `docs_get` | Product docs (`coderunner`, `shell`, `design-standard`, `css-and-styling`, `databases` are embedded how-tos) |
-| `suggest_cli` | Command to run: login, deploy, init_app, publish_app, … |
+| `docs_list` / `docs_get` | Product docs (`coderunner`, `shell`, `design-standard`, `css-and-styling`, `databases` are embedded; `access` and `m2m` are live pages) |
+| `suggest_cli` | Command to run: login, deploy, init_app, publish_app, m2m_token, … |
 
 Never create `app_kind=coderunner`. Deploy with `gf deploy`.
 
@@ -91,10 +91,10 @@ is ready through Dataplane; Postgres is what you can deploy today.
 `coderunner-overview`). That page covers:
 
 - Types: `function`, `job`, `schedule`, `service` (**also called Deployment**)
-- **Authentication must be active** before creating a coderunner
+- App authentication is optional (end-user login); not required to create a coderunner
 - **Dockerfile is required** for `service` / Deployment
 - Runtime contract: Node `scripts.start`, listen on `PORT`/8080, bind `0.0.0.0` (`docs_get` id `coderunner-runtime`)
-- Local development against live vault/files/secrets (`gf env` + `gf token`)
+- Local development against live vault/files/secrets (`gf env`; as the workload use `gf m2m token`, not `gf token`)
 
 `workspace_context` includes a `coderunner_howto` summary so agents see this
 without an extra fetch.

package/dist/index.js

@@ -169,11 +169,31 @@ var CpError = class extends Error {
   }
   status;
 };
+function formatCpErrorDetail(detail, fallback) {
+  if (typeof detail === "string" && detail.trim()) return detail.trim();
+  if (detail && typeof detail === "object") {
+    const obj = detail;
+    if (typeof obj.message === "string" && obj.message.trim()) {
+      return obj.message.trim();
+    }
+    if (typeof obj.detail === "string" && obj.detail.trim()) {
+      return obj.detail.trim();
+    }
+    try {
+      return JSON.stringify(detail);
+    } catch {
+      return fallback;
+    }
+  }
+  return fallback;
+}
 async function parseError(res) {
   let detail = res.statusText;
   try {
     const body = await res.json();
-    if (body?.detail) detail = String(body.detail);
+    if (body?.detail !== void 0) {
+      detail = formatCpErrorDetail(body.detail, res.statusText);
+    }
   } catch {
   }
   return `${res.status} ${detail}`;
@@ -504,13 +524,11 @@ Also \`docs_get\` id \`coderunner-runtime\`.
 
 ## Prerequisites (do these before create/deploy)
 
-1. **Workspace Authentication is required** before creating a coderunner.
-   Portal \u2192 Administer \u2192 Authentication \u2192 set mode to \`groundfloor\` (or
-   \`external\` with an issuer) and wait until the realm is **active**.
-   Code Runner JWTs use the workspace site issuer. Mode \`none\` cannot mint
-   that token \u2014 create/deploy fails with "requires the workspace site issuer".
-2. \`gf login\` (\`--stage\` / \`--dev\` as needed) and \`gf workspaces use <uuid>\`.
-3. Dataplane for vault/files/secrets: \`gf dataplane provision\` if those APIs
+1. \`gf login\` (\`--stage\` / \`--dev\` as needed) and \`gf workspaces use <uuid>\`.
+   Team **write** can create Coderunners without App authentication. Site auth
+   (Groundfloor/external) is only for end-user login. Mode \`none\` mints
+   management JWTs against Portal JWKS (\`GET /v1/public/jwks.json\`).
+2. Dataplane for vault/files: \`gf dataplane provision\` if those APIs
    are needed (local live data or the deployed workload).
 
 ## Workload types
@@ -613,21 +631,41 @@ curl -sS -X POST http://127.0.0.1:8080/ -H 'Content-Type: application/json' \\
 
 Live vault / files / secrets from the laptop:
 
+\`gf token\` is a **builder** credential. Use it for operator Vault. To call
+Vault and Files as a Coderunner does, use an M2M client and \`gf m2m token\`.
+
 \`\`\`bash
+# Builder token:
 curl -sS -H "Authorization: Bearer $(gf token)" \\
   "$CONTROLPLANE_URL/v1/workspaces/$GROUNDFLOOR_WORKSPACE_ID/vault/collections"
+
+# M2M (same class as an attached Coderunner):
+curl -sS -H "Authorization: Bearer $(gf m2m token)" \\
+  "$CONTROLPLANE_URL/v1/workspaces/$GROUNDFLOOR_WORKSPACE_ID/vault/collections"
+curl -sS -H "Authorization: Bearer $(gf m2m token)" \\
+  "$CONTROLPLANE_URL/v1/workspaces/$GROUNDFLOOR_WORKSPACE_ID/files"
 \`\`\`
 
-In app code, use \`CONTROLPLANE_URL\` + Bearer (\`gf token\` locally;
-injected env / workspace secrets after \`gf deploy\`). Never put
-\`DATAPLANE_SERVICE_API_KEY\` in a browser bundle.
+In app code, use \`CONTROLPLANE_URL\` + Bearer from
+\`POST \u2026/m2m/token\` (\`gf m2m token\` locally; injected
+\`GROUNDFLOOR_M2M_CLIENT_ID\` / \`GROUNDFLOOR_M2M_CLIENT_SECRET\` after
+\`gf deploy\`). Never put \`DATAPLANE_SERVICE_API_KEY\` in a browser bundle
+or customer env.
 
 When the handler looks right locally, \`gf deploy\` the same tree.
 
+## M2M tokens (Vault and Files)
+
+New Coderunners cannot call Vault or Files until an M2M client is attached
+and the workload is redeployed. Create the client in Portal **Administer \u2192
+M2M tokens**, attach it on the Coderunner card, then deploy. v1 M2M is Team
+Writer on that workspace (full Vault skip-ACL + Files). Grant site users on
+**Administer \u2192 Access**. Never inject a Dataplane key.
+
 ## Agent actions
 
 Inspect: \`workspace_context\`, \`docs_get\` id \`coderunner\` or \`coderunner-runtime\`, \`suggest_cli\`.
-Act: \`gf deploy\`, \`gf coderunner run|status\`. MCP does not deploy.
+Act: \`gf deploy\`, \`gf coderunner run|status\`, \`gf m2m token\`. MCP does not deploy.
 `.trim();
 
 // src/css-and-styling-guide.ts
@@ -771,8 +809,9 @@ gf apps publish --path release.zip
 \`\`\`
 
 \`npm run release\` packs **all** of dist/assets (remoteEntry.js + hashed
-\`__federation_*.js\` + CSS) at the zip root. Do not zip \`dist/\`. Do not
-upload a lone \`remoteEntry.js\`. \`gf apps publish\` rejects incomplete zips.
+\`__federation_*.js\` + CSS) at the zip root and rewrites \`./assets/\` imports
+in remoteEntry.js. Do not zip \`dist/\`. Do not upload a lone \`remoteEntry.js\`.
+\`gf apps publish\` rejects incomplete zips.
 
 Production builds use Vite \`base: './'\` so imported images resolve next to
 remoteEntry.js. Header logos: manifest \`theme.logoUrl\` (absolute https).
@@ -796,19 +835,19 @@ var DOC_CATALOG = [
     id: "agents",
     title: "Deploy with agents",
     path: "/docs/customer-portal/agents",
-    summary: "How agents should deploy Coderunner workloads and init/publish Shell apps with gf / MCP. Enable workspace Authentication before create. Service (Deployment) requires a Dockerfile. Shell apps: gf apps init, never invent App.tsx."
+    summary: "How agents should deploy Coderunner workloads and init/publish Shell apps with gf / MCP. App authentication is optional (end-user login). Service (Deployment) requires a Dockerfile. Shell apps: gf apps init, never invent App.tsx."
   },
   {
     id: "developers",
     title: "Developers (gf CLI)",
     path: "/docs/customer-portal/developers",
-    summary: "gf login, workspaces, deploy, secrets, files, apps. Coderunner types: function, job, schedule, service (also called Deployment)."
+    summary: "gf login, workspaces, deploy, secrets, files, apps, gf m2m token. Coderunner types: function, job, schedule, service (also called Deployment). App authentication optional."
   },
   {
     id: "coderunner",
     title: "Coderunner",
     path: "/docs/customer-portal/coderunner",
-    summary: "Workload types (function, job, schedule, service/Deployment), runtime contract (scripts.start, 0.0.0.0:8080), Dockerfile for services, Authentication before create, local live data, gf deploy.",
+    summary: "Workload types (function, job, schedule, service/Deployment), runtime contract (scripts.start, 0.0.0.0:8080), Dockerfile for services, Coderunner identities for Vault, App authentication optional, local live data, gf deploy.",
     embedded: CODERUNNER_GUIDE
   },
   {
@@ -822,14 +861,26 @@ var DOC_CATALOG = [
     id: "coderunner-overview",
     title: "Coderunner overview",
     path: "/docs/integrations/coderunner/overview",
-    summary: "Architecture and lifecycle. Prefer docs_get id coderunner for type usage, Dockerfile, and auth prerequisites.",
+    summary: "Architecture and lifecycle. Prefer docs_get id coderunner for type usage, Dockerfile, and create prerequisites.",
     embedded: CODERUNNER_GUIDE
   },
   {
     id: "authentication",
     title: "Workspace Authentication",
     path: "/docs/customer-portal/authentication",
-    summary: "Workspace site auth (Groundfloor or external) must be active before creating a Coderunner. Separate from portal Team."
+    summary: "Workspace site auth (Groundfloor or external) is optional end-user login. Leaving Groundfloor keeps the realm (disabled) until Delete Groundfloor login. Separate from portal Team. Not required to create Apps or Coderunners."
+  },
+  {
+    id: "access",
+    title: "Access",
+    path: "/docs/customer-portal/access",
+    summary: "Grant site roles Data Vault collections, workspace-wide Files, and Apps launch. Admin is implicit. M2M is not an Access subject. Team membership is unchanged."
+  },
+  {
+    id: "m2m",
+    title: "M2M tokens",
+    path: "/docs/customer-portal/m2m-tokens",
+    summary: "Confidential client secret \u2192 short Control Plane JWT (typ=m2m). Attach on Coderunner or gf m2m token. Never DATAPLANE_SERVICE_API_KEY. v1 is Team Writer, no collection ACL."
   },
   {
     id: "api-authentication",
@@ -934,7 +985,7 @@ function suggestCli(intent, args) {
     case "deploy":
       return {
         command: name ? `gf deploy -n ${name}${ws}` : `gf deploy${ws}`,
-        why: 'Package the current (or --path) folder and deploy as a Coderunner. Workspace Authentication (groundfloor/external) must already be active. workloadType function|job|schedule|service (service = Deployment; requires a Dockerfile). Schedules need --schedule "<cron>" or groundfloor.json schedule. Node bootstrap: scripts.start, listen PORT||8080, bind 0.0.0.0. Do not create an App for this.',
+        why: 'Package the current (or --path) folder and deploy as a Coderunner. App authentication is optional (end-user login only). workloadType function|job|schedule|service (service = Deployment; requires a Dockerfile). Schedules need --schedule "<cron>" or groundfloor.json schedule. Node bootstrap: scripts.start, listen PORT||8080, bind 0.0.0.0. Do not create an App for this.',
         docs: "https://docs.groundfloor.cloud/docs/customer-portal/coderunner"
       };
     case "run":
@@ -993,10 +1044,17 @@ function suggestCli(intent, args) {
         why: "Dataplane is required for vault, files, and secrets.",
         docs: "https://docs.groundfloor.cloud/docs/customer-portal/developers"
       };
+    case "vault_token":
+    case "m2m_token":
+      return {
+        command: `gf m2m token${ws}`,
+        why: "Exchange GROUNDFLOOR_M2M_CLIENT_ID + GROUNDFLOOR_M2M_CLIENT_SECRET for a short Control Plane JWT. Call Vault and Files at $CONTROLPLANE_URL. Never DATAPLANE_SERVICE_API_KEY. gf token is a builder credential.",
+        docs: "https://docs.groundfloor.cloud/docs/customer-portal/m2m-tokens"
+      };
     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.`,
+        why: `Unknown intent "${intent}". Use login | switch_workspace | deploy | run | status | logs | environments | cancel_deployment | init_app | publish_app | secrets | dataplane | vault_token.`,
         docs: "https://docs.groundfloor.cloud/docs/customer-portal/developers"
       };
   }
@@ -1101,7 +1159,7 @@ server.tool(
         coderunner_howto: {
           docs_get: "coderunner",
           runtime_contract: "coderunner-runtime",
-          before_create: "Enable Administer \u2192 Authentication (mode groundfloor or external, realm active). Mode none cannot mint a Code Runner JWT.",
+          before_create: "Team write can create Coderunners without App authentication. Site auth is optional (end-user login). Mode none uses Portal JWKS (GET /v1/public/jwks.json).",
           types: {
             function: "HTTP handler on PORT/8080 bound to 0.0.0.0. Invoke with gf coderunner run or the Deployment URL. Node requires package.json scripts.start.",
             job: "Run-to-completion worker. Deploy, then gf coderunner run.",
@@ -1109,7 +1167,7 @@ server.tool(
             service: "Long-running Deployment (same type as service). Dockerfile at ZIP root is required. Listen on 8080 / 0.0.0.0."
           },
           node: "No Dockerfile \u2192 platform injects node:18-alpine CMD npm start EXPOSE 8080. Require scripts.start; listen on PORT||8080; bind 0.0.0.0. gf deploy fails fast if scripts.start is missing.",
-          local_live_data: 'eval "$(gf env)" then call Control Plane vault/files/secrets with Bearer $(gf token). Do not zip .env files.'
+          local_live_data: 'eval "$(gf env)". For files/secrets as a builder use Bearer $(gf token). For Vault/Files as the deployed workload, attach an M2M client and use Bearer $(gf m2m token). Never DATAPLANE_SERVICE_API_KEY. Do not zip .env files.'
         },
         shell_app_howto: {
           docs_get: "shell",
@@ -1132,6 +1190,7 @@ server.tool(
           logs: suggestCli("logs"),
           environments: suggestCli("environments"),
           cancel_deployment: suggestCli("cancel_deployment"),
+          vault_token: suggestCli("m2m_token"),
           init_app: suggestCli("init_app"),
           publish_app: suggestCli("publish_app")
         },
@@ -1430,10 +1489,10 @@ server.tool(
 );
 server.tool(
   "docs_get",
-  "How-to for Coderunner, Shell, design-standard, css-and-styling, databases. Pass id from docs_list. Prefer id coderunner or coderunner-runtime before deploying. For data work use id databases. For own CSS framework use id css-and-styling.",
+  "How-to for Coderunner, Shell, design-standard, css-and-styling, databases, access, m2m. 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"
+      "Catalog id, e.g. coderunner | coderunner-runtime | shell | design-standard | css-and-styling | databases | agents | developers | authentication | access | m2m"
     )
   },
   async ({ id }) => {
@@ -1468,10 +1527,12 @@ server.tool(
       "init_app",
       "publish_app",
       "secrets",
-      "dataplane"
+      "dataplane",
+      "vault_token",
+      "m2m_token"
     ]),
     workspace: z.string().optional(),
-    name: z.string().optional().describe("Coderunner name/id for deploy/run/status/logs/cancel_deployment"),
+    name: z.string().optional().describe("Coderunner name/id for deploy/run/status/logs/cancel_deployment/vault_token"),
     slug: z.string().optional().describe("Portal app slug for init_app / publish_app"),
     cell: z.enum(["production", "stage", "dev"]).optional()
   },

package/package.json

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