@simpligen/mcp 0.1.0

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -0,0 +1,41 @@
+# @simpligen/mcp
+
+MCP server that lets an AI agent drive SimpliGen (local + cloud AI image/video generation). Requires the SimpliGen desktop app running and a pairing token (Settings -> Connect an agent).
+
+## Configure (Claude Code / Claude Desktop)
+
+The easiest path is in the SimpliGen app: **Settings -> Connect an agent**, pick your client, and click Install (or copy the guided command). The manual config below is the fallback.
+
+```json
+{
+  "mcpServers": {
+    "simpligen": {
+      "command": "npx",
+      "args": ["-y", "@simpligen/mcp"],
+      "env": { "SIMPLIGEN_TOKEN": "sg-agent-..." }
+    }
+  }
+}
+```
+
+## Tools
+
+`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`.
+
+`get_result_image` returns a completed job's result image inline (a viewable image block) so the agent can display it in chat. Claude clients cap a tool result at ~1MB and only render base64 image blocks, so large renders are re-encoded to a **full-resolution WebP** preview (same dimensions; quality steps down, and only very large images are resized) that fits the cap. The uncompressed original file path is always included in the caption, so the agent keeps the full-quality artifact. Video results return the file path instead.
+
+## Env
+
+- `SIMPLIGEN_TOKEN` (required) -- pairing token from the app.
+- `SIMPLIGEN_API_PORT` (optional) -- override the control-API port (else read from the app's discovery file).
+- `SIMPLIGEN_USERDATA_DIR` / `SIMPLIGEN_APP_NAME` (optional) -- locate the app's data dir (CN variant / custom).
+
+## Manual smoke (for maintainers)
+
+With the app running and a token issued:
+
+```bash
+SIMPLIGEN_TOKEN=<token> npx @modelcontextprotocol/inspector node src/bin.js
+```
+
+Verify: tool list appears; call `get_status`; call `list_capabilities`; call `upload_file` with a PNG path and confirm a handle is returned; call `generate` with a local preset and confirm a `jobId`; call `wait_for_result` and confirm a `resultPath`; call `get_result_image` and confirm the image renders inline.

package/package.json

@@ -0,0 +1,23 @@
+{
+  "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"
+  }
+}

package/src/bin.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// packages/mcp-server/src/bin.js
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ControlApiClient } from './client.js';
+import { createMcpServer } from './server.js';
+
+async function main() {
+  const client = new ControlApiClient(); // resolves port (discovery file) + token (SIMPLIGEN_TOKEN)
+  const server = createMcpServer(client);
+  await server.connect(new StdioServerTransport());
+}
+
+main().catch((err) => { console.error('[simpligen-mcp] fatal:', err?.message || err); process.exit(1); });

package/src/client.js

