@kolbo/mcp 1.60.0 → 1.62.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.60.0",
+  "version": "1.62.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

@@ -170,7 +170,7 @@ function uiResult(uri, text, structured) {
 /* ------------------------------------------------------------------ */
 
 const ICON_TTL_MS = 10 * 60 * 1000;
-const infoCache = new Map(); // apiBase → { at, byKey: Map<lowername, {icon, eta}> }
+const infoCache = new Map(); // apiBase → { at, byKey: Map<lowername, info>, all: info[] }
 
 /**
  * Resolve a Model.avatar value to an absolute URL. Avatars are bare filenames
@@ -189,11 +189,12 @@ function resolveAvatarUrl(avatar) {
   return `${ICON_CDN_BASE}/${encodeURIComponent(avatar)}`;
 }
 
-async function modelInfoMap(client) {
+async function modelCatalog(client) {
   const cacheKey = client.apiBase || 'default';
   const hit = infoCache.get(cacheKey);
-  if (hit && Date.now() - hit.at < ICON_TTL_MS) return hit.byKey;
+  if (hit && Date.now() - hit.at < ICON_TTL_MS) return hit;
   const byKey = new Map();
+  const all = [];
   try {
     const res = await client.request('GET', '/v1/models');
     const models = res?.models || res?.data?.models || [];
@@ -206,10 +207,17 @@ async function modelInfoMap(client) {
       // `name` is the CLEAN display name ("Google TTS"); it is what widgets show.
       // Without it the model chip fell back to whatever raw string the caller or
       // the status endpoint supplied ("google_tts", "fal-ai/bytedance/omnihuman/v1.5").
-      const info = { icon, eta, id: m.identifier || null, name: m.name || null };
+      // `types` is the catalog `type` array ("text_to_video", "img_to_video", …) —
+      // the ONLY thing that tells two same-named variants apart. See canonicalModelId.
+      const raw = m.types !== undefined ? m.types : m.type;
+      const types = (Array.isArray(raw) ? raw : [raw]).filter(Boolean).map(String);
+      const info = { icon, eta, id: m.identifier || null, name: m.name || null, types };
+      all.push(info);
       // Display names collide across variants ("Nano Banana 2" names both the
       // t2i model and its editing sibling) — on collision keep the model with
-      // the SHORTEST identifier (the base model), deterministically.
+      // the SHORTEST identifier (the base model), deterministically. This map is
+      // for ICONS/ETAs, where the variant doesn't matter; identifier resolution
+      // must NOT use it (that is what made "Kling 2.6 Pro" always mean the t2v one).
       const setName = (k) => {
         const prev = byKey.get(k);
         if (!prev || !prev.id || (info.id && info.id.length < prev.id.length)) byKey.set(k, info);
@@ -220,11 +228,16 @@ async function modelInfoMap(client) {
   } catch (_) {
     /* fail open — widgets fall back to monogram chips, no ETA */
   }
+  const entry = { at: Date.now(), byKey, all };
   // Never cache an empty map: the first request in a fresh worker (typical
   // right after a deploy restart) can fail transiently, and caching that
   // failure blanks every model icon for the TTL window.
-  if (byKey.size > 0) infoCache.set(cacheKey, { at: Date.now(), byKey });
-  return byKey;
+  if (byKey.size > 0) infoCache.set(cacheKey, entry);
+  return entry;
+}
+
+async function modelInfoMap(client) {
+  return (await modelCatalog(client)).byKey;
 }
 
 /** Resolve one model's { icon, eta, name }; missing → all null. */
@@ -291,6 +304,22 @@ const AUTO_ALIASES = new Set([
   'auto', 'autoselect', 'smartselect', 'kolbosmartselectrouter', 'default', 'none',
 ]);
 
