mcp-duojie-image 0.5.4 → 0.5.6

package/README.md

@@ -9,7 +9,7 @@ MCP server for image generation via duojie.games API (Gemini Flash Image).
 - **Async mode** — for long-running generations (especially with reference images), use `async_mode: true` to get a `task_id` immediately and poll for completion; prevents MCP client timeout
 - **Sync mode** — for simple text-to-image generation without reference images, the default sync mode returns the result directly
 - **File saving** — automatic output directory creation, conflict handling (`overwrite` flag, auto-incrementing filename suffix)
-- **Configurable output** — size (512px/1K/2K/4K), aspect ratio, format
+- **Configurable output** — size (512px/1K/2K/4K), templated aspect ratio, format
 
 ## Installation
 
@@ -69,7 +69,7 @@ Generate an image and save it to disk.
 **Optional parameters:**
 - `reference_images` (string[]) — Local image paths for reference. Images are auto-compressed to max 1024px long-side before sending to API.
 - `size` ("512px" | "1K" | "2K" | "4K") — Output image size. Default: `1K`
-- `aspect_ratio` (string) — e.g., `"16:9"`, `"1:1"`
+- `aspect_ratio` (`"1:1"` | `"3:2"` | `"2:3"`) — Templated aspect ratio. Default: `"1:1"` for GPT image models
 - `format` (string) — Output format. Default: `"png"`
 - `model` (string) — Model override
 - `overwrite` (boolean) — Overwrite existing file. Default: `false` (auto-increments filename)
@@ -106,17 +106,27 @@ Check the status of an async image generation task.
 
 ## Usage Examples
 
-### Simple text-to-image (sync)
+### Simple text-to-image (sync)
 
 ```
 generate_image(
   prompt="A sunset over the ocean, photorealistic",
   output_dir="/tmp/images",
   output_filename="sunset"
-)
-```
-
-### With reference image (use async_mode to avoid timeout)
+)
+```
+
+### GPT image aspect ratio templates
+
+`gpt-image-2` does not accept free-form aspect ratios through MCP. Use one of these templates; the server converts it to a supported `size` value before calling the image API. For GPT image models, the `size` preset is ignored and the template controls the upstream size.
+
+| `aspect_ratio` | `size` sent upstream |
+|----------------|----------------------|
+| `1:1` | `1024x1024` |
+| `3:2` | `1536x1024` |
+| `2:3` | `1024x1536` |
+
+### With reference image (use async_mode to avoid timeout)
 
 ```
 generate_image(

package/dist/index.js

@@ -4,7 +4,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { createRequire } from "node:module";
 import { loadConfig } from "./config.js";
-import { generateImage } from "./provider.js";
+import { ASPECT_RATIOS, generateImage } from "./provider.js";
 import { saveImage } from "./saver.js";
 import { AppError } from "./errors.js";
 const require = createRequire(import.meta.url);
@@ -30,7 +30,7 @@ server.registerTool("generate_image", {
         output_filename: z.string().describe("Filename without ext"),
         reference_images: z.array(z.string()).optional().describe("Reference image paths"),
         size: z.enum(["512px", "1K", "2K", "4K"]).optional().describe("Default 1K"),
-        aspect_ratio: z.string().optional().describe("e.g. 16:9"),
+        aspect_ratio: z.enum(ASPECT_RATIOS).optional().describe("Aspect ratio template: 1:1, 3:2, or 2:3"),
         format: z.string().optional().describe("Default png"),
         model: z.enum(["gemini-3.1-flash-image", "gpt-image-2"]).describe("Required; ask once per conversation if unknown"),
         overwrite: z.boolean().optional().describe("Default false"),

package/dist/provider.js

@@ -1,5 +1,6 @@
 import { AppError } from "./errors.js";
 import { resizeIfNeeded } from "./resizer.js";
+export const ASPECT_RATIOS = ["1:1", "3:2", "2:3"];
 async function fetchWithRetry(url, init, timeoutMs, retries = 0) {
     let lastErr;
     for (let attempt = 0; attempt <= retries; attempt++) {
@@ -41,50 +42,19 @@ async function buildParts(opts) {
 function mapSize(size) {
     if (size === "512px")
         return "512";
-    return size; // "1K", "2K", "4K" are used as-is
+    return size;
 }
 function isOpenAIImageModel(model) {
     return model === "gpt-image-2";
 }
-function parseAspectRatio(aspectRatio) {
-    const match = aspectRatio?.match(/^(\d+):(\d+)$/);
-    if (!match)
-        return [1, 1];
-    return [Number(match[1]), Number(match[2])];
-}
-function mapOpenAI4KSize(aspectRatio) {
-    const [ratioWidth, ratioHeight] = parseAspectRatio(aspectRatio);
-    const maxPixels = 3840 * 2160;
-    const maxEdge = 3840;
-    let width = Math.floor(Math.sqrt((maxPixels * ratioWidth) / ratioHeight));
-    let height = Math.floor((width * ratioHeight) / ratioWidth);
-    if (width > maxEdge) {
-        width = maxEdge;
-        height = Math.floor((width * ratioHeight) / ratioWidth);
-    }
-    if (height > maxEdge) {
-        height = maxEdge;
-        width = Math.floor((height * ratioWidth) / ratioHeight);
-    }
-    width = Math.floor(width / 8) * 8;
-    height = Math.floor(height / 8) * 8;
-    return `${width}x${height}`;
-}
-function mapOpenAISize(size, aspectRatio) {
-    const squareBySize = {
-        "512px": "512x512",
-        "1K": "1024x1024",
-        "2K": "2048x2048",
+function mapOpenAISize(aspectRatio) {
+    const ratio = aspectRatio ?? "1:1";
+    const sizes = {
+        "1:1": "1024x1024",
+        "3:2": "1536x1024",
+        "2:3": "1024x1536",
     };
-    if (size === "4K")
-        return mapOpenAI4KSize(aspectRatio);
-    if (aspectRatio === "16:9" || aspectRatio === "3:2" || aspectRatio === "4:3") {
-        return size === "2K" ? "2048x1536" : "1536x1024";
-    }
-    if (aspectRatio === "9:16" || aspectRatio === "2:3" || aspectRatio === "3:4") {
-        return size === "2K" ? "1536x2048" : "1024x1536";
-    }
-    return squareBySize[size] ?? "1024x1024";
+    return sizes[ratio];
 }
 async function imageFromOpenAIResponse(res) {
     const data = (await res.json());
@@ -149,7 +119,7 @@ async function generateGeminiImage(config, opts) {
 async function generateOpenAIImage(config, opts) {
     const model = opts.model ?? config.model;
     const prompt = opts.negativePrompt ? `${opts.prompt}\n\nAvoid: ${opts.negativePrompt}` : opts.prompt;
-    const size = mapOpenAISize(opts.size ?? "1K", opts.aspectRatio);
+    const size = mapOpenAISize(opts.aspectRatio);
     const hasReferenceImages = Boolean(opts.referenceImages?.length);
     const url = `${config.baseUrl}${hasReferenceImages ? "/v1/images/edits" : "/v1/images/generations"}`;
     let body;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-duojie-image",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "description": "MCP server for image generation via duojie.games",
   "type": "module",
   "main": "dist/index.js",