@kolbo/mcp 1.37.0 → 1.37.1

package/README.md

@@ -239,6 +239,7 @@ Every generation tool also accepts an optional `project_id` arg that routes the
 | `create_project` / `update_project` / `archive_project` / `unarchive_project` | Project lifecycle (create/rename/describe/archive; deletion stays in-app) |
 | `list_agents` / `create_agent` / `update_agent` / `delete_agent` | Custom chat agents (reusable named personas; `description` is the system instruction) |
 | `get_creative_director_status` | Re-check a Creative Director batch by generation_id until all parallel scenes finish (use after a `_timed_out` Director run) |
+| `app_builder_list_projects` / `app_builder_create_session` / `app_builder_generate_app` / `app_builder_edit_app` / `app_builder_get_build_status` / `app_builder_get_session` / `app_builder_list_sessions` / `app_builder_list_generations` / `app_builder_delete_session` | **App Builder (preview)** — full React app generation that auto-provisions a GitHub repo + Supabase DB + a live deployment URL. Different surface from the generation tools (4-layer mental model: project → session → app → end-users). The app embeds `@kolbo/app-sdk` so visitors can call Kolbo AI from the browser; the OWNER pays for visitor AI usage. Read the App Builder workflow doc before the first turn. |
 | `list_sessions` | Enumerate sessions across all types, filterable by project and type |
 | `add_project_context` / `list_project_context` / `delete_project_context` / `get_project_profile` / `regenerate_project_profile` | Project knowledge base (RAG): feed scripts/URLs/notes, read the synthesized living brief |
 | `create_moodboard` / `update_moodboard` / `delete_moodboard` | Build/edit moodboards from image URLs (AI style analysis → master prompt) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.37.0",
