@falldownthesystem/imagen-mcp 0.2.0 → 0.3.0

package/README.md

@@ -1,10 +1,10 @@
 # imagen-mcp
 
-Minimal MCP server for OpenAI GPT Image 2.5 and Krea 3. Generate and edit tools for each provider.
+Minimal MCP server for OpenAI GPT Image 2.6 and Krea 3. Generate and edit tools for each provider.
 
 | Provider | Tools | Models |
 |---|---|---|
-| OpenAI | `generate_image`, `edit_image` | `flare` (default, `gpt-image-2.5-flare`): fast, general purpose. `sunburst` (`gpt-image-2.5-sunburst`): slower, higher precision. |
+| OpenAI | `generate_image`, `edit_image` | `flare` (default, `gpt-image-2.6-flare`): fast, good layouts. `sunburst` (`gpt-image-2.6-sunburst`): more detail, more consistent across edits. |
 | Krea | `krea_generate_image`, `krea_edit_image` | Krea 3: fast, instruction-following editor. Early-access beta. |
 
 The server registers a provider's tools only when that provider's API key is set.
@@ -66,22 +66,26 @@ claude mcp add imagen -e OPENAI_API_KEY=sk-... -e KREA_API_KEY=... -- npx -y @fa
 
 ### `generate_image`
 
-Text to image. Required: `prompt`.
+Text to image, animated GIF, or SVG. Required: `prompt`.
 
 | Option | Values | Default | Notes |
 |---|---|---|---|
+| `output_format` | `png`, `jpeg`, `webp`, `gif`, `svg` | `png` | Also sets the file extension. `gif` is an animation: describe the subject, the motion, and how it loops, and `size` sets each frame. `svg` is a static vector file (paths, shapes, colors); it needs `n` = 1. `gif` and `svg` reject `output_compression`. |
+| `frame_count` | 2 to 16 | 9 | `gif` only. Frames, frame size, and `n` share one pixel budget, so use a small `size` for many frames. |
+| `frame_duration_ms` | 20 to 2000 | 200 | `gif` only. Delay per frame, rounded to 10 ms. |
 | `moderation` | `auto`, `low` | `low` | OpenAI content filter strictness. `low` refuses fewer borderline prompts; OpenAI usage policies still apply. The API default is `auto`; this tool sends `low` unless set. |
 
 ### `edit_image`
 
-Reference images to image. Required: `prompt`, `images`. The model regenerates the whole picture guided by the references and the prompt. Without a mask, the prompt alone decides what changes.
+Reference images to image. Required: `prompt`, `images`. The model regenerates the whole picture guided by the references and the prompt. Without a mask or markup, the prompt alone decides what changes. Output is `png`, `jpeg`, or `webp`; the edit endpoint does not make GIF or SVG.
 
 | Option | Values | Default | Notes |
 |---|---|---|---|
 | `images` | 1 to 16 file paths | required | `png`, `jpeg`, or `webp`. The first image is the main subject; extra images supply elements to combine, such as a logo or a style reference. Relative paths resolve against the server working directory. |
-| `mask` | file path | none | PNG with an alpha channel, same width and height as the first image. Fully transparent pixels mark the region the model may repaint; opaque pixels mark what to keep. Use for inpainting one area or filling an extended canvas. It is guidance, not a hard pixel lock. |
+| `mask` | file path | none | PNG with an alpha channel, same width and height as the first image. Fully transparent pixels mark the region the model may repaint; opaque pixels mark what to keep. Use for inpainting one area or filling an extended canvas. It is guidance, not a hard pixel lock. Cannot be combined with `markup`. |
+| `markup` | file path | none | Transparent PNG annotation layer, same width and height as the first image, at most 50 MB. Draw circles, arrows, or scribbles where the change goes, and say in the prompt what to change and to remove the marks. Applies to the first image; other images stay references. Cannot be combined with `mask`. |
 
-There is no `input_fidelity` option. The GPT Image 2.5 models always process reference images at high fidelity, and the API rejects the parameter. Faces, logos, text, and textures from the references are preserved by default.
+There is no `input_fidelity` option. The GPT Image 2.6 models always process reference images at high fidelity, and the API rejects the parameter. Faces, logos, text, and textures from the references are preserved by default.
 
 ### Shared options
 