+/**
+ * Narrow several models that answer to the same string down to one identifier.
+ * The CALLING TOOL's catalog type decides: a display name like "Kling 2.6 Pro"
+ * names one model PER MODALITY (…/text-to-video and …/image-to-video), and only
+ * the caller knows which it wants. No type match (or no type given) → shortest
+ * identifier, the same deterministic tiebreak the icon map uses.
+ */
+function pickForType(candidates, types) {
+  if (!candidates.length) return null;
+  const typed = types.length
+    ? candidates.filter((i) => i.types.some((t) => types.includes(t)))
+    : [];
+  const pool = typed.length ? typed : candidates;
+  return pool.reduce((a, b) => (b.id.length < a.id.length ? b : a)).id;
+}
+
 /**
  * Lenient model-identifier resolution for LLM-supplied model args.
  * Users say "z-image"; the real identifier is "z-image/turbo" — the backend
@@ -299,6 +328,12 @@ const AUTO_ALIASES = new Set([
  * else a separator-insensitive hit ("flux-2-flash" → "flux-2/flash"); else a
  * UNIQUE prefix match ("z-image" → "z-image/turbo").
  *
+ * `type` is the calling tool's catalog type (a string, or an array when the
+ * tool spans several — lipsync, 3D). It is what makes resolution MODALITY-AWARE:
+ * without it, "Kling 2.6 Pro" from generate_video_from_image resolved to
+ * kling-video/v2.6/pro/text-to-video (2026-08-10), so the image-to-video
+ * pipeline submitted the TEXT-to-video endpoint and billed against it.
+ *
  * Still unresolved: throw with the near misses named. The API answers a bad
  * identifier with a bare INVALID_*_MODEL and no hint, which on 2026-08-09 sent
  * an agent guessing "minimax-hailuo-3" (real id: "minimax-h3") and then
@@ -307,43 +342,46 @@ const AUTO_ALIASES = new Set([
  * unchanged, so identifiers the catalog does not publish (hidden models) still
  * reach the API and it stays the source of truth.
  */