+  "version": "1.37.1",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {

package/skill/SKILL.md

@@ -83,7 +83,7 @@ For multi-scene / batch work this pairs with `generate_creative_director` (see b
 | **Transcribe** or **analyze** audio/video | `references/workflows/transcription.md` |
 | **Scrape brand/product info** before generating + persist as `.kolbo/brand-kits/<slug>.md` | `references/workflows/research-first.md` |
 | Browse, manage, or present existing **media library** items | `references/workflows/media-library.md` |
-| Use the **App Builder** (React app generation) | `references/workflows/app-builder.md` |
+| Use the **App Builder** (React app generation) — preview, ask first | `references/workflows/app-builder.md` |
 | Confirm **cost** or validate **resolution / aspect / duration** against model caps | `references/workflows/cost-and-validation.md` |
 | Hit an **auth / MCP / 429** issue | `references/workflows/troubleshooting.md` |
 
@@ -124,7 +124,7 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 | `trim_video` | Frame-accurate trim of a Kolbo-hosted video (tool waits and returns the URL). `edit_video` also gained `remove_background`. |
 | `create_doc` / `list_docs` / `get_doc` / `update_doc` / `share_doc` / `delete_doc` | AI Docs (Magic Pad): YOU author full HTML documents (plans, briefs, scripts, research) saved into the user's project, editable in the Kolbo app. `share_doc` returns a public link. `update_doc` content replaces the WHOLE doc — `get_doc` first. |
 | `chat_send_message` / `chat_list_conversations` / `chat_get_messages` | Kolbo chat with optional `media_urls` (up to 10 per call) |
-| `app_builder_*` (9 tools) | Full React app generation — see `workflows/app-builder.md` |
+| `app_builder_*` (9 tools) | Full React app generation (preview) — see `workflows/app-builder.md`. Different surface from generation tools: produces a deployed app with GitHub repo + Supabase DB + live URL. Don't confuse `session_id` types, don't confuse `app_builder_generate_app` with `generate_image`. |
 | `publish_html_artifact` | Publish HTML / SVG / Mermaid to `sites.kolbo.ai`. Server dedupes by content hash. Strict CSP. |
 
 ## ⚠️ If the User Names a Tool, USE THAT TOOL (HARD RULE)
@@ -175,9 +175,20 @@ Everything in Kolbo — sessions, generations, media, docs — lives inside a PR
 
 1. **User names a project** ("in my Acme project", "for the film") → call `list_projects` ONCE to resolve the name to an ObjectId, then pass that id as `project_id` on **EVERY** subsequent `generate_*` / `upload_media` / `create_doc` / `chat_send_message` call in the conversation. It is **per-call, NOT sticky** — any call that omits it silently lands in the default "API Generations" bucket (`is_default: true`).
 2. **No project mentioned** → omit `project_id`; the default bucket is correct. Don't ask unless intent is ambiguous.
-3. **`list_projects` ≠ `app_builder_list_projects`** — the latter scopes App Builder coding sessions only.
+3. **`list_projects` ≠ `app_builder_list_projects`** — both return the SAME Kolbo projects (different endpoints, different shapes). Use `list_projects` for generation/media/chat flows; use `app_builder_list_projects` when scoping an App Builder session. Never substitute one for the other.
 4. **Work landed in the wrong project? MOVE it, never regenerate**: `move_session` relocates a whole session + all its media (works for any session type — the `session_id` from generation responses, chats, transcriptions); `move_media` / `bulk_move_media` / `move_folder_contents` relocate individual media items.
 
+## 🧱 App Builder ≠ regular Kolbo project (4-layer mental model)
+
+App Builder is a separate surface that builds and runs full React apps. It shares the **Kolbo project** layer with regular generations (a single Kolbo project can hold BOTH app-builder sessions AND image/video sessions), but every layer above it is distinct. The single biggest routing mistake is treating an `app_builder_generate_app` call as a media-generation call, or passing an App Builder `session_id` to `generate_image`. Read `workflows/app-builder.md` before the first App Builder turn — the four layers are:
+
+1. **Kolbo project** (shared) — `list_projects` / `app_builder_list_projects`
+2. **App Builder session** — `app_builder_create_session(project_id)` → returns a `session_id` distinct from any chat/generation session id
+3. **The app itself** — `deployment_url` + `github_repo_url` + `supabase_url` + `supabase_anon_key` (auto-provisioned on first successful build)
+4. **App end-users** — per-app JWT, hit `/api/apps/:appId/ai/*`; the OWNER of the app pays for their AI usage (NOT surfaced as MCP tools — owned by `@kolbo/app-sdk` in the deployed bundle)
+
+Heuristic: deliverable is a **single file** (image / video / doc / artifact) → regular tools. Deliverable is "**an app** that does X" or "my **users** can do Y" → App Builder. App Builder is **preview** — don't proactively advertise; if the user asks, load `workflows/app-builder.md` and confirm they're an opted-in owner.
+
 ## Cost Awareness — Quick Rules
 
 Full tables + formulas in `references/workflows/cost-and-validation.md`. Quick rules:

package/skill/references/workflows/app-builder.md

@@ -1,41 +1,160 @@
 # App Builder
 
-Load this file when the user wants to build / edit / iterate on a React app via Kolbo's App Builder ("build me a todo app", "add dark mode to my app", "give me the GitHub repo").
+Load this file when the user wants to **build, edit, or iterate on a full React app** with Kolbo's App Builder — "build me a todo app", "add dark mode to my app", "give me the GitHub repo", "I want my app to use Kolbo image generation from the user's browser". Do NOT load this for single-asset generation requests (use the regular `generate_*` tools).
 
-Use the App Builder tools to generate and iterate on full React apps from a text prompt. The backend auto-provisions a GitHub repo, Supabase database (when the app needs storage), and a live hosted deployment — all in one flow.
+## 🚦 Preview / not live to the public yet
 
-## Standard Workflow
+App Builder is in **preview** as of this writing. The MCP tools (`app_builder_*`) are wired and the backend runs end-to-end — owners can create projects, generate apps, edit them, get GitHub repos + Supabase DBs + a live deployment URL. The user-facing launch (in-app promo, self-serve public onboarding) is still pending. So:
 
-1. **Find project ID**: `app_builder_list_projects` → pick the right project
-2. **Create session**: `app_builder_create_session` with `project_id`
-3. **Generate app**: `app_builder_generate_app` with `session_id` + `prompt`
-   - Fires the build in the background, polls until `build_status === "deployed"` (up to 5 min)
-   - Always surface the `deployment_url` to the user: **"Your app is live at: [url]"**
-4. **Iterate**: `app_builder_list_generations` → get `generation_id` → `app_builder_edit_app` with natural language instruction
+- **You CAN call these tools** for owners / opted-in users — the flow works.
+- **Don't proactively advertise App Builder** to users who haven't asked for it (no marketing pitch about "build apps with AI").
+- If the user pushes back ("is this ready?"), say it's a working preview and ask if they want to try it.
 
-No manual polling needed — `generate_app` and `edit_app` block until the build completes.
+## 🧠 Mental model — 4 layers, easy to conflate
 
-## Local Dev Workflow
+This is the single biggest source of confusion. App Builder is NOT a generation tool. It's a **complete app factory** with its own lifecycle, its own runtime, and its own end-user identity model. Lock this in once:
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│ Layer 1 — KOLBO PROJECT (Kolbo account)                                 │
+│   The same project you use for generations/media/chat.                  │
+│   `list_projects` returns these. `app_builder_list_projects` ALSO       │
+│   returns these (same data, different endpoint shape). A project can    │
+│   hold BOTH regular sessions AND app-builder sessions at the same time. │
+└─────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│ Layer 2 — APP BUILDER SESSION (one session = one app being built)       │
+│   Created with `app_builder_create_session` against a Kolbo project.    │
+│   Has a `session_id` that is COMPLETELY DIFFERENT from the              │
+│   `session_id` returned by `chat_send_message` or any `generate_*`      │
+│   tool. Don't mix them.                                                 │
+│   A session accumulates "generations" — each one is a build / edit.     │
+└─────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│ Layer 3 — THE APP ITSELF (a deployed React app)                         │
+│   After the first successful generation the session has a real app:     │
+│     • `deployment_url` — the live, hosted URL (e.g. apps.kolbo.ai/…)   │
+│     • `github_repo_url` — auto-provisioned GitHub repo (clone, hack)    │
+│     • `supabase_url` + `supabase_anon_key` — auto-provisioned DB        │
+│   The app embeds `@kolbo/app-sdk` so it can call Kolbo AI directly      │
+│   from the user's browser — see Layer 4.                                │
+└─────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│ Layer 4 — APP END-USERS (real humans visiting the deployed app)         │
+│   Each visitor authenticates with a PER-APP JWT — NOT a Kolbo user      │
+│   account, NOT an API key. They hit `/api/apps/:appId/ai/*` endpoints   │
+│   that proxy Kolbo AI. The OWNER of the app (the person who built it)  │
+│   is the one whose credits get billed for every generation. This is a   │
+│   completely different surface from the MCP — there are no MCP tools    │
+│   for app end-users; the SDK lives in the generated app's bundle.       │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+**The five easy confusions** — re-read this before every App Builder turn:
+
+1. `list_projects` and `app_builder_list_projects` return the **same Kolbo projects** — different endpoints, different shapes, but the same data. Use whichever the current flow needs.
+2. `session_id` from `app_builder_create_session` is NOT the same as `session_id` from `chat_send_message`. Don't pass an App Builder session id to a `generate_*` tool or vice versa.
+3. `app_builder_generate_app` is NOT a media-generation tool. It kicks off a full multi-minute app build that produces code + infra + a deployment URL. Never confuse it with `generate_image` / `generate_video`.
+4. The deployed app is its OWN product. Visiting it is not "using Kolbo"; the visitor's identity is per-app, not Kolbo.
+5. The OWNER pays. App end-users consume credits from the owner's account. Confirm the owner understands this before they share their app publicly.
+
+## When to route here
+
+The user wants to **build or modify a full app**, not generate a single asset:
+
+- "Build me a [todo / landing page / dashboard / form / marketplace / internal tool / mobile-friendly site] app"
+- "Make me a [SaaS / site / app] that does X"
+- "I want an app where my users can [Y]" (the visitor-runtime question — usually means App Builder + Layer 4)
+- "Add [dark mode / a contact form / a chart / auth / a settings page] to my app"
+- "Show me the GitHub repo" / "I want to clone it" / "Connect my own Supabase"
+- "Is my app deployed?" / "My build failed" / "Why is the deployment URL blank?"
+- "What apps have I built?" / "Show me my App Builder sessions"
+- "Delete this app" (always confirm — see Rules)
+
+## When NOT to route here
+
+The user wants a single asset or a Kolbo-internal workflow. Stay on the regular `generate_*` / media / doc / chat tools:
+
+- "Generate an image / video / song / voice / 3D model" → regular tools (the output lives in Kolbo)
+- "Edit this image" → `generate_image_edit`
+- "Write me a [plan / brief / script]" → `create_doc` (AI Docs)
+- "Build a presentation / landing page artifact" → `publish_html_artifact`
+- "I want a campaign with 4 product shots" → `generate_creative_director`
+- "Make me a Kolbo character consistent across images" → Visual DNA tools
+
+**Heuristic:** if the deliverable is a single file (image / video / doc / page artifact), it's NOT App Builder. If the deliverable is "an app that does X" or "my users can do Y in it", it IS App Builder.
+
+## Standard workflow (build + iterate)
+
+```
+1. app_builder_list_projects                → pick a Kolbo project (or note "default bucket")
+2. app_builder_create_session(project_id)   → returns session_id
+3. app_builder_generate_app(session_id,
+                            prompt="...")   → blocks until build_status="deployed"
+                                             (up to ~5 min — surface the deployment_url!)
+4. (later) app_builder_list_generations(session_id)
+         → app_builder_edit_app(session_id,
+                                generation_id=<latest>,
+                                edit_prompt="add dark mode")
+                                             → blocks until redeployed
+```
+
+**Surface the deployment URL on success** — always show the user: "Your app is live at: `<deployment_url>`". That's the whole payoff. If `deployment_url` is null after a successful build, treat it as a build failure and call `app_builder_get_build_status` to investigate.
+
+**No manual polling needed.** `generate_app` and `edit_app` block until the build completes (or throws). If a build times out, the user can resume by calling `app_builder_get_build_status(session_id)` — DO NOT auto-retry; wait for the user's call.
+
+## Local dev + handoff
 
 If the user wants to run the app locally or connect to the database directly:
+
 ```
 app_builder_get_session(session_id) → returns:
-  github_repo_url  →  git clone <url> && npm install && npm run dev
-  supabase_url     →  paste into .env as NEXT_PUBLIC_SUPABASE_URL
-  supabase_anon_key → paste into .env as NEXT_PUBLIC_SUPABASE_ANON_KEY
+  github_repo_url     → git clone <url> && npm install && npm run dev
+  supabase_url        → paste into .env as NEXT_PUBLIC_SUPABASE_URL
+  supabase_anon_key   → paste into .env as NEXT_PUBLIC_SUPABASE_ANON_KEY
+  deployment_url      → the currently deployed URL
 ```
 
-## ⚠️ Rules
+The repo is a standard Next.js + Tailwind + shadcn/ui + Supabase app. The bundled `@kolbo/app-sdk` (`kolbo.auth`, `kolbo.data`, `kolbo.storage`, `kolbo.ai`) is what lets the app call Kolbo AI without exposing a full-access API key.
+
+## End-user runtime — when the user asks "can my visitors do X in the app?"
 
-- **Always confirm before `app_builder_delete_session`** — permanently deletes the GitHub repo, Supabase DB (unless user-connected), deployed files, and history. IRREVERSIBLE.
-- **On build timeout** (rare): use `app_builder_get_build_status` to check manually, then continue or report.
+This is Layer 4 — the deployed app's AI proxy. The MCP doesn't have direct tools for it, but you should KNOW it exists so you can answer:
 
-Whitelabel works automatically — the MCP client routes App Builder calls through whitelabel API endpoints.
+- **What end-users see:** the deployed React app at `deployment_url`. They authenticate with a per-app JWT (auto-issued; the SDK handles it).
+- **What they can do:** anything the app is coded to do, including calling Kolbo AI (image / video / chat / etc.) via `@kolbo/app-sdk`. The SDK hits `/api/apps/:appId/ai/*` proxy endpoints server-side; the OWNER's account is billed for those calls.
+- **Spend controls:** the owner can set a per-app spend policy and per-user rate limits on the AI proxy (see `appAI/spendPolicy.js`). If the user says "my app is burning credits" or "someone is abusing my app", route them to that dashboard.
+- **What you CAN'T do from the MCP:** inspect an end-user's session inside the app, view their chat history, or read their app-scoped data. Those live in the Kolbo dashboard under the App's settings.
 
 ## Routing examples
 
 | User says | Sequence |
 |---|---|
-| "Build me a todo app" / "Make a landing page with waitlist" | `app_builder_list_projects` → `app_builder_create_session` → `app_builder_generate_app` → show `deployment_url` |
-| "Add dark mode to my app" / "Add a contact form" | `app_builder_list_generations` → `app_builder_edit_app` |
-| "Give me the GitHub repo" / "Supabase credentials" | `app_builder_get_session` → return `github_repo_url` + `supabase_url` + `supabase_anon_key` |
+| "Build me a todo app" / "Make me a SaaS landing page with waitlist" | `app_builder_list_projects` → `app_builder_create_session` → `app_builder_generate_app` → show `deployment_url` |
+| "Add dark mode to my app" / "Add a contact form / chart / auth" | `app_builder_list_generations` → grab latest `generation_id` → `app_builder_edit_app` → show `deployment_url` |
+| "Give me the GitHub repo" / "I want to clone it and run it locally" | `app_builder_get_session` → return `github_repo_url` (+ `supabase_url` + `supabase_anon_key` if they ask) |
+| "Show me my apps" / "What apps have I built?" | `app_builder_list_projects` → for each, `app_builder_list_sessions` → surface session list |
+| "Is my build still running?" / "My build timed out" | `app_builder_get_build_status(session_id)` → resume |
+| "Delete this app" | **ALWAYS CONFIRM FIRST** — see Rules. Then `app_builder_delete_session` |
+| "My app visitors are burning my credits" | Not an MCP action — point them at the App → Settings → Spend Policy dashboard |
+| "I want my app users to be able to generate images inside the app" | Tell them the `@kolbo/app-sdk` `kolbo.ai.generateImage` namespace handles it server-side via `/api/apps/:appId/ai/generate/image` — the OWNER pays |
+
+## Hard rules
+
+- **ALWAYS confirm before `app_builder_delete_session`** — permanently deletes the GitHub repo, Supabase DB (unless user-connected their own), deployed files, generation history, messages, and form submissions. IRREVERSIBLE.
+- **On build timeout / failure:** use `app_builder_get_build_status(session_id)` and report the actual status to the user. DO NOT auto-retry the build.
+- **Never invent a `deployment_url` or `github_repo_url`** — they come back from the tool. If null, the build didn't finish.
+- **The owner pays for every AI call made by an app visitor.** Make sure the user understands this before they share the app publicly. Direct them to spend-policy settings if they need a cap.
+- **Whitelabel works automatically** — the MCP client routes App Builder calls through the whitelabel API endpoints when configured.
+- **Don't conflate `project_id` types.** A Kolbo project holds App Builder sessions; the App Builder session is a CHILD of that project. The deployed app has its OWN `:appId` (visible in `app_builder_get_session`) which is what the app-runtime uses to route AI calls — that's a different id namespace from the Kolbo `project_id`.
+
+## Versioning note (MCP)
+
+- The App Builder MCP surface is **stable as of `@kolbo/mcp@1.37.0`**. No renames or removals planned. New optional args ship as `npm version minor` per the standard rules.
+- The kolbo-code skill mirrors this doc (canonical source: `kolbo-code/packages/opencode/skills/kolbo/references/workflows/app-builder.md`); a `chore(skill)` bot keeps them in sync.

package/src/index.js

@@ -113,7 +113,7 @@ function createServer(opts = {}) {
       'PROJECT CONTRACT (read this before generating anything):',
       'Everything in Kolbo lives inside a PROJECT — sessions, generations, and media are all project-scoped.',
       '1. When the user names a project ("in my Acme project", "for the summer campaign"), call `list_projects` ONCE to resolve the name to an id, then pass that id as `project_id` on EVERY subsequent generate_* / chat_send_message / upload_media call in the conversation. The target project is per-call, NOT sticky — any call that omits `project_id` silently lands in the default "API Generations" bucket (flagged is_default:true), which users experience as their work going to the wrong project.',
-      '2. `list_projects` lists the user\'s platform projects (for generations/media/chat). `app_builder_list_projects` is a DIFFERENT tool that scopes App Builder coding sessions only — never use one where the other is meant.',
+      '2. `list_projects` lists the user\'s platform projects (for generations/media/chat). `app_builder_list_projects` is a DIFFERENT tool that scopes App Builder coding sessions only — never use one where the other is meant (both return the same projects but via different endpoints, different shapes). The App Builder surface (project → session → deployed app with GitHub+Supabase+live URL → end-users who hit `/api/apps/:appId/ai/*`) is a SEPARATE world from the generation tools — `app_builder_generate_app` is NOT a media-generation call, and an App Builder `session_id` is NOT interchangeable with a chat/generation `session_id`. Read `skill/references/workflows/app-builder.md` before the first App Builder turn; App Builder is preview-only, do not proactively advertise it.',
       '3. Misplaced work is fixable: `move_media` / `bulk_move_media` / `move_folder_contents` move media items between projects; `move_session` moves a whole session (plus its media) to another project. If the user says a generation landed in the wrong project, move it rather than regenerating.',
       '4. If the user has not mentioned any project, omit `project_id` — the default bucket is correct in that case. Do not ask which project to use unless the user\'s intent is ambiguous.',
       '5. Written deliverables (plans, briefs, scripts, research summaries) can live in Kolbo too: author them as AI Docs with `create_doc` (project-scoped, editable in the app, shareable via `share_doc`).',