mcp-duojie-image 0.5.5 → 0.5.7

package/README.md

@@ -1,169 +1,118 @@
-# mcp-duojie-image
-
-MCP server for image generation via duojie.games API (Gemini Flash Image).
-
-## Features
-
-- **Text-to-image generation** — generate images from prompts with configurable size and aspect ratio
-- **Reference image support** — provide local image files as visual references (auto-compressed to 1024px long-side)
-- **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
-
-## Installation
-
-```bash
-npx mcp-duojie-image
-```
-
-Or with a specific version:
-
-```bash
-npx mcp-duojie-image@0.1.3
-```
-
-## Configuration
-
-Set the `DUOJIE_API_KEY` environment variable:
-
-```bash
-export DUOJIE_API_KEY=sk-your-key-here
-```
-
-Or configure in your MCP client (e.g., Claude Desktop, Factory):
-
-```json
-{
-  "mcpServers": {
-    "duojie-image": {
-      "command": "node",
-      "args": ["/path/to/mcp-duojie-image/dist/index.js"],
-      "env": {
-        "DUOJIE_API_KEY": "sk-your-key-here"
-      }
-    }
-  }
-}
-```
-
-Optional environment variables:
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `DUOJIE_API_KEY` | (required) | API key |
-| `DUOJIE_BASE_URL` | `https://api.duojie.ai/v1` | API endpoint |
-| `DUOJIE_MODEL` | `gemini-2.0-flash-exp-image-generation` | Model to use |
-
-## Tools
-
-### `generate_image`
-
-Generate an image and save it to disk.
-
-**Required parameters:**
-- `prompt` (string) — Image description
-- `output_dir` (string) — Output directory (absolute path)
-- `output_filename` (string) — Output filename (no extension needed)
-
-**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"`
-- `format` (string) — Output format. Default: `"png"`
-- `model` (string) — Model override
-- `overwrite` (boolean) — Overwrite existing file. Default: `false` (auto-increments filename)
-- `negative_prompt` (string) — What to avoid in the image
-- `async_mode` (boolean) — When `true`, returns `task_id` immediately and generates in background. **Recommended when using `reference_images`** to avoid MCP client timeout. Default: `false`
-
-**Response (sync mode):**
-```json
-{ "success": true, "saved_path": "/absolute/path/to/image.png", "model": "gemini-..." }
-```
-
-**Response (async mode):**
-```json
-{ "task_id": "uuid", "status": "pending" }
-```
-
-### `check_image_task`
-
-Check the status of an async image generation task.
-
-**Required parameters:**
-- `task_id` (string) — Task ID returned by `generate_image` with `async_mode: true`
-
-**Polling workflow:**
-1. Call `generate_image` with `async_mode: true` → get `task_id`
-2. Call `check_image_task` with `task_id` every few seconds
-3. When `status` is `"done"`, retrieve `saved_path` from the response
-4. If `status` is `"failed"`, check `error` and `message` fields
-
-**Response:**
-```json
-{ "task_id": "uuid", "status": "done", "saved_path": "/path/to/image.png", "model": "gemini-..." }
-```
-
-## Usage Examples
-
-### 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)
-
-```
-generate_image(
-  prompt="Same style as reference, but with mountains instead",
-  reference_images=["/path/to/reference.png"],
-  output_dir="/tmp/images",
-  output_filename="mountain_scene",
-  async_mode=true
-)
-→ { "task_id": "abc-123", "status": "pending" }
-
-check_image_task(task_id="abc-123")
-→ { "status": "running" }  # poll again
-
-check_image_task(task_id="abc-123")
-→ { "status": "done", "saved_path": "/tmp/images/mountain_scene.png" }
-```
-
-## Development
-
-```bash
-# Install dependencies
-npm install
-
-# Build
-npm run build
-
-# Run tests
-npm test
-
-# Type check / lint
-npm run lint
-```
-
-## Architecture
-
-```
-src/
-  index.ts       — MCP server, tool registration (generate_image, check_image_task)
-  provider.ts    — HTTP client for image generation API
-  resizer.ts     — Reference image compression (jimp, max 1024px long-side)
-  task-queue.ts  — In-memory async task state machine (pending→running→done/failed, 30min TTL)
-  config.ts      — Environment variable loading
-  saver.ts       — File saving with conflict handling
-  errors.ts      — Error codes (E_CONFIG_MISSING_KEY, E_PROVIDER_AUTH, etc.)
-```
-
-## License
-
-MIT
+# mcp-duojie-image
+
+MCP server for image generation via duojie.games GPT image API.
+
+## Features
+
+- Text-to-image generation with `gpt-image-2`
+- Reference image editing via local image paths
+- Async submission with task status lookup
+- File saving with overwrite/conflict handling
+- Verified size templates for `1K`, `2K`, and `4K`
+
+## Configuration
+
+Required:
+
+| Variable | Default | Description |
+|---|---|---|
+| `DUOJIE_API_KEY` | required | duojie.games API key |
+| `DUOJIE_BASE_URL` | `https://api.duojie.games` | API base URL |
+| `DUOJIE_IMAGE_MODEL` | `gpt-image-2` | Optional; only `gpt-image-2` is supported |
+
+## Tool: `generate_image`
+
+Generates an image asynchronously and saves it to disk.
+
+Required parameters:
+
+| Parameter | Type | Description |
+|---|---|---|
+| `prompt` | string | Image prompt |
+| `output_dir` | string | Absolute output directory |
+| `output_filename` | string | Filename without extension |
+| `model` | `gpt-image-2` | Only supported model |
+
+Optional parameters:
+
+| Parameter | Type | Default | Description |
+|---|---|---:|---|
+| `size` | `1K` \| `2K` \| `4K` | `1K` | Output size tier |
+| `aspect_ratio` | `1:1` \| `3:2` \| `2:3` \| `16:9` \| `9:16` | `1:1` | Verified ratio template |
+| `reference_images` | string[] | - | Local reference image paths |
+| `format` | string | `png` | Output format |
+| `overwrite` | boolean | `false` | Overwrite existing file |
+| `negative_prompt` | string | - | Content to avoid |
+| `silent` | boolean | `false` | Disable desktop notification |
+
+Response:
+
+```json
+{
+  "success": true,
+  "status": "submitted",
+  "task_id": "uuid",
+  "message": "已提交异步生成；如需诊断失败原因，可调用 check_image_task"
+}
+```
+
+## Tool: `check_image_task`
+
+Checks async task status and failure details.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `task_id` | string | Task id returned by `generate_image` |
+
+Done response:
+
+```json
+{
+  "success": true,
+  "task_id": "uuid",
+  "status": "done",
+  "saved_path": "D:/images/output.png",
+  "model": "gpt-image-2"
+}
+```
+
+Failed response:
+
+```json
+{
+  "success": false,
+  "task_id": "uuid",
+  "status": "failed",
+  "error": "E_PROVIDER_BAD_REQUEST",
+  "message": "Upstream error details"
+}
+```
+
+## Verified GPT size templates
+
+These templates were tested directly against `/v1/images/generations`; all returned the requested dimensions.
+
+| `size` | `1:1` | `3:2` | `2:3` | `16:9` | `9:16` |
+|---|---:|---:|---:|---:|---:|
+| `1K` | `1024x1024` | `1536x1024` | `1024x1536` | `1792x1024` | `1024x1792` |
+| `2K` | `2048x2048` | `2304x1536` | `1536x2304` | `2560x1440` | `1440x2560` |
+| `4K` | `2880x2880` | `3456x2304` | `2304x3456` | `3840x2160` | `2160x3840` |
+
+`512px` is intentionally unsupported because direct API testing returned `Invalid size ... below the current minimum pixel budget`.
+
+## Example
+
+```text
+generate_image(
+  prompt="A futuristic city at sunset",
+  model="gpt-image-2",
+  size="2K",
+  aspect_ratio="16:9",
+  output_dir="D:/ai-images",
+  output_filename="city_sunset"
+)
+```
+
+```text
+check_image_task(task_id="uuid")
+```

