docs(mcp v2.4): template pathway recipe + apps.templates tools

The template pathway is the new recommended default for popular
third-party apps — strongly preferred over composeRaw whenever an
upstream Coolify template exists.

Made-with: Cursor

AI_CAPABILITIES.md

@@ -109,7 +109,7 @@ Version: **2.1.0**.
 |---|---|---|
 | `apps.list` | All Coolify apps in the workspace. | — |
 | `apps.get` | Single app details (status, fqdn, domains, git info). | `{ uuid }` |
-| `apps.create` | Create a Coolify app. **Three pathways** depending on the source — choose the right one for the job: **(1) Gitea repo** (user's own code): pass `repo`. Clones over HTTPS+PAT; no SSH. **(2) Docker image** (pre-built third-party app, e.g. `nginx:alpine`): pass `image`. No repo created. **(3) Inline Docker Compose YAML** (multi-service third-party app, e.g. Twenty, Directus): pass `composeRaw` with the full compose YAML as a string. No repo created. Use pathways 2 and 3 for any third-party SaaS app — they are faster, simpler, and avoid stale-git-state issues. Auto-domain `{name}.{slug}.vibnai.com` for all pathways. | **Pathway 1 (repo):** `{ repo, branch?, name?, ports?, buildPack?, domain?, envs?, instantDeploy?, dockerComposeLocation?, dockerfileLocation?, baseDirectory? }` **Pathway 2 (image):** `{ image, name?, ports?, domain?, envs?, instantDeploy? }` **Pathway 3 (compose):** `{ composeRaw, name?, domain?, composeService?, composeDomains?, envs?, instantDeploy? }` — `composeDomains` is `[{ service, domain }]`; defaults to `[{ service: "server", domain: auto }]` |
+| `apps.create` | Create a Coolify app. **Four pathways** — pick the one that matches your source. **(1) Gitea repo** (user's own code): pass `repo`. Clones over HTTPS+PAT; no SSH. **(2) Docker image** (pre-built single-container third-party app, e.g. `nginx:alpine`): pass `image`. **(3) Inline Docker Compose YAML** (custom multi-service stack): pass `composeRaw`. **(4) Coolify one-click template** (RECOMMENDED for popular apps — Twenty, n8n, Supabase, Ghost, etc): pass `template` with a slug from `apps.templates.search`. Templates have battle-tested env defaults, healthchecks, and `depends_on` graphs. **Use pathway 4 over pathway 3 whenever a template exists** — it is dramatically more reliable. Auto-domain `{name}.{slug}.vibnai.com` for all pathways. | **(1) repo:** `{ repo, branch?, name?, ports?, buildPack?, domain?, envs?, instantDeploy?, dockerComposeLocation?, dockerfileLocation?, baseDirectory? }` **(2) image:** `{ image, name?, ports?, domain?, envs?, instantDeploy? }` **(3) composeRaw:** `{ composeRaw, name?, domain?, envs?, instantDeploy? }` **(4) template:** `{ template, name?, domain?, envs?, instantDeploy? }` |
 | `apps.update` | PATCH a whitelisted set of fields (name, description, git branch/commit, ports, build commands, base directory, Dockerfile location, docker-compose location…). Returns `applied`, `ignored`, and `rerouted` arrays so the agent can see exactly what persisted; setting `fqdn`/`domains`/`docker_compose_domains` returns a `rerouted` entry pointing at `apps.domains.set`, and setting `git_repository` returns one pointing at `apps.rewire_git`. | `{ uuid, patch }` |
 | `apps.rewire_git` | Re-point an app's `git_repository` at the canonical HTTPS+PAT clone URL. Use to recover older apps that were created with SSH URLs, or to refresh a rotated bot PAT. | `{ uuid, repo? }` — `repo` optional; inferred from current URL if omitted |
 | `apps.delete` | Destroy the app. Volumes kept by default. | `{ uuid, confirm }` — `confirm` must equal the app's exact name |
@@ -118,6 +118,8 @@ Version: **2.1.0**.
 | `apps.logs` | Runtime logs for a running app. Compose-aware: returns per-service logs for `dockercompose` build packs, single stream for `dockerfile`/`nixpacks`. Includes container status and any diagnostic warnings. | `{ uuid, service?, lines? }` — `service` filter (compose only), `lines` default 200, max 5000 |
 | `apps.volumes.list` | List Docker volumes belonging to an app (name + size in bytes). Use before `apps.volumes.wipe` to know exact volume names. | `{ uuid }` |
 | `apps.volumes.wipe` | **Destructive / irreversible.** Stop all app containers, remove a specific volume, leave it ready for a fresh `apps.deploy`. Use to recover from stale DB state on first boot (the most common compose app failure). `confirm` must equal the exact volume name. | `{ uuid, volume, confirm }` |
+| `apps.templates.list` | Browse the full Coolify one-click template catalog (320+ vetted apps: CRMs, AI tools, CMSes, dashboards, databases, …). Each entry is deployable via `apps.create({ template: <slug> })`. Returns `{ total, offset, limit, items: [{ slug, slogan, tags, port, documentation, logo }] }`. Catalog is fetched from upstream and cached for 1h. | `{ limit?, offset?, tag? }` — `limit` default 50, max 500; `tag` substring filter (e.g. `"crm"`, `"ai"`) |
+| `apps.templates.search` | Find templates by name, tag, or slogan. Ranked: exact-slug > slug-starts-with > slug-contains > tag-exact > tag-contains > slogan. Use this **before** `apps.create` to discover the right slug (e.g. `"twenty"`, `"n8n-with-postgres-and-worker"`, `"forgejo-with-postgresql"`). | `{ query, tag?, limit? }` — `limit` default 25, max 100. Either `query` or `tag` must be set |
 | `apps.exec` | Run a one-shot command inside an app container (via `docker exec` on the Coolify host). Compose-aware: pass `service` when the app has >1 container. Returns `{ container, service, code, stdout, stderr, truncated, durationMs, containerHealth }`. Default timeout 60s (max 10 min); default output cap 1 MB (max 5 MB). Command is run through `sh -lc` so shell syntax works. Use this for database migrations, seeds, CLI invocations, and ad-hoc debugging. Every call is audit-logged (command + target, not output). | `{ uuid, command, service?, user?, workdir?, timeout_ms?, max_bytes? }` |
 | `apps.domains.list` | Current domain set. | `{ uuid }` |
 | `apps.domains.set` | Replace the domain set. All entries must end with `.{slug}.vibnai.com`. Compose-aware: for `dockercompose` apps the domain is attached to a specific service (`server` by default; override with `service`). | `{ uuid, domains: string[], service? }` |
@@ -583,7 +585,7 @@ The MCP descriptor at `GET /api/mcp` reports a semver `version`. Tool names
 are append-only within a major version — agents can cache the tool list
 safely for the duration of a conversation but should re-fetch on 404.
 
-Current version: **2.3.0**.
+Current version: **2.4.0**.
 
 - **1.x** — session-cookie-only MCP, no tenant keys.
 - **2.0** — `vibn_sk_…` keys, workspace-scoped Gitea bot + Coolify project.
@@ -595,6 +597,9 @@ Current version: **2.3.0**.
 - **2.3** — `apps.create` Docker-image and inline-composeRaw pathways (no
   Gitea repo required for third-party apps), `apps.volumes.list` +
   `apps.volumes.wipe` for self-service volume recovery.
+- **2.4** — `apps.create` Coolify-template pathway (`{ template: "twenty" }`
+  etc.) for one-click deploy of 320+ vetted apps, plus `apps.templates.list`
+  / `apps.templates.search` for catalog discovery.
 
 ---
 
@@ -665,11 +670,32 @@ single-container apps use `domains` (comma-separated string).
 |---|---|
 | User's own code lives in their Gitea org | `repo` (pathway 1) |
 | Single-container third-party app (nginx, redis, a docker image) | `image` (pathway 2) |
-| Multi-service third-party app (Twenty, Directus, Cal.com, Plane…) | `composeRaw` (pathway 3) |
+| Custom multi-service stack (no upstream template exists) | `composeRaw` (pathway 3) |
+| **Popular third-party app (Twenty, n8n, Supabase, Ghost, Wordpress, …)** | **`template` (pathway 4) — strongly preferred** |
 
-**Never** create a Gitea repo just to host a third-party app's compose file. Use `composeRaw` instead — it's faster, has no git-clone overhead, and avoids the partial-state problems that can happen when Coolify clones a fork.
+**Always check `apps.templates.search { query: "<app name>" }` first.** Coolify ships 320+ vetted one-click templates. Each one has tested env defaults, healthchecks, `depends_on` graphs, and the right volume mounts. The same app deployed via `composeRaw` will hit application-specific quirks (URL validation, DB bootstrap order, secret generation) that the template author already solved.
 
-For `composeRaw`, fetch the app's official `docker-compose.yml` (from GitHub/DockerHub) and pass it inline. Override any hard-coded image tags with pinned versions for reproducibility.
+**Never** create a Gitea repo just to host a third-party app's compose file.
+
+**Recipe — deploying any popular app in 3 calls:**
+
+```json
+// 1. Find the right template slug
+{ "action": "apps.templates.search", "params": { "query": "twenty" } }
+// → { "items": [{ "slug": "twenty", "slogan": "Twenty is a CRM…", "tags": ["crm","self-hosted"], "port": 3000 }] }
+
+// 2. Deploy it
+{ "action": "apps.create", "params": { "template": "twenty", "name": "crm" } }
+// → { "uuid": "...", "domain": "crm.<slug>.vibnai.com", "started": true,
+//      "note": "First boot may take 1-5 min while Coolify pulls images and runs migrations." }
+
+// 3. Watch it come up
+{ "action": "apps.logs", "params": { "uuid": "...", "lines": 200 } }
+```
+
+For `composeRaw` (only when no template exists), fetch the app's official `docker-compose.yml` (from GitHub/DockerHub) and pass it inline. Override any hard-coded image tags with pinned versions for reproducibility.
+
+**Browsing the catalog** with `apps.templates.list { tag: "ai" }` returns all AI/ML templates; `{ tag: "crm" }` returns CRMs; etc. Useful when the user asks "what self-hosted analytics tools can I deploy?" or similar open-ended questions.
 
 ### 11.5 "Compose app fails on second+ deploy — relation/table does not exist"