@cloudgrid-io/mcp 0.20.20 → 0.20.22

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

@@ -102,7 +102,7 @@ name: web-app
 #   # disk — persistent FS mount (PVC). Injects DISK_PATH. Pins to 1 replica.
 #   #   true | { size: 1Gi, mount: /var/data }  (forbidden: /proc /sys /dev)
 #   disk: true
-#   # ai — AI Gateway via @cloudgrid-io/ai. Injects AI_GATEWAY_URL. true | false.
+#   # ai — AI Gateway via @cloudgrid-io/runtime. Injects RUNTIME_GATEWAY_URL. true | false.
 #   ai: true
 
 
@@ -198,7 +198,7 @@ services:
     #   path: /api/health
     #   expected: "200"
     # Static runtime env vars (strings). Reserved: PORT, APP_NAME, SERVICE_NAME,
-    # NODE_ENV, MONGODB_URL, REDIS_URL, AI_GATEWAY_URL, N8N_WEBHOOK_URL, CLOUDGRID_*.
+    # NODE_ENV, MONGODB_URL, REDIS_URL, RUNTIME_GATEWAY_URL, N8N_WEBHOOK_URL, CLOUDGRID_*.
     # env:
     #   LOG_LEVEL: info
     # Sibling services/private resources that must be Ready first (no cron, no cycles).

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

@@ -4,8 +4,8 @@ when: chatbot, AI assistant, Q&A bot, conversational app, support bot, ask-me-an
 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 }` — now available, #1545 shipped (verified live 2026-07-16); this template ships the plain chatbot without it.)
-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.
+capabilities_note: AI chatbot — needs ai (the grid AI gateway) + a database (Mongo) for chat history. Next.js App Router app. Uses @cloudgrid-io/runtime runtime.ai.chat({ model, messages }) — zero-config in-grid identity (the SDK reads RUNTIME_GATEWAY_URL automatically; chat needs a model; 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 }` — now available, #1545 shipped (verified live 2026-07-16); this template ships the plain chatbot without it.)
+summary: Build an AI chatbot on the grid — a Next.js app that calls @cloudgrid-io/runtime runtime.ai.chat({ model, messages }) (zero-config in-grid auth, reads RUNTIME_GATEWAY_URL, 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
@@ -80,15 +80,19 @@ ai: true, database: true }`).
    (`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:
