mcp-duojie-image 0.1.2 → 0.3.0

package/README.md

@@ -1,13 +1,15 @@
 # mcp-duojie-image
 
-MCP server for image generation via duojie.games API (Gemini 3.1 Flash Image).
+MCP server for image generation via duojie.games API (Gemini Flash Image).
 
 ## Features
 
-- Text-to-image generation
-- Image-to-image with reference images
-- Automatic file saving with conflict handling
-- Configurable output format and size
+- **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
 
@@ -15,22 +17,28 @@ MCP server for image generation via duojie.games API (Gemini 3.1 Flash Image).
 npx mcp-duojie-image
 ```
 
+Or with a specific version:
+
+```bash
+npx mcp-duojie-image@0.1.3
+```
+
 ## Configuration
 
-Set environment variable:
+Set the `DUOJIE_API_KEY` environment variable:
 
 ```bash
 export DUOJIE_API_KEY=sk-your-key-here
 ```
 
-Or configure in MCP client (e.g., Claude Desktop):
+Or configure in your MCP client (e.g., Claude Desktop, Factory):
 
 ```json
 {
   "mcpServers": {
     "duojie-image": {
-      "command": "npx",
-      "args": ["-y", "mcp-duojie-image"],
+      "command": "node",
+      "args": ["/path/to/mcp-duojie-image/dist/index.js"],
       "env": {
         "DUOJIE_API_KEY": "sk-your-key-here"
       }
@@ -39,23 +47,122 @@ Or configure in MCP client (e.g., Claude Desktop):
 }
 ```
 
-## Usage
+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 |
 
-The server provides one tool: `generate_image`
+## Tools
+
+### `generate_image`
+
+Generate an image and save it to disk.
 
 **Required parameters:**
-- `prompt`: Image description
-- `output_dir`: Output directory path
-- `output_filename`: Output filename (extension optional)
+- `prompt` (string) — Image description
+- `output_dir` (string) — Output directory (absolute path)
+- `output_filename` (string) — Output filename (no extension needed)
 
 **Optional parameters:**
-- `reference_images`: Array of local image paths for reference
-- `size`: "512px" | "1K" | "2K" | "4K"
-- `aspect_ratio`: e.g., "16:9"
-- `format`: Output format (default: "png")
-- `model`: Model override
-- `overwrite`: Overwrite existing file (default: false)
-- `negative_prompt`: What to avoid in the image
+- `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
 

package/dist/config.js

@@ -13,6 +13,6 @@ export function loadConfig(overrides) {
         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",
-        timeoutMs: 60_000,
+        timeoutMs: 300_000,
     };
 }

package/dist/index.js

@@ -2,27 +2,40 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 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 { saveImage } from "./saver.js";
 import { AppError } from "./errors.js";
+const require = createRequire(import.meta.url);
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const notifier = require("node-notifier");
+function notify(title, message) {
+    try {
+        notifier.notify({ title, message, sound: false });
+    }
+    catch {
+        // 系统通知失败时静默忽略
+    }
+}
 const server = new McpServer({
     name: "duojie-image",
     version: "0.1.0",
 });
 server.registerTool("generate_image", {
-    description: "Generate an image and save to disk.",
+    description: "Generate an image and save to disk. Returns immediately; generation runs in background (60~120s) with system notification on completion.",
     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"),
+        size: z.enum(["512px", "1K", "2K", "4K"]).optional().describe("Image size, default 1K. Use 512px for thumbnails, 2K/4K only if explicitly requested."),
         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."),
     }),
 }, async (args) => {
     let config;
@@ -33,40 +46,57 @@ server.registerTool("generate_image", {
         const code = err instanceof AppError ? err.code : "E_CONFIG_MISSING_KEY";
         return { content: [{ type: "text", text: JSON.stringify({ success: false, error: code, message: String(err instanceof Error ? err.message : err) }) }], isError: true };
     }
-    // Enrich prompt with size/aspect hints
-    let fullPrompt = args.prompt;
-    if (args.size)
-        fullPrompt += ` [size: ${args.size}]`;
-    if (args.aspect_ratio)
-        fullPrompt += ` [aspect_ratio: ${args.aspect_ratio}]`;
-    try {
-        const imageBuffer = await generateImage(config, {
-            prompt: fullPrompt,
-            referenceImages: args.reference_images,
-            model: args.model,
-            negativePrompt: args.negative_prompt,
-        });
-        const savedPath = saveImage(imageBuffer, {
-            outputDir: args.output_dir,
-            outputFilename: args.output_filename,
-            format: args.format ?? "png",
-            overwrite: args.overwrite ?? false,
-        });
-        return {
-            content: [{
-                    type: "text",
-                    text: JSON.stringify({ success: true, saved_path: savedPath, model: args.model ?? config.model }),
-                }],
-        };
-    }
-    catch (err) {
-        const code = err instanceof AppError ? err.code : "E_PROVIDER_BAD_REQUEST";
-        const msg = err instanceof Error ? err.message : String(err);
-        return {
-            content: [{ type: "text", text: JSON.stringify({ success: false, error: code, message: msg }) }],
-            isError: true,
-        };
-    }
+    const silent = args.silent ?? false;
+    // Start background generation (don't await)
+    (async () => {
+        try {
+            const imageBuffer = await generateImage(config, {
+                prompt: args.prompt,
+                referenceImages: args.reference_images,
+                model: args.model,
+                negativePrompt: args.negative_prompt,
+                size: args.size ?? "1K",
+                aspectRatio: args.aspect_ratio,
+            });
+            const savedPath = saveImage(imageBuffer, {
+                outputDir: args.output_dir,
+                outputFilename: args.output_filename,
+                format: args.format ?? "png",
+                overwrite: args.overwrite ?? false,
+            });
+            await server.sendLoggingMessage({
+                level: "info",
+                data: `图片生成完成：${savedPath}`,
+            });
+            if (!silent)
+                notify("图片生成完成", savedPath);
+        }
+        catch (err) {
+            const code = err instanceof AppError ? err.code : "E_INTERNAL";
+            const msg = err instanceof Error ? err.message : String(err);
+            await server.sendLoggingMessage({
+                level: "error",
+                data: `图片生成失败 [${code}]: ${msg}`,
+            }).catch(() => { });
+            if (!silent) {
+                if (code === "E_PROVIDER_TIMEOUT") {
+                    notify("图片生成超时", `${args.output_filename} 生成超过 300 秒，请重试`);
+                }
+                else {
+                    notify("图片生成失败", `[${code}] ${msg}`);
+                }
+            }
+        }
+    })();
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({
+                    status: "pending",
+                    message: `开始异步生成 ${args.output_filename}，通常需要等待 60~120s。请耐心等待。任务完成后会有通知。`,
+                }),
+            }],
+    };
 });
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/provider.js

