@groundfloorcloud/mcp 0.1.1 → 0.1.3

package/README.md

@@ -67,11 +67,27 @@ The `command` must be your Node (from `which node`), not `npx` and not Cursor’
 | `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 |
+| `docs_list` / `docs_get` | Product docs (`coderunner` and `shell` are embedded how-tos) |
 | `suggest_cli` | Command to run: login, deploy, init_app, publish_app, … |
 
 Never create `app_kind=coderunner`. Deploy with `gf deploy`.
 
+**Shell apps:** `docs_get` id `shell`. Always `gf apps init --slug <portal-slug>`,
+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`.
+
+**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

@@ -380,6 +380,177 @@ 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/shell-guide.ts
+var SHELL_APP_GUIDE = `
+# Shell federated apps
+
+A Groundfloor **App** (app_kind=shell_federated) is a Module Federation remote
+loaded by the workspace Shell. It is **not** a Coderunner. Do not \`gf deploy\`.
+
+## Required path (do not invent a Vite app)
+
+Agents must not scaffold App.tsx, vite.config.ts, or BrowserRouter from memory.
+A from-scratch remote 404s in Shell (missing sibling chunks) or crashes
+(extra Router). Federation \`name\` must be federationRemoteName(slug)
+(\`hello-world\` \u2192 \`hello_world\`).
+
+\`\`\`bash
+gf apps create --name "Hello World" --slug hello-world --kind shell_federated
+gf apps init --slug hello-world
+cd hello-world
+npm install
+# edit src/ inside the kit only
+npm run release
+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.
+
+## suggest_cli
+
+- init_app \u2192 \`gf apps init --slug <portal-slug>\`
+- publish_app \u2192 init + npm install + npm run release + gf apps publish --path release.zip
+`;
+
 // src/docs.ts
 var DOCS_ORIGIN = "https://docs.groundfloor.cloud";
 var DOC_CATALOG = [
@@ -387,22 +558,36 @@ 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."
+    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."
   },
   {
     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."
@@ -411,7 +596,8 @@ var DOC_CATALOG = [
     id: "shell",
     title: "Shell federated apps",
     path: "/docs/integrations/shell",
-    summary: "Product Apps vs Coderunner deploy."
+    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
   }
 ];
 function docUrl(entry) {
@@ -421,7 +607,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));
   });
 }
@@ -432,6 +618,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"
@@ -444,7 +639,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
@@ -467,7 +668,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":
@@ -486,14 +687,14 @@ function suggestCli(intent, args) {
       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.",
+        why: "Download the official Shell starter-kit and stamp APP_ID. Never scaffold vite.config / App.tsx from memory. Never wrap App in BrowserRouter. Never zip dist/ or upload only remoteEntry.js.",
         docs: "https://docs.groundfloor.cloud/docs/integrations/shell"
       };
     }
     case "publish_app":
       return {
         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.",
+        why: "Ship a Shell federated App. Always init the kit first. npm run release (not zip dist/, not a lone remoteEntry.js). Do not gf deploy. Do not invent App.tsx.",
         docs: "https://docs.groundfloor.cloud/docs/integrations/shell"
       };
     case "secrets":
@@ -555,7 +756,7 @@ async function resolveCoderunnerId(apiUrl, workspaceId, idOrSlug) {
 }
 var server = new McpServer({
   name: "groundfloor",
-  version: "0.1.0"
+  version: "0.1.3"
 });
 server.tool(
   "whoami",
@@ -582,7 +783,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 {
@@ -613,15 +814,35 @@ 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.'
+        },
+        shell_app_howto: {
+          docs_get: "shell",
+          rule: "Never invent a Vite + Module Federation app. gf apps init --slug <portal-slug>, npm install, npm run release, gf apps publish --path release.zip. Do not zip dist/ or upload only remoteEntry.js.",
+          suggest_cli: "init_app | publish_app"
+        },
         actions: {
           deploy: suggestCli("deploy"),
           switch_workspace: suggestCli("switch_workspace"),
-          run: suggestCli("run")
+          run: suggestCli("run"),
+          init_app: suggestCli("init_app"),
+          publish_app: suggestCli("publish_app")
         },
         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) {
@@ -819,9 +1040,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 {
@@ -841,7 +1064,7 @@ server.tool(
 );
 server.tool(
   "suggest_cli",
-  "Return the gf command the developer (or agent terminal) should run. MCP does not execute mutations.",
+  "Return the gf command to run. For a Shell App use intent init_app or publish_app (never scaffold App.tsx; never gf deploy). MCP does not execute mutations.",
   {
     intent: z.enum([
       "login",

package/package.json

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