@@ -0,0 +1,65 @@
+// packages/mcp-server/src/client.js
+// Thin client over the SimpliGen local control API. Resolves base URL + token,
+// does authed fetch calls, throws a structured error on non-2xx.
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveUserDataDir, readDiscoveryPort } from './userdata.js';
+
+export class ControlApiError extends Error {
+  constructor(status, errorCode, message) {
+    super(message || errorCode || `HTTP ${status}`);
+    this.name = 'ControlApiError';
+    this.status = status;
+    this.errorCode = errorCode || null;
+  }
+}
+
+export class ControlApiClient {
+  // opts: { baseUrl?, token?, fetchImpl?, env? }. Falls back to discovery file + env.
+  constructor(opts = {}) {
+    const env = opts.env || process.env;
+    this.token = opts.token || env.SIMPLIGEN_TOKEN || null;
+    this.fetch = opts.fetchImpl || globalThis.fetch;
+    if (opts.baseUrl) {
+      this.baseUrl = opts.baseUrl;
+    } else {
+      const port = env.SIMPLIGEN_API_PORT ? Number(env.SIMPLIGEN_API_PORT) : readDiscoveryPort(resolveUserDataDir(env));
+      this.baseUrl = port ? `http://127.0.0.1:${port}` : null;
+    }
+  }
+
+  async #req(method, p, body) {
+    if (!this.baseUrl) throw new ControlApiError(0, 'app_not_running', 'SimpliGen is not running (no control-API port found). Start the app.');
+    if (!this.token) throw new ControlApiError(0, 'missing_token', 'No pairing token. Set SIMPLIGEN_TOKEN (Settings -> Connect an agent).');
+    const res = await this.fetch(`${this.baseUrl}${p}`, {
+      method,
+      headers: { Authorization: `Bearer ${this.token}`, 'Content-Type': 'application/json' },
+      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    });
+    let json = {};
+    try { json = await res.json(); } catch { /* empty body */ }
+    if (!res.ok) throw new ControlApiError(res.status, json.errorCode, json.message);
+    return json;
+  }
+
+  getCapabilities() { return this.#req('GET', '/capabilities'); }
+  getStatus() { return this.#req('GET', '/status'); }
+  listProjects() { return this.#req('GET', '/projects'); }
+  createProject(name) { return this.#req('POST', '/projects', { name }); }
+  generate(args) { return this.#req('POST', '/generate', args); }
+  getJob(id) { return this.#req('GET', `/jobs/${encodeURIComponent(id)}`); }
+  listJobs() { return this.#req('GET', '/jobs'); }
+  cancelJob(id) { return this.#req('POST', `/jobs/${encodeURIComponent(id)}/cancel`, {}); }
+  preparePreset(args) { return this.#req('POST', '/presets/prepare', args); }
+  getActiveDownloads() { return this.#req('GET', '/presets/prepare'); }
+
+  async uploadFile(filePath) {
+    let buf;
+    try {
+      buf = fs.readFileSync(filePath);
+    } catch (e) {
+      throw new ControlApiError(0, 'file_not_found', `Cannot read file to upload: ${filePath} (${e.code || e.message}).`);
+    }
+    return this.#req('POST', '/uploads', { filename: path.basename(filePath), dataBase64: buf.toString('base64') });
+  }
+}

package/src/index.js

@@ -0,0 +1,6 @@
+// packages/mcp-server/src/index.js
+export { ControlApiClient, ControlApiError } from './client.js';
+export { createMcpServer } from './server.js';
+export { registerTools, TOOL_NAMES } from './tools.js';
+export { buildResultImageContent } from './resultImage.js';
+export { resolveUserDataDir, readDiscoveryPort } from './userdata.js';

package/src/resultImage.js

@@ -0,0 +1,121 @@
+// packages/mcp-server/src/resultImage.js
+// Build MCP content for a completed job's result image so an agent can display
+// it inline. Claude clients only render base64 `image` blocks and cap a tool
+// result at ~1MB, so a full-resolution PNG (often >1MB once base64-inflated)
+// will not display. We therefore:
+//   - inline the ORIGINAL file untouched when it already fits the budget, else
+//   - re-encode a FULL-RESOLUTION WebP preview (no dimension change) at high
+//     quality, stepping quality down -- and only resizing as a last resort for
+//     enormous renders -- until it fits.
+// The original full-quality file is ALWAYS reported via its path in the caption,
+// so the agent keeps the uncompressed artifact; the WebP is a display preview.
+// `readFile` and `encodeWebp` are injected for tests (no native sharp needed).
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Inline content types Claude renders directly (so we pass the original through
+// when it already fits, no re-encode).
+const DIRECT_MIME = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+};
+
+// Raw-byte budget for the inline payload. base64 inflates ~4/3, so 700KB raw
+// -> ~933KB base64, under the client's 1MB tool-result cap with envelope room.
+export const DEFAULT_BUDGET_BYTES = 700 * 1024;
+
+// Tried in order; first encoding under budget wins. Quality drops first to keep
+// full resolution; resizing is the last resort for very large renders.
+const ENCODE_PLAN = [
+  { quality: 90 },
+  { quality: 82 },
+  { quality: 72 },
+  { quality: 80, maxDimension: 2048 },
+  { quality: 78, maxDimension: 1280 },
+  { quality: 75, maxDimension: 1024 },
+];
+
+let _sharp;
+async function defaultEncodeWebp(input, { quality, maxDimension } = {}) {
+  if (!_sharp) _sharp = (await import('sharp')).default;
+  let img = _sharp(input, { failOn: 'none', animated: false });
+  if (maxDimension) {
+    img = img.resize({ width: maxDimension, height: maxDimension, fit: 'inside', withoutEnlargement: true });
+  }
+  return img.webp({ quality, effort: 4 }).toBuffer();
+}
+
+const note = (text) => ({ content: [{ type: 'text', text }] });
+const imageBlock = (buf, mimeType, caption) => ({
+  content: [
+    { type: 'image', data: buf.toString('base64'), mimeType },
+    { type: 'text', text: caption },
+  ],
+});
+
+// job: agent-facing job shape ({ jobId, status, resultPath, mediaType, ... }).
+// opts: { readFile?, encodeWebp?, budgetBytes? }.
+export async function buildResultImageContent(job, opts = {}) {
+  const readFile = opts.readFile || fs.readFileSync;
+  const encodeWebp = opts.encodeWebp || defaultEncodeWebp;
+  const budget = opts.budgetBytes || DEFAULT_BUDGET_BYTES;
+
+  if (!job) return note('No such job.');
+  if (job.status !== 'completed') {
+    return note(`Job ${job.jobId || ''} is "${job.status || 'unknown'}"; no result image yet.`);
+  }
+  const p = job.resultPath;
+  if (!p) return note('Job completed but has no result path.');
+  if (job.mediaType === 'video') {
+    return note(`Result is a video, which cannot be displayed inline. It is at: ${p}`);
+  }
+
+  const ext = path.extname(p).toLowerCase();
+  const directMime = DIRECT_MIME[ext];
+  if (!directMime) {
+    return note(`Result is not an inlineable image (${ext || 'no extension'}). It is at: ${p}`);
+  }
+
+  let original;
+  try {
+    original = readFile(p);
+  } catch (e) {
+    return note(`Could not read the result file (${e.code || e.message}). It is at: ${p}`);
+  }
+
+  // Already small enough: inline the original untouched (lossless).
+  if (original.length <= budget) {
+    return imageBlock(original, directMime, `Result image (${directMime}, full file): ${p}`);
+  }
+
+  // Too big to inline as-is: produce a full-resolution WebP preview that fits.
+  // The original full-quality file stays on disk and is named in the caption.
+  let smallest = null;
+  let smallestCfg = null;
+  for (const cfg of ENCODE_PLAN) {
+    let webp;
+    try {
+      webp = await encodeWebp(original, cfg);
+    } catch (e) {
+      return note(`Could not encode a preview (${e.message}). Full-quality original is at: ${p}`);
+    }
+    if (!smallest || webp.length < smallest.length) {
+      smallest = webp;
+      smallestCfg = cfg;
+    }
+    if (webp.length <= budget) {
+      const dim = cfg.maxDimension ? `, resized to <=${cfg.maxDimension}px for display` : ', full resolution';
+      return imageBlock(webp, 'image/webp', `Inline preview (WebP q${cfg.quality}${dim}). Full-quality original (uncompressed) is at: ${p}`);
+    }
+  }
+
+  // Even the most aggressive config exceeded the budget (extreme image): give
+  // the smallest preview we made, flagged, plus the original path.
+  if (smallest) {
+    return imageBlock(smallest, 'image/webp', `Inline preview (WebP q${smallestCfg.quality}, best effort -- may exceed the client size cap). Full-quality original is at: ${p}`);
+  }
+  return note(`Image too large to preview inline. Open it at: ${p}`);
+}

package/src/server.js

@@ -0,0 +1,9 @@
+// packages/mcp-server/src/server.js
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerTools } from './tools.js';
+
+export function createMcpServer(client) {
+  const server = new McpServer({ name: 'simpligen', version: '0.1.0' });
+  registerTools(server, client);
+  return server;
+}

package/src/tools.js

@@ -0,0 +1,96 @@
+// 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', 'get_job', 'wait_for_result', 'list_jobs',
+  'cancel_job', 'prepare_preset', 'get_result_image',
+];
+
+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)'),
+        options: z.object({ resolution: z.string().optional(), durationSeconds: z.number().optional(), steps: z.number().optional(), cfg: z.number().optional(), seed: z.number().optional() }).optional(),
+      },
+    },
+    wrap((args) => client.generate(args)));
+
+  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);
+      }
+    });
+}