+3. **Call the AI gateway with `@cloudgrid-io/runtime`** — 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
+   import { runtime } from "@cloudgrid-io/runtime";
+   // Chat expects a model and returns { text }. No key, no baseURL.
+   const { text: reply } = await runtime.ai.chat({
+     model: "claude-haiku",
+     messages: [{ role: "user", content: 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`).
+   The SDK reads `RUNTIME_GATEWAY_URL` (injected by the grid) and the in-grid
+   identity automatically — **do NOT set an API key or reference the env var.**
+   `chat` needs a `model`. 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

package/src/corpus/workflows/ai-knowledge-base.md

@@ -5,7 +5,7 @@ needs: ai+database
 deploy: runtime
 editions: local
 kind: blueprint
-capabilities_note: "persistent RAG — needs ai + database. Runtime app, async build, local edition only. Declare needs:{ai:true, database:true}; the deployer injects AI_GATEWAY_URL (AI Gateway via @cloudgrid-io/ai — works today) and DATABASE_MONGODB_URL (+legacy MONGODB_URL). The ideal embedding store needs:{vector:pgvector} (VECTOR_PGVECTOR_URL) is now AVAILABLE — #1545 shipped (verified live 2026-07-16) — but this blueprint still stores embeddings in a Mongo `chunks` collection and cosine-ranks in-app; declare vector:pgvector only if you also build the retrieval on pgvector."
+capabilities_note: "persistent RAG — needs ai + database. Runtime app, async build, local edition only. Declare needs:{ai:true, database:true}; the deployer injects RUNTIME_GATEWAY_URL (AI Gateway via @cloudgrid-io/runtime — works today) and DATABASE_MONGODB_URL (+legacy MONGODB_URL). The ideal embedding store needs:{vector:pgvector} (VECTOR_PGVECTOR_URL) is now AVAILABLE — #1545 shipped (verified live 2026-07-16) — but this blueprint still stores embeddings in a Mongo `chunks` collection and cosine-ranks in-app; declare vector:pgvector only if you also build the retrieval on pgvector."
 summary: "A BLUEPRINT for a retrieval-augmented 'ask my docs' knowledge base — ingest documents, chunk + embed them, retrieve the nearest chunks per question, and answer grounded with citations, on persistent Next.js + Mongo + the CloudGrid AI Gateway. This is not fill-in-the-blanks app code; it ships structure + cloudgrid.yaml. Fetch the template, read AGENTS.md for the file tree / collections / RAG loop / CloudGrid wiring (needs ai+database, the pgvector note — #1545 shipped), then BUILD the app under services/web/ following it, and deploy async to a live URL (local edition only)."
 ---
 
@@ -18,7 +18,7 @@ grid's shared Mongo) with a **RAG loop**: ingest documents → chunk → embed
 → at query time embed the question, retrieve the nearest chunks, and ask the model
 to answer using only those. It is the `app-with-data` shape plus embeddings +
 retrieval + a grounded answer step. Both the embedding and answer calls run through
-CloudGrid's **AI Gateway** (`@cloudgrid-io/ai`).
+CloudGrid's **AI Gateway** (`@cloudgrid-io/runtime`).
 
 **This is a BLUEPRINT.** Unlike a fill-in-the-blanks template, it ships
 *structure* — a `cloudgrid.yaml` and an `AGENTS.md` structure guide — not finished
@@ -85,7 +85,7 @@ needs:
 
 **App code MUST live under `services/<name>/`** — `path:` is the URL mount, NOT
 the filesystem path. **Declare `needs: { ai: true, database: true }`** (canonical)
-— the deployer injects `AI_GATEWAY_URL` (routed through `@cloudgrid-io/ai`, no API
+— the deployer injects `RUNTIME_GATEWAY_URL` (routed through `@cloudgrid-io/runtime`, no API
 key) and provisions Mongo, injecting `DATABASE_MONGODB_URL` (+ legacy
 `MONGODB_URL`). `requires:` is the deprecated v1 alias; never author it and never
 set `needs:` and `requires:` together (the validator rejects the combination).
@@ -96,24 +96,27 @@ embeddings.
 ## 5. Build the app following AGENTS.md
 
 Generate the files under `services/web/` per the guide:
-- **Lazy getters** for injected values — read `process.env.DATABASE_MONGODB_URL`
-  (legacy `MONGODB_URL` fallback) in `lib/db.js` and `process.env.AI_GATEWAY_URL`
-  in `lib/ai.js`, **inside** a getter, never at module top level (a top-level read
-  fails `next build`).
+- **Lazy Mongo getter** — read `process.env.DATABASE_MONGODB_URL` (legacy
+  `MONGODB_URL` fallback) in `lib/db.js` **inside** a getter, never at module top
+  level (a top-level read fails `next build`). `lib/ai.js` just imports
+  `@cloudgrid-io/runtime` — the SDK reads `RUNTIME_GATEWAY_URL` itself, so there is
+  no env var to read (and none to set).
 - **Ingest** (`POST /api/documents`): chunk the text (`lib/chunk.js`), `embed()`
-  the chunks via the AI Gateway, store one `chunks` doc per chunk with its
-  `embedding` array, mark the `documents` doc `ready`.
+  the chunks via `runtime.ai.embeddings({ text })` (batch; `vec.values`), store one
+  `chunks` doc per chunk with its `embedding` array, mark the `documents` doc
+  `ready`.
 - **Retrieve** (`lib/retrieve.js`): embed the question, cosine-rank the Mongo
   `chunks`, return top-k `{ text, documentId, score }` — a pure function that swaps
   cleanly to a pgvector query (now available — #1545 shipped).
 - **Answer** (`POST /api/ask`): retrieve top-k, prompt the model to answer ONLY
-  from the provided context and to cite the chunks, `chat()` via the AI Gateway,
-  return the answer plus source chunks so the UI shows **citations**.
+  from the provided context and to cite the chunks, `runtime.ai.chat({ model,
+  system, messages })` via the AI Gateway (chat needs a model; it returns
+  `{ text }`), return the answer plus source chunks so the UI shows **citations**.
 
 ## 6. Config / secrets
 
 - The AI Gateway and Mongo need **no secrets** — they are injected by `needs:`. Do
-  **NOT** set `AI_GATEWAY_URL`, `DATABASE_MONGODB_URL`, or legacy `MONGODB_URL`
+  **NOT** set `RUNTIME_GATEWAY_URL`, `DATABASE_MONGODB_URL`, or legacy `MONGODB_URL`
   yourself; the grid injects them.
 - Only if you add auth/payments: map the secret in the `vault:` block
   (`AUTH_PROVIDER_KEY` and/or `STRIPE_KEY`) and store the value with

package/src/tools/constants.js

@@ -68,7 +68,7 @@ export const CLI_NPX_PKG = "@cloudgrid-io/cli@latest";
 // server-side with HTTP 426) — a gate below the floor green-lights CLIs the API
 // rejects on every call (issue #59). Bump this in lockstep with every floor
 // raise (CLI release protocol checklist).
-export const MIN_CLI_VERSION = "0.15.2";
+export const MIN_CLI_VERSION = "0.15.14";
 
 // Upload/create POST budget. The build itself is async (server returns 202 +
 // poll_url); this bounds only the request→response, so a stalled server errors

package/src/tools/register.js

@@ -28,6 +28,21 @@ import {
   runSource,
 } from "./deploy.js";
 
+// Build the argv for grid_create_project → `grid new` (CLI >= 0.15.14; `init`
+// is a deprecated alias we no longer author). Modern shape: `new <slug>` with
+// `--agent` for agents (NOT the legacy `init <kind> <slug>` positional). The
+// old `--description` flag was removed from the CLI, so it is gone here too.
+// Exported pure so the argv is unit-tested without spawning a CLI.
+export function buildCreateProjectArgs({ kind, name, type, needs, dir, org } = {}) {
+  const args = ["new", name];
+  if (kind === "agent") args.push("--agent");
+  if (type) args.push("--type", type);
+  if (Array.isArray(needs) && needs.length) args.push("--needs", needs.join(","));
+  if (dir) args.push("--dir", dir);
+  if (org) args.push("--grid", org); // CLI 0.12 dropped --org for --grid (same slug)
+  return args;
+}
+
 // ── Registration ───────────────────────────────────────────────────────────────
 // Registers the tools onto `server`. ctx.edition decides whether the CLI-wrapping
 // tools are included (they need a local machine).
@@ -861,26 +876,19 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_create_project",
-    "Register a new CloudGrid app or agent, optionally seeding a web service. Wraps `grid new` (`init` remains an alias).",
+    "Scaffold a new CloudGrid app or agent folder (cloudgrid.yaml + a web service), optionally pre-declaring resources. Wraps `grid new` (scaffolds locally; no server entity until you grid_deploy).",
     {
-      kind: z.enum(["app", "agent"]).describe("Entity kind."),
+      kind: z.enum(["app", "agent"]).describe("Entity kind. 'agent' scaffolds an agent: block."),
       name: z.string().describe("Slug: 3-40 lowercase alphanumerics and hyphens."),
       type: z.enum(["node", "nextjs", "python", "static"]).optional().describe("Seed a web service of this type."),
-      description: z.string().optional().describe("Initial one-line description."),
-      dir: z.string().optional().describe("Target directory. Defaults to ./<name>."),
-      org: z.string().optional().describe("Override the active grid for this project."),
+      needs: z.array(z.enum(["database", "cache", "kv", "queue", "pubsub", "vector", "ai", "disk"])).optional()
+        .describe("Pre-declare infrastructure needs in the scaffolded cloudgrid.yaml (e.g. [\"database\",\"ai\"])."),
+      dir: z.string().optional().describe("Target directory. Defaults to the current folder."),
+      org: z.string().optional().describe("Override the active grid this project will target."),
       cwd: z.string().optional().describe("Working directory. The CLI runs in this directory. Defaults to the MCP server's working directory."),
     },
     { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
-    cliTool(({ kind, name, type, description, dir, org }) => {
-      const args = ["init", kind, name];
-      if (type) args.push("--type", type);
-      if (description) args.push("--description", description);
-      if (dir) args.push("--dir", dir);
-      // CLI 0.12 dropped `--org` in favour of `--grid` (same slug).
-      if (org) args.push("--grid", org);
-      return args;
-    }, { cwdParam: true }),
+    cliTool((input) => buildCreateProjectArgs(input), { cwdParam: true }),
   );
 
   // NOTE: grid_deploy is no longer CLI-wrapping — the unified direct-API verb

package/src/tools.js

@@ -36,5 +36,5 @@ export {
   runFork,
   runSource,
 } from "./tools/deploy.js";
-export { registerTools } from "./tools/register.js";
+export { registerTools, buildCreateProjectArgs } from "./tools/register.js";
 export { decodeJwt } from "./auth.js";