@@ -90,18 +94,19 @@ Only the options you set are sent to the API. The default column shows what appl
 | Option | Values | Default | Notes |
 |---|---|---|---|
 | `prompt` | text, up to 32000 chars | required | |
-| `model` | `flare`, `sunburst` | `flare` | `flare` (`gpt-image-2.5-flare`) is fast and general purpose. `sunburst` (`gpt-image-2.5-sunburst`) is slower with higher precision. Same token price. `IMAGEN_DEFAULT_MODEL` env changes the default. |
+| `model` | `flare`, `sunburst` | `flare` | `flare` (`gpt-image-2.6-flare`) is fast and lays out posters and product shots well. `sunburst` (`gpt-image-2.6-sunburst`) gives more detail and keeps characters and products more consistent across edits at `medium` or `high` quality. Same token price. `IMAGEN_DEFAULT_MODEL` env changes the default. |
 | `size` | `auto`, `1024x1024`, `1536x1024`, `1024x1536`, `WIDTHxHEIGHT` | `auto` | Custom sizes: multiples of 16, ratio 1:3 to 3:1, long edge up to 3840. Overrides `aspect_ratio`. |
 | `aspect_ratio` | `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `16:9`, `9:16`, `21:9`, `9:21` | none | Combined with `long_edge` to compute a size. |
 | `long_edge` | 256 to 3840 | 1536 | Only used with `aspect_ratio`. |
 | `quality` | `low`, `medium`, `high`, `xhigh`, `max`, `auto` | `auto` | Higher tiers add detail and cost more output tokens. `auto` lets the model choose and may pick an expensive tier. Set it explicitly to control cost. |
+| `complexity` | `low`, `medium`, `high` | `high` | How much the model plans the scene before it renders. Separate from `quality`, no extra fee. `low` is faster and suits focused edits such as a new background or sign. `high` helps with dense text, complex layouts, and many objects, but can add latency and unwanted changes. |
 | `background` | `transparent`, `opaque`, `auto` | `auto` | `transparent` gives an alpha background for stickers, logos, and cut-outs. Needs `png` or `webp`. |
-| `output_format` | `png`, `jpeg`, `webp` | `png` | Also sets the file extension. |
+| `output_format` | `png`, `jpeg`, `webp` | `png` | Also sets the file extension. `generate_image` also takes `gif` and `svg`. |
 | `output_compression` | 0 to 100 | 100 | `jpeg` and `webp` only. Works like JPEG quality: lower is smaller with more artifacts. |
 | `n` | 1 to 10 | 1 | Number of separate variations generated from the same prompt in one call. Each costs its own output tokens. |
 | `output_dir` | directory path | `IMAGEN_OUTPUT_DIR` env, else `./output` | Relative to the server working directory. |
 | `file_name` | base name without extension | timestamp plus a slug of the prompt | With `n` greater than 1, a `-1`, `-2` suffix is added. |
-| `return_image` | boolean | `false` | Also return each image inline as MCP image content, so the client shows it and the model can inspect it. Adds about 1.4 MB of context per 1024x1024 png. The file is saved to disk either way. |
+| `return_image` | boolean | `false` | Also return each image inline as MCP image content, so the client shows it and the model can inspect it. Adds about 1.4 MB of context per 1024x1024 png. SVG files are never returned inline. The file is saved to disk either way. |
 
 The result lists the saved file paths, the model, the size, and token usage.
 

package/dist/index.js

@@ -17,7 +17,7 @@ if (!openaiKey && !kreaKey) {
     console.error("imagen-mcp: set OPENAI_API_KEY, KREA_API_KEY, or both.");
     process.exit(1);
 }
-const server = new McpServer({ name: "imagen-mcp", version: "0.2.0" });
+const server = new McpServer({ name: "imagen-mcp", version: "0.3.0" });
 // Tools are registered per configured provider so clients never see a tool that can only fail.
 if (openaiKey)
     registerOpenAITools(server);

package/dist/openai.js

@@ -18,20 +18,51 @@ const outputSchema = z.object({
     })
         .optional(),
 });
+const generateInput = {
+    ...commonInput,
+    output_format: z
+        .enum(["png", "jpeg", "webp", "gif", "svg"])
+        .optional()
+        .describe("Also the file extension. gif = animation (size is per frame). svg = static vector (n must be 1). gif/svg ignore output_compression. Default png."),
+    frame_count: z.number().int().min(2).max(16).optional().describe("gif only: frames per animation. Keep size small for many frames. Default 9."),
+    frame_duration_ms: z
+        .number()
+        .int()
+        .min(20)
+        .max(2000)
+        .optional()
+        .describe("gif only: delay per frame in ms, rounded to 10. Default 200."),
+    moderation: z
+        .enum(["auto", "low"])
+        .optional()
+        .describe("OpenAI content filter. low refuses fewer borderline prompts. Default low."),
+};
 function apiParams(input) {
     return {
         model: resolveModel(input.model),
         prompt: input.prompt,
         size: resolveSize(input),
         quality: input.quality,
+        complexity: input.complexity,
         background: input.background,
-        output_format: input.output_format,
         output_compression: input.output_compression,
         n: input.n,
     };
 }
-function saveResult(result, input, model, size) {
-    const ext = input.output_format ?? "png";
+// The API rejects these combinations, so fail before spending a request on them.
+function checkGenerateFormat(input) {
+    const format = input.output_format ?? "png";
+    if (format !== "gif" && (input.frame_count !== undefined || input.frame_duration_ms !== undefined)) {
+        throw new Error("frame_count and frame_duration_ms need output_format gif.");
+    }
+    if ((format === "gif" || format === "svg") && input.output_compression !== undefined) {
+        throw new Error(`output_compression is not supported with output_format ${format}.`);
+    }
+    if (format === "svg" && (input.n ?? 1) !== 1) {
+        throw new Error("output_format svg needs n = 1.");
+    }
+}
+function saveResult(result, input, ext, model, size) {
     const images = (result.data ?? []).map((image, i) => {
         if (!image.b64_json)
             throw new Error(`Image ${i + 1} has no b64_json payload.`);
@@ -49,24 +80,25 @@ export function registerOpenAITools(server) {
     const client = new OpenAI();
     server.registerTool("generate_image", {
         title: "Generate image",
-        description: "Generate images from a text prompt with OpenAI GPT Image 2.5. Saves files to disk and returns paths and token usage.",
-        inputSchema: z.object({
-            ...commonInput,
-            moderation: z
-                .enum(["auto", "low"])
-                .optional()
-                .describe("OpenAI content filter. low refuses fewer borderline prompts. Default low."),
-        }),
+        description: "Generate images, animated GIFs, or SVG vector graphics from a text prompt with OpenAI GPT Image 2.6. For a GIF, describe the subject, the motion, and how it loops. Saves files to disk and returns paths and token usage.",
+        inputSchema: z.object(generateInput),
         outputSchema,
         annotations,
     }, async (input) => {
+        checkGenerateFormat(input);
         const params = apiParams(input);
-        const result = await client.images.generate({ ...params, moderation: input.moderation ?? "low" });
-        return saveResult(result, input, params.model, params.size);
+        const result = await client.images.generate({
+            ...params,
+            output_format: input.output_format,
+            frame_count: input.frame_count,
+            frame_duration_ms: input.frame_duration_ms,
+            moderation: input.moderation ?? "low",
+        });
+        return saveResult(result, input, input.output_format ?? "png", params.model, params.size);
     });
     server.registerTool("edit_image", {
         title: "Edit image",
-        description: "Edit, restyle, or combine 1-16 reference images with a text prompt using OpenAI GPT Image 2.5. The whole picture is regenerated; without a mask the prompt decides what changes. Reference details are always kept at high fidelity (no input_fidelity option). Saves files to disk and returns paths and token usage.",
+        description: "Edit, restyle, or combine 1-16 reference images with a text prompt using OpenAI GPT Image 2.6. The whole picture is regenerated; without a mask or markup the prompt decides what changes. Reference details are always kept at high fidelity (no input_fidelity option). Output is png, jpeg, or webp only. Saves files to disk and returns paths and token usage.",
         inputSchema: z.object({
             ...commonInput,
             images: z
@@ -77,17 +109,25 @@ export function registerOpenAITools(server) {
             mask: z
                 .string()
                 .optional()
-                .describe("Path of a PNG with alpha, same size as first image. Transparent pixels = region to repaint (guidance, not a hard lock). Default none."),
+                .describe("Path of a PNG with alpha, same size as first image. Transparent pixels = region to repaint (guidance, not a hard lock). Not with markup. Default none."),
+            markup: z
+                .string()
+                .optional()
+                .describe("Path of a transparent PNG annotation layer, same size as first image, with circles, arrows, or scribbles that mark where to change. The prompt says what to change and to remove the marks. Max 50 MB. Not with mask. Default none."),
         }),
         outputSchema,
         annotations,
     }, async (input) => {
+        if (input.mask && input.markup)
+            throw new Error("Use mask or markup, not both.");
         const params = apiParams(input);
         const result = await client.images.edit({
             ...params,
+            output_format: input.output_format,
             image: await Promise.all(input.images.map(loadImage)),
             mask: input.mask ? await loadImage(input.mask) : undefined,
+            markup: input.markup ? await loadImage(input.markup) : undefined,
         });
-        return saveResult(result, input, params.model, params.size);
+        return saveResult(result, input, input.output_format ?? "png", params.model, params.size);
     });
 }

package/dist/output.js

@@ -1,7 +1,8 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import * as z from "zod/v4";
-export const MIME = { png: "image/png", jpeg: "image/jpeg", webp: "image/webp" };
+// svg is left out on purpose: MCP image content is raster, so saved SVGs are returned as file paths only.
+export const MIME = { png: "image/png", jpeg: "image/jpeg", webp: "image/webp", gif: "image/gif" };
 export const outputInput = {
     output_dir: z.string().optional().describe("Save directory. Default IMAGEN_OUTPUT_DIR env or ./output (relative to server cwd)."),
     file_name: z.string().optional().describe("Base name without extension. Default timestamp + prompt slug."),

package/dist/params.js

@@ -1,8 +1,8 @@
 import * as z from "zod/v4";
 import { outputInput } from "./output.js";
 export const MODELS = {
-    flare: "gpt-image-2.5-flare",
-    sunburst: "gpt-image-2.5-sunburst",
+    flare: "gpt-image-2.6-flare",
+    sunburst: "gpt-image-2.6-sunburst",
 };
 const ASPECT_RATIOS = {
     "1:1": 1,
@@ -29,7 +29,7 @@ export const commonInput = {
     model: z
         .enum(["flare", "sunburst"])
         .optional()
-        .describe("flare = fast, general purpose. sunburst = slower, higher precision. Same price. Default flare."),
+        .describe("flare = fast, good layouts. sunburst = more detail, more consistent across edits at medium/high quality. Same price. Default flare."),
     size: z
         .string()
         .regex(/^(auto|\d+x\d+)$/)
@@ -50,6 +50,10 @@ export const commonInput = {
         .enum(["low", "medium", "high", "xhigh", "max", "auto"])
         .optional()
         .describe("Higher = more detail, more output tokens. auto lets the model choose (may be costly). Default auto."),
+    complexity: z
+        .enum(["low", "medium", "high"])
+        .optional()
+        .describe("How much the model plans the scene before rendering; separate from quality, no extra fee. low = faster, suits focused edits. high = dense text, complex layouts, many objects. Default high."),
     background: z
         .enum(["transparent", "opaque", "auto"])
         .optional()

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@falldownthesystem/imagen-mcp",
-	"version": "0.2.0",
-	"description": "Minimal MCP server for OpenAI GPT Image 2.5 (flare and sunburst) and Krea 3: generate and edit images",
+	"version": "0.3.0",
+	"description": "Minimal MCP server for OpenAI GPT Image 2.6 (flare and sunburst) and Krea 3: generate and edit images",
 	"type": "module",
 	"bin": {
 		"imagen-mcp": "dist/index.js"
@@ -38,7 +38,7 @@
 	},
 	"dependencies": {
 		"@modelcontextprotocol/server": "^2.3.1",
-		"openai": "^7.34.0",
+		"openai": "^7.51.0",
 		"zod": "^4.6.7"
 	},
 	"devDependencies": {