@cloudgrid-io/mcp 0.11.0 → 0.12.0

package/src/corpus/troubleshooting/persistent-apps.md

@@ -1,7 +1,7 @@
 ---
 name: persistent-apps
-when: A persistent (Mongo-backed) app misbehaves — data doesn't survive refresh, MONGODB_URL is undefined, a runtime deploy seems stuck, or it won't build on hosted.
-summary: Symptom, cause, and fix for the common app-with-data (runtime Mongo app) problems — in-memory vs persistent, injected MONGODB_URL, async deploys, and the hosted-edition gate.
+when: A persistent (Mongo-backed) app misbehaves — data doesn't survive refresh, DATABASE_MONGODB_URL is undefined, a runtime deploy seems stuck, or it won't build on hosted.
+summary: Symptom, cause, and fix for the common app-with-data (runtime Mongo app) problems — in-memory vs persistent, injected DATABASE_MONGODB_URL (+legacy MONGODB_URL), async deploys, and the hosted-edition gate.
 ---
 
 # Troubleshooting: persistent apps (app-with-data)
@@ -12,11 +12,11 @@ Match the symptom to the row, apply the fix, and stop.
 | --- | --- | --- |
 | Data doesn't persist / resets on refresh | You built a static inspiration (in-memory / localStorage), not a runtime app | Use the `app-with-data` workflow: a real Next.js + Mongo runtime that reads `process.env.MONGODB_URL`. Static templates keep state only in memory. |
 | `Error: Service directory not found: …/services/web` | App code lives at the repo/template root, not under the service folder | App code must live under `services/<name>/` (e.g. `services/web/`). `path:` in `cloudgrid.yaml` is the URL mount, NOT the filesystem path — the service name is the folder the CLI looks for. |
-| `next build` fails / MONGODB_URL error at build time | The DB env var is read at module top level; `next build` imports the module for route analysis before the grid injects the var | Read `process.env.MONGODB_URL` LAZILY inside the getter (e.g. inside `getDb`), never at module load. Moving the check into the function lets the build pass. |
-| App builds + deploys but every request 500s with `MONGODB_URL not set` | You used `needs:` in `cloudgrid.yaml`; the deployer doesn't inject the DB from `needs:` yet | Switch to `requires: [mongodb]`. The CLI warns `requires:` is deprecated, but the deployer only injects `MONGODB_URL` from `requires:` (platform bug flagged to Gilad). Keep `requires:` until `needs:` is honored. |
-| `MONGODB_URL is undefined` (or the db.js guard throws) | The env var isn't present because you're not running under the grid | Run locally with `grid dev`, or deploy with `grid plug` — the grid injects `MONGODB_URL` at dev-time and runtime. Do NOT set it yourself and never hardcode a connection string. |
+| `next build` fails / DB connection error at build time | The DB env var is read at module top level; `next build` imports the module for route analysis before the grid injects the var | Read `process.env.DATABASE_MONGODB_URL` (with a legacy `MONGODB_URL` fallback) LAZILY inside the getter (e.g. inside `getDb`), never at module load. Moving the check into the function lets the build pass. |
+| App builds + deploys but every request 500s with `DATABASE_MONGODB_URL not set` | The datastore isn't declared, or you declared the deprecated `requires:` instead of `needs:` | Declare `needs: { database: true }` in `cloudgrid.yaml`. The deployer provisions Mongo and injects `DATABASE_MONGODB_URL` (plus the legacy `MONGODB_URL` alias). Never set `needs:` and `requires:` together (the validator rejects it). |
+| `DATABASE_MONGODB_URL is undefined` (or the db.js guard throws) | The env var isn't present because you're not running under the grid | Run locally with `grid dev`, or deploy with `grid plug` — the grid injects `DATABASE_MONGODB_URL` (+legacy `MONGODB_URL`) at dev-time and runtime. Do NOT set it yourself and never hardcode a connection string. |
 | Deploy seems stuck / no URL returned | Runtime deploys are asynchronous | `plug` returns `status: building`, not a URL. Poll `gridctl_status` (or the poll_url) until the app is live, then return the live URL. Don't treat the build/log link as the deliverable. |
 | It won't build on the hosted edition | Hosted MCP is inline-only — it can't run the CLI or folder-plug | Runtime apps need the LOCAL edition (Claude Desktop/Code) or the CLI. On hosted, tell the user persistence isn't available there and offer a static version instead. |
