@cloudgrid-io/mcp 0.11.2 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.11.2",
+  "version": "0.13.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:archetypes": "node test/archetypes.test.mjs",
     "test:self-describing": "node test/self-describing.test.mjs",
     "test:canonical-yaml": "node test/canonical-yaml.test.mjs",
     "test:content": "node test/content-handling.test.mjs",

package/src/corpus/capability-map.md

@@ -13,20 +13,53 @@ cloudgrid.yaml schema (every field, the `needs:` injection table, the
 requires-vs-needs caveat, validation rules), fetch the companion reference:
 `gridctl_fetch("doc", "cloudgrid-yaml")`.
 
-## The 6 templates
+## The 19 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 |
+| landing page, marketing/product/hero page, coming-soon, link-in-bio, event page — a single-section page | `landing-page` | none | inspiration (instant) | all |
+| SaaS marketing site, product marketing page, features + pricing page — multi-section with pricing tiers, testimonials, FAQ | `saas-marketing` | none | inspiration (instant) | all |
+| documentation site, docs, developer docs, guide, manual, knowledge base — prose docs with sidebar + search | `docs-site` | none | inspiration (instant) | all |
+| API documentation, API reference, endpoint docs, REST API docs — method badges, params tables, request/response examples | `api-docs` | none | inspiration (instant) | all |
+| status page, service status, uptime page, incident history, is-it-down page — display-only, status baked in | `status-page` | none | inspiration (instant) | all |
+| changelog, release notes, what's new, product updates, version history | `changelog` | none | inspiration (instant) | all |
+| portfolio, personal site, freelancer site, my work, showcase — projects grid + about + skills + contact | `portfolio` | none | inspiration (instant) | all |
+| waitlist, coming soon, early access, join the list, launch page — email capture form (form is static; storing signups needs a runtime crud-app) | `waitlist` | 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 |
+| CRM, contacts, leads, sales pipeline, customer manager, deal tracker | `crm` | `database: true` | runtime (async, poll) | local |
+| kanban board, task board, trello-style board, workflow columns | `kanban` | `database: true` | runtime (async, poll) | local |
+| task manager, to-do app (richer than the app-with-data starter), task list with due dates/priorities | `task-manager` | `database: true` | runtime (async, poll) | local |
+| admin dashboard, admin panel, back-office, CRUD admin, manage records | `admin-dashboard` | `database: true` | runtime (async, poll) | local |
+| 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 | `api-service` | `database: true` | runtime (async, poll) | local |
+| chatbot, AI assistant, Q&A bot, conversational app, support bot, ask-me-anything, an app that talks to an LLM / generates text with AI | `ai-app` | `ai: true, 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.
+users/sessions, log in, or store submissions → it is persistent → runtime, local
+edition. Pick by shape: a full web UI → `app-with-data`; a plain backend/JSON API
+(no UI) → `api-service`; an app that talks to an LLM → `ai-app` (adds `ai:`).
+Otherwise a static template deploys instantly anywhere.
+
+**The DB-CRUD family.** `crm`, `kanban`, `task-manager`, and `admin-dashboard`
+all share the exact `app-with-data` shape (nextjs + `needs: { database: true }`,
+app under `services/web/`, lazy Mongo getter, force-dynamic App-Router routes) —
+they differ only by domain schema + UI. Match the request to the closest one by
+its `when:`; if it is a bare to-do or generic "save this data" with no specific
+domain, use `app-with-data` (the minimal reference). Deploy path is identical for
+all five.
+
+## Held / pending platform (not yet buildable)
+
+Two more archetypes are designed but blocked on platform work — the LLM should
+know they are coming but must NOT author them yet:
+
+| Intent | Would need | Status |
+|---|---|---|
+| scheduled task, cron job, "run every day/hour", periodic worker | a `type: cron` service (`schedule`, `timezone`) | **HELD** — platform issue #1543 (cron entities crash the online-check). Do not build. |
+| RAG chatbot, "answer over my own docs", semantic search, retrieval-augmented Q&A | `ai-app` + `needs: { vector: pgvector }` | **HELD** — platform issue #1545 (pgvector crashes the deploy). Ship the plain `ai-app` (no vector) for now. |
 
 ## The full `needs:` vocabulary (the whole menu)
 
@@ -65,8 +98,9 @@ engine hint. Cron is NOT a need — it is a **service type** (`type: cron` with
 ## 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`.)