package/dist/config.js

@@ -9,10 +9,14 @@ export function loadConfig(overrides) {
     if (!apiKey) {
         throw new AppError("E_CONFIG_MISSING_KEY", "DUOJIE_API_KEY is not set");
     }
+    const model = overrides?.model ?? process.env.DUOJIE_IMAGE_MODEL ?? "gpt-image-2";
+    if (model !== "gpt-image-2") {
+        throw new AppError("E_INPUT_INVALID", "Only gpt-image-2 is supported");
+    }
     return {
         apiKey,
         baseUrl: overrides?.baseUrl ?? process.env.DUOJIE_BASE_URL ?? "https://api.duojie.games",
-        model: overrides?.model ?? process.env.DUOJIE_IMAGE_MODEL ?? "gemini-3.1-flash-image",
+        model,
         timeoutMs: 300_000,
     };
 }

package/dist/index.js

@@ -4,9 +4,10 @@ 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, IMAGE_SIZES, generateImage } from "./provider.js";
 import { saveImage } from "./saver.js";
 import { AppError } from "./errors.js";
+import { createTask, getTask, updateTask } from "./task-queue.js";
 const require = createRequire(import.meta.url);
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const notifier = require("node-notifier");
@@ -18,6 +19,14 @@ function notify(title, message) {
         // 系统通知失败时静默忽略
     }
 }
