@kolbo/mcp 1.32.0 → 1.33.0

package/README.md

@@ -232,8 +232,9 @@ Every generation tool also accepts an optional `project_id` arg that routes the
 | `list_presets` | Generation presets across image/video/music/text-to-video catalogs |
 | `list_projects` | List owned + shared projects (id, name, role, is_default) — call first to resolve a project name into the `project_id` you pass to generation tools |
 | `move_session` | Move a session (generation, chat, transcription…) and ALL its media to another project |
+| `create_doc` / `list_docs` / `get_doc` / `update_doc` / `share_doc` / `delete_doc` | AI Docs (Magic Pad): author project-scoped HTML documents, edit them, get public share links |
 | `check_credits` | Check credit balance |
-| `get_generation_status` | Poll a generation by ID (fallback if a tool times out) |
+| `get_generation_status` | Check one or many generations (`generation_ids`); `wait=true` blocks server-side until done — replaces client polling loops |
 
 ## Environment Variables
 

package/package.json

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

package/skill/GENERATED.md

@@ -1,7 +1,7 @@
 # AUTO-GENERATED — do not edit
 
 This skill/ tree is mirrored from kolbo-code (the single source of truth)
-by .github/workflows/sync-skill-to-plugin.yml — synced from kolbo-code@53720a8.
+by .github/workflows/sync-skill-to-plugin.yml — synced from kolbo-code@17e585e.
 
 It is the skill that 'npx @kolbo/mcp install' deploys into the user's agent.
 To change it, edit packages/opencode/skills/kolbo/ in kolbo-code and push;

package/skill/SKILL.md

@@ -35,7 +35,7 @@ Once per conversation, before any other Kolbo tool call:
 
 1. **Run `check_credits`.** If it fails with "Session expired" / "Not authenticated", ask the user to run `kolbo auth login` (or their branded CLI command like `sapir auth login`) and reload the editor.
 2. **If `list_models` returns empty**, MCP isn't wired — same fix.
-3. Remember the credit balance for the session; don't re-check on every turn.
+3. Use the balance ONLY for the low-balance check at this moment. **Never quote a "credits remaining" number later in the session** — coding/chat usage also deducts credits, so any remembered or computed balance is stale. Report only what each generation cost (`credits_used`); if the user asks what's left, run `check_credits` fresh right then.
 
 If the user is on a whitelabel build (`sapir`, etc.), they must use their branded command — not `kolbo`. See `references/workflows/troubleshooting.md`.
 
@@ -154,8 +154,9 @@ A user-named tool — in any language — overrides every other rule. Recognized
    - Auto-select → only from "Auto-selectable" section (models with a `summary`). Cheapest fit. Prefer `[RECOMMENDED]` when cost is similar.
    - Never auto-select from "Named-only" section.
 4. **Validate inputs** against model caps — see `references/workflows/cost-and-validation.md`.
-5. **How calls work**: each tool blocks until generation is fully complete. Images: seconds. Video: minutes. Multiple tool calls in one response run concurrently. If a call times out, use `get_generation_status` with the returned generation ID.
-6. **Share the URL** after success. Never fabricate URLs.
+5. **How calls work**: each tool blocks until generation is fully complete. Images: seconds. Video: minutes. Multiple tool calls in one response run concurrently. On hosts with live widgets the tool instead returns `submitted` instantly — the card updates on its own; you only need `get_generation_status` when a follow-up step needs the output URLs.
+6. **Checking status — NEVER poll in a loop**: `get_generation_status` takes `wait=true` (blocks server-side until done, ~3 min) and `generation_ids` (check MANY generations in ONE call — returns `all_done` + which are still running). One `wait=true` call replaces any polling loop. If it comes back with some still processing, call it ONCE more with `wait=true` and the remaining ids.
+7. **Share the URL** after success. Never fabricate URLs.
 
 Model types for `list_models`: `text_to_img`, `image_editing`, `text_to_video`, `img_to_video`, `draw_to_video`, `video_to_video`, `elements`, `firstlastgenerations`, `lipsync-image`, `lipsync-video`, `music_gen`, `text_to_speech`, `text_to_sound`, `stt`, `text`, `3d_text_to_model`, `3d_image_to_model`, `3d_multi_image_to_model`, `3d_world`.
 
