@groundfloorcloud/mcp 0.1.8 → 0.1.11

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,18 +572,28 @@ 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
 
 - Same as job, plus a cron expression at deploy:
   \`gf deploy --workload-type schedule --schedule "<cron>"\`
   (or \`groundfloor.json\` \`"schedule"\`).
-- No public invoke URL. Debug with Process Log, not curl.
+- 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)
 
@@ -654,7 +680,18 @@ or customer env.
 
 When the handler looks right locally, \`gf deploy\` the same tree.
 
-## M2M tokens (Vault and Files)
+## Secrets on deploy
+
+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, 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
@@ -662,10 +699,33 @@ 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.
 
+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\`.
-Act: \`gf deploy\`, \`gf coderunner run|status\`, \`gf m2m token\`. MCP does not deploy.
+Act: \`gf deploy\`, \`gf coderunner run|status|logs\`, \`gf m2m token\`, \`gf identities ls|mint\`, \`gf api\`. MCP does not deploy.
 `.trim();
 
 // src/css-and-styling-guide.ts
@@ -711,30 +771,46 @@ Dataplane is not a database. It is how Groundfloor talks to databases.
 When the user starts any data or database work, say this first. Do not mention
 infrastructure internals (cluster operators, installers, and the like):
 
-You have ArangoDB ready to use through Dataplane. If you want another
-database, deploy it first. You can use a deployed database through Dataplane,
-or connect to it on your own.
+You have Postgres ready to use through Dataplane \u2014 a shared, platform-managed
+cluster, already there, no deploy step. If you want a different engine, or a
+database that is entirely your own (own scaling, own backups schedule), you
+can deploy one first.
 
 ## Options
 
-- ArangoDB \u2014 shared, managed, already there. Default for app data and Vault.
-  No deploy step. Query via Control Plane vault:
-  POST /v1/workspaces/{id}/vault/collections/{name}/query
-- Postgres \u2014 what you can deploy today (portal Data \u2192 Databases). After it is
-  ready, use it through Dataplane or with the connection secrets.
+- Postgres (shared) \u2014 platform-managed, already there. Default for app data
+  and Vault. No deploy step. This is NOT a workspace-owned resource: it does
+  not appear on the customer Databases page, and there is nothing to scale,
+  back up, or delete yourself \u2014 it's offered, not provisioned. Query via
+  Control Plane vault: POST /v1/workspaces/{id}/vault/collections/{name}/query
+- ArangoDB \u2014 also shared, managed, already there, no deploy step. Still fully
+  supported; just no longer the pre-selected engine for new collections.
+- A dedicated database you deploy and own (Postgres, Redis, ClickHouse,
+  Qdrant) \u2014 portal Data \u2192 Databases, or
+  POST /v1/workspaces/{id}/managed-databases. Heavier than the shared
+  default: you own its scaling, backups, and lifecycle. Use this when you
+  need a tier/engine the shared default doesn't offer (Redis, ClickHouse,
+  Qdrant) or want a database isolated to this workspace.
 - A database they already run \u2014 through Dataplane if they wire it, or direct.
 
 Do not list other engines as available to deploy. Do not call Dataplane hosts
 from apps or embed service keys.
 
+## Creating a collection / table
+
+Pass the engine explicitly \u2014 do not rely on Dataplane's default connector
+resolution. POST /v1/workspaces/{id}/vault/collections with
+\`"schema": {"engine": "postgresql", ...}\` for the shared default, or
+\`"engine": "arangodb"\` to use ArangoDB instead.
+
 ## Paths
 
 - Browse / edit rows \u2192 Data Vault (portal or vault APIs)
-- Deploy Postgres \u2192 Customer Portal Databases page, or
-  POST /v1/workspaces/{id}/managed-databases with engine postgres
+- Deploy your own database \u2192 Customer Portal Databases page, or
+  POST /v1/workspaces/{id}/managed-databases with engine postgres|redis|clickhouse|qdrant
 - Shell 403 / empty vault \u2192 collection Access for the site role
 
-docs_get id databases. Human docs: /docs/customer-portal/databases
+docs_get id databases. Human docs: /docs/customer-portal/databases and /docs/customer-portal/data-vault
 `;
 
 // src/design-standard-guide.ts
@@ -818,9 +894,11 @@ remoteEntry.js. Header logos: manifest \`theme.logoUrl\` (absolute https).
 UI look: \`docs_get\` id \`design-standard\`. CSS: Tailwind by default;
 own framework uses FederatedStyleRoot (Shadow DOM) \u2014 \`docs_get\` id
 \`css-and-styling\`. Data: Dataplane is not a database. Say first: you have
-ArangoDB ready through Dataplane; deploy Postgres if you want another
-database; use it through Dataplane or on your own (\`docs_get\` id
-\`databases\`). Local UI without live vault: \`npm run dev:fixtures\`.
+Postgres (shared, platform-managed, no deploy step) ready through Dataplane
+by default; ArangoDB is also ready the same way. Deploy your own dedicated
+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\`.
 
 ## suggest_cli
 
@@ -828,6 +906,102 @@ database; use it through Dataplane or on your own (\`docs_get\` id
 - publish_app \u2192 init + npm install + npm run release + gf apps publish --path release.zip
 `;
 