-| Redis not available | `redis` wasn't declared | Add `redis: private` to `requires` in `cloudgrid.yaml`; the grid then injects `REDIS_URL`. Only add it if the app actually needs Redis. |
+| Redis not available | `cache` wasn't declared | Add `cache: true` to `needs:` in `cloudgrid.yaml`; the grid then injects `CACHE_REDIS_URL` (plus the legacy `REDIS_URL` alias). Only add it if the app actually needs Redis. |
 
 See the `app-with-data` workflow for the full recipe.

package/src/corpus/workflows/ai-app.md

@@ -0,0 +1,136 @@
+---
+name: ai-app
+when: chatbot, AI assistant, Q&A bot, conversational app, support bot, ask-me-anything, an app that talks to an LLM / generates text with AI. Needs AI + a database → runtime → local edition.
+needs: ai, database
+deploy: runtime
+editions: local
+capabilities_note: AI chatbot — needs ai (the grid AI gateway) + a database (Mongo) for chat history. Next.js App Router app. Uses @cloudgrid-io/ai createClient().chat() with zero-config in-grid identity auth (no API key). Runtime app, async build, local edition only. Declare `needs: { ai: true, database: true }`. (RAG over your own docs needs `needs: { vector: pgvector }` — not yet available, platform issue #1545.)
+summary: Build an AI chatbot on the grid — a Next.js app that calls @cloudgrid-io/ai createClient().chat({messages}) (zero-config in-grid auth, no key) and persists the conversation to grid-shared Mongo. Edition-gate first, scaffold, put the app under services/web/, declare needs:{ai:true,database:true}, read DATABASE_MONGODB_URL lazily, deploy async, poll to a live URL.
+---
+
+# Workflow: ai-app
+
+The user wants an app that **talks to an LLM** — a chatbot, an AI assistant, a
+Q&A/support bot, an ask-me-anything. It calls the grid's AI gateway to generate
+replies and **remembers the conversation** in the grid-shared Mongo. So it needs
+two capabilities: `ai` (the gateway) and `database` (chat history). That makes it
+a **runtime app**, not a static page.
+
+Follow this recipe. Be honest that a runtime deploy is async and needs the local
+edition.
+
+## 1. Edition check FIRST (hard gate)
+
+An AI chatbot is a built + deployed container. It requires the **local edition**
+(Claude Desktop / Claude Code) or the CLI, because the grid must run the CLI and
+folder-plug your project.
+
+- **Hosted edition (Claude Web / hosted MCP):** you CANNOT build a runtime app —
+  hosted is inline-only and can only publish static pages. Tell the user plainly:
+  "An AI chatbot needs the local edition (Claude Desktop/Code) or the CloudGrid
+  CLI; the hosted edition can only publish static pages." STOP the runtime path
+  here.
+- **Local edition:** continue.
+
+## 2. Auth + grid
+
+Persistent apps are owned entities.
+1. Ensure signed in: `gridctl_login_status`; if not, `gridctl_login`.
+2. A grid is required. Respect the grid picker: if the user has more than one
+   grid, ask which to use; do not assume a target.
+
+## 3. Scaffold
+
+`gridctl_init` an app `<name>`. `init` creates the entity + `.cloudgrid/link.json`
+and writes a `cloudgrid.yaml` with an EMPTY `services: {}`. `plug` needs a linked
+directory, so run `init` FIRST.
+
+You then do two things: (a) write the app under **`services/web/`**, and (b) fill
+in `cloudgrid.yaml` to the shape below (`services.web` type `nextjs` + `needs: {
+ai: true, database: true }`).
+
+## 4. Wire the AI gateway + Mongo
+
+1. Set `cloudgrid.yaml` to declare the `web` service and the capabilities it
+   needs. **App code MUST live under `services/<name>/`** — `path:` is the URL
+   mount, NOT the filesystem path. A service named `web` → the CLI looks for
+   `services/web/`; files at the repo root fail with
+   `Error: Service directory not found: …/services/web`.
+   ```yaml
+   name: my-chatbot
+   services:
+     web:
+       type: nextjs
+       path: /
+   needs:
+     ai: true
+     database: true
+   # For retrieval-augmented (RAG) over your own docs, add `needs: { vector:
+   # pgvector }` once platform issue #1545 ships — not yet available.
+   ```
+   **Declare `needs: { ai: true, database: true }`** — the canonical shape. The
+   deployer wires the AI gateway (in-grid identity) and provisions Mongo,
+   injecting `DATABASE_MONGODB_URL` (plus the legacy `MONGODB_URL` alias) at
+   dev-time and runtime. `requires:` is the deprecated v1 alias; don't author new
+   yaml with it, and never set `needs:` and `requires:` together (the validator
+   rejects it).
+2. Fetch the template for the chat wiring:
+   `gridctl_fetch("template", "ai-app")`. It is a minimal Next.js App Router chat
+   app under `services/web/`: a chat page, an API route
+   (`app/api/chat/route.js`, `export const dynamic = "force-dynamic"`) that reads
+   the user message, calls the AI gateway, persists the exchange to Mongo, and
+   returns the reply.
+3. **Call the AI gateway with `@cloudgrid-io/ai`** — zero config, no API key:
+   ```js
+   import { createClient } from "@cloudgrid-io/ai";
+   const client = createClient();                    // zero-arg, no key
+   const r = await client.chat({ messages: [{ role: "user", content: text }] });
+   const reply = r.text ?? r.content;                // reply text
+   ```
+   The SDK auto-detects the in-grid identity — **do NOT set an API key.** It only
+   works inside a deployed grid app (or under `grid dev`).
+4. **Persist the exchange to Mongo** — read `process.env.DATABASE_MONGODB_URL`
+   (falling back to the legacy `process.env.MONGODB_URL`) **lazily inside the
+   getter, never at module top level**, or `next build` fails (the module is
+   imported for route analysis before the grid injects the var). Store the user
+   message and the assistant reply so the conversation survives refresh. Never
+   hardcode a connection string; never commit a secret.
+   - (Optional) fetch `gridctl_fetch("example", "ai-app")` for a richer filled
+     reference (a themed assistant) to imitate.
+
+## 5. (Optional) Run locally
+
+Mention that the user can `grid dev` to run locally — the AI gateway and Mongo
+are wired in dev too — and send a test message before deploying. Don't require it.
+
+## 6. Config
+
+- Extra API keys / secrets (only if the app needs its own) → `gridctl_secrets`.
+- Non-secret config → `gridctl_env`.
+- Do **NOT** set the DB connection var yourself (`DATABASE_MONGODB_URL` / legacy
+  `MONGODB_URL`) and do **NOT** set an AI key — the grid injects the DB var and
+  the AI SDK auto-detects the in-grid identity.
+
+## 7. Deploy (async)
+
+Deploy the folder with `gridctl_plug`. A **runtime deploy is ASYNC**: the first
+response is `status: "building"` with a `poll_url` / entity, NOT a live URL yet.
+- Poll `gridctl_status` (or the returned poll_url) until the entity is live.
+- Surface a liveness signal while it builds — never a bare silent wait.
+- Only once it is live, return the deployed URL (the app URL, NOT the build/log
+  link).
+
+## 8. Return the live URL + iterate
+
+Give the user the live chatbot URL — that is the deliverable. To iterate, re-plug
+the SAME entity (`target_entity_id`) so it updates the same URL.
+
+## Note on RAG / retrieval
+
+If the user wants the bot to answer over **their own documents** (retrieval-
+augmented generation), that needs a vector store (`needs: { vector: pgvector }`).
+That path is **not yet available** — platform issue #1545. Ship the plain
+chatbot now; add retrieval once the vector need is unblocked.
+
+Keep it honest: async build, local-edition only, AI auth and DB credentials
+provided by the grid.

package/src/corpus/workflows/api-service.md

@@ -0,0 +1,118 @@
+---
+name: api-service
+when: REST API, backend for X, API endpoint(s), CRUD API, JSON API, webhook receiver, a backend/service that stores data and isn't a full web UI. Needs a database → runtime → local edition.
+needs: database
+deploy: runtime
+editions: local
+capabilities_note: persistent backend service — needs a database (Mongo). A plain Node HTTP service (type: node), not a web UI. Runtime app, async build, local edition only. Declare the canonical `needs: { database: true }`; the deployer injects DATABASE_MONGODB_URL (+legacy MONGODB_URL).
+summary: Build a real REST/JSON API on the grid — a Node HTTP service backed by grid-shared Mongo. Edition-gate first, scaffold, put the service under services/api/, read process.env.DATABASE_MONGODB_URL (legacy MONGODB_URL fallback) lazily, declare needs:{database:true} (not requires:), deploy async, poll to a live URL.
+---
+
+# Workflow: api-service
+
+The user wants a **backend API**, not a full web UI — a REST/JSON service with
+endpoints, a resource it stores and returns (a `/items` CRUD API, a webhook
+receiver, a small backend for another app). It **saves data**, so it is a
+**runtime app** backed by the grid's shared Mongo. This is the plain-service
+sibling of `app-with-data`: no Next.js, no pages — just a Node HTTP server
+speaking JSON.
+
+Follow this recipe. Be honest that a runtime deploy is async (not instant like a
+static drop) and that it needs the local edition.
+
+## 1. Edition check FIRST (hard gate)
+
+An API service is a built + deployed container. It requires the **local
+edition** (Claude Desktop / Claude Code) or the CLI, because the grid must run
+the CLI and folder-plug your project.
+
+- **Hosted edition (Claude Web / hosted MCP):** you CANNOT build a runtime
+  service — hosted is inline-only and can only publish static pages. Tell the
+  user plainly: "An API service needs the local edition (Claude Desktop/Code) or
+  the CloudGrid CLI; the hosted edition can only publish static pages." STOP the
+  runtime path here (there is no useful static fallback for a backend API).
+- **Local edition:** continue.
+
+## 2. Auth + grid
+
+Persistent services are owned entities.
+1. Ensure signed in: `gridctl_login_status`; if not, `gridctl_login`.
+2. A grid is required. Respect the grid picker: if the user has more than one
+   grid, ask which to use; do not assume a target.
+
+## 3. Scaffold
+
+`gridctl_init` an app `<name>`. `init` creates the entity + `.cloudgrid/link.json`
+and writes a `cloudgrid.yaml` with an EMPTY `services: {}`. `plug` needs a linked
+directory, so run `init` FIRST.
+
+You then do two things: (a) write the service under **`services/api/`**, and (b)
+fill in `cloudgrid.yaml` to the shape below (`services.api` type `node` + `needs:
+{ database: true }`).
+
+## 4. Add the datastore + wire Mongo
+
+1. Set `cloudgrid.yaml` to declare the `api` service and the store it needs.
+   **Service code MUST live under `services/<name>/`** — `path:` is the URL
+   mount, NOT the filesystem path. A service named `api` → the CLI looks for
+   `services/api/`; files at the repo root fail with
+   `Error: Service directory not found: …/services/api`.
+   ```yaml
+   name: my-api
+   services:
+     api:
+       type: node
+       path: /
+   needs:
+     database: true
+   ```
+   **Declare the datastore with `needs: { database: true }`** — this is the
+   canonical shape. The deployer provisions Mongo and injects
+   `DATABASE_MONGODB_URL` (plus the legacy `MONGODB_URL` alias) at dev-time and
+   runtime. `requires:` is the deprecated v1 alias; don't author new yaml with
+   it, and never set `needs:` and `requires:` together (the validator rejects it).
+2. Fetch the template for the server + Mongo shape:
+   `gridctl_fetch("template", "api-service")`. It is a minimal Node `http`
+   server under `services/api/`: it listens on `process.env.PORT || 8080` and
+   serves a small REST resource (`/items` GET list / POST create / DELETE by id)
+   backed by Mongo.
+3. Adapt it to the user's API (rename the resource, change the fields, add
+   routes). **Read the database from `process.env.DATABASE_MONGODB_URL`** (falling
+   back to the legacy `process.env.MONGODB_URL`) — the grid injects those env
+   vars at dev-time and runtime. Never hardcode a connection string; never commit
+   a secret.
+   - **Read the connection string LAZILY inside the request handler / a getter —
+     never at module top level, or node startup crashes** before the grid has
+     injected the var.
+   - Return clear JSON errors (`{ "error": "…" }`) with the right status codes.
+   - (Optional) fetch `gridctl_fetch("example", "api-service")` for a slightly
+     richer filled reference to imitate.
+
+## 5. (Optional) Run locally
+
+Mention that the user can `grid dev` to run locally against the injected Mongo
+and hit the endpoints before deploying. Don't require it.
+
+## 6. Config
+
+- API keys / secrets → `gridctl_secrets`.
+- Non-secret config → `gridctl_env`.
+- Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL`, or the
+  legacy `MONGODB_URL` alias) — the grid injects them.
+
+## 7. Deploy (async)
+
+Deploy the folder with `gridctl_plug`. A **runtime deploy is ASYNC**: the first
+response is `status: "building"` with a `poll_url` / entity, NOT a live URL yet.
+- Poll `gridctl_status` (or the returned poll_url) until the entity is live.
+- Surface a liveness signal while it builds — never a bare silent wait.
+- Only once it is live, return the deployed URL (the API base URL, NOT the
+  build/log link).
+
+## 8. Return the live URL + iterate
+
+Give the user the live API URL — that is the deliverable. Point out the endpoints
+(e.g. `GET /items`, `POST /items`). To iterate, re-plug the SAME entity
+(`target_entity_id`) so it updates the same URL.
+
+Keep it honest: async build, local-edition only, credentials injected by the grid.

package/src/corpus/workflows/app-with-data.md

@@ -4,8 +4,8 @@ when: to-do, task list, notes app, guestbook, CRUD app, form that SAVES/STORES s
 needs: database
 deploy: runtime
 editions: local
-capabilities_note: persistent — needs a database (Mongo). Runtime app, async build, local edition only. Canonical need is `database: true` (metadata); the deployed yaml uses `requires: [mongodb]` until #1527 lands.
-summary: Build a real persistent Next.js + Mongo runtime app on the grid — edition-gate first, scaffold, put the app under services/web/, wire process.env.MONGODB_URL lazily, declare requires:[mongodb] (not needs:), deploy async, poll to a live URL.
+capabilities_note: persistent — needs a database (Mongo). Runtime app, async build, local edition only. Declare the canonical `needs: { database: true }`; the deployer injects DATABASE_MONGODB_URL (+legacy MONGODB_URL).
+summary: Build a real persistent Next.js + Mongo runtime app on the grid — edition-gate first, scaffold, put the app under services/web/, wire process.env.DATABASE_MONGODB_URL (legacy MONGODB_URL fallback) lazily, declare needs:{database:true} (not requires:), deploy async, poll to a live URL.
 ---
 
 # Workflow: app-with-data
@@ -48,7 +48,7 @@ the entity + `.cloudgrid/link.json` and writes a `cloudgrid.yaml` with an EMPTY
 `services: {}`. `plug` needs a linked directory, so run `init` FIRST.
 
 You then do two things: (a) write the app under **`services/web/`**, and (b) fill
-in `cloudgrid.yaml` to the shape below (`services.web` + `requires: [mongodb]`).
+in `cloudgrid.yaml` to the shape below (`services.web` + `needs: { database: true }`).
 
 ## 4. Add the datastore + wire Mongo
 
@@ -63,27 +63,28 @@ in `cloudgrid.yaml` to the shape below (`services.web` + `requires: [mongodb]`).
      web:
        type: nextjs
        path: /
-   requires:
-     - mongodb        # alias: db
-     # - redis: private   # OPTIONAL — add only if the app needs Redis
+   needs:
+     database: true
+     # cache: true      # OPTIONAL — add only if the app needs Redis
    ```
-   **Declare the datastore with `requires: [mongodb]` (NOT `needs:`)** — see the
-   yaml comment in the template. The CLI warns `requires:` is deprecated, but the
-   deployer only injects `MONGODB_URL` from `requires:`; `needs:` builds fine but
-   injects NO DB connection (every request 500s). Keep `requires:` until the
-   deployer honors `needs:`.
+   **Declare the datastore with `needs: { database: true }`** — this is the
+   canonical shape. The deployer provisions Mongo and injects
+   `DATABASE_MONGODB_URL` (plus the legacy `MONGODB_URL` alias) at dev-time and
+   runtime. `requires:` is the deprecated v1 alias; don't author new yaml with it,
+   and never set `needs:` and `requires:` together (the validator rejects it).
 2. Fetch the template for the Mongo wiring + CRUD shape:
    `gridctl_fetch("template", "app-with-data")`. It is a minimal, real
    Next.js + `mongodb`-driver to-do app under `services/web/`: a lazy client in
    `services/web/lib/db.js`, an App-Router GET/POST/DELETE route on a `todos`
    collection, and a page.
 3. Adapt it to the user's app (rename the collection, change the fields, adjust
-   the UI). **Read the database from `process.env.MONGODB_URL`** — the grid
-   injects that env var at dev-time and runtime. Never hardcode a connection
-   string; never commit a secret.
-   - **Put the DB connection behind a lazy getter — never read
-     `process.env.MONGODB_URL` at module top level, or `next build` fails** (the
-     module is imported for route analysis before the grid injects the var).
+   the UI). **Read the database from `process.env.DATABASE_MONGODB_URL`** (falling
+   back to the legacy `process.env.MONGODB_URL`) — the grid injects those env vars
+   at dev-time and runtime. Never hardcode a connection string; never commit a
+   secret.
+   - **Put the DB connection behind a lazy getter — never read the connection
+     string at module top level, or `next build` fails** (the module is imported
+     for route analysis before the grid injects the var).
    - (Optional) fetch `gridctl_fetch("example", "app-with-data")` for a slightly
      richer filled reference to imitate.
 
@@ -96,7 +97,9 @@ and sanity-check before deploying. Don't require it.
 
 - API keys / secrets → `gridctl_secrets`.
 - Non-secret config → `gridctl_env`.
-- Do **NOT** set `MONGODB_URL` or `REDIS_URL` yourself — the grid injects them.
+- Do **NOT** set the DB/cache connection vars yourself (`DATABASE_MONGODB_URL`,
+  `CACHE_REDIS_URL`, or their legacy `MONGODB_URL` / `REDIS_URL` aliases) — the
+  grid injects them.
 
 ## 7. Deploy (async)
 

package/src/tools.js

@@ -90,6 +90,7 @@ Operating rules:
 10. Publishing a heavy or local file: in the local edition use the path parameter so it is read from disk (no inline size limit); never base64-encode HTML and never pass a file path (or an @-prefixed path) as html. If a drop looks empty, use gridctl_source to check what was actually published, then re-plug with the real HTML/path and target_entity_id.
 11. Persistence check: if the user needs to SAVE data, share state across users/sessions, log in, or store submissions, that's a runtime app-with-data (Mongo-backed), NOT a static page — static templates keep state only in memory and lose it on refresh. Use the app-with-data workflow. This requires the LOCAL edition (Claude Desktop/Code or the CLI); on the hosted edition, tell the user persistence isn't available there and offer a static version.
 12. To choose what to build: match the request against the workflow when: triggers and the capability-map (gridctl_fetch({kind:"doc", name:"capability-map"})). Pick the template whose needs: matches what the app requires (persistence → database; scheduled → cron; etc.). Static (needs: none) deploys as an inspiration (instant, any edition); anything needing needs: is a runtime (async, local edition).
+13. Before writing a cloudgrid.yaml, fetch the reference: gridctl_fetch({kind:"doc", name:"cloudgrid-yaml"}) — it has the full schema, the needs: vocabulary, and the requires-vs-needs caveat (the deployer does not inject from needs: yet, so a database/cache today uses requires: [mongodb] / requires: [redis]).
 
 Deploy is edition-dependent: on the hosted MCP call the drop tool with the HTML; on local MCP / CLI write the file and run the plug tool. An HTML page deploys synchronously, so you get a URL right away.`;