@kolbo/mcp 1.87.14 → 1.88.0

package/README.md

@@ -1,5 +1,13 @@
 # @kolbo/mcp
 
+## Personal fonts
+
+Browse **My fonts** with `list_fonts({source:"custom"})` (the default), or the read-only **Font collection** with `source:"global"`. Use `source:"all"` to search both. Mix up to three family IDs across both sources in the same generation; inspect actual styles/scripts with `get_font`. Collection fonts do not need uploading and cannot be renamed or deleted by users.
+
+Use `list_fonts` / `get_font` to discover My Fonts. Local stdio clients upload one OTF/TTF/WOFF2 (up to 5 MiB) with `upload_font`; remote shell clients use `create_font_upload_ticket`, and browser clients use `font_upload_widget`. Poll `get_font_upload_status` until ready, then pass the returned family ID in `font_ids` to image creation/editing or image-mode Creative Director. `rename_font` and `delete_font` manage the library.
+
+Only models reporting `supports_custom_fonts: true` accept these selections. Fonts and backend-generated specimens never go through media upload. See [Personal Fonts](https://docs.kolbo.ai/developer-api/personal-fonts). Availability requires a published client and deployed backend containing these tools; source changes alone do not update installed clients.
+
 Use [Kolbo AI](https://kolbo.ai) as native tools in Claude Code and Claude Desktop via MCP (Model Context Protocol).
 
 Generate images, videos, music, speech, sound effects, multi-scene campaigns, and conversational chat — all from natural language in your coding environment. 100+ AI models behind Smart Select routing, with reusable Visual DNA profiles for character/style consistency.

package/package.json

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

package/src/apps/index.js

@@ -21,6 +21,7 @@ const { mediaGridWidgetHtml } = require('./widgets/mediaGrid');
 const { catalogWidgetHtml } = require('./widgets/catalog');
 const { transcriptWidgetHtml } = require('./widgets/transcript');
 const { uploadWidgetHtml } = require('./widgets/upload');
+const { fontUploadWidgetHtml } = require('./widgets/fontUpload');
 const { listWidgetHtml } = require('./widgets/list');
 const { HOST_MAP } = require('../cdn');
 const { plansWidgetHtml } = require('./widgets/plans');
@@ -31,6 +32,7 @@ const UI = {
   catalog: 'ui://kolbo/catalog.html',
   transcript: 'ui://kolbo/transcript.html',
   upload: 'ui://kolbo/upload.html',
+  fontUpload: 'ui://kolbo/font-upload.html',
   list: 'ui://kolbo/list.html',
   plans: 'ui://kolbo/plans.html',
 };
@@ -41,6 +43,7 @@ const WIDGET_BUILDERS = {
   [UI.catalog]: catalogWidgetHtml,
   [UI.transcript]: transcriptWidgetHtml,
   [UI.upload]: uploadWidgetHtml,
+  [UI.fontUpload]: fontUploadWidgetHtml,
   [UI.list]: listWidgetHtml,
   [UI.plans]: plansWidgetHtml,
 };
@@ -732,6 +735,7 @@ const TOOL_WIDGETS = {
   list_color_palettes: UI.mediaGrid,
   // upload widget
   media_upload_widget: UI.upload,
+  font_upload_widget: UI.fontUpload,
   // generic list widget — flat record lists with no natural thumbnail
   list_projects: UI.list,
   // Must stay list.html — mapping this to generation.html mounts "Kolbo Generation /

package/src/apps/widgets/fontUpload.js

@@ -0,0 +1,45 @@
+'use strict';
+const { widgetPage } = require('../html');
+function fontUploadWidgetHtml() {
+  return widgetPage({ title: 'My Fonts', body: '<div class="k-card"><div class="k-head">Upload to My Fonts</div><div class="k-body"><p>One OTF, TTF or WOFF2 file · up to 5 MiB</p><input id="font" type="file" accept=".otf,.ttf,.woff2" aria-label="Choose font"><button id="external" type="button">Open browser upload</button><p id="status" role="status"></p></div></div>', script: `
+var state;
+window.kolbo.onToolResult(function(result) { state = result.structuredContent || structured(result); });
+function endpoint() {
+  if (!state) throw new Error('Waiting for upload ticket.');
+  var url = new URL(state.upload_url);
+  if (url.protocol !== 'https:' || !['api.kolbo.ai','upload-api.kolbo.ai'].includes(url.host) || url.pathname !== '/api/v1/fonts/ticket-upload' || url.search || url.hash || url.username || url.password) throw new Error('Unsupported font upload endpoint. Use a shell upload ticket instead.');
+  if (!Number.isFinite(Date.parse(state.expires_at)) || Date.now() >= Date.parse(state.expires_at)) throw new Error('Ticket expired. Open a new font upload card.');
+  if (!/^[A-Za-z0-9_-]{43}$/.test(state.token)) throw new Error('Invalid upload ticket. Open a new card.');
+  return url;
+}
+el('external').onclick = async function() {
+  try {
+    var url = endpoint();
+    url.pathname = '/api/v1/fonts/upload-ui';
+    url.hash = 'ticket=' + encodeURIComponent(state.token);
+    await window.kolbo.openLink(url.href);
+    el('font').disabled = true;
+    this.disabled = true;
+    el('status').textContent = 'After uploading in the browser, return with the preparation ID shown there.';
+  } catch(error) { el('status').textContent = error.message; }
+};
+el('font').onchange = async function() {
+  var file = this.files[0];
+  if (!file || !state) return;
+  if (!/\\.(otf|ttf|woff2)$/i.test(file.name) || file.size > 5242880 || !file.size) { el('status').textContent = 'Choose a font up to 5 MiB.'; return; }
+  this.disabled = true;
+  el('external').disabled = true;
+  el('status').textContent = 'Uploading font…';
+  try {
+    var url = endpoint();
+    var body = new FormData(); body.append('file', file);
+    var response = await fetch(url.href, {method:'POST',headers:{Authorization:'Bearer '+state.token},body:body,credentials:'omit',redirect:'error',signal:AbortSignal.timeout(65000)});
+    var result = await response.json();
+    if (!response.ok) throw new Error(typeof result.error === 'string' ? result.error : 'Upload failed. Open a new font upload card to retry.');
+    el('status').textContent = 'Uploaded. Preparing font…';
+    await window.kolbo.updateModelContext('Font uploaded to My Fonts. Poll get_font_upload_status before generating: '+JSON.stringify(result.data));
+  } catch(error) { el('status').textContent = error.message; }
+  window.kolbo.notifySize();
+};` });
+}
+module.exports = { fontUploadWidgetHtml };

package/src/index.js

@@ -66,6 +66,7 @@ const { registerChatTools } = require('./tools/chat');
 const { registerVisualDnaTools } = require('./tools/visual_dna');
 const { registerMoodboardTools } = require('./tools/moodboards');
 const { registerColorPaletteTools } = require('./tools/color_palettes');
+const { registerFontTools } = require('./tools/fonts');
 const { registerMediaTools } = require('./tools/media');
 const { registerPresetTools } = require('./tools/presets');
 const { registerArtifactTools } = require('./tools/artifacts');
@@ -115,6 +116,7 @@ function createServer(opts = {}) {
     // The single most common failure mode is project confusion — spell out
     // the project contract here so every client gets it without a skill file.
     instructions: [
+      'PERSONAL FONTS: use list_fonts/get_font, upload_font for local stdio, create_font_upload_ticket for remote shell, or font_upload_widget for browser uploads. Never use media upload for fonts. Poll get_font_upload_status until ready, then pass up to three family IDs as font_ids to image creation/editing or image-mode Creative Director. Verify supports_custom_fonts in model discovery. The backend prepares private specimens; never render or attach specimens yourself.',
       'LOCAL FILES: never upload a user file with your own cloud credentials, an S3/Spaces script, or a third-party host — Kolbo owns this. ' + LOCAL_FILE_ROUTING,
       'PROMPT CONVENTIONS (Kolbo-specific — these change the OUTPUT, not just the metadata):',
       'A. Visual DNA: passing `visual_dna_ids` is not enough — every DNA in play must ALSO be tagged inside the prompt text as `@Name`, using the DNA name (e.g. "@Kobi walks into frame"). Moodboards are referenced the same way with `#Name`. Resolve names via `list_visual_dnas` / `list_moodboards`.',
@@ -183,6 +185,7 @@ function createServer(opts = {}) {
   registerVisualDnaTools(server, client, toolOptions);
   registerMoodboardTools(server, client, toolOptions);
   registerColorPaletteTools(server, client, toolOptions);
+  registerFontTools(server, client, { allowLocalFiles: opts.allowLocalFiles === true && !toolOptions.remote });
   registerAnalyzeTools(server, client, toolOptions);
   registerMediaTools(server, client, toolOptions);
   registerPresetTools(server, client, toolOptions);
@@ -219,7 +222,7 @@ function createServer(opts = {}) {
 }
 
 async function main() {
-  const server = createServer();
+  const server = createServer({ allowLocalFiles: true });
 
   // Node kills the process on an unhandled rejection / uncaught exception. In a
   // long-lived stdio server that is not a stack trace the user ever sees — the

package/src/toolAnnotations.js

@@ -9,6 +9,7 @@
  */
 
 const READ_ONLY = [
+  'list_fonts', 'get_font', 'get_font_upload_status',
   'get_creative_director_status', 'get_generation_status', 'list_models',
   'check_credits', 'show_plans', 'get_session_usage', 'list_voices',
   'chat_list_conversations', 'chat_get_messages',
@@ -36,6 +37,7 @@ const OPEN_WORLD_READ_ONLY = [
 ];
 
 const PRIVATE_WRITE = [
+  'upload_font', 'rename_font', 'create_font_upload_ticket', 'font_upload_widget',
   'media_upload_widget', 'create_upload_ticket', 'upload_media',
   'favorite_media', 'unfavorite_media',
   'create_media_folder', 'update_media_folder',
@@ -64,6 +66,7 @@ const PRIVATE_WRITE = [
 ];
 
 const DESTRUCTIVE_WRITE = [
+  'delete_font',
   // These actions spend credits, enqueue irreversible work, or cancel it.
   'generate_image', 'generate_image_edit', 'generate_creative_director',
   'generate_video', 'generate_video_from_image', 'generate_music',

package/src/tools/fonts.js

@@ -0,0 +1,49 @@
+'use strict';
+const { z } = require('zod');
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const FormData = require('form-data');
+const { UI, uiResult } = require('../apps');
+const id = z.string().regex(/^[a-f0-9]{24}$/i);
+const result = value => ({ content: [{ type: 'text', text: JSON.stringify(value) }] });
+
+function registerFontTools(server, client, options = {}) {
+  server.tool('list_fonts', 'Browse My fonts or the curated Font collection using source. Use ready family IDs from either as font_ids; previews are authenticated, not public media.', {
+    source: z.enum(['custom', 'global', 'all']).optional().describe('custom (default): My fonts, global: read-only Font collection, all: both. IDs from either can be combined.'),
+    search: z.string().max(120).optional(), cursor: z.string().optional(), limit: z.number().int().min(1).max(50).optional(),
+  }, async options => result(await client.get('/v1/fonts?' + new URLSearchParams(Object.entries(options).filter(([, value]) => value !== undefined)))));
+  server.tool('get_font', 'Inspect a personal or collection font family by ID, including available styles, scripts, source and collection license.', { font_id: id }, async ({ font_id }) => result(await client.get(`/v1/fonts/${font_id}`)));
+  server.tool('get_font_upload_status', 'Poll a font upload until ready or failed. Use its font_id only after ready.', { upload_id: id }, async ({ upload_id }) => result(await client.get(`/v1/fonts/uploads/${upload_id}`)));
+  server.tool('rename_font', 'Rename a family in My Fonts.', { font_id: id, name: z.string().min(1).max(120) }, async ({ font_id, name }) => result(await client.patch(`/v1/fonts/${font_id}`, { name })));
+  server.tool('delete_font', 'Delete a personal font family from future use. Completed generated images are not deleted.', { font_id: id }, async ({ font_id }) => result(await client.delete(`/v1/fonts/${font_id}`)));
+  server.tool('upload_font', 'Upload one LOCAL OTF, TTF or WOFF2 font (up to 5 MiB) directly to My Fonts, not the media library. Local stdio only: remote clients must use create_font_upload_ticket or font_upload_widget. Poll get_font_upload_status until ready.', {
+    file_path: z.string(), language: z.string().max(32).optional(),
+  }, async ({ file_path, language }) => {
+    if (!options.allowLocalFiles) throw new Error('Remote font upload: use create_font_upload_ticket or font_upload_widget; server-local file access is disabled');
+    if (!path.isAbsolute(file_path) || !/\.(otf|ttf|woff2)$/i.test(file_path)) throw new Error('Choose an absolute OTF, TTF or WOFF2 path');
+    const handle = await fs.open(file_path, 'r');
+    try {
+      const stat = await handle.stat();
+      if (!stat.isFile() || stat.size < 1 || stat.size > 5 * 1024 * 1024) throw new Error('Font must be a regular file up to 5 MiB');
+      const form = new FormData();
+      const bytes = Buffer.alloc(stat.size);
+      let offset = 0;
+      while (offset < bytes.length) {
+        const read = await handle.read(bytes, offset, bytes.length - offset, offset);
+        if (!read.bytesRead) throw new Error('Font changed during upload; choose the file again');
+        offset += read.bytesRead;
+      }
+      form.append('file', bytes, { filename: path.basename(file_path), knownLength: bytes.length });
+      if (language) form.append('language', language);
+      return result(await client.postMultipart('/v1/fonts', form));
+    } finally { await handle.close(); }
+  });
+  server.tool('create_font_upload_ticket', 'Create a one-use, ten-minute ticket for a remote client with shell access. POST multipart field file to upload_url with Authorization: Bearer <ticket>. Never use upload_media for fonts. Poll returned upload ID with get_font_upload_status.', {}, async () => result(await client.post('/v1/fonts/upload-tickets', {})));
+  server.tool('font_upload_widget', 'Show a dedicated font upload picker for browser-only clients. Uploads ONE OTF/TTF/WOFF2 up to 5 MiB into My Fonts. Create another widget for another file or retry. Poll returned upload ID until ready.', {}, async () => {
+    const { data } = await client.post('/v1/fonts/upload-tickets', {});
+    return uiResult(UI.fontUpload, 'Choose a font in the upload card, then poll get_font_upload_status with the returned upload ID.', {
+      widget: 'font-upload', upload_url: data.upload_url, token: data.ticket, expires_at: data.expires_at,
+    });
+  });
+}
+module.exports = { registerFontTools };

package/src/tools/generate.js

@@ -162,6 +162,7 @@ const ELEMENTS_MAX_UPLOAD_BYTES = 200 * 1024 * 1024;
 // the card, and not the agent reading the tool result, so a follow-up call
 // could not reuse the same DNA or preset without re-listing. Carry the ids.
 const refSettings = (a = {}) => ({
+  font_ids: a.font_ids?.length ? a.font_ids : undefined,
   enhance_prompt: a.enhance_prompt || undefined,
   web_search: a.enable_web_search || undefined,
   visual_dna_ids: (a.visual_dna_ids && a.visual_dna_ids.length) ? a.visual_dna_ids : undefined,
@@ -258,6 +259,7 @@ function registerGenerateTools(server, client, options = {}) {
     {
       prompt: z.string().optional().describe('Text description of the image to generate. Required unless `prompts` is provided.'),
       prompts: promptsField('images'),
+      font_ids: z.array(z.string().regex(/^[a-f0-9]{24}$/i)).max(3).optional().describe('Ready family IDs from My Fonts (list_fonts/upload_font). Requires supports_custom_fonts=true. State exact text/language/weight in prompt; server prepares private references. Applies to every prompt in a batch.'),
       model: z.string().optional().describe('Model identifier — REQUIRED in practice: pick a specific model, do NOT omit (omitting = Smart Select auto-pick, which we avoid). Strong current defaults: "nano-banana-2" (versatile, text rendering, multilingual) or "gpt-image-2" (photoreal, infographics). Call list_models type="text_to_img" to see all options and pick per the user\'s intent.'),
       aspect_ratio: z.string().optional().describe(aspectRatioDescribe('1:1')),
       enhance_prompt: z.boolean().optional().describe('Enhance the prompt for better results. Default: false — only pass true if the user explicitly asks to enhance/improve the prompt.'),
@@ -274,12 +276,12 @@ function registerGenerateTools(server, client, options = {}) {
       project_id: projectIdField,
       session_id: sessionIdField
     },
-    async ({ prompt, prompts, model, aspect_ratio, enhance_prompt = false, num_images, reference_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, quality, preset_id, cinematic, skip_color_palette, project_id, session_id }) => {
+    async ({ prompt, prompts, model, aspect_ratio, enhance_prompt = false, num_images, reference_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, quality, preset_id, cinematic, skip_color_palette, project_id, session_id, font_ids }) => {
       if (!prompt && !(prompts && prompts.length)) throw new Error('Provide prompt or prompts');
       model = await canonicalModelId(client, model, 'text_to_img'); // lenient id resolution ("z-image" → "z-image/turbo")
       aspect_ratio = await resolveCatalogAspectRatio(client, model, aspect_ratio, 'text_to_img');
       const shared = {
-        model, aspect_ratio, enhance_prompt,
+        model, aspect_ratio, enhance_prompt, font_ids,
         reference_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, quality, preset_id, cinematic, skip_color_palette, project_id, session_id
       };
 
@@ -342,6 +344,7 @@ function registerGenerateTools(server, client, options = {}) {
     {
       prompt: z.string().optional().describe('Description of the edit to apply (e.g., "remove the background", "change the sky to sunset"). Required unless `prompts` is provided.'),
       prompts: promptsField('edits of the SAME source images'),
+      font_ids: z.array(z.string().regex(/^[a-f0-9]{24}$/i)).max(3).optional().describe('Ready My Fonts family IDs. Requires supports_custom_fonts=true. Describe requested typography changes; unrelated text is preserved. Applies to every batch edit.'),
       model: z.string().optional().describe('Model identifier — REQUIRED in practice: pick a specific model, do NOT omit (omitting = Smart Select auto-pick, which we avoid). Many text-to-image ids double as editors: the server auto-routes a base id to its editing variant when source_images is present (e.g. "gpt-image-2" → gpt-image-2/edit, "nano-banana-2" → nano-banana-2-image-editing) — passing the bare id is fine, no need to hunt for the "/edit" suffix yourself. BUT this only works for models that actually have a registered edit variant. For prompt-driven photoreal photo edits (object removal, keep-this-person/remove-the-rest, crowd cleanup, inpainting) the ONLY auto-pick defaults are "nano-banana-2" or "gpt-image-2" (use GPT Image 2 when the image needs readable text). Do NOT auto-pick Flux 2 / flux-2/edit / Flux Klein — those are generate-from-scratch / style models; use them only if the user names Flux. If unsure, confirm the model appears in `list_models type="image_editing"` and choose by the strengths summary — Flux edit variants are named-only.'),
       source_images: z.array(z.string()).describe('PIXEL-ACCURATE compositing. Array of source images (URLs or absolute local paths) whose pixel content is composited into the output. **Cap: pass at most `max_reference_images` URLs from list_models for the chosen model — exceeding it is a deterministic 400.** Three modes the model auto-detects from input shape: (1) Single image → edit/transform that image. (2) Multiple images, one base + others → composite the others into the base. (3) Multiple images with no clear base → generate a new scene that pixel-accurately embeds the supplied images at positions described in the prompt. Mode 3 is the canonical pattern for thumbnails / branded compositions where exact-pixel logo + face fidelity matter. Refer to source images in the prompt by ordinal position ("FIRST source image", "SECOND source image") or use @image1/@image2 tags. Add "composite AS-IS, do not redraw or restyle" to lock pixels.'),
       reference_images: z.array(z.string()).optional().describe('STYLE/COMPOSITION inspiration, alongside `source_images` on the same call — does NOT embed reference pixels. Use when the edit should follow a look sampled from other images ("re-light this shot like these references"). The pixels that must survive the edit go in `source_images`; these only steer the look. **Cap: `source_images` + `reference_images` together must not exceed `max_reference_images` from list_models for the chosen model.**'),
@@ -359,12 +362,12 @@ function registerGenerateTools(server, client, options = {}) {
       project_id: projectIdField,
       session_id: sessionIdField
     },
-    async ({ prompt, prompts, model, source_images, reference_images, aspect_ratio, enhance_prompt = false, num_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, quality, preset_id, cinematic, skip_color_palette, project_id, session_id }) => {
+    async ({ prompt, prompts, model, source_images, reference_images, aspect_ratio, enhance_prompt = false, num_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, quality, preset_id, cinematic, skip_color_palette, project_id, session_id, font_ids }) => {
       if (!prompt && !(prompts && prompts.length)) throw new Error('Provide prompt or prompts');
       model = await canonicalModelId(client, model, 'image_editing'); // lenient id resolution ("z-image" → "z-image/turbo")
       aspect_ratio = await resolveCatalogAspectRatio(client, model, aspect_ratio, 'image_editing');
       const shared = {
-        model, source_images, reference_images, aspect_ratio, enhance_prompt,
+        model, source_images, reference_images, aspect_ratio, enhance_prompt, font_ids,
         visual_dna_ids, moodboard_id, enable_web_search, resolution, quality, preset_id, cinematic, skip_color_palette, project_id, session_id
       };
       const settings = imageSettings(shared);
@@ -444,13 +447,14 @@ function registerGenerateTools(server, client, options = {}) {
       moodboard_id: z.string().optional().describe('A single moodboard ID whose master_prompt and style_guide should shape every scene.'),
       moodboard_ids: z.array(z.string()).optional().describe('Multiple moodboard IDs when blending styles. Prefer `moodboard_id` for single moodboards.'),
       resolution: z.string().optional().describe('Resolution tier applied to every scene. Images: "1K" / "2K" / "3K" / "4K". Videos: "720p" / "1080p" / "1440p" / "2160p". Values are model-dependent — call list_models and read supported_resolutions on the target model. Multiplied across every scene.'),
+      font_ids: z.array(z.string().regex(/^[a-f0-9]{24}$/i)).max(3).optional().describe('Image workflows only: ready My Fonts family IDs applied to each scene. Requires supports_custom_fonts=true; do not create specimen references yourself.'),
       project_id: projectIdField
     },
-    async ({ prompt, scene_count, model, aspect_ratio, workflow_type, duration, enhance_prompt = false, reference_images, visual_dna_ids, moodboard_id, moodboard_ids, resolution, project_id }) => {
+    async ({ prompt, scene_count, model, aspect_ratio, workflow_type, duration, enhance_prompt = false, reference_images, visual_dna_ids, moodboard_id, moodboard_ids, resolution, project_id, font_ids }) => {
       model = await canonicalModelId(client, model, workflow_type === 'video' ? 'text_to_video' : 'text_to_img'); // lenient id resolution ("z-image" → "z-image/turbo")
       aspect_ratio = await resolveCatalogAspectRatio(client, model, aspect_ratio, workflow_type === 'video' ? 'text_to_video' : 'text_to_img');
       const gen = await client.post('/v1/generate/creative-director', {
-        prompt, scene_count, model, aspect_ratio, workflow_type, duration,
+        prompt, scene_count, model, aspect_ratio, workflow_type, duration, font_ids,
         enhance_prompt, reference_images, visual_dna_ids, moodboard_id, moodboard_ids, resolution, project_id
       });