+// src/vault-guide.ts
+var VAULT_GUIDE = `
+# Data Vault collections
+
+Vault is workspace data behind Control Plane
+\`/v1/workspaces/{workspace_id}/vault/\u2026\`. Browser apps send the Shell JWT.
+Coderunners use \`gf m2m token\` (preferred) or a workload-identity Vault JWT.
+
+## Create a collection (JSON Schema)
+
+POST \`/v1/workspaces/{id}/vault/collections\` with a **JSON Schema** object
+(\`type: object\`, \`properties\`, optional \`required\`). A missing schema is a
+**400** with a field error \u2014 not a 500.
+
+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
+{
+  "name": "properties",
+  "engine": "postgresql",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": { "type": "string" },
+      "metadata": { "type": "object" }
+    },
+    "required": ["name"]
+  }
+}
+\`\`\`
+
+Or use \`gf api -X POST /v1/workspaces/{workspace_id}/vault/collections --body '{...}'\`.
+
+\`GET \u2026/vault/collections\` lists schema-registered collections. Implicit
+tables created by the first \`POST \u2026/vault/{collection}\` appear when you pass
+\`include_implicit=true\` (or after a schema create).
+
+## Query totals
+
+\`POST \u2026/vault/{collection}/query\` \`total\` is the **unpaged** match count.
+\`limit\` only sizes \`records\`. Do not treat \`total === records.length\` as
+the full table size.
+
+## Filters
+
+Top-level fields work in \`filter\`. Nested paths such as \`metadata.sector\`
+are either supported by the connector or rejected with **400 unsupported
+path** \u2014 never a silent empty page.
+
+## ACLs
+
+Grant site roles on **Administer \u2192 Access**. Workload identities get
+collection grants via \`PUT \u2026/vault/collections/{name}/acl\`. M2M is Team
+Writer (workspace-wide), not an Access subject.
+
+## Identities vs M2M
+
+- Unattended Coderunners: attach an M2M client, \`gf deploy\`, then
+  \`gf m2m token\`.
+- Workload identity mint: \`gf identities mint --identity <id>\`. The **first**
+  mint returns \`refresh_secret\` once. Later mints omit it unless
+  \`--rotate-refresh\`. Prefer M2M for new workloads.
+
+## Scheduled jobs
+
+\`gf deploy --workload-type schedule --schedule "<cron>"\`.
+\`gf coderunner status -c <slug>\` shows **type**, **schedule**, and **last_job**.
+\`gf coderunner logs -c <slug>\` shows stdout. There is no public URL for
+schedules.
+
+## Secrets on deploy
+
+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 = [
@@ -848,21 +1022,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-23"
   },
   {
     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-23"
   },
   {
     id: "authentication",
@@ -893,28 +1070,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-22"
   },
   {
     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. ArangoDB is ready through Dataplane. Postgres you deploy first, then use through Dataplane or on your own.",
-    embedded: DATABASES_GUIDE
+    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,
+    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,
+    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,
+    lastUpdated: "2026-09-23"
   }
 ];
 function docUrl(entry) {
@@ -941,7 +1138,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, {
@@ -961,7 +1160,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
   };
 }
 
@@ -1098,7 +1299,7 @@ async function resolveCoderunnerId(apiUrl, workspaceId, idOrSlug) {
 }
 var server = new McpServer({
   name: "groundfloor",
-  version: "0.1.7"
+  version: GF_MCP_VERSION
 });
 server.tool(
   "whoami",
@@ -1179,9 +1380,10 @@ server.tool(
         databases_howto: {
           docs_get: "databases",
           dataplane: "Dataplane is not a database. It is how Groundfloor talks to databases.",
-          say_first: "You have ArangoDB ready to use through Dataplane. If you want another database, deploy it first. You can use a deployed database through Dataplane, or connect to it on your own.",
-          arango: "Shared, managed, already there. Default for app data and Vault. No deploy step.",
-          deploy: "Postgres is what you can deploy today."
+          say_first: "You have Postgres ready to use through Dataplane \u2014 shared, platform-managed, already there, no deploy step. ArangoDB is also available the same way. If you want your own dedicated database instead, deploy it first.",
+          shared_postgres: 'Default for app data and Vault. Platform-managed, not workspace-owned \u2014 nothing to scale/backup/delete yourself. Pass engine "postgresql" explicitly when creating a collection.',
+          arango: "Also shared, managed, already there, no deploy step. Still fully supported; just no longer pre-selected.",
+          deploy: "A dedicated Postgres/Redis/ClickHouse/Qdrant you own is what you can deploy today (portal Data \u2192 Databases)."
         },
         actions: {
           deploy: suggestCli("deploy"),
@@ -1459,7 +1661,7 @@ server.tool(
 );
 server.tool(
   "dataplane_status",
-  "Dataplane setup status (Dataplane is how Groundfloor talks to databases, not a database itself). ArangoDB is ready through it. Provision with `gf dataplane provision`.",
+  "Dataplane setup status (Dataplane is how Groundfloor talks to databases, not a database itself). Postgres (shared, platform-managed) is ready through it by default; ArangoDB is also ready. Provision with `gf dataplane provision`.",
   { workspace_id: wsId },
   async ({ workspace_id }) => {
     try {
@@ -1478,11 +1680,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.8",
+  "version": "0.1.11",
   "description": "Groundfloor MCP — inspect workspace state and docs; take actions with the gf CLI.",
   "type": "module",
   "bin": {