@groundfloorcloud/mcp 0.1.0 → 0.1.2

package/README.md

@@ -22,6 +22,8 @@ Switch workspace: `gf workspaces use <uuid>` (then MCP sees it). Expired session
 
 `gf` must be on `PATH` and you must have run `gf login` (and usually `gf workspaces use`).
 
+Clients that spawn a real Node (Claude Code, some IDEs) can use:
+
 ```json
 {
   "mcpServers": {
@@ -33,7 +35,28 @@ Switch workspace: `gf workspaces use <uuid>` (then MCP sees it). Expired session
 }
 ```
 
-Optional: `"GROUNDFLOOR_API_URL"` only if you are not using the cell from `gf login`. Do not put a JWT in mcp.json.
+**Cursor on macOS:** do not use bare `npx`. Cursor runs npm with its bundled Node, which then looks for `Cursor.app/.../resources/lib` and fails with `ENOENT`. Install the package with *your* Node, then point MCP at that binary:
+
+```bash
+npm i -g @groundfloorcloud/mcp
+which node
+# → /Users/you/.nvm/versions/node/v20.x.x/bin/node
+```
+
+```json
+{
+  "mcpServers": {
+    "groundfloor": {
+      "command": "/FULL/PATH/TO/node",
+      "args": [
+        "/FULL/PATH/TO/lib/node_modules/@groundfloorcloud/mcp/dist/index.js"
+      ]
+    }
+  }
+}
+```
+
+The `command` must be your Node (from `which node`), not `npx` and not Cursor’s helper Node. Do not put a JWT in mcp.json.
 
 ## Tools
 
@@ -44,11 +67,23 @@ Optional: `"GROUNDFLOOR_API_URL"` only if you are not using the cell from `gf lo
 | `coderunner_list` / `_get_status` / `_get_logs` | Inspect workloads |
 | `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 |
-| `suggest_cli` | Command to run: login, deploy, run, … |
+| `docs_list` / `docs_get` | Product docs (`coderunner` returns the full type/auth/Dockerfile guide) |
+| `suggest_cli` | Command to run: login, deploy, init_app, publish_app, … |
 
 Never create `app_kind=coderunner`. Deploy with `gf deploy`.
 