@@ -1,6 +1,6 @@
-import { readFileSync } from "node:fs";
 import { AppError } from "./errors.js";
-async function fetchWithRetry(url, init, timeoutMs, retries = 2) {
+import { resizeIfNeeded } from "./resizer.js";
+async function fetchWithRetry(url, init, timeoutMs, retries = 0) {
     let lastErr;
     for (let attempt = 0; attempt <= retries; attempt++) {
         const controller = new AbortController();
@@ -24,33 +24,30 @@ async function fetchWithRetry(url, init, timeoutMs, retries = 2) {
     }
     throw new AppError("E_PROVIDER_BAD_REQUEST", `Network error: ${lastErr}`);
 }
-function buildMessages(opts) {
+async function buildMessages(opts) {
     const { prompt, referenceImages, negativePrompt } = opts;
     const fullPrompt = negativePrompt ? `${prompt}\n\nAvoid: ${negativePrompt}` : prompt;
     if (!referenceImages || referenceImages.length === 0) {
         return [{ role: "user", content: fullPrompt }];
     }
-    const parts = referenceImages.map((imgPath) => {
-        let data;
-        try {
-            data = readFileSync(imgPath);
-        }
-        catch {
-            throw new AppError("E_REFERENCE_NOT_FOUND", `Cannot read reference image: ${imgPath}`);
-        }
+    const parts = await Promise.all(referenceImages.map(async (imgPath) => {
+        const data = await resizeIfNeeded(imgPath);
         const b64 = data.toString("base64");
-        const mime = imgPath.toLowerCase().endsWith(".jpg") || imgPath.toLowerCase().endsWith(".jpeg")
-            ? "image/jpeg"
-            : "image/png";
-        return { type: "image_url", image_url: { url: `data:${mime};base64,${b64}` } };
-    });
+        return { type: "image_url", image_url: { url: `data:image/png;base64,${b64}` } };
+    }));
     parts.push({ type: "text", text: fullPrompt });
     return [{ role: "user", content: parts }];
 }
 export async function generateImage(config, opts) {
-    const messages = buildMessages(opts);
+    const messages = await buildMessages(opts);
     const model = opts.model ?? config.model;
-    const body = JSON.stringify({ model, messages });
+    const imageConfig = {
+        image_size: opts.size ?? "1K",
+    };
+    if (opts.aspectRatio) {
+        imageConfig.aspect_ratio = opts.aspectRatio;
+    }
+    const body = JSON.stringify({ model, messages, image_config: imageConfig });
     const url = `${config.baseUrl}/v1/chat/completions`;
     const res = await fetchWithRetry(url, {
         method: "POST",

package/dist/resizer.js

@@ -0,0 +1,17 @@
+import { Jimp, JimpMime } from "jimp";
+import { AppError } from "./errors.js";
+const MAX_SIDE = 1024;
+export async function resizeIfNeeded(imgPath) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let image;
+    try {
+        image = await Jimp.read(imgPath);
+    }
+    catch {
+        throw new AppError("E_REFERENCE_NOT_FOUND", `Cannot read reference image: ${imgPath}`);
+    }
+    if (image.width > MAX_SIDE || image.height > MAX_SIDE) {
+        image.scaleToFit({ w: MAX_SIDE, h: MAX_SIDE });
+    }
+    return image.getBuffer(JimpMime.png);
+}

package/dist/task-queue.js

@@ -0,0 +1,37 @@
+import { randomUUID } from "node:crypto";
+const tasks = new Map();
+// 清理超过 30 分钟的已完成/失败任务
+const CLEANUP_INTERVAL_MS = 5 * 60 * 1000;
+const TASK_TTL_MS = 30 * 60 * 1000;
+// Cleanup function exposed for testing
+export function cleanupExpiredTasks() {
+    const now = Date.now();
+    for (const [id, task] of tasks) {
+        if ((task.status === "done" || task.status === "failed") &&
+            task.completedAt &&
+            now - task.completedAt > TASK_TTL_MS) {
+            tasks.delete(id);
+        }
+    }
+}
+setInterval(() => {
+    cleanupExpiredTasks();
+}, CLEANUP_INTERVAL_MS).unref();
+export function createTask() {
+    const task = {
+        id: randomUUID(),
+        status: "pending",
+        createdAt: Date.now(),
+    };
+    tasks.set(task.id, task);
+    return task;
+}
+export function getTask(id) {
+    return tasks.get(id);
+}
+export function updateTask(id, updates) {
+    const task = tasks.get(id);
+    if (task) {
+        Object.assign(task, updates);
+    }
+}

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "mcp-duojie-image",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "MCP server for image generation via duojie.games",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "mcp-duojie-image": "./dist/index.js"
+    "mcp-duojie-image": "dist/index.js"
   },
   "scripts": {
     "dev": "tsx src/index.ts",
@@ -25,10 +25,13 @@
   "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"