@@ -167,11 +168,13 @@ Full tables + formulas in `references/workflows/cost-and-validation.md`. Quick r
 - **Otherwise confirm** via the labeled-question card: the parameters + the credit cost, suggest a cheaper alternative if one fits, wait for the user's pick. Never fire on defaults the user didn't choose.
 - **Batch totalling 100+ credits**: run `check_credits` first.
 - **Quote real cost**: after firing, log `credits_used` (from the tool result) to `.kolbo/production.md` — never `base × count`.
+- **Never state "credits remaining" from arithmetic** (opening balance − generation costs). Coding/chat usage deducts credits too, so the math is always wrong. Report cost only; if the user asks for their balance, call `check_credits` fresh at that moment.
 
 ## Rate Limiting & Batch Generation
 
 - `generate_image`: 30/min. All other generation tools: 10/min per type. 300/min global. `upload_media`: 300/min, no credit cost.
-- **⚠️ NEVER re-fire a generation you already called.** Aborted / timed-out calls still process server-side. Run `get_generation_status` before retrying.
+- **⚠️ NEVER re-fire a generation you already called.** Aborted / timed-out calls still process server-side. Run `get_generation_status` (with `wait=true`) before retrying.
+- **Tracking a batch**: check ALL in-flight ids in ONE `get_generation_status` call with `generation_ids` + `wait=true`. Read `all_done` / `still_processing` from the response — do not check ids one by one, and never re-call without `wait`.
 - **Batch ≤10 items**: output ALL tool calls in one response — they run concurrently.
 - **Bulk >10 items**: real-world ceilings — `generate_image` 8–10 in-flight, image-edit 5–8, video tools 3–5, `generate_video_from_video` 3, music/speech/sound 5–8. Fire one batch → wait → fire next. Persist every `generation_id` in `.kolbo/production.md`.
 - **`upload_media` external URLs first.** `files`/`source_images`/`image_url` only accept Kolbo-hosted URLs reliably; external URLs cause `400`.
@@ -224,7 +227,7 @@ A generation can fail three ways. Treat ALL as failure:
 
 1. **Tool returns `error`** — explicit. Surface, suggest retry, log `generation_id`.
 2. **Tool returns `completed` but `urls` is empty** — silent failure (NSFW filter, model OOM, upstream 5xx). Tell user "completed without an output — retrying" and re-fire ONCE. Do NOT log to `.kolbo/production.md`. Do NOT claim it worked.
-3. **Tool hangs / never returns** — MCP poll timed out. Call `get_generation_status(generation_id)` IMMEDIATELY. The server might be done.
+3. **Tool hangs / never returns** — MCP poll timed out. Call `get_generation_status(generation_id, wait=true)` IMMEDIATELY. The server might be done.
 
 **Always:**
 - Don't celebrate before reading the result. Verify `urls` is non-empty.

package/skill/references/workflows/cost-and-validation.md

@@ -48,6 +48,8 @@ Apply when confirming cost before firing:
 
 **Batch totalling 100+ credits:** run `check_credits` first and include the available balance in the summary.
 
+**After generating, report cost only — never "credits remaining".** Coding/chat usage also deducts credits, so any balance you compute (opening balance − generation costs) is wrong by the time you say it. Quote `credits_used` per generation / batch total; if the user asks what's left, run `check_credits` fresh at that moment and quote that number.
+
 ## ⚠️ Quote Real Cost, Never Estimates (CRITICAL)
 
 Pre-flight formulas above are for **preview only**. After firing, every generation returns `credits_used` (multiplier-adjusted total) and `credits_breakdown` (per-model attribution).

package/skill/references/workflows/troubleshooting.md

@@ -30,6 +30,10 @@ This re-wires the MCP configuration automatically. Then restart the session.
 
 Wait 60s for the window to reset, retry only the failed calls. For batch image work prefer `generate_creative_director` over multiple `generate_image` calls. Full rate-limit details + retry sequence: see SKILL.md "Rate Limiting & Batch Generation".
 
+## Checking generation status without spinning
+
+`get_generation_status` supports `wait=true` (blocks server-side until the generation reaches a final state, up to ~3 min) and `generation_ids` (many ids in one call → returns `all_done`, `still_processing`, and per-generation results). **Never call it repeatedly in a loop** — one `wait=true` call replaces the loop. If some generations are still running after the wait window, call it ONCE more with `wait=true` and only the `still_processing` ids.
+
 ## Failure envelope from `get_generation_status`
 
 When a generation fails, `get_generation_status` returns a structured `failure` field alongside `error`:

package/src/index.js

