@cloudgrid-io/mcp 0.20.6 → 0.20.8

package/src/corpus/templates/semantic-search/AGENTS.md

@@ -77,12 +77,12 @@ os.environ.get("MONGODB_URL")` inside `get_client()`, never at module top level.
 `requires:` together (the validator rejects the combination).
 
 **No `needs: vector`.** The ideal embedding store is pgvector
-(`needs: { vector: pgvector }` → `VECTOR_PGVECTOR_URL`), but the runtime
-role-grant is **blocked on platform issue #1545**. Until it lands, embeddings live
-in the Mongo `chunks.embedding` float array and are cosine-ranked in-app
-(`search.py::_cosine`). When #1545 ships, move the vectors to pgvector and replace
-the in-app cosine block with an `ORDER BY embedding <=> $q LIMIT k` query — the
-rest of the pipeline is unchanged.
+(`needs: { vector: pgvector }` → `VECTOR_PGVECTOR_URL`), and it is **now
+available** — #1545 shipped (verified live 2026-07-16). This template still keeps
+embeddings in the Mongo `chunks.embedding` float array and cosine-ranks in-app
+(`search.py::_cosine`). To swap, move the vectors to pgvector and replace the
+in-app cosine block with an `ORDER BY embedding <=> $q LIMIT k` query — the rest
+of the pipeline is unchanged.
 
 ---
 
@@ -155,9 +155,9 @@ to store the same way. Non-secret public config can also go via `grid env`.
    source or embeddings are unconfigured. `GET /backend/status` reports capability
    **booleans** (`source_configured`, `embeddings_configured`, …), never secret
    values.
-4. **No `needs: vector`.** `needs:` is `database` only — pgvector's runtime
-   role-grant is still blocked (#1545). (The scheduled cron refresh IS active — see
-   §8.)
+4. **No `needs: vector`.** `needs:` is `database` only — the pgvector need is
+   available (#1545 shipped), but this template's code uses Mongo embeddings (§3
+   for the swap). (The scheduled cron refresh IS active — see §8.)
 
 ---
 

package/src/corpus/templates/semantic-search/README.md

@@ -17,9 +17,10 @@ aggregated to the document level with a best-passage highlight.
 | `backend` | `python` (FastAPI) | `/backend` | `services/backend/src/main.py` |
 
 `needs: { database: true }` → CloudGrid injects `DATABASE_MONGODB_URL` (fallback
-`MONGODB_URL`). **No `needs: vector`** — pgvector runtime role-grant is blocked
-(platform #1545), so embeddings live in the Mongo `chunks` collection and are
-cosine-ranked in-app. Refresh runs two ways: the manager "Refresh now" endpoint
+`MONGODB_URL`). **No `needs: vector`** — the need is available now (#1545
+shipped, verified live 2026-07-16), but this template stores embeddings in the
+Mongo `chunks` collection and cosine-ranks in-app; declare `vector: pgvector`
+only if you also switch the code to pgvector. Refresh runs two ways: the manager "Refresh now" endpoint
 (on demand) and an active Python `type: cron` job (`services/refresh/`, daily 03:00
 UTC) — both call the same `indexing.run_sync` (see AGENTS.md §8).
 

package/src/corpus/templates/semantic-search/cloudgrid.yaml

@@ -89,9 +89,9 @@ name: semantic-search
 #   pubsub: true
 #   # vector — pgvector on Postgres. Injects VECTOR_PGVECTOR_URL (+ PGVECTOR_URL).
 #   #   true | pgvector | { engine: pgvector, dim: 1536 }
-#   #   NOT USED HERE — pgvector runtime role-grant is blocked (platform #1545).
-#   #   This template stores embeddings in the Mongo `chunks` collection and
-#   #   cosine-ranks in-app instead. Swap to `vector: pgvector` once #1545 lands.
+#   #   NOT USED HERE — available now (#1545 shipped). This template stores
+#   #   embeddings in the Mongo `chunks` collection and cosine-ranks in-app.
+#   #   Uncomment `vector: pgvector` only if you also switch the code to pgvector.
 #   vector: pgvector
 #   # object_storage — GCS bucket. Injects OBJECT_STORAGE_GCS_BUCKET, _GCS_REGION.
 #   #   true | { size: 10Gi }
@@ -204,8 +204,9 @@ services:
     timezone: UTC
     run: job                    # batch job — runs services/refresh/src/main.py once
 # CloudGrid managed Mongo → injects DATABASE_MONGODB_URL (+ legacy MONGODB_URL).
-# NO `needs: vector` — pgvector runtime role-grant is still blocked (#1545);
-# embeddings live in the Mongo `chunks` collection and are cosine-ranked in-app.
+# NO `needs: vector` — available now (#1545 shipped), but this template stores
+# embeddings in the Mongo `chunks` collection and cosine-ranks in-app;
+# uncomment `vector: pgvector` only if you also switch the code to pgvector.
 needs:
   database: true
 

package/src/corpus/templates/semantic-search/index.md

@@ -24,9 +24,11 @@ level with a best-passage highlight.
    `$text` index exists at boot — `$text` returns `[]` on an empty catalog rather
    than raising `IndexNotFound` (a 500). The `$text` query is also guarded in
    `except OperationFailure` as belt-and-suspenders.
-5. **No `needs: vector`** — pgvector runtime role-grant is blocked (#1545), so
-   embeddings live in the Mongo `chunks` collection (a float array) and are
-   cosine-ranked in-app. **The refresh cron IS active** — a Python `type: cron`,
+5. **No `needs: vector`** — the need is available now (#1545 shipped, verified
+   live 2026-07-16), but this
+   template stores embeddings in the Mongo `chunks` collection (a float array)
+   and cosine-ranks in-app; declare `vector: pgvector` only if you also switch
+   the code to pgvector. **The refresh cron IS active** — a Python `type: cron`,
    `run: job` service (`services/refresh/`) reindexes daily at 03:00 UTC, and the
    manager "Refresh now" endpoint reindexes on demand; both call the same
    `indexing.run_sync` (the cron vendors the backend `app/` modules — see AGENTS.md §8).
@@ -86,7 +88,8 @@ needs:
 
 > **Capability:** the need is `database: true` — the deployer provisions Mongo and
 > injects `DATABASE_MONGODB_URL` (+ legacy `MONGODB_URL`). NO `needs: vector`
-> (#1545). Three services: `web` (static), `backend` (python), `refresh` (cron).
+> (available, #1545 shipped — this template uses Mongo embeddings). Three
+> services: `web` (static), `backend` (python), `refresh` (cron).
 > `requires:` is the deprecated v1 alias — don't mix it with `needs:`.
 
 ## Configure + deploy

package/src/corpus/templates/simple-semantic-search/README.md

@@ -0,0 +1,20 @@
+# simple-semantic-search
+
+Semantic search over a document in one node service, on the CloudGrid managed
+vector substrate. `needs: { vector: pgvector }` provisions pgvector and injects
+`VECTOR_PGVECTOR_URL`; `needs: { ai: true }` gives embeddings through
+`@cloudgrid-io/runtime` with no API key. On startup the service embeds
+`document.txt` (one vector per paragraph) into a `chunks` table sized from a
+probe embedding, then `POST /search` embeds the query and returns the nearest
+passages by cosine distance. `/health` returns 503 until the seed finishes, so
+the platform holds the pod out of traffic until search works.
+
+Proven by a real end-to-end deploy (live in under 3 minutes, 2026-07-16).
+
+- Deploy: `grid init app <name> --here`, then `grid plug`.
+- The CLI writes `.cloudgrid/link.json` (folder ↔ entity binding) — never
+  hand-author it; `rm -rf .cloudgrid` + re-init to take a copied folder as your
+  own app.
+- Replace `services/web/src/document.txt` with the content to index.
+- For a multi-service search portfolio (upload UI + refresh cron), use the
+  `semantic-search` blueprint instead.

package/src/corpus/templates/simple-semantic-search/cloudgrid.yaml

@@ -0,0 +1,235 @@
+# ============================================================================
+# cloudgrid.yaml — Complete Example
+# ============================================================================
+#
+# This file shows EVERY field the platform supports, with comments explaining
+# each one. It is a reference — no real project would use all of these at once.
+#
+# STANDARD: every CloudGrid template ships its cloudgrid.yaml in THIS full form.
+# Uncomment ONLY the fields the archetype needs (always: name + services; plus
+# needs: for runtime apps). Leave everything else commented. Comments are
+# ignored by the parser, so the file deploys to exactly the active fields.
+#
+# Only two fields are required: name and services. Everything else is optional.
+# Full docs: docs/cloudgrid-yaml-reference.md
+# ============================================================================
+
+
+# ─── IDENTITY ───────────────────────────────────────────────────────────────
+
+# Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
+# Must start and end with a letter or digit.
+# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+name: simple-semantic-search
+description: Semantic search over a bundled document, backed by pgvector.
+icon: "🔎"
+
+# One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.
+# description: Order processing API for the e-commerce platform
+
+# Single emoji or short text shown as the entity icon. Max 64 chars.
+# icon: "📦"
+
+# Entity type: 'app' (default) or 'agent'. An agent is an app with an agent: block.
+# kind: app
+
+
+# ─── NETWORKING ─────────────────────────────────────────────────────────────
+
+# Whether this entity serves public HTTP traffic.
+# true = public URL + Ingress (default). false = internal only.
+# expose: true
+
+# Additional domain names this entity serves on (the platform URL is always active).
+# custom_domains:
+#   - orders.example.com
+#   - shop.example.com
+
+
+# ─── HEALTH PROBE (entity-level override) ──────────────────────────────────
+
+# Override the default health check for the entire entity.
+# probe:
+#   path: /healthz               # HTTP path to probe (default: /).
+#   expected: "<500"             # '<500' (default), '200', '2xx'.
+
+
+# ─── DEPLOY NOTIFICATIONS ──────────────────────────────────────────────────
+
+# Slack notification to the org's default channel on deploy failure.
+# true = notify (default), false = silent.
+# notify: true
+
+
+# ─── SCALING ────────────────────────────────────────────────────────────────
+
+# Replica scaling intent.
+#   'auto'  — platform decides from the grid tier (default).
+#   'alert' — single-replica, emit a SPOF warning at plug time.
+#   1-10    — explicit replica count, clamped to the grid max.
+# scale: auto
+
+
+# ─── INFRASTRUCTURE NEEDS ──────────────────────────────────────────────────
+#
+# Declare infrastructure; the platform provisions it and injects connection
+# details as env vars. Nine needs: database, cache, kv, queue, pubsub, vector,
+# object_storage, disk, ai. Simplest form is `true`.
+#
+# needs:
+#   # database — MongoDB. Injects DATABASE_MONGODB_URL (+ legacy MONGODB_URL).
+#   #   true | pool | dedicated | { tier: external, secret: MY_DB }
+#   database: true
+#   # cache — Redis, LRU eviction (derived data). Injects CACHE_REDIS_URL (+ REDIS_URL).
+#   #   true | redis | { engine: external, secret: MY_REDIS_URL }
+#   cache: true
+#   # kv — Redis, no eviction (durable: flags, idempotency). Injects KV_REDIS_URL.
+#   kv: true
+#   # queue — Redis job-queue substrate (BullMQ). Injects QUEUE_REDIS_URL.
+#   queue: true
+#   # pubsub — Redis broadcast pub/sub. Injects PUBSUB_REDIS_URL.
+#   pubsub: true
+#   # vector — pgvector on Postgres. Injects VECTOR_PGVECTOR_URL (+ PGVECTOR_URL).
+#   #   true | pgvector | { engine: pgvector, dim: 1536 }
+#   vector: pgvector
+#   # object_storage — GCS bucket. Injects OBJECT_STORAGE_GCS_BUCKET, _GCS_REGION.
+#   #   true | { size: 10Gi }
+#   object_storage: true
+#   # 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: true
+
+
+# ─── INTER-ENTITY COMMUNICATION ────────────────────────────────────────────
+
+# Entities this app calls (outbound). Service-account token injected per pair.
+# calls:
+#   - org:atomic/billing-api
+
+# Inbound caller policy — who can call YOUR entity.
+# callers:
+#   policy: auto                 # 'auto' | 'manual' (default).
+#   scope: org                   # 'org' (default) | 'space' | 'explicit'.
+#   fallback: deny               # 'deny' (default) | 'warn'.
+#   # allowed_apps:              # required only when scope: explicit
+#   #   - org:atomic/frontend
+
+
+# ─── VAULT ──────────────────────────────────────────────────────────────────
+
+# Map org vault items to env vars. Keys UPPER_SNAKE_CASE; values = vault item keys.
+# vault:
+#   STRIPE_KEY: stripe-live-key
+#   SENDGRID_API_KEY: sendgrid-key
+
+
+# ─── CONNECTORS AND HOOKS ──────────────────────────────────────────────────
+
+# connectors:
+#   - id: team-slack
+#     target: org                # 'system' | 'org'.
+#     channel: "#deploys"
+# hooks:
+#   - on: deploy.failed          # release.published | deploy.failed | feedback.received | entity.created
+#     via: team-slack
+#     template: "Deploy failed for {entity_name}: {error}"
+#     channel: "#alerts"
+# triggers:
+#   - from: team-slack
+#     event: message
+#     channel: "#support"
+#     route: /webhooks/slack
+
+
+# ─── LOCAL DEVELOPMENT ──────────────────────────────────────────────────────
+
+# Config for `grid dev`. Redact fields in dev data snapshots.
+# dev:
+#   snapshot:
+#     mask:
+#       - users.email
+#       - users.phone
+
+
+# ─── AGENT METADATA ────────────────────────────────────────────────────────
+
+# An agent is an app with kind: agent (above) and an agent: block.
+# agent:
+#   purpose: Sync customer data from external CRM every night
+#   schedule: "0 2 * * *"
+#   trigger: webhook
+
+
+# ─── PRIVATE RESOURCE AUTO-DEPENDENCIES ────────────────────────────────────
+
+# When true (default), private resources are auto-injected as depends_on.
+# auto_depends_on_private_requires: true
+
+
+# ─── SERVICES (REQUIRED) ───────────────────────────────────────────────────
+#
+# At least one service is required. Key = service name (slug rules).
+# Types: node, nextjs, python, static, cron.
+#
+services:
+  web:
+    # type (REQUIRED): node | nextjs | python | static | cron
+    type: node
+    # HTTP route: '/' | '/api' | false (internal) | omitted (=false + warning).
+    # Only one service per entity can claim '/'.
+    path: /
+    # Container port (default 8080; read process.env.PORT). Not for cron.
+    # port: 3000
+    # nextjs only: base_image: distroless (default) | alpine
+    # base_image: distroless
+    # node only: lang: javascript (default) | typescript
+    # lang: typescript
+    # Custom source location (default services/<name>/). '.' = project root.
+    # source:
+    #   path: src/worker
+    # Health probe: false/omitted (TCP) | true (/health) | "/path" | {path,expected}
+    # Returns 503 until the startup seed finishes, so traffic waits for a ready index.
+    health: /health
+    # Static runtime env vars (strings). Reserved: PORT, APP_NAME, SERVICE_NAME,
+    # NODE_ENV, MONGODB_URL, REDIS_URL, AI_GATEWAY_URL, N8N_WEBHOOK_URL, CLOUDGRID_*.
+    # env:
+    #   LOG_LEVEL: info
+    # Sibling services/private resources that must be Ready first (no cron, no cycles).
+    # depends_on:
+    #   - worker
+    # Per-service needs override (merges with app-level needs).
+    # needs:
+    #   queue: true
+    # Static-only build step:
+    # build:
+    #   command: npm run build
+    #   output: dist
+    #   env:
+    #     VITE_API_URL: https://api.example.com
+    # node_version: "22"          # static build step: '18'|'20'|'22'|'24' (quoted)
+    # Cron-only: schedule (REQUIRED), timezone (UTC|EST|PST), run (job | https URL)
+    # schedule: "0 9 * * 1"
+    # timezone: UTC
+    # run: job
+    # Verbose per-service persistence (prefer needs.disk):
+    # persist:
+    #   - name: scratch
+    #     path: /tmp/scratch
+    #     size: 500Mi
+
+
+
+needs:
+  vector: pgvector    # pgvector on Postgres. Injects VECTOR_PGVECTOR_URL (+legacy PGVECTOR_URL).
+  ai: true            # AI Gateway for embeddings via @cloudgrid-io/runtime. Injects AI_GATEWAY_URL.
+
+
+# ============================================================================
+# NOTES
+# - NOT here: org:/entity_id: (→ .cloudgrid/link.json), secrets (→ grid secrets set),
+#   Dockerfile (platform generates from services.*.type).
+# - Deploy: grid plug   |   Local with grid resources: grid dev
+# - Full reference: docs/cloudgrid-yaml-reference.md  |  CLI: docs/cli-reference.md
+# ============================================================================