package/src/userdata.js

@@ -0,0 +1,33 @@
+// packages/mcp-server/src/userdata.js
+// Resolve the SimpliGen App's userData dir (this runs as a standalone Node
+// process, not Electron) and read the control-API discovery file for the port.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+// env defaults to process.env, platform to process.platform; passed in for tests.
+export function resolveUserDataDir(env = process.env, platform = process.platform) {
+  if (env.SIMPLIGEN_USERDATA_DIR) return env.SIMPLIGEN_USERDATA_DIR;
+  const name = env.SIMPLIGEN_APP_NAME || 'simpligen';
+  if (platform === 'win32') {
+    const appData = env.APPDATA || path.join(env.USERPROFILE || os.homedir(), 'AppData', 'Roaming');
+    return path.join(appData, name);
+  }
+  if (platform === 'darwin') {
+    // Electron derives userData from app.getName(), which returns the App's
+    // package.json `name` ("simpligen", lowercase) -- there is no productName
+    // or app.setName() at runtime, so the dir is lowercase on macOS too.
+    return path.join(env.HOME || os.homedir(), 'Library', 'Application Support', name);
+  }
+  return path.join(env.HOME || os.homedir(), '.config', name);
+}
+
+export function readDiscoveryPort(userDataDir) {
+  try {
+    const raw = fs.readFileSync(path.join(userDataDir, 'agent-api.json'), 'utf8');
+    const port = JSON.parse(raw).port;
+    return Number.isInteger(port) ? port : null;
+  } catch {
+    return null;
+  }
+}