@@ -69,6 +69,7 @@ const { registerPresetTools } = require('./tools/presets');
 const { registerAppBuilderTools } = require('./tools/app_builder');
 const { registerArtifactTools } = require('./tools/artifacts');
 const { registerProjectTools } = require('./tools/projects');
+const { registerDocTools } = require('./tools/docs');
 const { registerVoiceTools } = require('./tools/voices');
 const { registerMusicLibraryTools } = require('./tools/music_library');
 const { registerStockLibraryTools } = require('./tools/stock_library');
@@ -113,7 +114,8 @@ function createServer(opts = {}) {
       '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.',
       '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.'
+      '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`).'
     ].join('\n')
   });
 
@@ -133,6 +135,7 @@ function createServer(opts = {}) {
   registerAppBuilderTools(server, client, toolOptions);
   registerArtifactTools(server, client, toolOptions);
   registerProjectTools(server, client, toolOptions);
+  registerDocTools(server, client, toolOptions);
   registerMusicLibraryTools(server, client, toolOptions);
   registerStockLibraryTools(server, client, toolOptions);
   registerShortsCreatorTools(server, client, toolOptions);

package/src/tools/_shared.js

@@ -396,7 +396,7 @@ async function uiGenerating(p) {
   const text = JSON.stringify({
     status: 'submitted',
     generation_id: p.gen.generation_id,
-    _widget_note: 'A live Kolbo widget is rendering this generation for the user (progress + final result + action buttons). Tell the user it is generating and the card above will update — do NOT poll in a loop. If you later need the output URLs (e.g. for a follow-up edit), call get_generation_status once with this generation_id.',
+    _widget_note: 'A live Kolbo widget is rendering this generation for the user (progress + final result + action buttons). Tell the user it is generating and the card above will update — do NOT poll in a loop. If you need the output URLs (e.g. for a follow-up edit or a report), call get_generation_status ONCE with wait=true — it blocks until done. Tracking several generations? Pass ALL their ids in generation_ids in that one call.',
   }, null, 2);
   return uiResult(UI.generation, text, structured);
 }

package/src/tools/docs.js

@@ -0,0 +1,119 @@
+/* ⛔ BACKWARD COMPATIBILITY: Tool names and arg names below are a PUBLIC
+ * CONTRACT. Never rename, remove, or break an existing tool/arg — old cached
+ * `npx @kolbo/mcp` installs in the wild will break silently. Add new tools or
+ * new OPTIONAL args only. Full rules: ../index.js top-of-file and CLAUDE.md. */
+
+const { z } = require('zod');
+const { projectIdField } = require('./_shared');
+
+const CONTENT_GUIDE = 'HTML body content. Use clean semantic HTML the in-app editor understands: <h1>-<h3>, <p>, <ul>/<ol>/<li>, <table>, <blockquote>, <strong>/<em>, <a>. No <script>/<style>/<iframe> (stripped server-side). Write the FULL document yourself — this is where you author the doc.';
+
+function registerDocTools(server, client) {
+  // ─── create_doc ────────────────────────────────────────────
+  server.tool(
+    'create_doc',
+    'Create an AI Doc (Magic Pad document) in the user\'s Kolbo workspace. YOU author the document: write complete, well-structured HTML content (plans, briefs, scripts, research summaries, meeting notes…) and save it here so the user can read and edit it in the Kolbo app. Docs are project-scoped — when the user is working in a named project, resolve it with `list_projects` and pass `project_id`. Returns the doc id; use `share_doc` afterwards if the user wants a public link.',
+    {
+      title: z.string().describe('Document title (shown in the app sidebar).'),
+      content: z.string().describe(CONTENT_GUIDE),
+      project_id: projectIdField
+    },
+    async ({ title, content, project_id }) => {
+      const body = { title, content };
+      if (project_id) body.project_id = project_id;
+      const result = await client.post('/v1/docs', body);
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            doc: result.doc,
+            _hint: 'Doc created. The user can open it in the Kolbo app under the project\'s AI Docs. Call share_doc with shared:true to get a public link.'
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── list_docs ─────────────────────────────────────────────
+  server.tool(
+    'list_docs',
+    'List the user\'s AI Docs (Magic Pad documents) across all projects, most recently updated first. Pass `project_id` (from `list_projects`) to narrow to one project. Returns id, title, project_id, share state, and timestamps — use `get_doc` to read a doc\'s content.',
+    {
+      project_id: z.string().optional().describe('Restrict to docs in one project (ObjectId from `list_projects`). Omit to list across all projects.'),
+      page: z.number().optional().describe('Page number, 1-indexed. Default: 1'),
+      limit: z.number().optional().describe('Results per page, max 50. Default: 20')
+    },
+    async ({ project_id, page, limit }) => {
+      const params = new URLSearchParams();
+      if (project_id) params.set('project_id', project_id);
+      if (page) params.set('page', String(page));
+      if (limit) params.set('limit', String(limit));
+      const qs = params.toString();
+      const result = await client.get(`/v1/docs${qs ? '?' + qs : ''}`);
+      return { content: [{ type: 'text', text: JSON.stringify({ docs: result.docs || [], pagination: result.pagination || null }, null, 2) }] };
+    }
+  );
+
+  // ─── get_doc ───────────────────────────────────────────────
+  server.tool(
+    'get_doc',
+    'Fetch one AI Doc including its full HTML content. Use before editing an existing doc (read → modify → `update_doc`).',
+    {
+      doc_id: z.string().describe('The doc ObjectId (from create_doc or list_docs).')
+    },
+    async ({ doc_id }) => {
+      const result = await client.get(`/v1/docs/${encodeURIComponent(doc_id)}`);
+      return { content: [{ type: 'text', text: JSON.stringify(result.doc, null, 2) }] };
+    }
+  );
+
+  // ─── update_doc ────────────────────────────────────────────
+  server.tool(
+    'update_doc',
+    'Update an AI Doc\'s title and/or content. Content REPLACES the whole document — call `get_doc` first, apply the user\'s edits to the full HTML, and send the complete result back.',
+    {
+      doc_id: z.string().describe('The doc ObjectId to update.'),
+      title: z.string().optional().describe('New title. Omit to keep the current one.'),
+      content: z.string().optional().describe('Full replacement ' + CONTENT_GUIDE)
+    },
+    async ({ doc_id, title, content }) => {
+      const body = {};
+      if (title !== undefined) body.title = title;
+      if (content !== undefined) body.content = content;
+      const result = await client.put(`/v1/docs/${encodeURIComponent(doc_id)}`, body);
+      return { content: [{ type: 'text', text: JSON.stringify(result.doc, null, 2) }] };
+    }
+  );
+
+  // ─── share_doc ─────────────────────────────────────────────
+  server.tool(
+    'share_doc',
+    'Enable or disable public sharing of an AI Doc. When enabling, returns a stable public link (app.kolbo.ai/shared/magicpad/…) anyone can open — give it to the user. Set `editable` to also let link visitors edit the doc.',
+    {
+      doc_id: z.string().describe('The doc ObjectId.'),
+      shared: z.boolean().describe('true = publicly shared, false = private again (the link stops working).'),
+      editable: z.boolean().optional().describe('Whether link visitors can edit. Default: unchanged (false for new shares).')
+    },
+    async ({ doc_id, shared, editable }) => {
+      const body = { shared };
+      if (editable !== undefined) body.editable = editable;
+      const result = await client.patch(`/v1/docs/${encodeURIComponent(doc_id)}/share`, body);
+      return { content: [{ type: 'text', text: JSON.stringify(result.doc, null, 2) }] };
+    }
+  );
+
+  // ─── delete_doc ────────────────────────────────────────────
+  server.tool(
+    'delete_doc',
+    'Delete an AI Doc (soft delete — recoverable from the app\'s trash flow). Owner only. Confirm with the user before deleting anything they did not just create in this conversation.',
+    {
+      doc_id: z.string().describe('The doc ObjectId to delete.')
+    },
+    async ({ doc_id }) => {
+      const result = await client.delete(`/v1/docs/${encodeURIComponent(doc_id)}`);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+}
+
+module.exports = { registerDocTools };

package/src/tools/generate.js

@@ -418,17 +418,71 @@ function registerGenerateTools(server, client, options = {}) {
   // ─── get_generation_status ─────────────────────────────────
   server.tool(
     'get_generation_status',
-    'Check the status of a generation. Use this as a FALLBACK when a generation tool returned a timeout error — the generation is probably still running on the server. Pass the generation_id from the timeout error (or from any prior generation response).',
+    'Check the status of one or more generations. Use after a generation tool returned "submitted" (widget hosts) or timed out. Tracking SEVERAL concurrent generations? Pass them ALL in generation_ids — one call returns an all_done summary. Need the final result? Set wait=true and the server blocks until every generation finishes (up to ~3 min). NEVER call this tool repeatedly in a loop — one wait=true call replaces the whole loop.',
     {
-      generation_id: z.string().describe('The generation ID to check')
+      generation_id: z.string().optional().describe('A single generation ID to check'),
+      generation_ids: z.array(z.string()).optional().describe('Multiple generation IDs to check in ONE call. Returns { all_done, pending, generations[] } — always prefer this over checking IDs one by one.'),
+      wait: z.boolean().optional().describe('If true, block until every generation reaches a terminal state (completed/failed), up to ~3 minutes, then return the final results. Use this instead of re-calling the tool in a loop.')
     },
-    async ({ generation_id }) => {
-      const result = await client.get(`/v1/generate/${encodeURIComponent(generation_id)}/status`);
+    async ({ generation_id, generation_ids, wait }) => {
+      const ids = (generation_ids && generation_ids.length > 0)
+        ? generation_ids
+        : (generation_id ? [generation_id] : []);
+      if (ids.length === 0) throw new Error('Provide generation_id or generation_ids');
+
+      // One status check (or blocking poll) per id. Never let one bad id
+      // reject the whole batch — surface it as a failed entry instead.
+      const checkOne = async (id) => {
+        try {
+          if (wait) {
+            const result = await pollUntilDone(client, id, { interval: 5000, timeout: 180000 });
+            return { generation_id: id, ...result };
+          }
+          const result = await client.get(`/v1/generate/${encodeURIComponent(id)}/status`);
+          return { generation_id: id, ...result };
+        } catch (err) {
+          if (err.timedOut) {
+            return { generation_id: id, state: 'processing', note: 'Still running after 3 min of waiting — call get_generation_status again with wait=true.' };
+          }
+          if (err.name === 'GenerationFailedError') {
+            return { generation_id: id, state: 'failed', error: err.message };
+          }
+          return { generation_id: id, state: 'unknown', error: err.message };
+        }
+      };
+
+      const results = await Promise.all(ids.map(checkOne));
+
+      const pending = results.filter(r => r.state !== 'completed' && r.state !== 'failed' && r.state !== 'cancelled');
+      const doneHint = 'ALL generations are in a final state — do NOT poll again. Report the results to the user.';
+      const pendingHint = wait
+        ? 'Some generations are still running after the wait window. Call get_generation_status ONCE more with wait=true and the remaining generation_ids — do not spin without wait.'
+        : 'Some generations are still processing. Do NOT re-call this tool in a loop — call it ONCE with wait=true (and all pending generation_ids) to block until they finish.';
+
+      // Single-id calls keep the original flat shape — the generation widget
+      // polls this tool with { generation_id } and reads state/result at the
+      // top level.
+      if (!generation_ids || generation_ids.length === 0) {
+        const single = results[0];
+        single._hint = pending.length === 0
+          ? 'This generation is in a FINAL state — do not poll it again.'
+          : pendingHint;
+        return {
+          content: [{ type: 'text', text: JSON.stringify(single, null, 2) }]
+        };
+      }
 
       return {
         content: [{
           type: 'text',
-          text: JSON.stringify(result, null, 2)
+          text: JSON.stringify({
+            all_done: pending.length === 0,
+            completed: results.filter(r => r.state === 'completed').length,
+            failed: results.filter(r => r.state === 'failed' || r.state === 'cancelled').length,
+            still_processing: pending.map(r => r.generation_id),
+            _hint: pending.length === 0 ? doneHint : pendingHint,
+            generations: results
+          }, null, 2)
         }]
       };
     }
@@ -833,7 +887,7 @@ function registerGenerateTools(server, client, options = {}) {
         return uiResult(UI.transcript, JSON.stringify({
           status: 'submitted',
           generation_id: startResponse.generation_id,
-          _widget_note: 'A live Kolbo transcription widget is rendering above — it shows progress, the transcript text, and SRT/TXT download buttons. Tell the user it is transcribing. If you need the transcript text for a follow-up step, call get_generation_status with this generation_id once done.',
+          _widget_note: 'A live Kolbo transcription widget is rendering above — it shows progress, the transcript text, and SRT/TXT download buttons. Tell the user it is transcribing. If you need the transcript text for a follow-up step, call get_generation_status ONCE with this generation_id and wait=true — it blocks until done; do NOT poll in a loop.',
         }, null, 2), {
           widget: 'transcript', phase: 'generating',
           generation_id: startResponse.generation_id,