-async function canonicalModelId(client, input) {
+async function canonicalModelId(client, input, type) {
   if (!input || typeof input !== 'string') return input;
   const key = input.toLowerCase().trim();
   const want = normId(key);
   if (!want || AUTO_ALIASES.has(want)) return input;
 
-  let map;
+  let all;
   try {
-    map = await modelInfoMap(client);
+    all = (await modelCatalog(client)).all;
   } catch (_) {
     return input; // fail open — never block a generation on a catalog hiccup
   }
-  if (!map || map.size === 0) return input;
+  const models = (all || []).filter((i) => i.id);
+  if (!models.length) return input;
+
+  const types = (Array.isArray(type) ? type : [type]).filter(Boolean);
+  const dashed = key.replace(/\s+/g, '-');
 
   // 1. exact name / identifier hit
-  const hit = map.get(key) || map.get(key.replace(/\s+/g, '-'));
-  if (hit && hit.id) return hit.id;
-
-  // 2 + 3. separator-insensitive exact, then unique prefix
-  const byNorm = new Map();
-  for (const info of map.values()) {
-    if (!info.id) continue;
-    for (const k of [info.id, info.name]) {
-      const n = normId(k);
-      if (n && !byNorm.has(n)) byNorm.set(n, info.id);
-    }
-  }
-  if (byNorm.has(want)) return byNorm.get(want);
-  const prefixed = new Set();
-  for (const [n, id] of byNorm) if (n.startsWith(want)) prefixed.add(id);
-  if (prefixed.size === 1) return [...prefixed][0];
+  const exact = pickForType(models.filter((i) => [i.id, i.name].some(
+    (k) => k && (k.toLowerCase() === key || k.toLowerCase() === dashed)
+  )), types);
+  if (exact) return exact;
+
+  // 2. separator-insensitive exact ("flux-2-flash" → "flux-2/flash")
+  const loose = pickForType(models.filter((i) => normId(i.id) === want || normId(i.name) === want), types);
+  if (loose) return loose;
+
+  // 3. unique prefix ("z-image" → "z-image/turbo") — the modality filter runs
+  //    FIRST, so a stem shared by a t2v/i2v pair is no longer ambiguous.
+  const prefixed = models.filter((i) => normId(i.id).startsWith(want) || normId(i.name).startsWith(want));
+  const narrowed = types.length ? prefixed.filter((i) => i.types.some((t) => types.includes(t))) : [];
+  const ids = new Set((narrowed.length ? narrowed : prefixed).map((i) => i.id));
+  if (ids.size === 1) return [...ids][0];
 
   // 4. unknown — name the near misses instead of dead-ending at the API.
   const stem = normId(key.split(/[\s._/-]+/).filter(Boolean)[0] || key);
   const near = [...new Set(
-    [...map.values()]
-      .filter((i) => i.id && stem && (normId(i.id).startsWith(stem) || normId(i.name).startsWith(stem)))
+    models
+      .filter((i) => stem && (normId(i.id).startsWith(stem) || normId(i.name).startsWith(stem)))
       .map((i) => (i.name ? `${i.id} (${i.name})` : i.id))
   )].sort().slice(0, 12);
   if (!near.length) return input;

package/src/tools/chat.js

@@ -5,6 +5,7 @@
 
 const { z } = require('zod');
 const { pollOrTimedOut, creditFields, projectIdField } = require('./_shared');
+const { canonicalModelId } = require('../apps');
 
 function registerChatTools(server, client) {
   // ─── chat_send_message ─────────────────────────────────────
@@ -13,7 +14,7 @@ function registerChatTools(server, client) {
     'Send a chat message to Kolbo AI. Starts a new conversation (omit session_id) or continues an existing one. Returns the assistant response when complete. Supports image/video/audio analysis via media_urls — pass public URLs and the model auto-routes to a vision-capable model (e.g. Gemini) when media is detected. Supports web search and deep think modes.',
     {
       message: z.string().describe('The user message to send'),
-      model: z.string().optional().describe('Model identifier (e.g. "gpt-4o", "claude-sonnet-4-6"). Prefer passing a SPECIFIC model (list_models type="text") — omitting falls back to Smart Select auto-routing, which we avoid unless the user explicitly asks for auto-pick. Exception: when media_urls contains video or audio, omitting is fine — routing goes to a Gemini vision model regardless of this field.'),
+      model: z.string().optional().describe('Model identifier from list_models type="text". Identifiers resolve leniently, so the DISPLAY NAME that list_models shows works too ("Grok 4.5" → its identifier). Do NOT hardcode an id you have not seen in list_models — the text catalog turns over fast. Prefer passing a SPECIFIC model — omitting falls back to Smart Select auto-routing, which we avoid unless the user explicitly asks for auto-pick. Exception: when media_urls contains video or audio, omitting is fine — routing goes to a Gemini vision model regardless of this field.'),
       session_id: z.string().optional().describe('Existing chat session ID to continue. Omit to start a new conversation.'),
       system_prompt: z.string().optional().describe('System prompt for the conversation. Only applied when creating a new session.'),
       web_search: z.boolean().optional().describe('Enable web search for this message. Default: false'),
@@ -23,6 +24,13 @@ function registerChatTools(server, client) {
       project_id: projectIdField
     },
     async ({ message, model, session_id, system_prompt, web_search, deep_think, enhance_prompt = false, media_urls, project_id }) => {
+      // Every generate_* tool resolves its model this way; chat was the one
+      // `model` arg that went straight to the API, which has no fuzzy matching.
+      // So the display names list_models hands back ("Claude Fable 5") came
+      // back as a bare `Model not found: Claude Fable 5 [MODEL_NOT_FOUND]` —
+      // discovery had no path to use.
+      model = await canonicalModelId(client, model, 'text'); // lenient id resolution ("Grok 4.5" → its identifier)
+
       const gen = await client.post('/v1/chat', {
         message,
         model,

package/src/tools/generate.js

@@ -139,7 +139,7 @@ function registerGenerateTools(server, client, options = {}) {
     },
     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 }) => {
       if (!prompt && !(prompts && prompts.length)) throw new Error('Provide prompt or prompts');
-      model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
+      model = await canonicalModelId(client, model, 'text_to_img'); // lenient id resolution ("z-image" → "z-image/turbo")
       const shared = {
         model, aspect_ratio, enhance_prompt,
         reference_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, quality, preset_id, cinematic, skip_color_palette, project_id
@@ -210,7 +210,7 @@ function registerGenerateTools(server, client, options = {}) {
       project_id: projectIdField
     },
     async ({ prompt, model, source_images, aspect_ratio, enhance_prompt = false, num_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, cinematic, skip_color_palette, project_id }) => {
-      model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
+      model = await canonicalModelId(client, model, 'image_editing'); // lenient id resolution ("z-image" → "z-image/turbo")
       const gen = await client.post('/v1/generate/image-edit', {
         prompt, model, source_images, aspect_ratio, enhance_prompt, num_images,
         visual_dna_ids, moodboard_id, enable_web_search, resolution, cinematic, skip_color_palette, project_id
@@ -270,7 +270,7 @@ function registerGenerateTools(server, client, options = {}) {
       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 }) => {
-      model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
+      model = await canonicalModelId(client, model, workflow_type === 'video' ? 'text_to_video' : 'text_to_img'); // lenient id resolution ("z-image" → "z-image/turbo")
       const gen = await client.post('/v1/generate/creative-director', {
         prompt, scene_count, model, aspect_ratio, workflow_type, duration,
         enhance_prompt, reference_images, visual_dna_ids, moodboard_id, moodboard_ids, resolution, project_id
@@ -423,7 +423,7 @@ function registerGenerateTools(server, client, options = {}) {
     },
     async ({ prompt, prompts, model, aspect_ratio, duration, enhance_prompt = false, reference_images, resolution, preset_id, sound_enabled, skip_color_palette, project_id }) => {
       if (!prompt && !(prompts && prompts.length)) throw new Error('Provide prompt or prompts');
-      model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
+      model = await canonicalModelId(client, model, 'text_to_video'); // lenient id resolution ("z-image" → "z-image/turbo")
       const shared = {
         model, aspect_ratio, duration, enhance_prompt, reference_images, resolution, preset_id, sound_enabled, skip_color_palette, project_id
       };
@@ -495,7 +495,7 @@ function registerGenerateTools(server, client, options = {}) {
       project_id: projectIdField
     },
     async ({ image_url, prompt, model, aspect_ratio, duration, enhance_prompt = false, visual_dna_ids, resolution, sound_enabled, skip_color_palette, project_id }) => {
-      model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
+      model = await canonicalModelId(client, model, 'img_to_video'); // lenient id resolution ("z-image" → "z-image/turbo")
       const gen = await client.post('/v1/generate/video/from-image', {
         image_url, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution, sound_enabled, skip_color_palette, project_id
       });
@@ -558,7 +558,7 @@ function registerGenerateTools(server, client, options = {}) {
       project_id: projectIdField
     },
     async ({ prompt, model, style, title, instrumental, lyrics, vocal_gender, negative_tags, duration_seconds, enhance_prompt = false, preset_id, style_weight, weirdness, audio_weight, persona_id, use_composition_plan, singing_dna_id, singing_voice_id, project_id }) => {
-      model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
+      model = await canonicalModelId(client, model, 'music_gen'); // lenient id resolution ("z-image" → "z-image/turbo")
       const gen = await client.post('/v1/generate/music', {
         prompt, model, style, title, instrumental, lyrics, vocal_gender, negative_tags,
         duration_seconds, enhance_prompt, preset_id,
@@ -630,7 +630,7 @@ function registerGenerateTools(server, client, options = {}) {
       project_id: projectIdField
     },
     async ({ text, voice, model, language, style_instructions, selected_style, emotion, speaking_speed, similarity_boost, style, use_speaker_boost, variance, tempo, promptBoost, seed, accentControl, voiceTitle, minimax_pitch, minimax_vol, minimax_intensity, minimax_timbre, project_id }) => {
-      model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
+      model = await canonicalModelId(client, model, 'text_to_speech'); // lenient id resolution ("z-image" → "z-image/turbo")
       // Resolve the requested voice against the REAL catalog (cached) so the card
       // can show its display name + portrait instead of a raw id, and so an id
       // that does not exist is reported instead of rendering silently: Google
@@ -704,7 +704,7 @@ function registerGenerateTools(server, client, options = {}) {
       project_id: projectIdField
     },
     async ({ prompt, model, duration, prompt_influence, cfg_strength, sound_loop, sound_tempo, sound_key, seed_voice, seed_speed, seed_volume, seed_pitch, seed_reference_audio_urls, seed_reference_image_url, project_id }) => {
-      model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
+      model = await canonicalModelId(client, model, 'text_to_sound'); // lenient id resolution ("z-image" → "z-image/turbo")
       const gen = await client.post('/v1/generate/sound', {
         prompt, model, duration, prompt_influence,
         cfg_strength, sound_loop, sound_tempo, sound_key,
@@ -920,7 +920,7 @@ function registerGenerateTools(server, client, options = {}) {
       project_id: projectIdField
     },
     async ({ prompt, model, reference_images, reference_videos, reference_audio_urls, audio_url, files, duration, aspect_ratio, motion, preset_id, enhance_prompt = false, visual_dna_ids, resolution, keyframes, project_id }) => {
-      model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
+      model = await canonicalModelId(client, model, 'elements'); // lenient id resolution ("z-image" → "z-image/turbo")
       if (!prompt) throw new Error('prompt is required');
 
       let startResponse;
@@ -1001,7 +1001,7 @@ function registerGenerateTools(server, client, options = {}) {
       project_id: projectIdField
     },
     async ({ first_frame_url, last_frame_url, first_frame, last_frame, prompt, model, duration, aspect_ratio, enhance_prompt = false, visual_dna_ids, resolution, project_id }) => {
-      model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
+      model = await canonicalModelId(client, model, 'firstlastgenerations'); // lenient id resolution ("z-image" → "z-image/turbo")
       const urlMode = first_frame_url && last_frame_url;
       const fileMode = first_frame && last_frame;
       if (!urlMode && !fileMode) {
@@ -1091,7 +1091,7 @@ function registerGenerateTools(server, client, options = {}) {
       project_id: projectIdField
     },
     async ({ source, audio, text_prompt, model, bounding_box_target, sync_mode, model_mode, emotion, temperature, occlusion_detection_enabled, active_speaker_detection, project_id }) => {
-      model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
+      model = await canonicalModelId(client, model, ['lipsync-image', 'lipsync-video']); // lenient id resolution ("z-image" → "z-image/turbo")
       if (!source) throw new Error('source is required (URL or absolute local path to image/video)');
       if (!audio) throw new Error('audio is required (URL or absolute local path to audio file)');
 
@@ -1212,7 +1212,7 @@ function registerGenerateTools(server, client, options = {}) {
       project_id: projectIdField
     },
     async ({ source_video, prompt, model, aspect_ratio, duration, enhance_prompt = false, visual_dna_ids, resolution, reference_images, reference_videos, elements, preset, source_language, translation_language, srt_content, srt_file_url, vocabulary, customization, project_id }) => {
-      model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
+      model = await canonicalModelId(client, model, 'video_to_video'); // lenient id resolution ("z-image" → "z-image/turbo")
       if (!source_video) throw new Error('source_video is required');
 
       const isUrl = /^https?:\/\//i.test(source_video);
@@ -1371,7 +1371,7 @@ function registerGenerateTools(server, client, options = {}) {
       project_id: projectIdField
     },
     async ({ prompt, reference_images, mode, texture_prompt, model, topology, target_polycount, enable_tpose, enable_pbr, project_id }) => {
-      model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
+      model = await canonicalModelId(client, model, ['3d_text_to_model', '3d_image_to_model', '3d_multi_image_to_model', '3d_world']); // lenient id resolution ("z-image" → "z-image/turbo")
       if (!prompt && !(reference_images && reference_images.length > 0)) {
         throw new Error('Provide prompt (text mode) or reference_images (single/multi mode)');
       }
@@ -1514,6 +1514,9 @@ function registerGenerateTools(server, client, options = {}) {
       zoom_out_percentage, expand_left, expand_right, expand_top, expand_bottom,
       project_id
     }) => {
+      // No `type` argument: these are operation-routed tools (upscale / reframe /
+      // removebg / …), each operation with its own model family — there is no single
+      // catalog type to disambiguate against.
       model = await canonicalModelId(client, model);
 
       // Basic validation
@@ -1667,6 +1670,9 @@ function registerGenerateTools(server, client, options = {}) {
       start_time,
       project_id
     }) => {
+      // No `type` argument: these are operation-routed tools (upscale / reframe /
+      // removebg / …), each operation with its own model family — there is no single
+      // catalog type to disambiguate against.
       model = await canonicalModelId(client, model);
 
       // Validation

package/src/tools/models.js

@@ -67,6 +67,10 @@ function buildCatalogStructured(models, type, compact) {
     if (g.models.length >= 6) continue; // curated cap — full list lives in the text payload
     g.models.push({
       name: m.name,
+      // The widget renders `name`; the AGENT reads the same rows (hosts hand it
+      // structuredContent). Without the identifier the default call was a dead
+      // end — it named six models and gave no way to pass any of them on.
+      identifier: m.identifier,
       icon: resolveAvatarUrl(m.avatar),
       description: String(m.smartSelect_StrengthsSummary || m.summary || m.description || '').slice(0, 90),
       chips: modelChips(m),

package/src/tools/projects.js

@@ -12,21 +12,34 @@ function registerProjectTools(server, client, options = {}) {
   // ─── list_projects ─────────────────────────────────────────
   server.tool(
     'list_projects',
-    'List the user\'s platform projects (owned + shared with edit/full/owner permission). Use this to resolve a project NAME the user mentioned ("put this in my Acme Campaign project") into the project ObjectId you pass back as `project_id` on generation / chat / upload / move tools. Whenever the user mentions a project by name OR location, you MUST call this first — those tools accept only ObjectIds, not names — and then pass the resolved `project_id` on EVERY subsequent call in the conversation (it is per-call, not sticky; omitting it drops work into the default bucket). Returns id, name, role, and is_default. The project flagged `is_default: true` is the auto-created "API Generations" bucket every SDK generation lands in when project_id is omitted.',
-    {},
-    async () => {
-      const result = await client.get('/v1/projects');
+    'List the user\'s platform projects (owned + shared with edit/full/owner permission). Use this to resolve a project NAME the user mentioned ("put this in my Acme Campaign project") into the project ObjectId you pass back as `project_id` on generation / chat / upload / move tools. Whenever the user mentions a project by name OR location, you MUST call this first — those tools accept only ObjectIds, not names — and then pass the resolved `project_id` on EVERY subsequent call in the conversation (it is per-call, not sticky; omitting it drops work into the default bucket). Returns id, name, role, is_default, and is_archived. The project flagged `is_default: true` is the auto-created "API Generations" bucket every SDK generation lands in when project_id is omitted. Accounts routinely have HUNDREDS of projects, so this is paginated: when you already know the name, pass `search` — it is far cheaper than listing everything. Default page size is 50; use `page` to walk the rest (`pagination.has_more` tells you when to stop). Archived projects are hidden unless you pass `include_archived: true`.',
+    {
+      search: z.string().optional().describe('Case-insensitive substring match on the project name. Use this whenever the user named a project — it turns a full listing into a one-item answer.'),
+      page: z.number().optional().describe('Page number, 1-indexed. Default: 1'),
+      limit: z.number().optional().describe('Results per page, max 200. Default: 50'),
+      include_archived: z.boolean().optional().describe('Also return archived projects. Default false — archived projects are hidden here exactly as they are in the web app.')
+    },
+    async ({ search, page, limit, include_archived }) => {
+      const params = new URLSearchParams();
+      if (search) params.set('search', search);
+      if (page) params.set('page', String(page));
+      if (limit) params.set('limit', String(limit));
+      if (include_archived) params.set('include_archived', 'true');
+      const qs = params.toString();
+      const result = await client.get(`/v1/projects${qs ? '?' + qs : ''}`);
       const projects = (result.projects || []).map(p => ({
         id: p.id,
         name: p.name,
         role: p.role,
         is_default: !!p.is_default,
+        is_archived: !!p.is_archived,
         open_url: buildProjectUrl(p.id, { is_default: !!p.is_default })
       }));
       const text = JSON.stringify({
         projects,
         count: projects.length,
-        _hint: 'Pass the chosen `id` as `project_id` on any generate_* tool to drop the generation into that project. Omit project_id to use the project flagged is_default:true. `open_url` opens that project\'s media in the web app (share it with the user).'
+        pagination: result.pagination || null,
+        _hint: 'Pass the chosen `id` as `project_id` on any generate_* tool to drop the generation into that project. Omit project_id to use the project flagged is_default:true. `open_url` opens that project\'s media in the web app (share it with the user). If `pagination.has_more` is true there are more projects — narrow with `search` rather than paging through everything.'
       }, null, 2);
 
       if (ui()) {
@@ -36,7 +49,7 @@ function registerProjectTools(server, client, options = {}) {
           items: projects.map(p => ({
             id: p.id,
             title: p.name,
-            subtitle: p.role + (p.is_default ? ' · default' : ''),
+            subtitle: p.role + (p.is_default ? ' · default' : '') + (p.is_archived ? ' · archived' : ''),
             open_url: p.open_url,
             use_hint: 'Use my "{TITLE}" project (project_id: {ID}) for what I do next.'
           })),

package/src/tools/visual_dna.js

@@ -87,15 +87,19 @@ function registerVisualDnaTools(server, client, options = {}) {
     + 'because dumping them buries the user\'s own handful. Only pass scope="global" (optionally with '
     + '`collection` and `search`) when the user explicitly wants to BROWSE the preset cast — e.g. "find me a '
     + 'character", "show me street style models", "I need a location DNA" — and they have not named one of '
-    + 'their own. Use scope="all" only if the user genuinely wants both at once.',
+    + 'their own. Use scope="all" only if the user genuinely wants both at once. '
+    + 'The response reports `total` and `_truncated`; when there are more matches than one '
+    + 'page holds, raise `limit` or walk `page` — do not tell the user the extras do not exist.',
     {
       scope: z.enum(['all', 'personal', 'global', 'organization']).optional().describe('Default: "personal" — the user\'s own DNAs (plus a shared project\'s when project_id is set). "global" = the ~1000 system cast/preset DNAs, for browsing when the user needs a character and has none of their own. "organization" = org-shared. "all" = everything, rarely wanted.'),
-      search: z.string().optional().describe('Search by name, tags, or description (case-insensitive)'),
+      search: z.string().optional().describe('Search by name, tags, or description (case-insensitive). Matches at WORD STARTS, so "man" finds "Man"/"Manager" but not "woman" or "romantic". Name matches are ranked first.'),
       collection: z.string().optional().describe('Filter global presets by collection: cast, influencers, props, locations, styles, glamour, street'),
       tags: z.string().optional().describe('Comma-separated tags to filter by (OR logic)'),
+      page: z.number().optional().describe('Page number, 1-indexed. Default: 1. Needed to reach the global cast beyond the first page.'),
+      limit: z.number().optional().describe('Results per page, max 100. Default: 50'),
       project_id: projectScopeReadField
     },
-    async ({ scope, search, collection, tags, project_id } = {}) => {
+    async ({ scope, search, collection, tags, page, limit, project_id } = {}) => {
       const params = new URLSearchParams();
       // Default to the user's OWN DNAs. The API defaults to "all", which pulls
       // in ~1000 global cast presets and buries the handful the user actually
@@ -106,17 +110,23 @@ function registerVisualDnaTools(server, client, options = {}) {
       if (search) params.set('search', search);
       if (collection) params.set('collection', collection);
       if (tags) params.set('tags', tags);
+      // Always paged. Without these the ~1000-item global cast came back whole and
+      // was silently cut to the display cap, so nothing past the first screen was
+      // reachable through this tool at all.
+      params.set('page', String(page && page > 0 ? Math.floor(page) : 1));
+      params.set('limit', String(limit && limit > 0 ? Math.min(Math.floor(limit), 100) : 50));
       if (project_id) params.set('project_id', project_id);
       const qs = params.toString();
       const result = await client.get(`/v1/visual-dna${qs ? '?' + qs : ''}`);
       const dnas = result.visual_dnas || [];
+      const total = result.total != null ? result.total : (result.count || dnas.length);
       // Full profiles measured 74,310 chars — the embedded analysis/description
       // blobs are large and the model only needs enough to pick an id.
       const text = compactList(dnas, {
         fields: ['id', 'name', 'type', 'folder_id', 'tags', 'thumbnail'],
         cap: 60,
-        total: result.count || dnas.length,
-        note: 'Narrow with `search`, `tags`, or `collection`; get_visual_dna returns one in full.',
+        total,
+        note: 'Narrow with `search`, `tags`, or `collection`, or pass `page`/`limit` for the rest; get_visual_dna returns one in full.',
       });
 
       if (ui()) {
@@ -131,8 +141,8 @@ function registerVisualDnaTools(server, client, options = {}) {
             media_type: 'image',
             use_hint: 'Use Visual DNA "{TITLE}" (id: {ID}) in my next generation for character/style consistency.'
           })),
-          total: result.count || dnas.length,
-          has_more: dnas.length > 24
+          total,
+          has_more: result.has_more || dnas.length > 24
         });
       }