@simpligen/mcp 0.1.4 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simpligen/mcp",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "MCP server for SimpliGen -- drive local/cloud AI image & video generation from an agent.",
   "type": "module",
   "license": "MIT",

package/src/tools.js

@@ -1,435 +1,455 @@
-// packages/mcp-server/src/tools.js
-// Registers SimpliGen MCP tools on an McpServer-shaped object. Each tool calls a
-// ControlApiClient method and returns the JSON result as text content; client
-// errors become an isError tool result (so the agent sees the errorCode/message).
-import { z } from 'zod';
-import { buildResultImageContent } from './resultImage.js';
-
-export const TOOL_NAMES = [
-  'list_capabilities', 'get_status', 'list_projects', 'create_project',
-  'upload_file', 'generate', 'list_loras', 'get_job', 'wait_for_result', 'list_jobs',
-  'cancel_job', 'prepare_preset', 'get_result_image',
-  'list_characters', 'get_character', 'list_character_features', 'list_character_presets',
-  'remove_character', 'create_character', 'generate_character_image', 'generate_character_video',
-  'generate_character_frame', 'animate_character', 'set_character_preset',
-  'enhance_character_media', 'regenerate_character_base',
-  'list_recipe_blocks', 'compose_recipe', 'validate_recipe', 'list_recipes', 'get_recipe', 'publish_recipe',
-  'run_recipe', 'get_recipe_run', 'wait_for_recipe_run', 'list_recipe_runs', 'cancel_recipe_run',
-  'list_subjects', 'list_products', 'create_product', 'remove_product',
-];
-
-const ok = (data) => ({ content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] });
-const fail = (err) => ({ isError: true, content: [{ type: 'text', text: `${err.errorCode ? err.errorCode + ': ' : ''}${err.message || String(err)}` }] });
-const wrap = (fn) => async (args) => { try { return ok(await fn(args)); } catch (e) { return fail(e); } };
-
-export function registerTools(server, client) {
-  server.registerTool('list_capabilities',
-    { title: 'List capabilities', description: 'List every SimpliGen preset the agent can generate with (image/video), its inputs/options, whether it is installed locally (localReady) and cloud-eligible + credit cost.', inputSchema: {} },
-    wrap(() => client.getCapabilities()));
-
-  server.registerTool('get_status',
-    { title: 'Get status', description: 'Engine running state, whether cloud is connected, credit balance, and the active project.', inputSchema: {} },
-    wrap(() => client.getStatus()));
-
-  server.registerTool('list_projects',
-    { title: 'List projects', description: 'List projects (output containers).', inputSchema: {} },
-    wrap(() => client.listProjects()));
-
-  server.registerTool('create_project',
-    { title: 'Create project', description: 'Create a new project (output container).', inputSchema: { name: z.string().describe('Project name') } },
-    wrap(({ name }) => client.createProject(name)));
-
-  server.registerTool('upload_file',
-    { title: 'Upload a file', description: 'Upload a local image/video file and get an opaque handle to pass as image/referenceImages/video in generate.', inputSchema: { path: z.string().describe('Absolute local file path') } },
-    wrap(({ path }) => client.uploadFile(path)));
-
-  server.registerTool('generate',
-    {
-      title: 'Generate', description: 'Start an image or video generation. Inputs (image/referenceImages/video) are handles from upload_file. backend: local | cloud | auto. Returns a jobId; poll with wait_for_result or get_job.',
-      inputSchema: {
-        presetId: z.string(), mediaType: z.enum(['image', 'video']), prompt: z.string(),
-        packId: z.string().optional(), backend: z.enum(['local', 'cloud', 'auto']).optional(),
-        negativePrompt: z.string().optional(), project: z.string().optional(),
-        image: z.string().optional().describe('upload_file handle'),
-        referenceImages: z.array(z.string()).optional().describe('upload_file handles'),
-        video: z.string().optional().describe('upload_file handle (driving video)'),
-        loras: z.array(z.object({ name: z.string().describe('LoRA display name from list_loras'), weight: z.number().optional().describe('Strength; defaults to the LoRA default') })).optional().describe('LoRAs to apply. Local backend only, and only for presets where inputs.supportsLoras is true. Use the LoRA trigger words in the prompt so it activates.'),
-        options: z.object({ resolution: z.string().optional(), aspectRatio: z.string().optional().describe('Aspect ratio, e.g. "1:1", "16:9", "9:16" (portrait/vertical), "4:3", "3:4". See list_capabilities -> options.aspectRatio for the values each preset accepts. Defaults to 1:1 for images (16:9 for video) if omitted.'), durationSeconds: z.number().optional(), steps: z.number().optional(), cfg: z.number().optional(), seed: z.number().optional() }).optional(),
-      },
-    },
-    wrap((args) => client.generate(args)));
-
-  server.registerTool('list_loras',
-    { title: 'List LoRAs', description: 'List the installed user LoRAs (name, base model, trigger words) so you can pass them in generate -> loras.', inputSchema: {} },
-    wrap(() => client.listLoras()));
-
-  server.registerTool('get_job',
-    { title: 'Get job', description: 'Status + result of a generation job. resultPath is the local file when completed.', inputSchema: { jobId: z.string() } },
-    wrap(({ jobId }) => client.getJob(jobId)));
-
-  server.registerTool('list_jobs',
-    { title: 'List jobs', description: 'Recent generation jobs.', inputSchema: {} },
-    wrap(() => client.listJobs()));
-
-  server.registerTool('cancel_job',
-    { title: 'Cancel job', description: 'Cancel a queued/running job.', inputSchema: { jobId: z.string() } },
-    wrap(({ jobId }) => client.cancelJob(jobId)));
-
-  server.registerTool('prepare_preset',
-    { title: 'Prepare preset', description: 'Start downloading a local preset\'s models (so it becomes localReady). Poll list_capabilities for localReady.', inputSchema: { presetId: z.string(), mediaType: z.enum(['image', 'video']), packId: z.string().optional() } },
-    wrap((args) => client.preparePreset(args)));
-
-  // Convenience: poll get_job until terminal or timeout (no extra endpoint).
-  server.registerTool('wait_for_result',
-    { title: 'Wait for result', description: 'Block until a job completes or fails (or the timeout). Returns the final job (resultPath when completed).', inputSchema: { jobId: z.string(), timeoutSeconds: z.number().optional(), pollMs: z.number().optional() } },
-    wrap(async ({ jobId, timeoutSeconds = 300, pollMs = 2000 }) => {
-      const deadline = Date.now() + timeoutSeconds * 1000;
-      // eslint-disable-next-line no-constant-condition
-      while (true) {
-        const { job } = await client.getJob(jobId);
-        if (!job || job.status === 'completed' || job.status === 'failed') return job;
-        if (Date.now() >= deadline) return { ...job, note: 'timeout_still_running' };
-        await new Promise((r) => setTimeout(r, pollMs));
-      }
-    }));
-
-  // Return a completed job's result image inline (an MCP image block) so the
-  // agent can actually display it. Images only; video/unreadable -> path note.
-  server.registerTool('get_result_image',
-    { title: 'Get result image', description: 'Return a completed job\'s result image inline as a viewable image so it can be displayed in chat. Large images are re-encoded to a full-resolution WebP preview that fits the client size cap; the uncompressed original file path is always included in the caption. Video results return the file path instead. Call after the job is completed.', inputSchema: { jobId: z.string(), maxBytes: z.number().optional().describe('Inline byte budget before re-encoding/resizing (default ~700KB raw)') } },
-    async ({ jobId, maxBytes }) => {
-      try {
-        const { job } = await client.getJob(jobId);
-        return await buildResultImageContent(job, { budgetBytes: maxBytes });
-      } catch (e) {
-        return fail(e);
-      }
-    });
-
-  // ---- Character Studio tools ----
-
-  server.registerTool('list_characters',
-    { title: 'List characters', description: 'List all saved characters in Character Studio.', inputSchema: {} },
-    wrap(() => client.listCharacters()));
-
-  server.registerTool('get_character',
-    { title: 'Get character', description: 'Get a single character by ID, including its current base portrait and identity features.', inputSchema: { characterId: z.string() } },
-    wrap(({ characterId }) => client.getCharacter(characterId)));
-
-  server.registerTool('list_character_features',
-    { title: 'List character features', description: 'List available feature categories and their options (e.g. hairColor, eyeColor) for use with create_character identity.', inputSchema: {} },
-    wrap(() => client.listCharacterFeatures()));
-
-  server.registerTool('list_character_presets',
-    { title: 'List character presets', description: 'List generation presets available for Character Studio. Returns base, identityEdit, and i2v presets as well as enhanceImage and enhanceVideo presets (each with supportedScales). Use the returned ids as presetId/imagePresetId/videoPresetId/basePresetId arguments in other character tools.', inputSchema: {} },
-    wrap(() => client.listCharacterPresets()));
-
-  server.registerTool('remove_character',
-    { title: 'Remove character', description: 'Permanently delete a character and its associated data.', inputSchema: { characterId: z.string() } },
-    wrap(({ characterId }) => client.removeCharacter(characterId)));
-
-  server.registerTool('create_character',
-    {
-      title: 'Create character',
-      description: 'Create a new character. Three paths: (1) describe -- pass gender and identity features from list_character_features with mode "generate"; the server builds a base portrait automatically and this tool waits until ready. (2) upload as base -- pass baseFilePath pointing to a local image with mode "upload"; the image becomes the base portrait immediately. (3) vision recreate -- describe path but fill identity by having the agent analyse a reference photo first; the agent extracts features and passes them as identity.',
-      inputSchema: {
-        name: z.string().describe('Display name for the character'),
-        gender: z.enum(['woman', 'man', 'nonbinary']),
-        mode: z.enum(['generate', 'upload']).describe('generate: build base portrait from description; upload: use a provided image as base'),
-        identity: z.record(z.string()).optional().describe('An object of featureId to optionId pairs chosen from list_character_features (e.g. { hairColor: "black", eyeColor: "green" }). Do not include gender here; pass gender separately.'),
-        baseFilePath: z.string().optional().describe('Absolute local image path; required for mode "upload"'),
-        timeoutSeconds: z.number().optional().describe('Max seconds to wait for base portrait generation (default 300, mode generate only)'),
-        pollMs: z.number().optional().describe('Poll interval in milliseconds (default 2000, mode generate only)'),
-      },
-    },
-    async ({ name, gender, mode, identity, baseFilePath, timeoutSeconds, pollMs }) => {
-      try {
-        if (mode === 'upload') {
-          const up = await client.uploadFile(baseFilePath);
-          const char = await client.createCharacter({ name, gender, mode: 'upload', identity, baseHandle: up.handle });
-          return ok({ ...char, ready: true });
-        }
-        // mode === 'generate': create then poll until base_image_url is set
-        const c = await client.createCharacter({ name, gender, mode: 'generate', identity });
-        const { characterId } = c;
-        const deadline = Date.now() + (timeoutSeconds ?? 300) * 1000;
-        while (true) {
-          const { character } = await client.getCharacter(characterId);
-          if (character?.base_image_url) return ok(character);
-          if (Date.now() >= deadline) return ok({ ...character, base_pending: true });
-          await new Promise((r) => setTimeout(r, pollMs ?? 2000));
-        }
-      } catch (e) {
-        return fail(e);
-      }
-    });
-
-  server.registerTool('generate_character_image',
-    {
-      title: 'Generate character image',
-      description: 'Generate one or more images of a character in a scene. Returns jobIds; use wait_for_result then get_result_image for each. Pass presetId to override the default image preset (ids from list_character_presets).',
-      inputSchema: {
-        characterId: z.string(),
-        prompt: z.string(),
-        aspect: z.enum(['16:9', '9:16', '1:1']).optional(),
-        count: z.number().optional(),
-        presetId: z.string().optional().describe('Override image preset (id from list_character_presets)'),
-      },
-    },
-    wrap(({ characterId, prompt, aspect, count, presetId }) => {
-      const args = { prompt, aspect, count };
-      if (presetId !== undefined) args.presetId = presetId;
-      return client.generateCharacterImage(characterId, args);
-    }));
-
-  server.registerTool('generate_character_video',
-    {
-      title: 'Generate character video',
-      description: 'Generate a short video of a character in a scene. Internally generates a frame then animates it (I2V). Returns frameJobId and videoJobId; use wait_for_result then get_result_image on videoJobId. Use framePresetId to override the image-frame preset and videoPresetId to override the video/animate preset (ids from list_character_presets).',
-      inputSchema: {
-        characterId: z.string(),
-        prompt: z.string(),
-        motion: z.string().optional().describe('Optional motion description or style hint'),
-        aspect: z.enum(['16:9', '9:16', '1:1']).optional(),
-        timeoutSeconds: z.number().optional().describe('Max seconds to wait for the frame job (default 300)'),
-        pollMs: z.number().optional().describe('Poll interval in milliseconds (default 2000)'),
-        framePresetId: z.string().optional().describe('Override image-frame preset (id from list_character_presets)'),
-        videoPresetId: z.string().optional().describe('Override video/animate preset (id from list_character_presets)'),
-      },
-    },
-    async ({ characterId, prompt, motion, aspect, timeoutSeconds = 300, pollMs = 2000, framePresetId, videoPresetId }) => {
-      try {
-        // 1. Generate a frame (still image for I2V)
-        const { jobIds: [frameJobId] } = await client.generateCharacterFrame(characterId, { prompt, aspect, presetId: framePresetId });
-        // 2. Wait for frame to complete
-        const deadline = Date.now() + timeoutSeconds * 1000;
-        while (true) {
-          const { job: frameJob } = await client.getJob(frameJobId);
-          if (frameJob?.status === 'completed') break;
-          if (frameJob?.status === 'failed') return fail({ message: `Frame job failed: ${frameJobId}`, errorCode: 'frame_failed' });
-          if (Date.now() >= deadline) return fail({ message: `Frame job timed out: ${frameJobId}`, errorCode: 'frame_timeout' });
-          await new Promise((r) => setTimeout(r, pollMs));
-        }
-        // 3. Animate from the completed frame
-        const { jobIds: [videoJobId] } = await client.animateCharacter(characterId, { frameJobId, motion, aspect, presetId: videoPresetId });
-        return ok({ frameJobId, videoJobId });
-      } catch (e) { return fail(e); }
-    });
-
-  // ---- New Character Studio tools (Task 4) ----
-
-  server.registerTool('generate_character_frame',
-    {
-      title: 'Generate character frame',
-      description: 'Generate a start-frame image for a character that you can review or enhance before animating. Returns jobIds; use wait_for_result then get_result_image. Pass presetId to override the frame-image preset (ids from list_character_presets).',
-      inputSchema: {
-        characterId: z.string(),
-        prompt: z.string(),
-        aspect: z.enum(['16:9', '9:16', '1:1']).optional(),
-        presetId: z.string().optional().describe('Override image preset (id from list_character_presets)'),
-      },
-    },
-    wrap(({ characterId, prompt, aspect, presetId }) => {
-      const args = { prompt, aspect };
-      if (presetId !== undefined) args.presetId = presetId;
-      return client.generateCharacterFrame(characterId, args);
-    }));
-
-  server.registerTool('animate_character',
-    {
-      title: 'Animate character',
-      description: 'Animate a character from a completed image/frame job or a local file path (I2V). jobId may be any completed character image, frame, or upscale job. Returns jobIds; use wait_for_result then get_result_image. Pass videoPresetId to override the video preset (ids from list_character_presets).',
-      inputSchema: {
-        characterId: z.string(),
-        jobId: z.string().optional().describe('Any completed character image/frame/upscale jobId to use as the source frame'),
-        filePath: z.string().optional().describe('Absolute local image path to use as the source frame'),
-        motion: z.string().optional().describe('Optional motion description or style hint'),
-        aspect: z.enum(['16:9', '9:16', '1:1']).optional(),
-        videoPresetId: z.string().optional().describe('Override video/animate preset (id from list_character_presets)'),
-      },
-    },
-    wrap(({ characterId, jobId, filePath, motion, aspect, videoPresetId }) =>
-      client.animateCharacter(characterId, { frameJobId: jobId, framePath: filePath, motion, aspect, presetId: videoPresetId })));
-
-  server.registerTool('set_character_preset',
-    {
-      title: 'Set character preset',
-      description: 'Set sticky per-character default presets for image and/or video generation. Ids come from list_character_presets. Pass null to clear a preset back to the system default.',
-      inputSchema: {
-        characterId: z.string(),
-        imagePresetId: z.string().nullable().optional().describe('Default image preset id (null to clear)'),
-        videoPresetId: z.string().nullable().optional().describe('Default video preset id (null to clear)'),
-      },
-    },
-    wrap(({ characterId, imagePresetId, videoPresetId }) => client.setCharacterPreset(characterId, { imagePresetId, videoPresetId })));
-
-  server.registerTool('enhance_character_media',
-    {
-      title: 'Enhance character media',
-      description: 'Upscale a generated image/video, a local file, or the character base portrait (target: "base"). Returns a jobId; use wait_for_result then get_result_image. scale sets the upscale factor; keepResolution upscales then resizes back to source size for a sharper same-size result; applyAsBase replaces the character base portrait with the upscaled result. Enhance presets come from list_character_presets (enhanceImage/enhanceVideo, each with supportedScales).',
-      inputSchema: {
-        characterId: z.string(),
-        jobId: z.string().optional().describe('Completed job whose result to enhance'),
-        filePath: z.string().optional().describe('Absolute local image/video path to enhance'),
-        target: z.enum(['base']).optional().describe('Pass "base" to enhance the character base portrait'),
-        mediaType: z.enum(['image', 'video']).optional(),
-        presetId: z.string().optional().describe('Enhance preset id from list_character_presets'),
-        scale: z.number().optional().describe('Upscale factor (e.g. 2 for 2x)'),
-        keepResolution: z.boolean().optional().describe('Upscale then resize back to source dimensions for a sharper same-size result'),
-        applyAsBase: z.boolean().optional().describe('Replace the character base portrait with the upscaled result'),
-      },
-    },
-    wrap(({ characterId, jobId, filePath, target, mediaType, presetId, scale, keepResolution, applyAsBase }) =>
-      client.enhanceCharacterMedia(characterId, { jobId, filePath, target, mediaType, presetId, scale, keepResolution, applyAsBase })));
-
-  server.registerTool('regenerate_character_base',
-    {
-      title: 'Regenerate character base',
-      description: 'Switch the base model and regenerate the base portrait IN PLACE (no new character created). Replaces the current base when completed. Uses basePresetId from list_character_presets. Optionally update identity features at the same time. Polls until completed, then auto-accepts the new base.',
-      inputSchema: {
-        characterId: z.string(),
-        basePresetId: z.string().optional().describe('Base-generation preset id from list_character_presets'),
-        identity: z.record(z.string()).optional().describe('Updated identity feature map (featureId -> optionId) to apply alongside the new base'),
-        timeoutSeconds: z.number().optional().describe('Max seconds to wait for the base job (default 300)'),
-        pollMs: z.number().optional().describe('Poll interval in milliseconds (default 2000)'),
-      },
-    },
-    async ({ characterId, basePresetId, identity, timeoutSeconds = 300, pollMs = 2000 }) => {
-      try {
-        const { baseJobId } = await client.regenerateCharacterBase(characterId, { basePresetId, identity });
-        const deadline = Date.now() + timeoutSeconds * 1000;
-        while (true) {
-          const { job } = await client.getJob(baseJobId);
-          if (job?.status === 'completed') {
-            await client.acceptBase(characterId, { altImageId: baseJobId });
-            return ok(await client.getCharacter(characterId));
-          }
-          if (job?.status === 'failed') return fail({ message: `Base regeneration job failed: ${baseJobId}`, errorCode: 'base_failed' });
-          if (Date.now() >= deadline) return ok({ baseJobId, note: 'timeout_still_running' });
-          await new Promise((r) => setTimeout(r, pollMs));
-        }
-      } catch (e) { return fail(e); }
-    });
-
-  // --- Recipe authoring: compose multi-step recipes out of packs/presets ---
-
-  const recipeStep = z.object({
-    preset: z.string().describe('The preset this step runs, as "packId:presetId" (from list_recipe_blocks).'),
-    entry: z.string().optional().describe('Entry point: create-image | create-video | edit-image | upscale. Inferred from the preset when omitted.'),
-    promptInput: z.object({ key: z.string().optional(), label: z.string().optional() }).optional()
-      .describe('Name this step\'s prompt input, or set key to an existing input to SHARE a prompt. Default: a dedicated prompt input per step.'),
-    negativePrompt: z.string().optional(),
-    params: z.record(z.any()).optional().describe('Param bindings, literal or { from: "input:<key>" } (e.g. aspectRatio, seed, duration).'),
-  }).passthrough();
-
-  const recipeInput = z.object({
-    key: z.string().describe('Unique slug referenced as input:<key>.'),
-    kind: z.string().describe('subject | text | image | video | reference | audio | select | color | number | toggle'),
-    label: z.string().optional(),
-    required: z.boolean().optional(),
-  }).passthrough();
-
-  const recipeSpec = z.object({
-    name: z.string().describe('Recipe name shown to end users.'),
-    description: z.string().optional(),
-    category: z.string().optional().describe('e.g. product | ugc'),
-    mature: z.boolean().optional().describe('Creator-declared: this recipe produces adult content.'),
-    // Accepted, not for the benefit of third parties (breaking them is fine), but
-    // because an agent composing a recipe mid-transition would otherwise DROP the
-    // classification, which publishes adult content as unclassified (TASK-472).
-    nsfw: z.boolean().optional().describe('Deprecated alias for `mature`.'),
-    version: z.string().optional().describe('Creator-facing semver, default 1.0.0.'),
-    inputs: z.array(recipeInput).optional().describe('Extra user-facing inputs (subjects, choices, media holes). A prompt input is auto-created per step, so you rarely list prompts here.'),
-    steps: z.array(recipeStep).min(1).describe('The pipeline in order. Each step pins a preset; media output flows into the next step automatically, and a subject input seeds a reference port.'),
-  });
-
-  server.registerTool('list_recipe_blocks',
-    { title: 'List recipe blocks', description: 'The building blocks for authoring a recipe: entry points (create-image/video, edit-image, upscale) and every preset usable as a step, each with its port contract (inputs it needs, what it produces, which entry points it fits). Call this before compose_recipe to choose presets.', inputSchema: {} },
-    wrap(() => client.listRecipeBlocks()));
-
-  server.registerTool('compose_recipe',
-    { title: 'Compose a recipe', description: 'Author a new recipe from a high-level spec and save it as a draft. You give an ordered list of steps (each pinned to a preset from list_recipe_blocks) plus any extra inputs; SimpliGen auto-wires the ports, media chain, and per-step prompt inputs and validates it. Returns { recipeId, valid, errors }. Anyone can compose; publishing later needs a connected account.', inputSchema: { spec: recipeSpec } },
-    wrap(({ spec }) => client.composeRecipe({ spec })));
-
-  server.registerTool('validate_recipe',
-    { title: 'Validate a recipe', description: 'Dry-run without saving: pass a `spec` to compose+validate it, or a `config` to validate an existing recipe config. Returns precise errors (unbound ports, missing presets, type mismatches, cycles) to fix before compose_recipe.', inputSchema: { spec: recipeSpec.optional(), config: z.record(z.any()).optional() } },
-    wrap((args) => client.validateRecipe(args)));
-
-  server.registerTool('list_recipes',
-    { title: 'List recipes', description: 'List every recipe on this device: the ones installed from the Store into UGC Studio / Product Studio (category ugc | product) and drafts authored here. Each entry carries its `inputs` (key, kind, label, required, options) so you know what run_recipe needs: a `subject` input takes a character id from list_characters (or a product id), image/video/audio inputs take upload_file handles, text/select/number inputs take plain values.', inputSchema: {} },
-    wrap(() => client.listRecipes()));
-
-  // --- Running an installed recipe (what drives the UGC + Product Studios) ---
-
-  server.registerTool('run_recipe',
-    {
-      title: 'Run a recipe',
-      description: 'Run an installed recipe (from list_recipes) with its inputs filled: the same multi-step pipeline UGC Studio / Product Studio runs when a person clicks Generate, so results land in the Gallery grouped the same way. `inputs` is keyed by input key; a subject input takes a character/product id, media inputs take upload_file handles. engine: local (default when every step is installed) | cloud | auto. Returns a runId; poll with wait_for_recipe_run or get_recipe_run. Cloud runs are priced up front and count against this agent\'s spend cap.',
-      inputSchema: {
-        id: z.string().describe('Recipe id from list_recipes'),
-        inputs: z.record(z.any()).describe('Input values keyed by the recipe\'s input keys (see list_recipes -> inputs).'),
-        engine: z.enum(['local', 'cloud', 'auto']).optional().describe('Where the steps render. auto = local if every step is installed, else cloud when connected.'),
-      },
-    },
-    wrap(({ id, inputs, engine }) => client.runRecipe(id, { inputs: inputs || {}, ...(engine ? { engine } : {}) })));
-
-  server.registerTool('get_recipe_run',
-    { title: 'Get a recipe run', description: 'Status of a recipe run: overall status (running | completed | failed | cancelled), each step with its status and resultPath, and resultPath = the final output once done.', inputSchema: { runId: z.string().describe('Run id from run_recipe') } },
-    wrap(({ runId }) => client.getRecipeRun(runId)));
-
-  server.registerTool('wait_for_recipe_run',
-    { title: 'Wait for a recipe run', description: 'Block until a recipe run completes, fails, is cancelled, or the timeout passes. Returns the final run (resultPath when completed). Multi-step video recipes can take several minutes; call again if it returns timeout_still_running.', inputSchema: { runId: z.string(), timeoutSeconds: z.number().optional(), pollMs: z.number().optional() } },
-    wrap(async ({ runId, timeoutSeconds = 600, pollMs = 3000 }) => {
-      const deadline = Date.now() + timeoutSeconds * 1000;
-      // eslint-disable-next-line no-constant-condition
-      while (true) {
-        const { run } = await client.getRecipeRun(runId);
-        if (run && ['completed', 'failed', 'cancelled'].includes(run.status)) return { run };
-        if (Date.now() >= deadline) return { run, note: 'timeout_still_running' };
-        await new Promise((r) => setTimeout(r, pollMs));
-      }
-    }));
-
-  server.registerTool('list_recipe_runs',
-    { title: 'List recipe runs', description: 'Recent runs of a recipe (newest first) with their status and results.', inputSchema: { id: z.string().describe('Recipe id') } },
-    wrap(({ id }) => client.listRecipeRuns(id)));
-
-  // --- Products + subjects: what a recipe's `subject` inputs take ---
-
-  server.registerTool('list_subjects',
-    { title: 'List subjects', description: 'Every subject a recipe\'s `subject` input can take: characters and products (id, type, name). Use a character id from list_characters or a product id from list_products / create_product.', inputSchema: {} },
-    wrap(() => client.listSubjects()));
-
-  server.registerTool('list_products',
-    { title: 'List products', description: 'The products saved on this device (a product = a named thing with a base photo, used by Product Studio and UGC recipes).', inputSchema: {} },
-    wrap(() => client.listProducts()));
-
-  server.registerTool('create_product',
-    {
-      title: 'Create a product',
-      description: 'Save a product from a photo so recipes can use it: upload the photo with upload_file first, then pass its handle. The description and category are woven into recipe prompts, so describe what it is and how it looks. Returns the productId to pass as a `subject` input in run_recipe.',
-      inputSchema: {
-        name: z.string().describe('Product name shown in the app'),
-        image: z.string().describe('upload_file handle of the product photo (clean, well-lit, product centred)'),
-        description: z.string().optional().describe('What it is and looks like, e.g. "a matte black ceramic coffee mug with a wooden lid"'),
-        category: z.string().optional().describe('e.g. skincare | beverage | electronics'),
-      },
-    },
-    wrap(({ name, image, description, category }) => client.createProduct({ name, image, description, category })));
-
-  server.registerTool('remove_product',
-    { title: 'Remove a product', description: 'Delete a product and its photo from this device.', inputSchema: { id: z.string() } },
-    wrap(({ id }) => client.removeProduct(id)));
-
-  server.registerTool('cancel_recipe_run',
-    { title: 'Cancel a recipe run', description: 'Stop a running recipe: no further steps start; a local in-flight step is interrupted (a cloud step already running finishes server-side and is saved).', inputSchema: { runId: z.string() } },
-    wrap(({ runId }) => client.cancelRecipeRun(runId)));
-
-  server.registerTool('get_recipe',
-    { title: 'Get a recipe', description: 'Get a saved recipe and its full config by id.', inputSchema: { id: z.string().describe('Recipe id from compose_recipe or list_recipes') } },
-    wrap(({ id }) => client.getRecipe(id)));
-
-  server.registerTool('publish_recipe',
-    { title: 'Publish a recipe', description: 'Submit a saved recipe to the SimpliGen Creator Marketplace (queued for human review). Requires a connected account: if none, returns not_connected and the user connects once in Settings, then this succeeds on the same recipe. priceTokens sets an optional one-time price (0 or omitted = free). Every preset the recipe uses must be a distributable first-party pack.', inputSchema: { id: z.string().describe('Recipe id to publish'), changelog: z.string().optional(), priceTokens: z.number().optional().describe('One-time price in tokens (0/omitted = free).') } },
-    wrap(({ id, changelog, priceTokens }) => client.publishRecipe(id, { changelog, priceTokens })));
-}
+// packages/mcp-server/src/tools.js
+// Registers SimpliGen MCP tools on an McpServer-shaped object. Each tool calls a
+// ControlApiClient method and returns the JSON result as text content; client
+// errors become an isError tool result (so the agent sees the errorCode/message).
+import { z } from 'zod';
+import { buildResultImageContent } from './resultImage.js';
+
+export const TOOL_NAMES = [
+  'list_capabilities', 'get_status', 'list_projects', 'create_project',
+  'upload_file', 'generate', 'list_loras', 'get_job', 'wait_for_result', 'list_jobs',
+  'cancel_job', 'prepare_preset', 'get_result_image',
+  'list_characters', 'get_character', 'list_character_features', 'list_character_presets',
+  'remove_character', 'create_character', 'generate_character_image', 'generate_character_video',
+  'generate_character_frame', 'animate_character', 'set_character_preset',
+  'enhance_character_media', 'regenerate_character_base',
+  'list_recipe_blocks', 'compose_recipe', 'validate_recipe', 'list_recipes', 'get_recipe', 'publish_recipe',
+  'run_recipe', 'get_recipe_run', 'wait_for_recipe_run', 'list_recipe_runs', 'cancel_recipe_run',
+  'list_subjects', 'list_products', 'create_product', 'remove_product',
+];
+
+const ok = (data) => ({ content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] });
+const fail = (err) => ({ isError: true, content: [{ type: 'text', text: `${err.errorCode ? err.errorCode + ': ' : ''}${err.message || String(err)}` }] });
+const wrap = (fn) => async (args) => { try { return ok(await fn(args)); } catch (e) { return fail(e); } };
+
+export function registerTools(server, client) {
+  server.registerTool('list_capabilities',
+    { title: 'List capabilities', description: 'List every SimpliGen preset the agent can generate with (image/video), its inputs/options, whether it is installed locally (localReady) and cloud-eligible + credit cost.', inputSchema: {} },
+    wrap(() => client.getCapabilities()));
+
+  server.registerTool('get_status',
+    { title: 'Get status', description: 'Engine running state, whether cloud is connected, credit balance, and the active project.', inputSchema: {} },
+    wrap(() => client.getStatus()));
+
+  server.registerTool('list_projects',
+    { title: 'List projects', description: 'List projects (output containers).', inputSchema: {} },
+    wrap(() => client.listProjects()));
+
+  server.registerTool('create_project',
+    { title: 'Create project', description: 'Create a new project (output container).', inputSchema: { name: z.string().describe('Project name') } },
+    wrap(({ name }) => client.createProject(name)));
+
+  server.registerTool('upload_file',
+    { title: 'Upload a file', description: 'Upload a local image/video file and get an opaque handle to pass as image/referenceImages/video in generate.', inputSchema: { path: z.string().describe('Absolute local file path') } },
+    wrap(({ path }) => client.uploadFile(path)));
+
+  server.registerTool('generate',
+    {
+      title: 'Generate', description: 'Start an image or video generation. Inputs (image/referenceImages/video) are handles from upload_file. backend: local | cloud | auto. Returns a jobId; poll with wait_for_result or get_job.',
+      inputSchema: {
+        presetId: z.string(), mediaType: z.enum(['image', 'video']), prompt: z.string(),
+        packId: z.string().optional(), backend: z.enum(['local', 'cloud', 'auto']).optional(),
+        negativePrompt: z.string().optional(), project: z.string().optional(),
+        image: z.string().optional().describe('upload_file handle'),
+        referenceImages: z.array(z.string()).optional().describe('upload_file handles'),
+        video: z.string().optional().describe('upload_file handle (driving video)'),
+        loras: z.array(z.object({ name: z.string().describe('LoRA display name from list_loras'), weight: z.number().optional().describe('Strength; defaults to the LoRA default') })).optional().describe('LoRAs to apply. Local backend only, and only for presets where inputs.supportsLoras is true. Use the LoRA trigger words in the prompt so it activates.'),
+        // .passthrough(), not the zod default: a plain z.object STRIPS every key it
+        // does not name, silently. The App's /generate accepts any Advanced
+        // Control the preset declares (unlock, shift, high_steps, ...) and
+        // list_capabilities advertises them under options.controls, so an agent
+        // was told a control exists, sent it, and got the preset default back
+        // with no error: unlock: 1 arrived at the graph as 0.5 (Melvyl, 1.63.0).
+        // The App applies only what the preset declares and ignores the rest,
+        // so forwarding everything is safe. Known fields stay named so the
+        // agent still sees them in the tool's schema.
+        options: z.object({
+          resolution: z.string().optional().describe('Resolution tier label; see list_capabilities -> options.resolution.'),
+          aspectRatio: z.string().optional().describe('Aspect ratio, e.g. "1:1", "16:9", "9:16" (portrait/vertical), "4:3", "3:4". See list_capabilities -> options.aspectRatio for the values each preset accepts. Defaults to 1:1 for images (16:9 for video) if omitted.'),
+          durationSeconds: z.number().optional(),
+          steps: z.number().optional(),
+          cfg: z.number().optional(),
+          seed: z.number().optional(),
+          negativePrompt: z.string().optional(),
+          fasterAttention: z.boolean().optional().describe('Accelerator toggle; absent = preset default.'),
+          solAttn: z.boolean().optional().describe('Accelerator toggle; absent = preset default.'),
+          spectrum: z.boolean().optional().describe('Accelerator toggle; absent = preset default.'),
+        }).passthrough().optional().describe('Run options. Besides the named fields, pass ANY Advanced Control the preset declares under list_capabilities -> options.controls (for example unlock, shift, high_steps) as a top-level key of this object, using the value range that map gives. A key the preset does not declare is ignored.'),
+      },
+    },
+    wrap((args) => client.generate(args)));
+
+  server.registerTool('list_loras',
+    { title: 'List LoRAs', description: 'List the installed user LoRAs (name, base model, trigger words) so you can pass them in generate -> loras.', inputSchema: {} },
+    wrap(() => client.listLoras()));
+
+  server.registerTool('get_job',
+    { title: 'Get job', description: 'Status + result of a generation job. resultPath is the local file when completed.', inputSchema: { jobId: z.string() } },
+    wrap(({ jobId }) => client.getJob(jobId)));
+
+  server.registerTool('list_jobs',
+    { title: 'List jobs', description: 'Recent generation jobs.', inputSchema: {} },
+    wrap(() => client.listJobs()));
+
+  server.registerTool('cancel_job',
+    { title: 'Cancel job', description: 'Cancel a queued/running job.', inputSchema: { jobId: z.string() } },
+    wrap(({ jobId }) => client.cancelJob(jobId)));
+
+  server.registerTool('prepare_preset',
+    { title: 'Prepare preset', description: 'Start downloading a local preset\'s models (so it becomes localReady). Poll list_capabilities for localReady.', inputSchema: { presetId: z.string(), mediaType: z.enum(['image', 'video']), packId: z.string().optional() } },
+    wrap((args) => client.preparePreset(args)));
+
+  // Convenience: poll get_job until terminal or timeout (no extra endpoint).
+  server.registerTool('wait_for_result',
+    { title: 'Wait for result', description: 'Block until a job completes or fails (or the timeout). Returns the final job (resultPath when completed).', inputSchema: { jobId: z.string(), timeoutSeconds: z.number().optional(), pollMs: z.number().optional() } },
+    wrap(async ({ jobId, timeoutSeconds = 300, pollMs = 2000 }) => {
+      const deadline = Date.now() + timeoutSeconds * 1000;
+      // eslint-disable-next-line no-constant-condition
+      while (true) {
+        const { job } = await client.getJob(jobId);
+        if (!job || job.status === 'completed' || job.status === 'failed') return job;
+        if (Date.now() >= deadline) return { ...job, note: 'timeout_still_running' };
+        await new Promise((r) => setTimeout(r, pollMs));
+      }
+    }));
+
+  // Return a completed job's result image inline (an MCP image block) so the
+  // agent can actually display it. Images only; video/unreadable -> path note.
+  server.registerTool('get_result_image',
+    { title: 'Get result image', description: 'Return a completed job\'s result image inline as a viewable image so it can be displayed in chat. Large images are re-encoded to a full-resolution WebP preview that fits the client size cap; the uncompressed original file path is always included in the caption. Video results return the file path instead. Call after the job is completed.', inputSchema: { jobId: z.string(), maxBytes: z.number().optional().describe('Inline byte budget before re-encoding/resizing (default ~700KB raw)') } },
+    async ({ jobId, maxBytes }) => {
+      try {
+        const { job } = await client.getJob(jobId);
+        return await buildResultImageContent(job, { budgetBytes: maxBytes });
+      } catch (e) {
+        return fail(e);
+      }
+    });
+
+  // ---- Character Studio tools ----
+
+  server.registerTool('list_characters',
+    { title: 'List characters', description: 'List all saved characters in Character Studio.', inputSchema: {} },
+    wrap(() => client.listCharacters()));
+
+  server.registerTool('get_character',
+    { title: 'Get character', description: 'Get a single character by ID, including its current base portrait and identity features.', inputSchema: { characterId: z.string() } },
+    wrap(({ characterId }) => client.getCharacter(characterId)));
+
+  server.registerTool('list_character_features',
+    { title: 'List character features', description: 'List available feature categories and their options (e.g. hairColor, eyeColor) for use with create_character identity.', inputSchema: {} },
+    wrap(() => client.listCharacterFeatures()));
+
+  server.registerTool('list_character_presets',
+    { title: 'List character presets', description: 'List generation presets available for Character Studio. Returns base, identityEdit, and i2v presets as well as enhanceImage and enhanceVideo presets (each with supportedScales). Use the returned ids as presetId/imagePresetId/videoPresetId/basePresetId arguments in other character tools.', inputSchema: {} },
+    wrap(() => client.listCharacterPresets()));
+
+  server.registerTool('remove_character',
+    { title: 'Remove character', description: 'Permanently delete a character and its associated data.', inputSchema: { characterId: z.string() } },
+    wrap(({ characterId }) => client.removeCharacter(characterId)));
+
+  server.registerTool('create_character',
+    {
+      title: 'Create character',
+      description: 'Create a new character. Three paths: (1) describe -- pass gender and identity features from list_character_features with mode "generate"; the server builds a base portrait automatically and this tool waits until ready. (2) upload as base -- pass baseFilePath pointing to a local image with mode "upload"; the image becomes the base portrait immediately. (3) vision recreate -- describe path but fill identity by having the agent analyse a reference photo first; the agent extracts features and passes them as identity.',
+      inputSchema: {
+        name: z.string().describe('Display name for the character'),
+        gender: z.enum(['woman', 'man', 'nonbinary']),
+        mode: z.enum(['generate', 'upload']).describe('generate: build base portrait from description; upload: use a provided image as base'),
+        identity: z.record(z.string()).optional().describe('An object of featureId to optionId pairs chosen from list_character_features (e.g. { hairColor: "black", eyeColor: "green" }). Do not include gender here; pass gender separately.'),
+        baseFilePath: z.string().optional().describe('Absolute local image path; required for mode "upload"'),
+        timeoutSeconds: z.number().optional().describe('Max seconds to wait for base portrait generation (default 300, mode generate only)'),
+        pollMs: z.number().optional().describe('Poll interval in milliseconds (default 2000, mode generate only)'),
+      },
+    },
+    async ({ name, gender, mode, identity, baseFilePath, timeoutSeconds, pollMs }) => {
+      try {
+        if (mode === 'upload') {
+          const up = await client.uploadFile(baseFilePath);
+          const char = await client.createCharacter({ name, gender, mode: 'upload', identity, baseHandle: up.handle });
+          return ok({ ...char, ready: true });
+        }
+        // mode === 'generate': create then poll until base_image_url is set
+        const c = await client.createCharacter({ name, gender, mode: 'generate', identity });
+        const { characterId } = c;
+        const deadline = Date.now() + (timeoutSeconds ?? 300) * 1000;
+        while (true) {
+          const { character } = await client.getCharacter(characterId);
+          if (character?.base_image_url) return ok(character);
+          if (Date.now() >= deadline) return ok({ ...character, base_pending: true });
+          await new Promise((r) => setTimeout(r, pollMs ?? 2000));
+        }
+      } catch (e) {
+        return fail(e);
+      }
+    });
+
+  server.registerTool('generate_character_image',
+    {
+      title: 'Generate character image',
+      description: 'Generate one or more images of a character in a scene. Returns jobIds; use wait_for_result then get_result_image for each. Pass presetId to override the default image preset (ids from list_character_presets).',
+      inputSchema: {
+        characterId: z.string(),
+        prompt: z.string(),
+        aspect: z.enum(['16:9', '9:16', '1:1']).optional(),
+        count: z.number().optional(),
+        presetId: z.string().optional().describe('Override image preset (id from list_character_presets)'),
+      },
+    },
+    wrap(({ characterId, prompt, aspect, count, presetId }) => {
+      const args = { prompt, aspect, count };
+      if (presetId !== undefined) args.presetId = presetId;
+      return client.generateCharacterImage(characterId, args);
+    }));
+
+  server.registerTool('generate_character_video',
+    {
+      title: 'Generate character video',
+      description: 'Generate a short video of a character in a scene. Internally generates a frame then animates it (I2V). Returns frameJobId and videoJobId; use wait_for_result then get_result_image on videoJobId. Use framePresetId to override the image-frame preset and videoPresetId to override the video/animate preset (ids from list_character_presets).',
+      inputSchema: {
+        characterId: z.string(),
+        prompt: z.string(),
+        motion: z.string().optional().describe('Optional motion description or style hint'),
+        aspect: z.enum(['16:9', '9:16', '1:1']).optional(),
+        timeoutSeconds: z.number().optional().describe('Max seconds to wait for the frame job (default 300)'),
+        pollMs: z.number().optional().describe('Poll interval in milliseconds (default 2000)'),
+        framePresetId: z.string().optional().describe('Override image-frame preset (id from list_character_presets)'),
+        videoPresetId: z.string().optional().describe('Override video/animate preset (id from list_character_presets)'),
+      },
+    },
+    async ({ characterId, prompt, motion, aspect, timeoutSeconds = 300, pollMs = 2000, framePresetId, videoPresetId }) => {
+      try {
+        // 1. Generate a frame (still image for I2V)
+        const { jobIds: [frameJobId] } = await client.generateCharacterFrame(characterId, { prompt, aspect, presetId: framePresetId });
+        // 2. Wait for frame to complete
+        const deadline = Date.now() + timeoutSeconds * 1000;
+        while (true) {
+          const { job: frameJob } = await client.getJob(frameJobId);
+          if (frameJob?.status === 'completed') break;
+          if (frameJob?.status === 'failed') return fail({ message: `Frame job failed: ${frameJobId}`, errorCode: 'frame_failed' });
+          if (Date.now() >= deadline) return fail({ message: `Frame job timed out: ${frameJobId}`, errorCode: 'frame_timeout' });
+          await new Promise((r) => setTimeout(r, pollMs));
+        }
+        // 3. Animate from the completed frame
+        const { jobIds: [videoJobId] } = await client.animateCharacter(characterId, { frameJobId, motion, aspect, presetId: videoPresetId });
+        return ok({ frameJobId, videoJobId });
+      } catch (e) { return fail(e); }
+    });
+
+  // ---- New Character Studio tools (Task 4) ----
+
+  server.registerTool('generate_character_frame',
+    {
+      title: 'Generate character frame',
+      description: 'Generate a start-frame image for a character that you can review or enhance before animating. Returns jobIds; use wait_for_result then get_result_image. Pass presetId to override the frame-image preset (ids from list_character_presets).',
+      inputSchema: {
+        characterId: z.string(),
+        prompt: z.string(),
+        aspect: z.enum(['16:9', '9:16', '1:1']).optional(),
+        presetId: z.string().optional().describe('Override image preset (id from list_character_presets)'),
+      },
+    },
+    wrap(({ characterId, prompt, aspect, presetId }) => {
+      const args = { prompt, aspect };
+      if (presetId !== undefined) args.presetId = presetId;
+      return client.generateCharacterFrame(characterId, args);
+    }));
+
+  server.registerTool('animate_character',
+    {
+      title: 'Animate character',
+      description: 'Animate a character from a completed image/frame job or a local file path (I2V). jobId may be any completed character image, frame, or upscale job. Returns jobIds; use wait_for_result then get_result_image. Pass videoPresetId to override the video preset (ids from list_character_presets).',
+      inputSchema: {
+        characterId: z.string(),
+        jobId: z.string().optional().describe('Any completed character image/frame/upscale jobId to use as the source frame'),
+        filePath: z.string().optional().describe('Absolute local image path to use as the source frame'),
+        motion: z.string().optional().describe('Optional motion description or style hint'),
+        aspect: z.enum(['16:9', '9:16', '1:1']).optional(),
+        videoPresetId: z.string().optional().describe('Override video/animate preset (id from list_character_presets)'),
+      },
+    },
+    wrap(({ characterId, jobId, filePath, motion, aspect, videoPresetId }) =>
+      client.animateCharacter(characterId, { frameJobId: jobId, framePath: filePath, motion, aspect, presetId: videoPresetId })));
+
+  server.registerTool('set_character_preset',
+    {
+      title: 'Set character preset',
+      description: 'Set sticky per-character default presets for image and/or video generation. Ids come from list_character_presets. Pass null to clear a preset back to the system default.',
+      inputSchema: {
+        characterId: z.string(),
+        imagePresetId: z.string().nullable().optional().describe('Default image preset id (null to clear)'),
+        videoPresetId: z.string().nullable().optional().describe('Default video preset id (null to clear)'),
+      },
+    },
+    wrap(({ characterId, imagePresetId, videoPresetId }) => client.setCharacterPreset(characterId, { imagePresetId, videoPresetId })));
+
+  server.registerTool('enhance_character_media',
+    {
+      title: 'Enhance character media',
+      description: 'Upscale a generated image/video, a local file, or the character base portrait (target: "base"). Returns a jobId; use wait_for_result then get_result_image. scale sets the upscale factor; keepResolution upscales then resizes back to source size for a sharper same-size result; applyAsBase replaces the character base portrait with the upscaled result. Enhance presets come from list_character_presets (enhanceImage/enhanceVideo, each with supportedScales).',
+      inputSchema: {
+        characterId: z.string(),
+        jobId: z.string().optional().describe('Completed job whose result to enhance'),
+        filePath: z.string().optional().describe('Absolute local image/video path to enhance'),
+        target: z.enum(['base']).optional().describe('Pass "base" to enhance the character base portrait'),
+        mediaType: z.enum(['image', 'video']).optional(),
+        presetId: z.string().optional().describe('Enhance preset id from list_character_presets'),
+        scale: z.number().optional().describe('Upscale factor (e.g. 2 for 2x)'),
+        keepResolution: z.boolean().optional().describe('Upscale then resize back to source dimensions for a sharper same-size result'),
+        applyAsBase: z.boolean().optional().describe('Replace the character base portrait with the upscaled result'),
+      },
+    },
+    wrap(({ characterId, jobId, filePath, target, mediaType, presetId, scale, keepResolution, applyAsBase }) =>
+      client.enhanceCharacterMedia(characterId, { jobId, filePath, target, mediaType, presetId, scale, keepResolution, applyAsBase })));
+
+  server.registerTool('regenerate_character_base',
+    {
+      title: 'Regenerate character base',
+      description: 'Switch the base model and regenerate the base portrait IN PLACE (no new character created). Replaces the current base when completed. Uses basePresetId from list_character_presets. Optionally update identity features at the same time. Polls until completed, then auto-accepts the new base.',
+      inputSchema: {
+        characterId: z.string(),
+        basePresetId: z.string().optional().describe('Base-generation preset id from list_character_presets'),
+        identity: z.record(z.string()).optional().describe('Updated identity feature map (featureId -> optionId) to apply alongside the new base'),
+        timeoutSeconds: z.number().optional().describe('Max seconds to wait for the base job (default 300)'),
+        pollMs: z.number().optional().describe('Poll interval in milliseconds (default 2000)'),
+      },
+    },
+    async ({ characterId, basePresetId, identity, timeoutSeconds = 300, pollMs = 2000 }) => {
+      try {
+        const { baseJobId } = await client.regenerateCharacterBase(characterId, { basePresetId, identity });
+        const deadline = Date.now() + timeoutSeconds * 1000;
+        while (true) {
+          const { job } = await client.getJob(baseJobId);
+          if (job?.status === 'completed') {
+            await client.acceptBase(characterId, { altImageId: baseJobId });
+            return ok(await client.getCharacter(characterId));
+          }
+          if (job?.status === 'failed') return fail({ message: `Base regeneration job failed: ${baseJobId}`, errorCode: 'base_failed' });
+          if (Date.now() >= deadline) return ok({ baseJobId, note: 'timeout_still_running' });
+          await new Promise((r) => setTimeout(r, pollMs));
+        }
+      } catch (e) { return fail(e); }
+    });
+
+  // --- Recipe authoring: compose multi-step recipes out of packs/presets ---
+
+  const recipeStep = z.object({
+    preset: z.string().describe('The preset this step runs, as "packId:presetId" (from list_recipe_blocks).'),
+    entry: z.string().optional().describe('Entry point: create-image | create-video | edit-image | upscale. Inferred from the preset when omitted.'),
+    promptInput: z.object({ key: z.string().optional(), label: z.string().optional() }).optional()
+      .describe('Name this step\'s prompt input, or set key to an existing input to SHARE a prompt. Default: a dedicated prompt input per step.'),
+    negativePrompt: z.string().optional(),
+    params: z.record(z.any()).optional().describe('Param bindings, literal or { from: "input:<key>" } (e.g. aspectRatio, seed, duration).'),
+  }).passthrough();
+
+  const recipeInput = z.object({
+    key: z.string().describe('Unique slug referenced as input:<key>.'),
+    kind: z.string().describe('subject | text | image | video | reference | audio | select | color | number | toggle'),
+    label: z.string().optional(),
+    required: z.boolean().optional(),
+  }).passthrough();
+
+  const recipeSpec = z.object({
+    name: z.string().describe('Recipe name shown to end users.'),
+    description: z.string().optional(),
+    category: z.string().optional().describe('e.g. product | ugc'),
+    mature: z.boolean().optional().describe('Creator-declared: this recipe produces adult content.'),
+    // Accepted, not for the benefit of third parties (breaking them is fine), but
+    // because an agent composing a recipe mid-transition would otherwise DROP the
+    // classification, which publishes adult content as unclassified (TASK-472).
+    nsfw: z.boolean().optional().describe('Deprecated alias for `mature`.'),
+    version: z.string().optional().describe('Creator-facing semver, default 1.0.0.'),
+    inputs: z.array(recipeInput).optional().describe('Extra user-facing inputs (subjects, choices, media holes). A prompt input is auto-created per step, so you rarely list prompts here.'),
+    steps: z.array(recipeStep).min(1).describe('The pipeline in order. Each step pins a preset; media output flows into the next step automatically, and a subject input seeds a reference port.'),
+  });
+
+  server.registerTool('list_recipe_blocks',
+    { title: 'List recipe blocks', description: 'The building blocks for authoring a recipe: entry points (create-image/video, edit-image, upscale) and every preset usable as a step, each with its port contract (inputs it needs, what it produces, which entry points it fits). Call this before compose_recipe to choose presets.', inputSchema: {} },
+    wrap(() => client.listRecipeBlocks()));
+
+  server.registerTool('compose_recipe',
+    { title: 'Compose a recipe', description: 'Author a new recipe from a high-level spec and save it as a draft. You give an ordered list of steps (each pinned to a preset from list_recipe_blocks) plus any extra inputs; SimpliGen auto-wires the ports, media chain, and per-step prompt inputs and validates it. Returns { recipeId, valid, errors }. Anyone can compose; publishing later needs a connected account.', inputSchema: { spec: recipeSpec } },
+    wrap(({ spec }) => client.composeRecipe({ spec })));
+
+  server.registerTool('validate_recipe',
+    { title: 'Validate a recipe', description: 'Dry-run without saving: pass a `spec` to compose+validate it, or a `config` to validate an existing recipe config. Returns precise errors (unbound ports, missing presets, type mismatches, cycles) to fix before compose_recipe.', inputSchema: { spec: recipeSpec.optional(), config: z.record(z.any()).optional() } },
+    wrap((args) => client.validateRecipe(args)));
+
+  server.registerTool('list_recipes',
+    { title: 'List recipes', description: 'List every recipe on this device: the ones installed from the Store into UGC Studio / Product Studio (category ugc | product) and drafts authored here. Each entry carries its `inputs` (key, kind, label, required, options) so you know what run_recipe needs: a `subject` input takes a character id from list_characters (or a product id), image/video/audio inputs take upload_file handles, text/select/number inputs take plain values.', inputSchema: {} },
+    wrap(() => client.listRecipes()));
+
+  // --- Running an installed recipe (what drives the UGC + Product Studios) ---
+
+  server.registerTool('run_recipe',
+    {
+      title: 'Run a recipe',
+      description: 'Run an installed recipe (from list_recipes) with its inputs filled: the same multi-step pipeline UGC Studio / Product Studio runs when a person clicks Generate, so results land in the Gallery grouped the same way. `inputs` is keyed by input key; a subject input takes a character/product id, media inputs take upload_file handles. engine: local (default when every step is installed) | cloud | auto. Returns a runId; poll with wait_for_recipe_run or get_recipe_run. Cloud runs are priced up front and count against this agent\'s spend cap.',
+      inputSchema: {
+        id: z.string().describe('Recipe id from list_recipes'),
+        inputs: z.record(z.any()).describe('Input values keyed by the recipe\'s input keys (see list_recipes -> inputs).'),
+        engine: z.enum(['local', 'cloud', 'auto']).optional().describe('Where the steps render. auto = local if every step is installed, else cloud when connected.'),
+      },
+    },
+    wrap(({ id, inputs, engine }) => client.runRecipe(id, { inputs: inputs || {}, ...(engine ? { engine } : {}) })));
+
+  server.registerTool('get_recipe_run',
+    { title: 'Get a recipe run', description: 'Status of a recipe run: overall status (running | completed | failed | cancelled), each step with its status and resultPath, and resultPath = the final output once done.', inputSchema: { runId: z.string().describe('Run id from run_recipe') } },
+    wrap(({ runId }) => client.getRecipeRun(runId)));
+
+  server.registerTool('wait_for_recipe_run',
+    { title: 'Wait for a recipe run', description: 'Block until a recipe run completes, fails, is cancelled, or the timeout passes. Returns the final run (resultPath when completed). Multi-step video recipes can take several minutes; call again if it returns timeout_still_running.', inputSchema: { runId: z.string(), timeoutSeconds: z.number().optional(), pollMs: z.number().optional() } },
+    wrap(async ({ runId, timeoutSeconds = 600, pollMs = 3000 }) => {
+      const deadline = Date.now() + timeoutSeconds * 1000;
+      // eslint-disable-next-line no-constant-condition
+      while (true) {
+        const { run } = await client.getRecipeRun(runId);
+        if (run && ['completed', 'failed', 'cancelled'].includes(run.status)) return { run };
+        if (Date.now() >= deadline) return { run, note: 'timeout_still_running' };
+        await new Promise((r) => setTimeout(r, pollMs));
+      }
+    }));
+
+  server.registerTool('list_recipe_runs',
+    { title: 'List recipe runs', description: 'Recent runs of a recipe (newest first) with their status and results.', inputSchema: { id: z.string().describe('Recipe id') } },
+    wrap(({ id }) => client.listRecipeRuns(id)));
+
+  // --- Products + subjects: what a recipe's `subject` inputs take ---
+
+  server.registerTool('list_subjects',
+    { title: 'List subjects', description: 'Every subject a recipe\'s `subject` input can take: characters and products (id, type, name). Use a character id from list_characters or a product id from list_products / create_product.', inputSchema: {} },
+    wrap(() => client.listSubjects()));
+
+  server.registerTool('list_products',
+    { title: 'List products', description: 'The products saved on this device (a product = a named thing with a base photo, used by Product Studio and UGC recipes).', inputSchema: {} },
+    wrap(() => client.listProducts()));
+
+  server.registerTool('create_product',
+    {
+      title: 'Create a product',
+      description: 'Save a product from a photo so recipes can use it: upload the photo with upload_file first, then pass its handle. The description and category are woven into recipe prompts, so describe what it is and how it looks. Returns the productId to pass as a `subject` input in run_recipe.',
+      inputSchema: {
+        name: z.string().describe('Product name shown in the app'),
+        image: z.string().describe('upload_file handle of the product photo (clean, well-lit, product centred)'),
+        description: z.string().optional().describe('What it is and looks like, e.g. "a matte black ceramic coffee mug with a wooden lid"'),
+        category: z.string().optional().describe('e.g. skincare | beverage | electronics'),
+      },
+    },
+    wrap(({ name, image, description, category }) => client.createProduct({ name, image, description, category })));
+
+  server.registerTool('remove_product',
+    { title: 'Remove a product', description: 'Delete a product and its photo from this device.', inputSchema: { id: z.string() } },
+    wrap(({ id }) => client.removeProduct(id)));
+
+  server.registerTool('cancel_recipe_run',
+    { title: 'Cancel a recipe run', description: 'Stop a running recipe: no further steps start; a local in-flight step is interrupted (a cloud step already running finishes server-side and is saved).', inputSchema: { runId: z.string() } },
+    wrap(({ runId }) => client.cancelRecipeRun(runId)));
+
+  server.registerTool('get_recipe',
+    { title: 'Get a recipe', description: 'Get a saved recipe and its full config by id.', inputSchema: { id: z.string().describe('Recipe id from compose_recipe or list_recipes') } },
+    wrap(({ id }) => client.getRecipe(id)));
+
+  server.registerTool('publish_recipe',
+    { title: 'Publish a recipe', description: 'Submit a saved recipe to the SimpliGen Creator Marketplace (queued for human review). Requires a connected account: if none, returns not_connected and the user connects once in Settings, then this succeeds on the same recipe. priceTokens sets an optional one-time price (0 or omitted = free). Every preset the recipe uses must be a distributable first-party pack.', inputSchema: { id: z.string().describe('Recipe id to publish'), changelog: z.string().optional(), priceTokens: z.number().optional().describe('One-time price in tokens (0/omitted = free).') } },
+    wrap(({ id, changelog, priceTokens }) => client.publishRecipe(id, { changelog, priceTokens })));
+}