@simpligen/mcp 0.1.0 → 0.1.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 SimpliGen
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 SimpliGen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,23 +1,37 @@
-{
-  "name": "@simpligen/mcp",
-  "version": "0.1.0",
-  "description": "MCP server for SimpliGen -- drive local/cloud AI image & video generation from an agent.",
-  "type": "module",
-  "license": "MIT",
-  "homepage": "https://simpligen.io",
-  "repository": { "type": "git", "url": "git+https://github.com/RaynoldVanHeyningen/SimpliGen.git", "directory": "packages/mcp-server" },
-  "bin": { "simpligen-mcp": "src/bin.js" },
-  "main": "src/index.js",
-  "files": ["src", "README.md", "LICENSE"],
-  "engines": { "node": ">=18" },
-  "publishConfig": { "access": "public" },
-  "scripts": {
-    "test": "node --test src/*.test.js",
-    "prepublishOnly": "node --test src/*.test.js"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1",
-    "sharp": "^0.35.1",
-    "zod": "^3"
-  }
-}
+{
+  "name": "@simpligen/mcp",
+  "version": "0.1.1",
+  "description": "MCP server for SimpliGen -- drive local/cloud AI image & video generation from an agent.",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://simpligen.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RaynoldVanHeyningen/SimpliGen.git",
+    "directory": "packages/mcp-server"
+  },
+  "bin": {
+    "simpligen-mcp": "src/bin.js"
+  },
+  "main": "src/index.js",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test src/*.test.js",
+    "prepublishOnly": "node --test src/*.test.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1",
+    "sharp": "^0.35.1",
+    "zod": "^3"
+  }
+}

package/src/client.js

@@ -53,6 +53,20 @@ export class ControlApiClient {
   preparePreset(args) { return this.#req('POST', '/presets/prepare', args); }
   getActiveDownloads() { return this.#req('GET', '/presets/prepare'); }
 
+  listCharacters() { return this.#req('GET', '/characters'); }
+  getCharacter(id) { return this.#req('GET', `/characters/${encodeURIComponent(id)}`); }
+  listCharacterFeatures() { return this.#req('GET', '/character-features'); }
+  listCharacterPresets() { return this.#req('GET', '/character-presets'); }
+  createCharacter(args) { return this.#req('POST', '/characters', args); }
+  generateCharacterImage(id, args) { return this.#req('POST', `/characters/${encodeURIComponent(id)}/generate-image`, args); }
+  generateCharacterFrame(id, args) { return this.#req('POST', `/characters/${encodeURIComponent(id)}/generate-frame`, args); }
+  animateCharacter(id, args) { return this.#req('POST', `/characters/${encodeURIComponent(id)}/animate`, args); }
+  acceptBase(id, args) { return this.#req('POST', `/characters/${encodeURIComponent(id)}/accept-base`, args); }
+  setCharacterPreset(id, args) { return this.#req('POST', `/characters/${encodeURIComponent(id)}/preset`, args); }
+  enhanceCharacterMedia(id, args) { return this.#req('POST', `/characters/${encodeURIComponent(id)}/enhance`, args); }
+  regenerateCharacterBase(id, args) { return this.#req('POST', `/characters/${encodeURIComponent(id)}/regenerate-base`, args); }
+  removeCharacter(id) { return this.#req('DELETE', `/characters/${encodeURIComponent(id)}`); }
+
   async uploadFile(filePath) {
     let buf;
     try {

package/src/tools.js

@@ -9,6 +9,10 @@ export const TOOL_NAMES = [
   'list_capabilities', 'get_status', 'list_projects', 'create_project',
   'upload_file', 'generate', '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',
 ];
 
 const ok = (data) => ({ content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] });
@@ -46,7 +50,7 @@ export function registerTools(server, client) {
         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)'),
-        options: z.object({ resolution: z.string().optional(), durationSeconds: z.number().optional(), steps: z.number().optional(), cfg: z.number().optional(), seed: z.number().optional() }).optional(),
+        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)));
@@ -93,4 +97,209 @@ export function registerTools(server, client) {
         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); }
+    });
 }