@cloudgrid-io/mcp 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "MCP server for CloudGrid. Three editions: a local stdio server (full toolset), a hosted web server (light, CLI-free toolset), and a public docs server (search_cloudgrid_documentation) over MCP Streamable HTTP.",
   "type": "module",
   "bin": {
@@ -20,6 +20,7 @@
     "test:error-reporting": "node test/error-reporting.test.mjs",
     "test:source": "node test/source-fetch.test.mjs",
     "test:app-with-data": "node test/app-with-data.test.mjs",
+    "test:self-describing": "node test/self-describing.test.mjs",
     "test:content": "node test/content-handling.test.mjs",
     "test:self-healing": "node test/self-healing.test.mjs",
     "test:grid-picker": "node test/grid-picker.test.mjs",

package/src/corpus/capability-map.md

@@ -0,0 +1,69 @@
+# Capability map — intent → template → capabilities → deploy
+
+This is the index an LLM uses to turn a user request into the right CloudGrid
+template, the way Superpowers matches a skill's `when:`. Match the request to a
+template by its `when:` triggers, adopt that template's `needs:`, then deploy:
+
+- **static → inspiration** (instant, any client / any edition) via `gridctl_drop`.
+- **anything needing `needs:` → runtime** (async build, **local edition** only)
+  via `gridctl_plug` on a linked folder.
+
+Fetch this doc any time with `gridctl_fetch("doc", "capability-map")`.
+
+## The 6 templates
+
+| Intent (match on `when:`) | Template | `needs:` | Deploy | Edition |
+|---|---|---|---|---|
+| landing page, marketing/product/hero page, coming-soon, waitlist, pricing, portfolio, link-in-bio, event page | `landing-page` | none | inspiration (instant) | all |
+| calculator, converter, generator, timer, quiz, interactive tool, mini-app, widget — computed client-side, no saved data | `web-app` | none | inspiration (instant) | all |
+| dashboard, metrics, KPIs, stats page, status board, charts, analytics view — display-only, static data baked in | `dashboard` | none | inspiration (instant) | all |
+| report, one-pager, summary, brief, whitepaper, case study, formatted document | `report` | none | inspiration (instant) | all |
+| slides, deck, pitch, presentation, slideshow | `presentation` (dir: `deck`) | none | inspiration (instant) | all |
+| to-do, task list, notes app, guestbook, CRUD app, a form that SAVES/STORES submissions, anything that PERSISTS data or shares state across users/sessions, sign-in/accounts | `app-with-data` | `database: true` | runtime (async, poll) | local |
+
+**Rule of thumb:** if the app must SAVE/remember data, share state across
+users/sessions, log in, or store submissions → it is persistent → `app-with-data`
+(runtime, local edition). Otherwise a static template deploys instantly anywhere.
+
+## The full `needs:` vocabulary (the whole menu)
+
+`needs:` is a MAP declaring infrastructure capabilities. Values are `true` or an
+engine hint. Cron is NOT a need — it is a **service type** (`type: cron` with
+`schedule` + `timezone`). See the cloudgrid.yaml reference §5, §12, §14.
+
+| `needs:` key | Provides | Injected env var(s) | Status |
+|---|---|---|---|
+| `database: true` | MongoDB primary datastore | `DATABASE_MONGODB_URL` (+legacy `MONGODB_URL`) | **Today via `requires: [mongodb]`** — `needs:` pending #1527 |
+| `cache: true` | Redis, LRU eviction | `CACHE_REDIS_URL` (+legacy `REDIS_URL`) | **Today via `requires: [redis]`** — `needs:` pending #1527 |
+| `kv: true` | Redis, no eviction | `KV_REDIS_URL` | Pending #1527 |
+| `queue: true` | Redis durable job queue | `QUEUE_REDIS_URL` | Pending #1527 |
+| `pubsub: true` | Redis pub/sub broadcast | `PUBSUB_REDIS_URL` | Pending #1527 |
+| `vector: pgvector` | pgvector embeddings DB | `VECTOR_PGVECTOR_URL` (+legacy `PGVECTOR_URL`) | Pending #1527 |
+| `object_storage: true` | GCS bucket | `OBJECT_STORAGE_GCS_BUCKET`, `OBJECT_STORAGE_GCS_REGION` | Pending #1527 |
+| `disk: true` | Persistent filesystem at `/data` | `DISK_PATH` | Pending #1527 |
+| `ai: true` | AI Gateway access | `AI_GATEWAY_URL` | **Today** (AI Gateway) |
+| `type: cron` (service) | Scheduled job (`schedule`, `timezone`) | — | Service type, not a need |
+
+### Injection status — today vs pending #1527
+
+- **Injects TODAY:** `database` and `cache` — but ONLY via the deprecated
+  `requires:` field (`requires: [mongodb]` → `MONGODB_URL`; `requires: [redis]`
+  → `REDIS_URL`). `needs:`-based provisioning does NOT inject anything on the
+  live deployer yet (bug #1527). `ai` (AI Gateway) is available today.
+- **Pending #1527:** `needs:`-based provisioning for everything — `vector`,
+  `queue`, `pubsub`, `kv`, `object_storage`, `disk`, and `needs: database` /
+  `needs: cache` once the deployer honors `needs:`.
+- **`needs:` and `requires:` cannot both be active** in one yaml — the validator
+  rejects the combination ("use one or the other"). So a DB template ships
+  `requires: [mongodb]` active with the canonical `needs: { database: true }`
+  shown only as a **comment** (and declared in the workflow frontmatter as
+  metadata), flipping to `needs:` when #1527 lands.
+
+## How to choose
+
+1. Read the request; match it against the workflow `when:` triggers above.
+2. Adopt that template's `needs:`. Persistence → `database`. (Future: scheduled →
+   `cron` service; semantic search / RAG → `vector` + `ai`.)
+3. Static (`needs: none`) → publish as an inspiration with `gridctl_drop`
+   (instant, any edition). Anything with a `needs:` → runtime, local edition,
+   `gridctl_plug` a linked folder, then poll to a live URL.

package/src/corpus/templates/app-with-data/cloudgrid.yaml

@@ -11,5 +11,9 @@ services:
   web:
     type: nextjs
     path: /
+# Canonical capability (metadata): this app needs a database.
+# When #1527 lands (deployer honors needs:), replace requires: with:
+#   needs:
+#     database: true
 requires:
   - mongodb

package/src/corpus/templates/app-with-data/index.md

@@ -53,10 +53,20 @@ services:
   web:
     type: nextjs
     path: /
+# Canonical capability (metadata): this app needs a database.
+# When #1527 lands (deployer honors needs:), replace requires: with:
+#   needs:
+#     database: true
 requires:
   - mongodb
 ```
 
+> **Capability:** this template's canonical need is `database: true` (see the
+> commented block above and the capability-map). The deployed yaml keeps
+> `requires: [mongodb]` because only `requires:` injects `MONGODB_URL` today
+> (#1527); `needs:` and `requires:` cannot co-exist active in the same yaml, so
+> the canonical `needs:` is shown only as a comment until the deployer honors it.
+
 ## services/web/package.json
 
 ```json

package/src/corpus/templates/dashboard/cloudgrid.yaml

@@ -0,0 +1,10 @@
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: dashboard
+services:
+  web:
+    type: static
+    path: /

package/src/corpus/templates/dashboard/index.md

@@ -0,0 +1,30 @@
+# Template: dashboard (static)
+
+A single self-contained HTML dashboard. **No infrastructure** — no database, no backend,
+no `needs:`. State (if any) lives only in memory and is lost on refresh.
+
+## How it deploys
+
+To publish this page, use **`gridctl_drop`** (or `gridctl_plug` with the inline
+HTML): it deploys as an **inspiration** — instant, and works on the **hosted**
+edition (Claude Web) as well as local. The reference `cloudgrid.yaml` in this
+directory (`type: static`) is ONLY for plugging the page as an OWNED static
+runtime (async, local edition only); the fast path is `gridctl_drop`.
+
+The fillable HTML is the real template — fetch it with
+`gridctl_fetch("template", "dashboard")` and fill in the user's content.
+
+## cloudgrid.yaml (reference only)
+
+```yaml
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: dashboard
+services:
+  web:
+    type: static
+    path: /
+```

package/src/corpus/templates/deck/cloudgrid.yaml

@@ -0,0 +1,10 @@
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: deck
+services:
+  web:
+    type: static
+    path: /

package/src/corpus/templates/deck/index.md

@@ -0,0 +1,30 @@
+# Template: deck (static)
+
+A single self-contained HTML deck. **No infrastructure** — no database, no backend,
+no `needs:`. State (if any) lives only in memory and is lost on refresh.
+
+## How it deploys
+
+To publish this page, use **`gridctl_drop`** (or `gridctl_plug` with the inline
+HTML): it deploys as an **inspiration** — instant, and works on the **hosted**
+edition (Claude Web) as well as local. The reference `cloudgrid.yaml` in this
+directory (`type: static`) is ONLY for plugging the page as an OWNED static
+runtime (async, local edition only); the fast path is `gridctl_drop`.
+
+The fillable HTML is the real template — fetch it with
+`gridctl_fetch("template", "deck")` and fill in the user's content.
+
+## cloudgrid.yaml (reference only)
+
+```yaml
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: deck
+services:
+  web:
+    type: static
+    path: /
+```

package/src/corpus/templates/landing-page/cloudgrid.yaml

@@ -0,0 +1,10 @@
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: landing-page
+services:
+  web:
+    type: static
+    path: /

package/src/corpus/templates/landing-page/index.md

@@ -0,0 +1,30 @@
+# Template: landing-page (static)
+
+A single self-contained HTML landing-page. **No infrastructure** — no database, no backend,
+no `needs:`. State (if any) lives only in memory and is lost on refresh.
+
+## How it deploys
+
+To publish this page, use **`gridctl_drop`** (or `gridctl_plug` with the inline
+HTML): it deploys as an **inspiration** — instant, and works on the **hosted**
+edition (Claude Web) as well as local. The reference `cloudgrid.yaml` in this
+directory (`type: static`) is ONLY for plugging the page as an OWNED static
+runtime (async, local edition only); the fast path is `gridctl_drop`.
+
+The fillable HTML is the real template — fetch it with
+`gridctl_fetch("template", "landing-page")` and fill in the user's content.
+
+## cloudgrid.yaml (reference only)
+
+```yaml
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: landing-page
+services:
+  web:
+    type: static
+    path: /
+```

package/src/corpus/templates/report/cloudgrid.yaml

@@ -0,0 +1,10 @@
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: report
+services:
+  web:
+    type: static
+    path: /

package/src/corpus/templates/report/index.md

@@ -0,0 +1,30 @@
+# Template: report (static)
+
+A single self-contained HTML report. **No infrastructure** — no database, no backend,
+no `needs:`. State (if any) lives only in memory and is lost on refresh.
+
+## How it deploys
+
+To publish this page, use **`gridctl_drop`** (or `gridctl_plug` with the inline
+HTML): it deploys as an **inspiration** — instant, and works on the **hosted**
+edition (Claude Web) as well as local. The reference `cloudgrid.yaml` in this
+directory (`type: static`) is ONLY for plugging the page as an OWNED static
+runtime (async, local edition only); the fast path is `gridctl_drop`.
+
+The fillable HTML is the real template — fetch it with
+`gridctl_fetch("template", "report")` and fill in the user's content.
+
+## cloudgrid.yaml (reference only)
+
+```yaml
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: report
+services:
+  web:
+    type: static
+    path: /
+```

package/src/corpus/templates/web-app/cloudgrid.yaml

@@ -0,0 +1,10 @@
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: web-app
+services:
+  web:
+    type: static
+    path: /

package/src/corpus/templates/web-app/index.md

@@ -0,0 +1,30 @@
+# Template: web-app (static)
+
+A single self-contained HTML web-app. **No infrastructure** — no database, no backend,
+no `needs:`. State (if any) lives only in memory and is lost on refresh.
+
+## How it deploys
+
+To publish this page, use **`gridctl_drop`** (or `gridctl_plug` with the inline
+HTML): it deploys as an **inspiration** — instant, and works on the **hosted**
+edition (Claude Web) as well as local. The reference `cloudgrid.yaml` in this
+directory (`type: static`) is ONLY for plugging the page as an OWNED static
+runtime (async, local edition only); the fast path is `gridctl_drop`.
+
+The fillable HTML is the real template — fetch it with
+`gridctl_fetch("template", "web-app")` and fill in the user's content.
+
+## cloudgrid.yaml (reference only)
+
+```yaml
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: web-app
+services:
+  web:
+    type: static
+    path: /
+```

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

@@ -1,6 +1,10 @@
 ---
 name: app-with-data
-when: The user wants an app that SAVES or PERSISTS data, shares state across users/sessions, has accounts/login, stores submissions, or needs a backend/API/database — e.g. a to-do list, a CRUD dashboard, a form that stores entries, a guestbook.
+when: to-do, task list, notes app, guestbook, CRUD app, form that SAVES/STORES submissions, anything that SAVES or PERSISTS data or shares state across users/sessions, sign-in/accounts, a backend/API/database — e.g. a to-do list, a CRUD dashboard, a form that stores entries, a guestbook. Needs a database → runtime → local edition.
+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.
 ---
 

package/src/corpus/workflows/dashboard.md

@@ -1,6 +1,10 @@
 ---
 name: dashboard
-when: The user wants to build a dashboard showing metrics, status, or KPIs with cards and charts.
+when: dashboard, metrics, KPIs, stats page, status board, charts, analytics view — display-only (static data baked in).
+needs: none
+deploy: inspiration
+editions: all
+capabilities_note: static — no infrastructure, data is baked into the page. Publishes as an inspiration (instant, works on hosted) via gridctl_drop.
 summary: Fetch the dashboard template, fill it with the user's metrics and inline charts, deploy it, and return the live share URL.
 ---
 

package/src/corpus/workflows/landing-page.md

@@ -1,6 +1,10 @@
 ---
 name: landing-page
-when: The user wants to build a landing page, marketing page, or product page for something.
+when: landing page, marketing page, product page, hero page, coming-soon, waitlist, pricing page, portfolio, link-in-bio, event page.
+needs: none
+deploy: inspiration
+editions: all
+capabilities_note: static — no infrastructure. Publishes as an inspiration (instant, works on hosted) via gridctl_drop.
 summary: Fetch the landing-page template, fill it with the user's content, deploy it, and return the live share URL.
 ---
 

package/src/corpus/workflows/presentation.md

@@ -1,6 +1,10 @@
 ---
 name: presentation
-when: The user wants to build a presentation, slide deck, or set of slides about a topic.
+when: slides, deck, pitch, presentation, slideshow.
+needs: none
+deploy: inspiration
+editions: all
+capabilities_note: static — no infrastructure. Publishes as an inspiration (instant, works on hosted) via gridctl_drop.
 summary: Fetch the deck template, fill it with the user's content, deploy it, and return the live share URL.
 ---
 

package/src/corpus/workflows/report.md

@@ -1,6 +1,10 @@
 ---
 name: report
-when: The user wants to build a report, one-pager, brief, or write-up with sections and data.
+when: report, one-pager, summary, brief, whitepaper, case study, formatted document.
+needs: none
+deploy: inspiration
+editions: all
+capabilities_note: static — no infrastructure. Publishes as an inspiration (instant, works on hosted) via gridctl_drop.
 summary: Fetch the report template, fill it with the user's content, deploy it, and return the live share URL.
 ---
 

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

@@ -1,6 +1,10 @@
 ---
 name: web-app
-when: The user wants to build a small interactive web app, tool, calculator, or mini single-page application.
+when: calculator, converter, generator, timer, quiz, interactive tool, mini-app, single-page tool, widget — anything computed client-side with no saved data.
+needs: none
+deploy: inspiration
+editions: all
+capabilities_note: static — no infrastructure, state lives only in memory. Publishes as an inspiration (instant, works on hosted) via gridctl_drop.
 summary: Fetch the web-app template, adapt its markup and inline JS to the user's tool, deploy it, and return the live share URL.
 ---
 

package/src/tools.js

@@ -89,6 +89,7 @@ Operating rules:
 9. To modify an existing drop when you don't already have its HTML in context, first call gridctl_source to fetch the current HTML, apply your change, then call gridctl_drop/gridctl_plug with target_entity_id (the drop's entity_id) to update the SAME URL in place. Do not ask the user to paste the HTML back.
 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).
 
 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.`;