mcp-duojie-image 0.5.0 → 0.5.2

package/README.md

@@ -1,169 +1,169 @@
-# 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 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

package/dist/index.js

@@ -23,19 +23,19 @@ const server = new McpServer({
     version: "0.1.0",
 });
 server.registerTool("generate_image", {
-    description: "Generate an image and save to disk. Returns immediately; generation runs in background (60~120s) with system notification on completion.",
+    description: "Generate image async. Ask user to choose model before calling.",
     inputSchema: z.object({
-        prompt: z.string().min(1).describe("Image prompt"),
-        output_dir: z.string().describe("Output directory (absolute path)"),
-        output_filename: z.string().describe("Output filename (no extension needed)"),
-        reference_images: z.array(z.string()).optional().describe("Local image paths for reference"),
-        size: z.enum(["512px", "1K", "2K", "4K"]).optional().describe("Image size, default 1K. Use 512px for thumbnails, 2K/4K only if explicitly requested."),
+        prompt: z.string().min(1).describe("Prompt"),
+        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"),
-        format: z.string().optional().describe("Output format, default png"),
-        model: z.string().optional().describe("Model override"),
-        overwrite: z.boolean().optional().describe("Overwrite existing file, default false"),
-        negative_prompt: z.string().optional().describe("What to avoid"),
-        silent: z.boolean().optional().describe("Suppress system notification on completion. Default false."),
+        format: z.string().optional().describe("Default png"),
+        model: z.enum(["gemini-3.1-flash-image", "gpt-image-2"]).describe("Required"),
+        overwrite: z.boolean().optional().describe("Default false"),
+        negative_prompt: z.string().optional().describe("Avoid"),
+        silent: z.boolean().optional().describe("No notification"),
     }),
 }, async (args) => {
     let config;
@@ -93,7 +93,7 @@ server.registerTool("generate_image", {
                 type: "text",
                 text: JSON.stringify({
                     status: "pending",
-                    message: `开始异步生成 ${args.output_filename}，通常需要等待 60~120s。请耐心等待。任务完成后会有通知。`,
+                    message: `已开始：${args.output_filename}`,
                 }),
             }],
     };

package/dist/provider.js

@@ -43,7 +43,50 @@ function mapSize(size) {
         return "512";
     return size; // "1K", "2K", "4K" are used as-is
 }
-export async function generateImage(config, opts) {
+function isOpenAIImageModel(model) {
+    return model === "gpt-image-2";
+}
+function mapOpenAISize(size, aspectRatio) {
+    const squareBySize = {
+        "512px": "512x512",
+        "1K": "1024x1024",
+        "2K": "2048x2048",
+        "4K": "4096x4096",
+    };
+    if (aspectRatio === "16:9" || aspectRatio === "3:2" || aspectRatio === "4:3") {
+        return size === "2K" ? "2048x1536" : size === "4K" ? "4096x3072" : "1536x1024";
+    }
+    if (aspectRatio === "9:16" || aspectRatio === "2:3" || aspectRatio === "3:4") {
+        return size === "2K" ? "1536x2048" : size === "4K" ? "3072x4096" : "1024x1536";
+    }
+    return squareBySize[size] ?? "1024x1024";
+}
+async function imageFromOpenAIResponse(res) {
+    const data = (await res.json());
+    const image = data.data?.[0];
+    if (image?.b64_json) {
+        return Buffer.from(image.b64_json, "base64");
+    }
+    if (image?.url) {
+        const imgRes = await fetch(image.url);
+        if (!imgRes.ok) {
+            throw new AppError("E_PROVIDER_BAD_REQUEST", `Image URL fetch failed: ${imgRes.status}`);
+        }
+        return Buffer.from(await imgRes.arrayBuffer());
+    }
+    throw new AppError("E_PROVIDER_BAD_REQUEST", "No image in response");
+}
+async function handleProviderError(res) {
+    if (res.status === 401 || res.status === 403) {
+        throw new AppError("E_PROVIDER_AUTH", `Auth failed (HTTP ${res.status})`);
+    }
+    if (res.status === 429) {
+        throw new AppError("E_PROVIDER_RATE_LIMIT", "Rate limit exceeded");
+    }
+    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 = {
@@ -68,15 +111,8 @@ export async function generateImage(config, opts) {
         },
         body,
     }, config.timeoutMs);
-    if (res.status === 401 || res.status === 403) {
-        throw new AppError("E_PROVIDER_AUTH", `Auth failed (HTTP ${res.status})`);
-    }
-    if (res.status === 429) {
-        throw new AppError("E_PROVIDER_RATE_LIMIT", "Rate limit exceeded");
-    }
     if (!res.ok) {
-        const text = await res.text().catch(() => "");
-        throw new AppError("E_PROVIDER_BAD_REQUEST", `Upstream error ${res.status}: ${text.slice(0, 200)}`);
+        await handleProviderError(res);
     }
     const data = (await res.json());
     const imagePart = data.candidates?.[0]?.content?.parts?.find((p) => p.inlineData);
@@ -85,3 +121,46 @@ export async function generateImage(config, opts) {
     }
     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 size = mapOpenAISize(opts.size ?? "1K", opts.aspectRatio);
+    const hasReferenceImages = Boolean(opts.referenceImages?.length);
+    const url = `${config.baseUrl}${hasReferenceImages ? "/v1/images/edits" : "/v1/images/generations"}`;
+    let body;
+    let headers = {
+        Authorization: `Bearer ${config.apiKey}`,
+    };
+    if (hasReferenceImages) {
+        const form = new FormData();
+        form.set("model", model);
+        form.set("prompt", prompt);
+        form.set("size", size);
+        for (const [index, imgPath] of opts.referenceImages.entries()) {
+            const data = await resizeIfNeeded(imgPath);
+            const bytes = data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+            form.append("image", new Blob([bytes], { type: "image/png" }), `reference-${index}.png`);
+        }
+        body = form;
+    }
+    else {
+        headers = { ...headers, "Content-Type": "application/json" };
+        body = JSON.stringify({ model, prompt, size });
+    }
+    const res = await fetchWithRetry(url, {
+        method: "POST",
+        headers,
+        body,
+    }, config.timeoutMs);
+    if (!res.ok) {
+        await handleProviderError(res);
+    }
+    return imageFromOpenAIResponse(res);
+}
+export async function generateImage(config, opts) {
+    const model = opts.model ?? config.model;
+    if (isOpenAIImageModel(model)) {
+        return generateOpenAIImage(config, opts);
+    }
+    return generateGeminiImage(config, opts);
+}

package/package.json

@@ -1,45 +1,45 @@
-{
-  "name": "mcp-duojie-image",
-  "version": "0.5.0",
-  "description": "MCP server for image generation via duojie.games",
-  "type": "module",
-  "main": "dist/index.js",
-  "bin": {
-    "mcp-duojie-image": "dist/index.js"
-  },
-  "scripts": {
-    "dev": "tsx src/index.ts",
-    "build": "tsc",
-    "start": "node dist/index.js",
-    "test": "vitest run",
-    "lint": "tsc --noEmit",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "mcp",
-    "image-generation",
-    "gemini",
-    "ai"
-  ],
-  "author": "",
-  "license": "MIT",
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0",
-    "jimp": "^1.6.0",
-    "node-notifier": "^10.0.1",
-    "zod": "^3.23.8"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "@types/node-notifier": "^8.0.5",
-    "tsx": "^4.19.0",
-    "typescript": "^5.5.0",
-    "vitest": "^2.0.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "files": [
-    "dist"
-  ]
-}
+{
+  "name": "mcp-duojie-image",
+  "version": "0.5.2",
+  "description": "MCP server for image generation via duojie.games",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-duojie-image": "dist/index.js"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "image-generation",
+    "gemini",
+    "ai"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "jimp": "^1.6.0",
+    "node-notifier": "^10.0.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/node-notifier": "^8.0.5",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist"
+  ]
+}