@groundfloorcloud/mcp 0.1.9 → 0.1.12

package/dist/index.js

@@ -473,6 +473,22 @@ server.listen(port, "0.0.0.0", () => {
 
 Offer GET \`/\` or \`/health\` for the probe. Sample: \`samples/hello-fn/\`.
 
+## Known issue: bootstrap has been reported to skip \`npm start\`
+
+Reported 2026-09-22 against a \`function\` deploy with no Dockerfile, **unresolved as of this
+writing**: instead of running \`npm start\` per the contract above, the platform's own
+\`/app/main.js\` ran \`require('./handler')\` \u2014 a file/module contract this document does not
+describe \u2014 even though \`scripts.start\` and the entrypoint were present and correct. Symptom in
+\`gf coderunner logs -c <id>\`: \`Cannot find module './handler'\` (\`MODULE_NOT_FOUND\`), repeated
+probe \`127.0.0.1:8080\` connection refused, deployment **Failed (status 4)**. Whether \`job\` and
+\`schedule\` share this bootstrap path and are equally affected has not been confirmed either way \u2014
+treat the workaround below as precautionary for those types too if you hit the same signature.
+
+**Workaround:** add your own root \`Dockerfile\` (e.g. \`CMD ["npm", "start"]\`) and keep your
+existing \`workload_type\` \u2014 a Dockerfile bypasses the injected bootstrap entirely regardless of
+type (see "Node (with Dockerfile)" below), so this sidesteps the bug without changing how the
+workload is invoked.
+
 ## Node (with Dockerfile)
 
 You own \`CMD\`. If it is \`npm start\`, you still need \`scripts.start\`.
@@ -556,11 +572,17 @@ Pick **one** type per coderunner. Changing type later means a new coderunner.
   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"}'\`.
+- \u26A0\uFE0F See "Known issue" in \`docs_get\` id \`coderunner-runtime\` if \`gf coderunner logs\` shows
+  \`Cannot find module './handler'\` despite a correct \`scripts.start\` \u2014 add a Dockerfile as the
+  workaround, no type change needed.
 
 ### 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.
+- \u26A0\uFE0F Not confirmed whether the no-Dockerfile bootstrap bug in \`docs_get\` id \`coderunner-runtime\`
+  ("Known issue") also hits \`job\` \u2014 if a run never starts and logs show the same
+  \`MODULE_NOT_FOUND: './handler'\`, apply the same Dockerfile workaround.
 
 ### Schedule
 
@@ -570,6 +592,8 @@ Pick **one** type per coderunner. Changing type later means a new coderunner.
 - GET/list/status expose top-level \`workload_type\` and \`schedule\`.
   \`gf coderunner status -c <slug>\` prints type, schedule, last_job.
 - No public invoke URL. Debug with \`gf coderunner logs\`, not curl.
+- \u26A0\uFE0F Same caveat as Job: unconfirmed whether the bootstrap "Known issue" affects scheduled runs;
+  same Dockerfile workaround if you see the identical crash signature.
 
 ### Service (Deployment)
 
@@ -661,8 +685,13 @@ When the handler looks right locally, \`gf deploy\` the same tree.
 Do not pass credential-shaped keys as \`--env KEY=VALUE\` (\`*_SECRET\`,
 \`*_API_KEY\`, \`DATABASE_URL\`, \u2026). Control Plane returns **422**.
 \`gf secrets set KEY\` then \`gf deploy --secret KEY\` (inject by reference).
+This requires \`CODERUNNER_INJECT_ENV_SECRETS\` enabled for the workspace \u2014
+**off by default**. If \`--secret\` 422s naming that setting, either ask your
+platform operator to enable it, or read the secret live via M2M
+\`secrets:read\` instead (below) rather than falling back to plaintext
+\`--env\`.
 
-## M2M tokens (Vault and Files)
+## M2M tokens (Vault, Files, and Secrets)
 
 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
@@ -670,6 +699,34 @@ 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.
 
+Cache the minted JWT for its \`expires_in\` (refresh at ~80%). Never mint per
+request: \`POST \u2026/m2m/token\` is rate-limited per client and per IP (default
+20/minute each) and returns **429** when exceeded. Treat 429/401 from the mint
+call as retryable, not a crash.
+
+An M2M client can also read secret **values** directly at runtime instead
+of (or alongside) \`--secret\` deploy-time injection: grant it the
+**\`secrets:read\`** scope (same Portal **Administer \u2192 M2M tokens** screen,
+per-client toggle), then call
+\`GET {CONTROLPLANE_URL}/v1/workspaces/{workspace_id}/secrets/{key}\` with
+\`Authorization: Bearer\` from \`gf m2m token\` locally, or the deployed
+workload's injected \`GROUNDFLOOR_M2M_CLIENT_ID\`/\`GROUNDFLOOR_M2M_CLIENT_SECRET\`
+exchanged the same way. This path is:
+
+- **Read-only** \u2014 \`secrets:read\` never grants \`upsert\`/\`delete\`, regardless
+  of the client's writer relation on Vault/Files.
+- **Live** \u2014 a rotated secret is visible on your next call, no redeploy
+  needed. \`--secret\` injection only updates on the next deploy.
+- **Workspace-wide, not per-key or per-environment** \u2014 granting the scope
+  exposes every secret in the workspace across all environments to that
+  client's code, same class of trade as the existing Vault/Files writer
+  grant. Not a fit for isolating one secret to one Coderunner.
+
+Prefer it over \`--secret\` injection when you want live rotation and can
+do the fetch yourself; keep using \`--secret\` injection for SDKs that only
+read a literal \`process.env\` value. Either way, cache the revealed value
+in your process rather than calling \`reveal\` on every request.
+
 ## Agent actions
 
 Inspect: \`workspace_context\`, \`docs_get\` id \`coderunner\` or \`coderunner-runtime\`, \`suggest_cli\`.
@@ -848,6 +905,14 @@ database only if you need a different engine or workspace-owned isolation
 (\`docs_get\` id \`databases\`). Local UI without live vault:
 \`npm run dev:fixtures\`.
 
+Detail routes (e.g. \`records/:id\`): once the record loads, call
+\`setBreadcrumbLabel(record.name)\` from the kit's \`src/lib/shellBridge.ts\`
+(wraps \`window.__GF_SET_BREADCRUMB_LABEL__(location.pathname, label)\`; no-op
+outside Shell) so the breadcrumb does not show the raw id. Give that route
+\`hidden: true\` in the manifest so it stays out of the sidebar nav but still
+routes (omit it or use \`false\` otherwise \u2014 never \`null\`). \`visibility:
+"public"\` makes a route reachable without login.
+
 ## suggest_cli
 
 - init_app \u2192 \`gf apps init --slug <portal-slug>\`
@@ -872,6 +937,10 @@ 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.
 
+\`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.
+
 Example:
 
 \`\`\`json
@@ -934,6 +1003,18 @@ Do not \`--env SENDGRID_SECRET=\u2026\`. That is **422**.
 \`gf secrets set SENDGRID_SECRET\` then \`gf deploy --secret SENDGRID_SECRET\`.
 `.trim();
 
+// src/version.ts
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+var moduleDir = dirname(fileURLToPath(import.meta.url));
+function readPackageVersion() {
+  const pkgPath = join(moduleDir, "..", "package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+  return pkg.version;
+}
+var GF_MCP_VERSION = readPackageVersion();
+
 // src/docs.ts
 var DOCS_ORIGIN = "https://docs.groundfloor.cloud";
 var DOC_CATALOG = [
@@ -954,21 +1035,24 @@ var DOC_CATALOG = [
     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, Coderunner identities for Vault, App authentication optional, local live data, gf deploy.",
-    embedded: CODERUNNER_GUIDE
+    embedded: CODERUNNER_GUIDE,
+    lastUpdated: "2026-09-24"
   },
   {
     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
+    embedded: CODERUNNER_RUNTIME_CONTRACT,
+    lastUpdated: "2026-09-23"
   },
   {
     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 create prerequisites.",
-    embedded: CODERUNNER_GUIDE
+    embedded: CODERUNNER_GUIDE,
+    lastUpdated: "2026-09-24"
   },
   {
     id: "authentication",
@@ -986,7 +1070,7 @@ var DOC_CATALOG = [
     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."
+    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. Secrets only with the opt-in secrets:read scope (read-only). Cache the token; minting is rate-limited per client and IP."
   },
   {
     id: "api-authentication",
@@ -999,42 +1083,48 @@ var DOC_CATALOG = [
     title: "Shell federated apps",
     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
+    embedded: SHELL_APP_GUIDE,
+    lastUpdated: "2026-09-24"
   },
   {
     id: "design-standard",
     title: "Shell app design standard",
     path: "/docs/integrations/shell/design-standard",
     summary: "Visual rules for Shell apps: grey ground, flat controls, Geist, one brand accent from theme.primaryColor, DataGrid, PhaseChevron. Use the kit; do not restyle to stock Tailwind.",
-    embedded: DESIGN_STANDARD_GUIDE
+    embedded: DESIGN_STANDARD_GUIDE,
+    lastUpdated: "2026-09-04"
   },
   {
     id: "css-and-styling",
     title: "CSS and styling",
     path: "/docs/integrations/shell/css-and-styling",
     summary: "Tailwind is the default. Own CSS framework (Bootstrap, MUI, \u2026) uses FederatedStyleRoot and Shadow DOM \u2014 do not load it globally onto the Shell page.",
-    embedded: CSS_AND_STYLING_GUIDE
+    embedded: CSS_AND_STYLING_GUIDE,
+    lastUpdated: "2026-09-04"
   },
   {
     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.",
-    embedded: DATABASES_GUIDE
+    embedded: DATABASES_GUIDE,
+    lastUpdated: "2026-09-22"
   },
   {
     id: "vault",
     title: "Data Vault",
     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
+    embedded: VAULT_GUIDE,
+    lastUpdated: "2026-09-22"
   },
   {
     id: "scheduled-jobs",
     title: "Scheduled jobs",
     path: "/docs/customer-portal/scheduled-jobs",
     summary: "workload_type=schedule plus cron. gf coderunner status shows type/schedule/last_job. Use Process Log, not a public URL.",
-    embedded: CODERUNNER_GUIDE
+    embedded: CODERUNNER_GUIDE,
+    lastUpdated: "2026-09-24"
   }
 ];
 function docUrl(entry) {
@@ -1061,7 +1151,9 @@ async function fetchDocPage(entry) {
       title: entry.title,
       text: entry.embedded.trim(),
       truncated: false,
-      source: "embedded"
+      source: "embedded",
+      lastUpdated: entry.lastUpdated ?? null,
+      mcpVersion: GF_MCP_VERSION
     };
   }
   const res = await fetch(url, {
@@ -1081,7 +1173,9 @@ async function fetchDocPage(entry) {
     title: entry.title,
     text: body,
     truncated,
-    source: "docs.groundfloor.cloud"
+    source: "docs.groundfloor.cloud",
+    lastUpdated: null,
+    mcpVersion: GF_MCP_VERSION
   };
 }
 
@@ -1218,7 +1312,7 @@ async function resolveCoderunnerId(apiUrl, workspaceId, idOrSlug) {
 }
 var server = new McpServer({
   name: "groundfloor",
-  version: "0.1.7"
+  version: GF_MCP_VERSION
 });
 server.tool(
   "whoami",
@@ -1599,11 +1693,13 @@ server.tool(
     const hits = findDoc(query ?? "");
     return text({
       origin: "https://docs.groundfloor.cloud",
+      mcpVersion: GF_MCP_VERSION,
       docs: hits.map((d) => ({
         id: d.id,
         title: d.title,
         url: `https://docs.groundfloor.cloud${d.path}`,
-        summary: d.summary
+        summary: d.summary,
+        lastUpdated: d.lastUpdated ?? null
       }))
     });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groundfloorcloud/mcp",
-  "version": "0.1.9",
+  "version": "0.1.12",
   "description": "Groundfloor MCP — inspect workspace state and docs; take actions with the gf CLI.",
   "type": "module",
   "bin": {
@@ -38,6 +38,7 @@
   },
   "devDependencies": {
     "@types/node": "^20",
+    "esbuild": "^0.27.7",
     "tsup": "^8.3.0",
     "typescript": "^5"
   },