@groundfloorcloud/mcp 0.1.2 → 0.1.4

package/README.md

@@ -67,18 +67,22 @@ 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 (`coderunner` returns the full type/auth/Dockerfile guide) |
+| `docs_list` / `docs_get` | Product docs (`coderunner`, `coderunner-runtime`, 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
+- 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`)
 
 `workspace_context` includes a `coderunner_howto` summary so agents see this

package/dist/index.js

@@ -380,6 +380,71 @@ async function resolveMcpConfig(overrides) {
   return { apiUrl, workspaceId, token };
 }
 
+// src/coderunner-runtime.ts
+var CODERUNNER_RUNTIME_BODY = `
+When a ZIP has **no Dockerfile**, Coderunner injects a language bootstrap image.
+Your process must match that image \u2014 \`gf deploy\` checks the Node bits before
+upload. A custom Dockerfile (required for \`service\` / Deployment) replaces
+the bootstrap; the listen/bind rules still apply.
+
+## Node (no Dockerfile)
+
+Bootstrap is effectively:
+
+\`\`\`dockerfile
+FROM node:18-alpine
+WORKDIR /app
+COPY . .
+EXPOSE 8080
+ENV PORT=8080
+CMD ["npm", "start"]
+\`\`\`
+
+1. \`package.json\` **must** define \`"scripts": { "start": "node <entrypoint>" }\`.
+   Missing \`start\` \u2192 container crash loop, probe \`127.0.0.1:8080\` connection
+   refused, deployment **Failed (status 4)** after several minutes.
+2. Listen on \`Number(process.env.PORT || 8080)\`.
+3. Bind **\`0.0.0.0\`**, not \`127.0.0.1\`. Cluster traffic is not loopback.
+
+\`\`\`js
+const port = Number(process.env.PORT || 8080);
+server.listen(port, "0.0.0.0", () => {
+  console.log(\`listening on 0.0.0.0:\${port}\`);
+});
+\`\`\`
+
+Offer GET \`/\` or \`/health\` for the probe. Sample: \`samples/hello-fn/\`.
+
+## Node (with Dockerfile)
+
+You own \`CMD\`. If it is \`npm start\`, you still need \`scripts.start\`.
+Listen on 8080 / \`PORT\` and bind \`0.0.0.0\`. \`service\` (Deployment)
+**requires** a root Dockerfile \u2014 bootstrap is not injected on that path.
+
+## Python
+
+Bind \`0.0.0.0\` and \`PORT\` (default 8080), for example
+\`uvicorn main:app --host 0.0.0.0 --port \${PORT:-8080}\`.
+
+## Jobs and schedules
+
+Same package/start rules. The process may exit 0 when finished; it does not
+need a public URL. Schedules have **no** Deployment URL.
+
+## What \`gf deploy\` checks
+
+- \`service\` without a root Dockerfile \u2192 fail immediately.
+- Node without a Dockerfile (or a Dockerfile that runs \`npm start\`) and no
+  \`scripts.start\` \u2192 fail immediately with this contract.
+- Listen/bind are not parsed from source; match the sample or the probe fails
+  at deploy time. Check Process Log / \`gf coderunner logs -c <id>\`.
+`.trim();
+var CODERUNNER_RUNTIME_CONTRACT = `
+# Runtime contract
+
+${CODERUNNER_RUNTIME_BODY}
+`.trim();
+
 // src/coderunner-guide.ts
 var CODERUNNER_GUIDE = `
 # Coderunner workloads
@@ -391,6 +456,12 @@ 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.
 
+## Runtime contract
+
+${CODERUNNER_RUNTIME_BODY}
+
+Also \`docs_get\` id \`coderunner-runtime\`.
+
 ## Prerequisites (do these before create/deploy)
 
 1. **Workspace Authentication is required** before creating a coderunner.
@@ -421,7 +492,7 @@ 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\`).
+- Listen on \`process.env.PORT || 8080\`, bind **\`0.0.0.0\`** (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)**.
@@ -467,8 +538,9 @@ CMD ["npm", "start"]
   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).
+  \`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>\`.
 - 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.
@@ -513,10 +585,44 @@ When the handler looks right locally, \`gf deploy\` the same tree.
 
 ## Agent actions
 
-Inspect: \`workspace_context\`, \`docs_get\` id \`coderunner\`, \`suggest_cli\`.
+Inspect: \`workspace_context\`, \`docs_get\` id \`coderunner\` or \`coderunner-runtime\`, \`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 = [
@@ -524,7 +630,7 @@ 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."
+    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",
@@ -536,9 +642,16 @@ var DOC_CATALOG = [
     id: "coderunner",
     title: "Coderunner",
     path: "/docs/customer-portal/coderunner",
-    summary: "Workload types (function, job, schedule, service/Deployment), 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, Authentication before create, local live data, gf deploy.",
     embedded: CODERUNNER_GUIDE
   },
+  {
+    id: "coderunner-runtime",
+    title: "Coderunner runtime contract",
+    path: "/docs/customer-portal/coderunner",
+    summary: "What the platform expects your code to do: Node bootstrap (npm start, PORT/8080, bind 0.0.0.0), Python bind, service Dockerfile.",
+    embedded: CODERUNNER_RUNTIME_CONTRACT
+  },
   {
     id: "coderunner-overview",
     title: "Coderunner overview",
@@ -550,7 +663,7 @@ var DOC_CATALOG = [
     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."
+    summary: "Workspace site auth (Groundfloor or external) must be active before creating a Coderunner. Separate from portal Team."
   },
   {
     id: "api-authentication",
@@ -562,7 +675,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) {
@@ -633,7 +747,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). Node needs package.json scripts.start. 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 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":
@@ -648,18 +762,24 @@ function suggestCli(intent, args) {
         why: "Inspect build/deploy state.",
         docs: "https://docs.groundfloor.cloud/docs/customer-portal/coderunner"
       };
+    case "logs":
+      return {
+        command: name ? `gf coderunner logs -c ${name}${ws}` : `gf coderunner logs -c <id-or-slug>${ws}`,
+        why: "Process Log (stdout/stderr). gf deploy prints the last lines on failure; this command fetches more. runner_id accepts a coderunner id.",
+        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.",
+        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":
@@ -721,7 +841,7 @@ async function resolveCoderunnerId(apiUrl, workspaceId, idOrSlug) {
 }
 var server = new McpServer({
   name: "groundfloor",
-  version: "0.1.0"
+  version: "0.1.4"
 });
 server.tool(
   "whoami",
@@ -748,7 +868,7 @@ server.tool(
 );
 server.tool(
   "workspace_context",
-  "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.",
+  "Live context for the selected workspace: session, coderunners, apps, dataplane, suggested gf commands, and Coderunner type/auth/Dockerfile/runtime-contract rules. Use docs_get id coderunner (or coderunner-runtime) before deploying.",
   { workspace_id: wsId },
   async ({ workspace_id }) => {
     try {
@@ -781,20 +901,29 @@ server.tool(
         dataplane,
         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.",
           types: {
-            function: "HTTP handler on PORT/8080. Invoke with gf coderunner run or the Deployment URL. Node requires package.json scripts.start.",
+            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.",
             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."
+            service: "Long-running Deployment (same type as service). Dockerfile at ZIP root is required. Listen on 8080 / 0.0.0.0."
           },
-          node: 'Bootstrap image uses CMD ["npm","start"]. Missing scripts.start \u2192 deploy Failed (status 4), 8080 connection refused.',
+          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.'
         },
+        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"),
+          logs: suggestCli("logs"),
+          init_app: suggestCli("init_app"),
+          publish_app: suggestCli("publish_app")
         },
         docs: DOC_CATALOG.map((d) => ({
           id: d.id,
@@ -870,7 +999,7 @@ server.tool(
 );
 server.tool(
   "coderunner_get_logs",
-  "Fetch logs for a job id from a previous `gf coderunner run`.",
+  "Job-run logs from a previous `gf coderunner run` (needs job_id). For deploy/build stdout use suggest_cli intent logs (`gf coderunner logs`).",
   {
     workspace_id: wsId,
     coderunner_id: z.string().min(1),
@@ -998,10 +1127,10 @@ server.tool(
 );
 server.tool(
   "docs_get",
-  "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.",
+  "How-to for Coderunner types, runtime contract (scripts.start, 0.0.0.0:8080), Dockerfile, Authentication, local live data, gf CLI, Shell. Pass id from docs_list. Prefer id coderunner or coderunner-runtime before deploying.",
   {
     id: z.string().min(1).describe(
-      "Catalog id, e.g. coderunner | coderunner-overview | agents | developers | authentication | api-authentication | shell"
+      "Catalog id, e.g. coderunner | coderunner-runtime | coderunner-overview | agents | developers | authentication | api-authentication | shell"
     )
   },
   async ({ id }) => {
@@ -1022,7 +1151,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",
@@ -1030,13 +1159,14 @@ server.tool(
       "deploy",
       "run",
       "status",
+      "logs",
       "init_app",
       "publish_app",
       "secrets",
       "dataplane"
     ]),
     workspace: z.string().optional(),
-    name: z.string().optional().describe("Coderunner name/id for deploy/run/status"),
+    name: z.string().optional().describe("Coderunner name/id for deploy/run/status/logs"),
     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.2",
+  "version": "0.1.4",
   "description": "Groundfloor MCP — inspect workspace state and docs; take actions with the gf CLI.",
   "type": "module",
   "bin": {