+**Coderunner how-to** is embedded: `docs_get` id `coderunner` (also
+`coderunner-overview`). That page covers:
+
+- Types: `function`, `job`, `schedule`, `service` (**also called Deployment**)
+- **Authentication must be active** before creating a coderunner
+- **Dockerfile is required** for `service` / Deployment
+- Node `scripts.start` + listen on 8080
+- Local development against live vault/files/secrets (`gf env` + `gf token`)
+
+`workspace_context` includes a `coderunner_howto` summary so agents see this
+without an extra fetch.
+
 ## Build (from this repo)
 
 ```bash

package/dist/index.js

@@ -296,17 +296,20 @@ var CELLS = {
   production: {
     apiUrl: "https://platform.groundfloor.cloud",
     issuer: "https://auth.groundfloor.cloud/realms/groundfloor",
-    clientId: "groundfloor-cli"
+    clientId: "groundfloor-cli",
+    consoleUrl: "https://console.groundfloor.cloud"
   },
   stage: {
     apiUrl: "https://platform.stage.groundfloor.cloud",
     issuer: "https://auth.stage.groundfloor.cloud/realms/groundfloor_pico_stage-realm",
-    clientId: "groundfloor-cli"
+    clientId: "groundfloor-cli",
+    consoleUrl: "https://console.stage.groundfloor.cloud"
   },
   dev: {
     apiUrl: "https://platform.dev.groundfloor.cloud",
     issuer: "https://auth.dev.groundfloor.cloud/realms/groundfloor_dev",
-    clientId: "groundfloor-cli"
+    clientId: "groundfloor-cli",
+    consoleUrl: "https://console.dev.groundfloor.cloud"
   }
 };
 function inferCell(apiUrl, issuer) {
@@ -377,6 +380,143 @@ async function resolveMcpConfig(overrides) {
   return { apiUrl, workspaceId, token };
 }
 
+// src/coderunner-guide.ts
+var CODERUNNER_GUIDE = `
+# Coderunner workloads
+
+Coderunner is Groundfloor's **apps runtime**. Deploy Node.js, Python, .NET, and
+other workloads as **functions**, **jobs**, **schedules**, or **services**.
+The Customer Portal, \`gf\` CLI, and this MCP all drive the same lifecycle.
+
+Do **not** create an App to run code. \`POST \u2026/apps\` with \`app_kind=coderunner\`
+is rejected. Optional Apps are Shell / product packaging only.
+
+## 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
+   are needed (local live data or the deployed workload).
+
+## Workload types
+
+Portal \`workload_type\` (CLI \`--workload-type\` / \`groundfloor.json\`
+\`workloadType\`) maps to upstream \`deploymentType\`. **Service and Deployment
+are the same type** \u2014 portal id \`service\`, UI often says Deployment,
+upstream \`deploymentType=4\`.
+
+| Portal id | Also called | Upstream | When to use | How it runs |
+|-----------|-------------|----------|-------------|-------------|
+| \`function\` | Function | 1 | Request/response HTTP handler (webhooks, APIs, agent invoke) | Scale-to-zero Knative. Invoke via Run or Deployment URL. |
+| \`job\` | Background job | 2 | One-shot batch (import, report, backfill) | Run-to-completion. Deploy, then \`gf coderunner run\`. |
+| \`schedule\` | Scheduled job | 3 | Cron (reminders, sync) | Same as job, plus cron. **No** public Deployment URL. |
+| \`service\` | **Deployment** | 4 | Long-running HTTP process (web app, always-on API) | Stays up (replicas). Public Deployment URL. Custom domains when App-bound. |
+
+Pick **one** type per coderunner. Changing type later means a new coderunner.
+
+### Function
+
+- ZIP at archive root (\`package.json\` / \`index.js\` or \`main.py\` not nested).
+- Listen on \`process.env.PORT || 8080\` (health GET \`/\` or \`/health\`).
+- **Node:** \`package.json\` **must** include \`"scripts": { "start": "node index.js" }\`.
+  The runtime image is \`CMD ["npm", "start"]\`. Missing \`start\` \u2192 crash loop,
+  probe \`127.0.0.1:8080\` connection refused, deployment **Failed (status 4)**.
+- Python: process must bind 0.0.0.0:\${PORT:-8080}.
+- After deploy: \`gf coderunner run -c <slug> --payload '{"hello":"world"}'\`.
+
+### Job
+
+- Same package rules as function. No need to serve forever; exit 0 on success.
+- Deploy, then start a run (\`gf coderunner run\`). Check Process Log.
+
+### Schedule
+
+- Same as job, plus a cron expression at create/deploy (\`schedule\` /
+  \`CronExpression\`).
+- No public invoke URL. Debug with Process Log, not curl.
+
+### Service (Deployment)
+
+- Long-running HTTP. **You must include a \`Dockerfile\` at the ZIP root.**
+  Kaniko builds with \`--dockerfile=Dockerfile\`. Language bootstrap does **not**
+  replace a missing Dockerfile for this type.
+- Dockerfile must expose and listen on **8080** (or \`PORT\`).
+- Node example:
+
+\`\`\`dockerfile
+FROM node:18-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --omit=dev
+COPY . .
+EXPOSE 8080
+ENV PORT=8080
+CMD ["npm", "start"]
+\`\`\`
+
+- Still require Node \`"start"\` if CMD is \`npm start\`.
+- Prefer curling the Deployment URL (\`/health\`) over \`\u2026/run\`.
+
+## Latest deploy rules (all types)
+
+- \`gf deploy\` from the project dir (or \`--path\` / \`--git\`). Creates the
+  coderunner if the slug is new; otherwise uploads a new version and deploys it.
+- Status: upload/build \`1\u20134\` (3=Completed, 4=Failed). Deployment \`1\u20137\`
+  (3=Deployed, 4=Failed). A templated \`deployment_url\` with empty
+  \`externalEndpoint\` and status 4 means the container never became ready \u2014
+  read Process Log (\`runner_id\` = deployment id).
+- 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.
+- Optional \`groundfloor.json\`: \`name\`, \`runtime\`, \`workloadType\`,
+  \`cpu\`, \`memory\`, \`env\`.
+
+## Local development with live workspace data
+
+Run the process on your laptop; call the **same** Control Plane + Dataplane
+the deployed coderunner uses. Do not copy production data into fixtures.
+
+\`\`\`bash
+gf login --stage          # or --dev / production
+gf workspaces use <uuid>
+eval "$(gf env)"          # GROUNDFLOOR_TOKEN, CONTROLPLANE_URL, GROUNDFLOOR_WORKSPACE_ID
+gf dataplane status       # provision if needed: gf dataplane provision
+gf secrets ls
+\`\`\`
+
+Local HTTP (Node function/service):
+
+\`\`\`bash
+export PORT=8080
+npm start                 # same entrypoint as production
+# other terminal:
+curl -sS -X POST http://127.0.0.1:8080/ -H 'Content-Type: application/json' \\
+  -d '{"hello":"local"}'
+\`\`\`
+
+Live vault / files / secrets from the laptop:
+
+\`\`\`bash
+curl -sS -H "Authorization: Bearer $(gf token)" \\
+  "$CONTROLPLANE_URL/v1/workspaces/$GROUNDFLOOR_WORKSPACE_ID/vault/collections"
+\`\`\`
+
+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.
+
+When the handler looks right locally, \`gf deploy\` the same tree.
+
+## Agent actions
+
+Inspect: \`workspace_context\`, \`docs_get\` id \`coderunner\`, \`suggest_cli\`.
+Act: \`gf deploy\`, \`gf coderunner run|status\`. MCP does not deploy.
+`.trim();
+
 // src/docs.ts
 var DOCS_ORIGIN = "https://docs.groundfloor.cloud";
 var DOC_CATALOG = [
@@ -384,22 +524,36 @@ var DOC_CATALOG = [
     id: "agents",
     title: "Deploy with agents",
     path: "/docs/customer-portal/agents",
-    summary: "How agents should deploy Coderunner workloads with gf / MCP."
+    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."
   },
   {
     id: "developers",
     title: "Developers (gf CLI)",
     path: "/docs/customer-portal/developers",
-    summary: "gf login, workspaces, deploy, secrets, files, apps."
+    summary: "gf login, workspaces, deploy, secrets, files, apps. Coderunner types: function, job, schedule, service (also called Deployment)."
   },
   {
     id: "coderunner",
     title: "Coderunner",
     path: "/docs/customer-portal/coderunner",
-    summary: "Functions, jobs, schedules, services \u2014 not Apps."
+    summary: "Workload types (function, job, schedule, service/Deployment), Dockerfile for services, Authentication before create, local live data, gf deploy.",
+    embedded: CODERUNNER_GUIDE
+  },
+  {
+    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.",
+    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 Members & Roles."
+  },
+  {
+    id: "api-authentication",
     title: "API authentication",
     path: "/docs/api/authentication",
     summary: "Control Plane Bearer tokens and workspace identity."
@@ -418,7 +572,7 @@ function findDoc(query) {
   const q = query.trim().toLowerCase();
   if (!q) return DOC_CATALOG;
   return DOC_CATALOG.filter((d) => {
-    const hay = `${d.id} ${d.title} ${d.summary} ${d.path}`.toLowerCase();
+    const hay = `${d.id} ${d.title} ${d.summary} ${d.path} ${d.embedded ?? ""}`.toLowerCase();
     return q.split(/\s+/).every((part) => hay.includes(part));
   });
 }
@@ -429,6 +583,15 @@ function htmlToText(html) {
 var MAX_CHARS = 12e3;
 async function fetchDocPage(entry) {
   const url = docUrl(entry);
+  if (entry.embedded?.trim()) {
+    return {
+      url,
+      title: entry.title,
+      text: entry.embedded.trim(),
+      truncated: false,
+      source: "embedded"
+    };
+  }
   const res = await fetch(url, {
     headers: { Accept: "text/html", "User-Agent": "groundfloor-mcp/0.1" },
     redirect: "follow"
@@ -441,7 +604,13 @@ async function fetchDocPage(entry) {
   const truncated = body.length > MAX_CHARS;
   if (truncated) body = `${body.slice(0, MAX_CHARS)}
 \u2026`;
-  return { url, title: entry.title, text: body, truncated };
+  return {
+    url,
+    title: entry.title,
+    text: body,
+    truncated,
+    source: "docs.groundfloor.cloud"
+  };
 }
 
 // src/playbook.ts
@@ -464,7 +633,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. Do not create an App for this.",
+        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). Node needs package.json scripts.start. Do not create an App for this.",
         docs: "https://docs.groundfloor.cloud/docs/customer-portal/coderunner"
       };
     case "run":
@@ -479,10 +648,18 @@ function suggestCli(intent, args) {
         why: "Inspect build/deploy state.",
         docs: "https://docs.groundfloor.cloud/docs/customer-portal/coderunner"
       };
+    case "init_app": {
+      const slug = args?.slug?.trim();
+      return {
+        command: slug ? `gf apps init --slug ${slug}` : "gf apps init --slug <portal-slug>",
+        why: "Download the official Shell starter-kit and stamp APP_ID. Never scaffold a federated App.tsx from memory \u2014 BrowserRouter in App.tsx crashes the Shell.",
+        docs: "https://docs.groundfloor.cloud/docs/integrations/shell"
+      };
+    }
     case "publish_app":
       return {
-        command: "gf apps publish --path release.zip",
-        why: "Ship a Shell federated product App (not a Coderunner workload).",
+        command: args?.slug ? `gf apps init --slug ${args.slug} && cd ${args.slug} && npm install && npm run release && gf apps publish --path release.zip` : "gf apps init --slug <portal-slug> && cd <slug> && npm install && npm run release && gf apps publish --path release.zip",
+        why: "Ship a Shell federated product App. Init the starter-kit first; run npm run release (do not zip Vite dist/). Do not gf deploy and do not invent App.tsx.",
         docs: "https://docs.groundfloor.cloud/docs/integrations/shell"
       };
     case "secrets":
@@ -500,7 +677,7 @@ function suggestCli(intent, args) {
     default:
       return {
         command: "gf --help",
-        why: `Unknown intent "${intent}". Use login | switch_workspace | deploy | run | status | publish_app | secrets | dataplane.`,
+        why: `Unknown intent "${intent}". Use login | switch_workspace | deploy | run | status | init_app | publish_app | secrets | dataplane.`,
         docs: "https://docs.groundfloor.cloud/docs/customer-portal/developers"
       };
   }
@@ -571,7 +748,7 @@ server.tool(
 );
 server.tool(
   "workspace_context",
-  "Live context for the selected workspace: session, coderunners, apps, dataplane, and suggested gf commands. This is how the agent knows *what is here*; use docs_get for *how to do it*.",
+  "Live context for the selected workspace: session, coderunners, apps, dataplane, suggested gf commands, and Coderunner type/auth/Dockerfile rules. Use docs_get id coderunner for the full how-to.",
   { workspace_id: wsId },
   async ({ workspace_id }) => {
     try {
@@ -602,6 +779,18 @@ server.tool(
           status: app.status
         })),
         dataplane,
+        coderunner_howto: {
+          docs_get: "coderunner",
+          before_create: "Enable Administer \u2192 Authentication (mode groundfloor or external, realm active). Mode none cannot mint a Code Runner JWT.",
+          types: {
+            function: "HTTP handler on PORT/8080. 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.",
+            schedule: "Cron job. No public Deployment URL. Set schedule/cron at create or deploy.",
+            service: "Long-running Deployment (same type as service). Dockerfile at ZIP root is required. Listen on 8080."
+          },
+          node: 'Bootstrap image uses CMD ["npm","start"]. Missing scripts.start \u2192 deploy Failed (status 4), 8080 connection refused.',
+          local_live_data: 'eval "$(gf env)" then call Control Plane vault/files/secrets with Bearer $(gf token). Do not zip .env files.'
+        },
         actions: {
           deploy: suggestCli("deploy"),
           switch_workspace: suggestCli("switch_workspace"),
@@ -610,7 +799,8 @@ server.tool(
         docs: DOC_CATALOG.map((d) => ({
           id: d.id,
           title: d.title,
-          url: `https://docs.groundfloor.cloud${d.path}`
+          url: `https://docs.groundfloor.cloud${d.path}`,
+          summary: d.summary
         }))
       });
     } catch (e) {
@@ -808,9 +998,11 @@ server.tool(
 );
 server.tool(
   "docs_get",
-  "Fetch a product doc page from docs.groundfloor.cloud (how/when to use CLI). Pass id from docs_list (agents, developers, coderunner, authentication, shell).",
+  "How-to for Coderunner types, Dockerfile, Authentication, local live data, gf CLI, Shell. Pass id from docs_list (coderunner, coderunner-overview, agents, developers, authentication, api-authentication, shell). Prefer id coderunner before deploying.",
   {
-    id: z.string().min(1).describe("Catalog id, e.g. agents | developers | coderunner")
+    id: z.string().min(1).describe(
+      "Catalog id, e.g. coderunner | coderunner-overview | agents | developers | authentication | api-authentication | shell"
+    )
   },
   async ({ id }) => {
     try {
@@ -838,12 +1030,14 @@ server.tool(
       "deploy",
       "run",
       "status",
+      "init_app",
       "publish_app",
       "secrets",
       "dataplane"
     ]),
     workspace: z.string().optional(),
     name: z.string().optional().describe("Coderunner name/id for deploy/run/status"),
+    slug: z.string().optional().describe("Portal app slug for init_app / publish_app"),
     cell: z.enum(["production", "stage", "dev"]).optional()
   },
   async (args) => {
@@ -852,7 +1046,8 @@ server.tool(
         workspace: args.workspace ?? "",
         name: args.name ?? "",
         coderunner: args.name ?? "",
-        cell: args.cell ?? ""
+        cell: args.cell ?? "",
+        slug: args.slug ?? ""
       })
     );
   }

package/package.json

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