+2. Adopt that template's `needs:`. Persistence → `database` (`app-with-data` or
+   `api-service`); talks to an LLM → `ai: true` + `database` (`ai-app`). (Held for
+   now: scheduled → a `cron` service, #1543; RAG → `vector: pgvector`, #1545.)
 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/examples/ai-app/index.md

@@ -0,0 +1,237 @@
+# Example: ai-app — "Trip Planner Bot"
+
+A filled reference imitating the `ai-app` template: a themed AI assistant — a
+travel trip planner. Same stack (Next.js App Router + `@cloudgrid-io/ai` for the
+grid AI gateway + the `mongodb` driver for chat history), slightly richer than
+the bare chatbot: it gives the assistant a **persona** via a `system` message and
+sends the **prior conversation** as context, so replies stay on-theme and
+coherent across turns.
+
+Data persists in the grid-shared Mongo, so the conversation survives refresh.
+
+**Same four proven rules as the template:** (1) app code lives under
+**`services/web/`** (the service name, NOT the repo root — `path:` is the URL
+mount); (2) the AI call is **zero-config — `createClient()` with no key** (it
+uses the in-grid identity); (3) the DB connection string is read **lazily inside
+the `getDb` getter**, never at module top level (a top-level read fails `next
+build`); (4) the datastore is declared with the canonical **`needs: { ai: true,
+database: true }`**. Don't use the deprecated `requires:` alias.
+
+## cloudgrid.yaml
+
+```yaml
+# `needs: { ai: true, database: true }` is canonical: the deployer wires the AI
+# gateway (in-grid identity — no key) and provisions Mongo, injecting
+# DATABASE_MONGODB_URL (plus the legacy MONGODB_URL alias). `requires:` is the
+# deprecated v1 alias — don't mix the two (the validator rejects it).
+name: trip-planner-bot
+services:
+  web:
+    type: nextjs
+    path: /
+needs:
+  ai: true
+  database: true
+# RAG over your own docs needs `needs: { vector: pgvector }` — not yet available
+# (platform issue #1545).
+```
+
+## services/web/package.json
+
+```json
+{
+  "name": "trip-planner-bot",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": { "dev": "next dev", "build": "next build", "start": "next start" },
+  "dependencies": {
+    "next": "^15.1.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@cloudgrid-io/ai": "^0.2.0",
+    "mongodb": "^6.12.0"
+  }
+}
+```
+
+## services/web/lib/db.js
+
+```js
+// Cached Mongo client for the chat history. The grid injects DATABASE_MONGODB_URL
+// (plus the legacy MONGODB_URL alias) at dev + runtime. Resolve it LAZILY inside
+// the getter — a top-level read fails `next build`. Never hardcode a connection
+// string; never commit a secret.
+import { MongoClient } from "mongodb";
+
+function clientPromise() {
+  const uri = process.env.DATABASE_MONGODB_URL || process.env.MONGODB_URL;
+  if (!uri) {
+    throw new Error(
+      "DATABASE_MONGODB_URL is not set. The grid injects it — run `grid dev` " +
+        "locally or deploy with `grid plug`. Do not set it by hand.",
+    );
+  }
+  if (!globalThis.__mongoClientPromise) {
+    globalThis.__mongoClientPromise = new MongoClient(uri).connect();
+  }
+  return globalThis.__mongoClientPromise;
+}
+
+export async function getDb() {
+  return (await clientPromise()).db();
+}
+```
+
+## services/web/app/api/chat/route.js
+
+```js
+// Trip-planner chat route: give the assistant a persona, send the prior
+// conversation as context, ask the grid AI gateway, persist the exchange,
+// return the reply. Zero-config AI — createClient() with no key uses the in-grid
+// identity.
+import { NextResponse } from "next/server";
+import { createClient } from "@cloudgrid-io/ai";
+import { getDb } from "../../../lib/db.js";
+
+export const dynamic = "force-dynamic";
+
+const SYSTEM = {
+  role: "system",
+  content:
+    "You are Trip Planner Bot, a concise, friendly travel assistant. Suggest " +
+    "itineraries, budgets, and practical tips. Ask a clarifying question when the " +
+    "destination or dates are unclear.",
+};
+
+async function messages() {
+  return (await getDb()).collection("messages");
+}
+
+export async function POST(request) {
+  const body = await request.json().catch(() => ({}));
+  const text = typeof body.message === "string" ? body.message.trim() : "";
+  if (!text) return NextResponse.json({ error: "message is required" }, { status: 400 });
+
+  const col = await messages();
+
+  // Load recent history for context (last 20 turns), oldest first.
+  const prior = await col.find({}).sort({ createdAt: -1 }).limit(20).toArray();
+  prior.reverse();
+  const context = prior.map((m) => ({ role: m.role, content: m.content }));
+
+  // Ask the grid AI gateway: persona + prior turns + the new user message.
+  const client = createClient();
+  const r = await client.chat({
+    messages: [SYSTEM, ...context, { role: "user", content: text }],
+  });
+  const reply = r.text ?? r.content ?? "";
+
+  // Persist the exchange.
+  const now = new Date();
+  await col.insertMany([
+    { role: "user", content: text, createdAt: now },
+    { role: "assistant", content: reply, createdAt: new Date(now.getTime() + 1) },
+  ]);
+
+  return NextResponse.json({ reply });
+}
+
+export async function GET() {
+  const col = await messages();
+  const history = await col.find({}).sort({ createdAt: 1 }).toArray();
+  return NextResponse.json(
+    history.map((m) => ({ id: m._id.toString(), role: m.role, content: m.content })),
+  );
+}
+```
+
+## services/web/app/page.js
+
+```js
+import { getDb } from "../lib/db.js";
+import Chat from "./chat.js";
+
+export const dynamic = "force-dynamic";
+
+async function listHistory() {
+  const items = await (await getDb())
+    .collection("messages")
+    .find({})
+    .sort({ createdAt: 1 })
+    .toArray();
+  return items.map((m) => ({ id: m._id.toString(), role: m.role, content: m.content }));
+}
+
+export default async function Page() {
+  const history = await listHistory();
+  return (
+    <main>
+      <h1>Trip Planner Bot</h1>
+      <p className="hint">Ask about a destination — powered by the grid AI gateway, saved to Mongo.</p>
+      <Chat initialHistory={history} />
+    </main>
+  );
+}
+```
+
+## services/web/app/chat.js
+
+```js
+"use client";
+import { useState } from "react";
+
+export default function Chat({ initialHistory }) {
+  const [history, setHistory] = useState(initialHistory);
+  const [text, setText] = useState("");
+  const [busy, setBusy] = useState(false);
+
+  async function send(e) {
+    e.preventDefault();
+    const value = text.trim();
+    if (!value || busy) return;
+    setBusy(true);
+    setHistory((p) => [...p, { id: `local-${Date.now()}`, role: "user", content: value }]);
+    setText("");
+    const res = await fetch("/api/chat", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ message: value }),
+    });
+    if (res.ok) {
+      const { reply } = await res.json();
+      setHistory((p) => [...p, { id: `local-${Date.now()}-a`, role: "assistant", content: reply }]);
+    }
+    setBusy(false);
+  }
+
+  return (
+    <div>
+      <ul className="log">
+        {history.length === 0 && <li className="empty">Where do you want to go?</li>}
+        {history.map((m) => (
+          <li key={m.id} className={m.role}>
+            <span className="who">{m.role === "user" ? "You" : "Trip Planner"}</span>
+            <span className="msg">{m.content}</span>
+          </li>
+        ))}
+      </ul>
+      <form onSubmit={send} className="row">
+        <input value={text} onChange={(e) => setText(e.target.value)} placeholder="e.g. 4 days in Lisbon on a budget" disabled={busy} />
+        <button type="submit" disabled={busy}>{busy ? "…" : "Send"}</button>
+      </form>
+    </div>
+  );
+}
+```
+
+## Notes
+
+- Deploy the same way as the template: `grid dev` locally, `grid plug` to deploy
+  (async — poll status to a live URL). Re-plug the same entity to keep one URL.
+- The needs are Mongo + the AI gateway (`needs: { ai: true, database: true }`).
+  The AI call is zero-config — `createClient()` with no key uses the in-grid
+  identity.
+- All app code lives under `services/web/`; the connection is read lazily inside
+  `getDb`, never at module top level.
+- To answer over your own documents (RAG) you'd add `needs: { vector: pgvector }`
+  — not yet available (platform issue #1545).

package/src/corpus/examples/api-service/index.md

@@ -0,0 +1,190 @@
+# Example: api-service — "Notes API"
+
+A filled reference imitating the `api-service` template: a small REST/JSON
+backend for notes. Same stack (a plain Node `http` server + the `mongodb`
+driver, grid-shared Mongo via `process.env.DATABASE_MONGODB_URL`), slightly
+richer than the bare items template — notes have a `title` and a `body`, and the
+API supports fetching a single note and updating it via PUT.
+
+Data persists in the grid-shared Mongo, so every caller sees the same notes
+across sessions and refresh.
+
+**Same four proven rules as the template:** (1) service code lives under
+**`services/api/`** (the service name, NOT the repo root — `path:` is the URL
+mount); (2) the DB connection string is read **lazily inside the `getClient`
+getter**, never at module top level (a top-level read crashes node startup); (3)
+the datastore is declared with the canonical **`needs: { database: true }`** —
+the deployer provisions Mongo and injects `DATABASE_MONGODB_URL` (plus the legacy
+`MONGODB_URL` alias); (4) the server listens on **`process.env.PORT || 8080`**.
+Don't use the deprecated `requires:` alias.
+
+## cloudgrid.yaml
+
+```yaml
+# `needs: { database: true }` is canonical: the deployer provisions Mongo and
+# injects DATABASE_MONGODB_URL (plus the legacy MONGODB_URL alias). `requires:`
+# is the deprecated v1 alias — don't mix the two (the validator rejects it).
+# Plain Node HTTP service; code lives under services/api/.
+name: notes-api
+services:
+  api:
+    type: node
+    path: /
+needs:
+  database: true
+```
+
+## services/api/package.json
+
+```json
+{
+  "name": "api",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "src/index.js",
+  "scripts": { "start": "node src/index.js" },
+  "dependencies": { "mongodb": "^6.12.0" }
+}
+```
+
+## services/api/src/index.js
+
+```js
+// Notes REST API backed by grid-shared Mongo.
+//   GET    /notes        -> list notes (newest first)
+//   POST   /notes        -> create a note; body { title, body }
+//   GET    /notes/:id    -> fetch one note
+//   PUT    /notes/:id    -> update a note; body { title?, body? }
+//   DELETE /notes/:id    -> remove a note
+//
+// The grid injects DATABASE_MONGODB_URL (plus the legacy MONGODB_URL alias) at
+// dev + runtime. The env var and Mongo client are resolved LAZILY inside
+// getClient, never at module top level — a top-level read crashes node startup
+// before the grid injects the var. Never hardcode a connection string or secret.
+import { createServer } from "node:http";
+import { MongoClient, ObjectId } from "mongodb";
+
+let clientPromise;
+
+function getClient() {
+  const uri = process.env.DATABASE_MONGODB_URL || process.env.MONGODB_URL;
+  if (!uri) {
+    throw new Error(
+      "DATABASE_MONGODB_URL is not set. The grid injects it — run `grid dev` " +
+        "locally or deploy with `grid plug`. Do not set it by hand.",
+    );
+  }
+  if (!clientPromise) clientPromise = new MongoClient(uri).connect();
+  return clientPromise;
+}
+
+async function notes() {
+  return (await getClient()).db().collection("notes");
+}
+
+function sendJson(res, status, body) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, {
+    "content-type": "application/json",
+    "content-length": Buffer.byteLength(payload),
+  });
+  res.end(payload);
+}
+
+function readBody(req) {
+  return new Promise((resolve) => {
+    let data = "";
+    req.on("data", (c) => {
+      data += c;
+      if (data.length > 1_000_000) req.destroy();
+    });
+    req.on("end", () => {
+      try {
+        resolve(data ? JSON.parse(data) : {});
+      } catch {
+        resolve(null);
+      }
+    });
+    req.on("error", () => resolve(null));
+  });
+}
+
+function shape(n) {
+  return { id: n._id.toString(), title: n.title, body: n.body, updatedAt: n.updatedAt };
+}
+
+async function handle(req, res) {
+  const url = new URL(req.url, "http://localhost");
+  const parts = url.pathname.split("/").filter(Boolean); // ["notes"] or ["notes", "<id>"]
+  const col = await notes();
+
+  if (parts[0] !== "notes") return sendJson(res, 404, { error: "not found" });
+
+  // Collection: /notes
+  if (parts.length === 1) {
+    if (req.method === "GET") {
+      const list = await col.find({}).sort({ updatedAt: -1 }).toArray();
+      return sendJson(res, 200, list.map(shape));
+    }
+    if (req.method === "POST") {
+      const body = await readBody(req);
+      if (body === null) return sendJson(res, 400, { error: "invalid JSON body" });
+      const title = typeof body.title === "string" ? body.title.trim() : "";
+      if (!title) return sendJson(res, 400, { error: "title is required" });
+      const doc = { title, body: typeof body.body === "string" ? body.body : "", updatedAt: new Date() };
+      const { insertedId } = await col.insertOne(doc);
+      return sendJson(res, 201, shape({ _id: insertedId, ...doc }));
+    }
+    return sendJson(res, 405, { error: "method not allowed" });
+  }
+
+  // Item: /notes/:id
+  const id = parts[1];
+  if (!ObjectId.isValid(id)) return sendJson(res, 400, { error: "invalid id" });
+  const _id = new ObjectId(id);
+
+  if (req.method === "GET") {
+    const note = await col.findOne({ _id });
+    if (!note) return sendJson(res, 404, { error: "note not found" });
+    return sendJson(res, 200, shape(note));
+  }
+  if (req.method === "PUT") {
+    const body = await readBody(req);
+    if (body === null) return sendJson(res, 400, { error: "invalid JSON body" });
+    const $set = { updatedAt: new Date() };
+    if (typeof body.title === "string") $set.title = body.title.trim();
+    if (typeof body.body === "string") $set.body = body.body;
+    const r = await col.findOneAndUpdate({ _id }, { $set }, { returnDocument: "after" });
+    if (!r) return sendJson(res, 404, { error: "note not found" });
+    return sendJson(res, 200, shape(r));
+  }
+  if (req.method === "DELETE") {
+    const { deletedCount } = await col.deleteOne({ _id });
+    if (deletedCount === 0) return sendJson(res, 404, { error: "note not found" });
+    return sendJson(res, 200, { ok: true });
+  }
+  return sendJson(res, 405, { error: "method not allowed" });
+}
+
+const server = createServer((req, res) => {
+  handle(req, res).catch((err) => {
+    console.error(err);
+    if (!res.headersSent) sendJson(res, 500, { error: "internal server error" });
+  });
+});
+
+const port = process.env.PORT || 8080;
+server.listen(port, () => console.log(`notes-api listening on :${port}`));
+```
+
+## Notes
+
+- Deploy the same way as the template: `grid dev` locally, `grid plug` to deploy
+  (async — poll status to a live URL). Re-plug the same entity to keep one URL.
+- The only store this needs is Mongo (`needs: { database: true }` — the deployer
+  provisions Mongo and injects `DATABASE_MONGODB_URL`, plus the legacy
+  `MONGODB_URL` alias). Add more `needs:` only for infra you actually use.
+- All service code lives under `services/api/`; the connection is read lazily
+  inside `getClient`, never at module top level; the server listens on
+  `process.env.PORT || 8080`.