+function toolText(data) {
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify(data),
+            }],
+    };
+}
 const server = new McpServer({
     name: "duojie-image",
     version: "0.1.0",
@@ -29,10 +38,10 @@ server.registerTool("generate_image", {
         output_dir: z.string().describe("Absolute output dir"),
         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"),
+        size: z.enum(IMAGE_SIZES).optional().describe("Default 1K. Supported: 1K, 2K, 4K"),
+        aspect_ratio: z.enum(ASPECT_RATIOS).optional().describe("Supported: 1:1, 3:2, 2:3, 16:9, 9:16"),
         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"),
+        model: z.enum(["gpt-image-2"]).describe("Required; only gpt-image-2 is supported"),
         overwrite: z.boolean().optional().describe("Default false"),
         negative_prompt: z.string().optional().describe("Avoid"),
         silent: z.boolean().optional().describe("No notification"),
@@ -47,9 +56,11 @@ server.registerTool("generate_image", {
         return { content: [{ type: "text", text: JSON.stringify({ success: false, error: code, message: String(err instanceof Error ? err.message : err) }) }], isError: true };
     }
     const silent = args.silent ?? false;
+    const task = createTask();
     // Start background generation (don't await)
     (async () => {
         try {
+            updateTask(task.id, { status: "running", startedAt: Date.now() });
             const imageBuffer = await generateImage(config, {
                 prompt: args.prompt,
                 referenceImages: args.reference_images,
@@ -64,9 +75,15 @@ server.registerTool("generate_image", {
                 format: args.format ?? "png",
                 overwrite: args.overwrite ?? false,
             });
+            updateTask(task.id, {
+                status: "done",
+                completedAt: Date.now(),
+                savedPath,
+                model: args.model,
+            });
             await server.sendLoggingMessage({
                 level: "info",
-                data: `图片生成完成：${savedPath}`,
+                data: `图片生成完成 [${task.id}]：${savedPath}`,
             });
             if (!silent)
                 notify("图片生成完成", savedPath);
@@ -74,9 +91,15 @@ server.registerTool("generate_image", {
         catch (err) {
             const code = err instanceof AppError ? err.code : "E_INTERNAL";
             const msg = err instanceof Error ? err.message : String(err);
+            updateTask(task.id, {
+                status: "failed",
+                completedAt: Date.now(),
+                errorCode: code,
+                error: msg,
+            });
             await server.sendLoggingMessage({
                 level: "error",
-                data: `图片生成失败 [${code}]: ${msg}`,
+                data: `图片生成失败 [${task.id}] [${code}]: ${msg}`,
             }).catch(() => { });
             if (!silent) {
                 if (code === "E_PROVIDER_TIMEOUT") {
@@ -94,10 +117,43 @@ server.registerTool("generate_image", {
                 text: JSON.stringify({
                     success: true,
                     status: "submitted",
-                    message: `已提交异步生成：${args.output_filename}；无需等待或检查结果`,
+                    task_id: task.id,
+                    message: `已提交异步生成：${args.output_filename}；如需诊断失败原因，可调用 check_image_task`,
                 }),
             }],
     };
 });
+server.registerTool("check_image_task", {
+    description: "Check an async image generation task status and failure details.",
+    inputSchema: z.object({
+        task_id: z.string().min(1).describe("Task id returned by generate_image"),
+    }),
+}, async (args) => {
+    const task = getTask(args.task_id);
+    if (!task) {
+        return {
+            ...toolText({
+                success: false,
+                error: "E_TASK_NOT_FOUND",
+                message: `Task ${args.task_id} not found. It may have expired or never existed.`,
+            }),
+            isError: true,
+        };
+    }
+    const response = {
+        success: task.status !== "failed",
+        task_id: task.id,
+        status: task.status,
+    };
+    if (task.status === "done") {
+        response.saved_path = task.savedPath;
+        response.model = task.model;
+    }
+    if (task.status === "failed") {
+        response.error = task.errorCode;
+        response.message = task.error;
+    }
+    return toolText(response);
+});
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/provider.js

@@ -1,5 +1,7 @@
 import { AppError } from "./errors.js";
 import { resizeIfNeeded } from "./resizer.js";
+export const ASPECT_RATIOS = ["1:1", "3:2", "2:3", "16:9", "9:16"];
+export const IMAGE_SIZES = ["1K", "2K", "4K"];
 async function fetchWithRetry(url, init, timeoutMs, retries = 0) {
     let lastErr;
     for (let attempt = 0; attempt <= retries; attempt++) {
@@ -24,81 +26,34 @@ async function fetchWithRetry(url, init, timeoutMs, retries = 0) {
     }
     throw new AppError("E_PROVIDER_BAD_REQUEST", `Network error: ${lastErr}`);
 }
-async function buildParts(opts) {
-    const { prompt, referenceImages, negativePrompt } = opts;
-    const fullPrompt = negativePrompt ? `${prompt}\n\nAvoid: ${negativePrompt}` : prompt;
-    const parts = [];
-    if (referenceImages && referenceImages.length > 0) {
-        const imageParts = await Promise.all(referenceImages.map(async (imgPath) => {
-            const data = await resizeIfNeeded(imgPath);
-            return { inlineData: { mimeType: "image/png", data: data.toString("base64") } };
-        }));
-        parts.push(...imageParts);
-    }
-    parts.push({ text: fullPrompt });
-    return parts;
-}
-function mapSize(size) {
-    if (size === "512px")
-        return "512";
-    return size; // "1K", "2K", "4K" are used as-is
-}
-function isOpenAIImageModel(model) {
-    return model === "gpt-image-2";
-}
-function normalizeAspectRatio(aspectRatio) {
-    const normalized = aspectRatio?.trim().replace("：", ":").replace(/\s+/g, "");
-    const match = normalized?.match(/^(\d+(?:\.\d+)?):(\d+(?:\.\d+)?)$/);
-    if (!match)
-        return undefined;
-    const width = Number(match[1]);
-    const height = Number(match[2]);
-    if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
-        return undefined;
-    }
-    return `${match[1]}:${match[2]}`;
-}
-function parseAspectRatio(aspectRatio) {
-    const normalized = normalizeAspectRatio(aspectRatio);
-    const match = normalized?.match(/^(\d+(?:\.\d+)?):(\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}`;
-}
+const GPT_IMAGE_MODEL = "gpt-image-2";
+const SIZE_TEMPLATES = {
+    "1K": {
+        "1:1": "1024x1024",
+        "3:2": "1536x1024",
+        "2:3": "1024x1536",
+        "16:9": "1792x1024",
+        "9:16": "1024x1792",
+    },
+    "2K": {
+        "1:1": "2048x2048",
+        "3:2": "2304x1536",
+        "2:3": "1536x2304",
+        "16:9": "2560x1440",
+        "9:16": "1440x2560",
+    },
+    "4K": {
+        "1:1": "2880x2880",
+        "3:2": "3456x2304",
+        "2:3": "2304x3456",
+        "16:9": "3840x2160",
+        "9:16": "2160x3840",
+    },
+};
 function mapOpenAISize(size, aspectRatio) {
-    const squareBySize = {
-        "512px": "512x512",
-        "1K": "1024x1024",
-        "2K": "2048x2048",
-    };
-    if (size === "4K")
-        return mapOpenAI4KSize(aspectRatio);
-    const [ratioWidth, ratioHeight] = parseAspectRatio(aspectRatio);
-    if (ratioWidth > ratioHeight) {
-        return size === "2K" ? "2048x1536" : "1536x1024";
-    }
-    if (ratioHeight > ratioWidth) {
-        return size === "2K" ? "1536x2048" : "1024x1536";
-    }
-    return squareBySize[size] ?? "1024x1024";
+    const imageSize = size ?? "1K";
+    const ratio = aspectRatio ?? "1:1";
+    return SIZE_TEMPLATES[imageSize][ratio];
 }
 async function imageFromOpenAIResponse(res) {
     const data = (await res.json());
@@ -125,46 +80,10 @@ async function handleProviderError(res) {
     const text = await res.text().catch(() => "");
     throw new AppError("E_PROVIDER_BAD_REQUEST", `Upstream error ${res.status}: ${text.slice(0, 200)}`);
 }
-async function generateGeminiImage(config, opts) {
-    const parts = await buildParts(opts);
-    const model = opts.model ?? config.model;
-    const imageConfig = {
-        imageSize: mapSize(opts.size ?? "1K"),
-    };
-    if (opts.aspectRatio) {
-        imageConfig.aspectRatio = opts.aspectRatio;
-    }
-    const body = JSON.stringify({
-        contents: [{ role: "user", parts }],
-        generationConfig: {
-            responseModalities: ["IMAGE"],
-            imageConfig,
-        },
-    });
-    const url = `${config.baseUrl}/v1beta/models/${model}:generateContent`;
-    const res = await fetchWithRetry(url, {
-        method: "POST",
-        headers: {
-            "x-goog-api-key": config.apiKey,
-            "Content-Type": "application/json",
-        },
-        body,
-    }, config.timeoutMs);
-    if (!res.ok) {
-        await handleProviderError(res);
-    }
-    const data = (await res.json());
-    const imagePart = data.candidates?.[0]?.content?.parts?.find((p) => p.inlineData);
-    if (!imagePart?.inlineData?.data) {
-        throw new AppError("E_PROVIDER_BAD_REQUEST", "No image in response");
-    }
-    return Buffer.from(imagePart.inlineData.data, "base64");
-}
 async function generateOpenAIImage(config, opts) {
     const model = opts.model ?? config.model;
     const prompt = opts.negativePrompt ? `${opts.prompt}\n\nAvoid: ${opts.negativePrompt}` : opts.prompt;
-    const aspectRatio = normalizeAspectRatio(opts.aspectRatio);
-    const size = mapOpenAISize(opts.size ?? "1K", aspectRatio);
+    const size = mapOpenAISize(opts.size, opts.aspectRatio);
     const hasReferenceImages = Boolean(opts.referenceImages?.length);
     const url = `${config.baseUrl}${hasReferenceImages ? "/v1/images/edits" : "/v1/images/generations"}`;
     let body;
@@ -176,8 +95,8 @@ async function generateOpenAIImage(config, opts) {
         form.set("model", model);
         form.set("prompt", prompt);
         form.set("size", size);
-        if (aspectRatio) {
-            form.set("aspect_ratio", aspectRatio);
+        if (opts.aspectRatio) {
+            form.set("aspect_ratio", opts.aspectRatio);
         }
         for (const [index, imgPath] of opts.referenceImages.entries()) {
             const data = await resizeIfNeeded(imgPath);
@@ -188,7 +107,12 @@ async function generateOpenAIImage(config, opts) {
     }
     else {
         headers = { ...headers, "Content-Type": "application/json" };
-        body = JSON.stringify({ model, prompt, size, ...(aspectRatio ? { aspect_ratio: aspectRatio } : {}) });
+        body = JSON.stringify({
+            model,
+            prompt,
+            size,
+            ...(opts.aspectRatio ? { aspect_ratio: opts.aspectRatio } : {}),
+        });
     }
     const res = await fetchWithRetry(url, {
         method: "POST",
@@ -202,8 +126,8 @@ async function generateOpenAIImage(config, opts) {
 }
 export async function generateImage(config, opts) {
     const model = opts.model ?? config.model;
-    if (isOpenAIImageModel(model)) {
-        return generateOpenAIImage(config, opts);
+    if (model !== GPT_IMAGE_MODEL) {
+        throw new AppError("E_PROVIDER_BAD_REQUEST", `Unsupported model: ${model}`);
     }
-    return generateGeminiImage(config, opts);
+    return generateOpenAIImage(config, opts);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-duojie-image",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "MCP server for image generation via duojie.games",
   "type": "module",
   "main": "dist/index.js",
@@ -18,7 +18,8 @@
   "keywords": [
     "mcp",
     "image-generation",
-    "gemini",
+    "gpt",
+    "openai",
     "ai"
   ],
   "author": "",