mcp-duojie-image 0.9.0 → 0.9.1

package/README.md

@@ -8,7 +8,7 @@ MCP server for image generation via duojie.games GPT image API.
 - Reference image support: requests with reference images route through `/v1/images/edits` (multipart form); text-only requests route through `/v1/images/generations` (JSON body)
 - Prompt structuring helpers for use case, asset type, constraints, and effective prompt echo
 - Optional chroma-key transparent background post-processing
-- Async submission with task status lookup
+- Async submission with explicit accepted/terminal semantics and required task polling
 - File saving with overwrite/conflict handling
 - Verified size templates for `1K`, `2K`, and `4K`
 
@@ -23,7 +23,11 @@ Required:
 
 ## Tool: `generate_image`
 
-Generates an image asynchronously and saves it to disk.
+Accepts an asynchronous image task and saves the image to disk when the task
+finishes. A submitted response is not a successful generation. Call
+`check_image_task` until it returns `status: "done"` or `status: "failed"`.
+Non-terminal responses intentionally omit `success`; only terminal responses use
+`success: true` or `success: false`.
 
 Required parameters:
 
@@ -69,11 +73,19 @@ Response:
 
 ```json
 {
-  "success": true,
+  "accepted": true,
+  "terminal": false,
   "status": "submitted",
   "task_id": "uuid",
+  "poll_required": true,
+  "retry_after_ms": 1000,
   "effective_prompt": "Primary request: ...",
-  "message": "已提交异步生成；如需诊断失败原因，可调用 check_image_task"
+  "prompt_stats": {
+    "characters": 123,
+    "utf8Bytes": 145,
+    "lines": 4
+  },
+  "message": "已接受异步生成任务；这不代表图片已生成，必须轮询 check_image_task"
 }
 ```
 
@@ -90,6 +102,7 @@ Done response:
 ```json
 {
   "success": true,
+  "terminal": true,
   "task_id": "uuid",
   "status": "done",
   "saved_path": "D:/images/output.png",
@@ -102,13 +115,32 @@ Failed response:
 ```json
 {
   "success": false,
+  "terminal": true,
   "task_id": "uuid",
   "status": "failed",
-  "error": "E_PROVIDER_BAD_REQUEST",
-  "message": "Upstream error details"
+  "error": "E_PROVIDER_EMPTY_RESPONSE",
+  "message": "Provider returned HTTP 200 but data contained no image",
+  "details": {
+    "request_id": "provider-request-id",
+    "response_summary": {
+      "status": 200,
+      "content_type": "application/json",
+      "body": {
+        "kind": "json_object",
+        "keys": ["data"],
+        "data_length": 1,
+        "data_0_keys": []
+      }
+    }
+  }
 }
 ```
 
+Provider diagnostics contain only response metadata and JSON shape/key summaries;
+prompt text, image payloads, authorization values, and arbitrary upstream body
+content are not echoed. The configured provider timeout covers receiving headers,
+reading the response body, and downloading a returned image URL.
+
 ## Verified GPT size templates
 
 These templates were tested directly against `/v1/images/generations`; all returned the requested dimensions.

package/dist/errors.js

@@ -1,8 +1,10 @@
 export class AppError extends Error {
     code;
-    constructor(code, message) {
+    details;
+    constructor(code, message, details) {
         super(message);
         this.code = code;
+        this.details = details;
         this.name = "AppError";
     }
 }

package/dist/index.js

@@ -8,6 +8,7 @@ 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";
+import { taskStatusResponse, taskSubmissionResponse } from "./task-response.js";
 import { IMAGE_INPUT_ROLES, PROMPT_USE_CASES, preparePrompt } from "./prompt.js";
 import { OUTPUT_FORMATS, removeChromaKey } from "./image-processing.js";
 const require = createRequire(import.meta.url);
@@ -31,10 +32,10 @@ function toolText(data) {
 }
 const server = new McpServer({
     name: "duojie-image",
-    version: "0.1.0",
+    version: "0.9.1",
 });
 server.registerTool("generate_image", {
-    description: "Generate image async with gpt-image-2. Reference images route through /v1/images/edits (multipart form); text-only requests route through /v1/images/generations. Return after tool call; don't wait/check.",
+    description: "Accept an asynchronous gpt-image-2 task. This submission is not generation success: after receiving task_id, you MUST call check_image_task until status is done or failed. Reference images use /v1/images/edits; text-only requests use /v1/images/generations.",
     inputSchema: z.object({
         prompt: z.string().min(1).describe("Prompt"),
         output_dir: z.string().describe("Absolute output dir"),
@@ -104,7 +105,10 @@ 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 task = createTask();
-    updateTask(task.id, { effectivePrompt: preparedPrompt.prompt });
+    updateTask(task.id, {
+        effectivePrompt: preparedPrompt.prompt,
+        promptStats: preparedPrompt.stats,
+    });
     // Start background generation (don't await)
     (async () => {
         try {
@@ -146,6 +150,7 @@ server.registerTool("generate_image", {
                 completedAt: Date.now(),
                 errorCode: code,
                 error: msg,
+                errorDetails: err instanceof AppError ? err.details : undefined,
             });
             await server.sendLoggingMessage({
                 level: "error",
@@ -161,21 +166,10 @@ server.registerTool("generate_image", {
             }
         }
     })();
-    return {
-        content: [{
-                type: "text",
-                text: JSON.stringify({
-                    success: true,
-                    status: "submitted",
-                    task_id: task.id,
-                    effective_prompt: preparedPrompt.prompt,
-                    message: `已提交异步生成：${args.output_filename}；如需诊断失败原因，可调用 check_image_task`,
-                }),
-            }],
-    };
+    return toolText(taskSubmissionResponse(getTask(task.id) ?? task, args.output_filename));
 });
 server.registerTool("check_image_task", {
-    description: "Check an async image generation task status and failure details.",
+    description: "Poll an asynchronous image task. Continue polling while poll_required=true. Only status=done with success=true means an image was generated and saved; status=failed is terminal and includes the provider error/details.",
     inputSchema: z.object({
         task_id: z.string().min(1).describe("Task id returned by generate_image"),
     }),
@@ -191,22 +185,8 @@ server.registerTool("check_image_task", {
             isError: true,
         };
     }
-    const response = {
-        success: task.status !== "failed",
-        task_id: task.id,
-        status: task.status,
-    };
-    if (task.status === "done") {
-        response.saved_path = task.savedPath;
-    }
-    if (task.effectivePrompt) {
-        response.effective_prompt = task.effectivePrompt;
-    }
-    if (task.status === "failed") {
-        response.error = task.errorCode;
-        response.message = task.error;
-    }
-    return toolText(response);
+    const response = toolText(taskStatusResponse(task));
+    return task.status === "failed" ? { ...response, isError: true } : response;
 });
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/prompt.js

@@ -84,5 +84,10 @@ export function preparePrompt(opts) {
         prompt,
         imagePaths: inputImages?.map((image) => image.path) ?? [],
         imageInputs: inputImages,
+        stats: {
+            characters: Array.from(prompt).length,
+            utf8Bytes: Buffer.byteLength(prompt, "utf8"),
+            lines: prompt ? prompt.split("\n").length : 0,
+        },
     };
 }

package/dist/provider.js

@@ -2,42 +2,102 @@ 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) {
+function getRequestId(res) {
+    return res.headers.get("x-request-id")
+        ?? res.headers.get("request-id")
+        ?? res.headers.get("x-trace-id")
+        ?? res.headers.get("cf-ray");
+}
+function summarizeJson(value) {
+    if (Array.isArray(value)) {
+        return { kind: "json_array", length: value.length };
+    }
+    if (!value || typeof value !== "object") {
+        return { kind: "json_scalar", type: value === null ? "null" : typeof value };
+    }
+    const record = value;
+    const summary = {
+        kind: "json_object",
+        keys: Object.keys(record).slice(0, 20),
+    };
+    if (Array.isArray(record.data)) {
+        summary.data_length = record.data.length;
+        const first = record.data[0];
+        if (first && typeof first === "object" && !Array.isArray(first)) {
+            summary.data_0_keys = Object.keys(first).slice(0, 20);
+        }
+    }
+    if (record.error && typeof record.error === "object" && !Array.isArray(record.error)) {
+        const error = record.error;
+        summary.error_keys = Object.keys(error).slice(0, 20);
+        if (typeof error.code === "string" && /^[a-zA-Z0-9_.:-]{1,80}$/.test(error.code)) {
+            summary.error_code = error.code;
+        }
+        if (typeof error.type === "string" && /^[a-zA-Z0-9_.:-]{1,80}$/.test(error.type)) {
+            summary.error_type = error.type;
+        }
+    }
+    return summary;
+}
+function responseDetails(res, body) {
+    const summary = {
+        status: res.status,
+        content_type: res.headers.get("content-type"),
+        content_length: res.headers.get("content-length"),
+        ...(body ? { body } : {}),
+    };
+    return {
+        request_id: getRequestId(res),
+        response_summary: summary,
+    };
+}
+function isAbortError(err) {
+    return err instanceof Error && (err.name === "AbortError" || err.name === "TimeoutError");
+}
+async function delayForRetry(attempt) {
+    const delayMs = 1_000 * Math.pow(2, attempt) + Math.random() * 500;
+    await new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+async function fetchWithRetry(url, init, timeoutMs, consume, retries = 0) {
     let lastErr;
     for (let attempt = 0; attempt <= retries; attempt++) {
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), timeoutMs);
+        let receivedResponse;
         try {
             const res = await fetch(url, { ...init, signal: controller.signal });
-            clearTimeout(timer);
+            receivedResponse = res;
             // 5xx: 上游随机故障(EOF等)，立刻 abort body 连接并重试，不等 chunked 终止
             if (res.status >= 500 && attempt < retries) {
-                try {
-                    controller.abort();
-                }
-                catch { }
-                const delayMs = 1000 * Math.pow(2, attempt) + Math.random() * 500;
-                await new Promise((r) => setTimeout(r, delayMs));
+                controller.abort();
+                clearTimeout(timer);
+                await delayForRetry(attempt);
                 continue;
             }
-            return res;
+            const result = await consume(res, controller.signal);
+            clearTimeout(timer);
+            return result;
         }
         catch (err) {
             clearTimeout(timer);
-            const isAbort = err instanceof Error && err.name === "AbortError";
-            // AbortError from our manual abort above is not a real timeout
-            if (isAbort && attempt < retries) {
-                lastErr = err;
-                const delayMs = 1000 * Math.pow(2, attempt) + Math.random() * 500;
-                await new Promise((r) => setTimeout(r, delayMs));
-                continue;
+            if (err instanceof AppError) {
+                throw err;
+            }
+            if (isAbortError(err)) {
+                throw new AppError("E_PROVIDER_TIMEOUT", `Provider request timed out after ${timeoutMs}ms`, {
+                    timeout_ms: timeoutMs,
+                    phase: receivedResponse ? "response_body_or_image_download" : "connection_or_headers",
+                    ...(receivedResponse ? responseDetails(receivedResponse) : {}),
+                });
             }
-            if (isAbort) {
-                throw new AppError("E_PROVIDER_TIMEOUT", "Request timed out");
+            // Once response headers have arrived, the generation may already be billable.
+            // Do not replay the POST for body/CDN failures and risk duplicate generation.
+            if (receivedResponse) {
+                throw new AppError("E_PROVIDER_BAD_REQUEST", "Provider response could not be read completely", responseDetails(receivedResponse));
             }
             lastErr = err;
             if (attempt < retries) {
-                await new Promise((r) => setTimeout(r, 1000 * Math.pow(2, attempt)));
+                await delayForRetry(attempt);
             }
         }
     }
@@ -72,34 +132,72 @@ function mapOpenAISize(size, aspectRatio) {
     const ratio = aspectRatio ?? "1:1";
     return SIZE_TEMPLATES[imageSize][ratio];
 }
-async function imageFromOpenAIResponse(res) {
-    const data = (await res.json());
+async function imageFromOpenAIResponse(res, signal) {
+    let data;
+    try {
+        data = (await res.json());
+    }
+    catch (err) {
+        if (isAbortError(err))
+            throw err;
+        if (!(err instanceof SyntaxError)) {
+            throw new AppError("E_PROVIDER_BAD_REQUEST", "Provider response body could not be read", responseDetails(res));
+        }
+        throw new AppError("E_PROVIDER_EMPTY_RESPONSE", "Provider returned HTTP 200 but the response body was not valid image JSON", responseDetails(res, { kind: "invalid_json" }));
+    }
     const image = data.data?.[0];
     if (image?.b64_json) {
-        return Buffer.from(image.b64_json, "base64");
+        const imageBuffer = Buffer.from(image.b64_json, "base64");
+        if (imageBuffer.length > 0) {
+            return imageBuffer;
+        }
     }
     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}`);
+        try {
+            const imgRes = await fetch(image.url, { signal });
+            if (!imgRes.ok) {
+                const summary = await readBodySummary(imgRes);
+                throw new AppError("E_PROVIDER_BAD_REQUEST", `Image URL fetch failed (HTTP ${imgRes.status})`, responseDetails(imgRes, summary));
+            }
+            const imageBuffer = Buffer.from(await imgRes.arrayBuffer());
+            if (imageBuffer.length > 0) {
+                return imageBuffer;
+            }
+            throw new AppError("E_PROVIDER_EMPTY_RESPONSE", "Provider image URL returned an empty body", responseDetails(imgRes, { kind: "empty", length: 0 }));
+        }
+        catch (err) {
+            if (isAbortError(err) || err instanceof AppError)
+                throw err;
+            throw new AppError("E_PROVIDER_BAD_REQUEST", "Image URL download failed", responseDetails(res));
         }
-        return Buffer.from(await imgRes.arrayBuffer());
     }
-    throw new AppError("E_PROVIDER_BAD_REQUEST", "No image in response");
+    throw new AppError("E_PROVIDER_EMPTY_RESPONSE", "Provider returned HTTP 200 but data contained no image", responseDetails(res, summarizeJson(data)));
+}
+async function readBodySummary(res) {
+    const text = await res.text();
+    if (!text)
+        return { kind: "empty", length: 0 };
+    try {
+        return summarizeJson(JSON.parse(text));
+    }
+    catch {
+        return { kind: "text", length: text.length };
+    }
 }
 async function handleProviderError(res) {
+    // 5xx: 上游随机故障，不读 body（chunked 连接可能挂起），直接返回安全的响应头摘要。
+    if (res.status >= 500) {
+        throw new AppError("E_PROVIDER_BAD_REQUEST", `Upstream error (HTTP ${res.status})`, responseDetails(res));
+    }
+    const summary = await readBodySummary(res);
+    const details = responseDetails(res, summary);
     if (res.status === 401 || res.status === 403) {
-        throw new AppError("E_PROVIDER_AUTH", `Auth failed (HTTP ${res.status})`);
+        throw new AppError("E_PROVIDER_AUTH", `Auth failed (HTTP ${res.status})`, details);
     }
     if (res.status === 429) {
-        throw new AppError("E_PROVIDER_RATE_LIMIT", "Rate limit exceeded");
+        throw new AppError("E_PROVIDER_RATE_LIMIT", "Rate limit exceeded", details);
     }
-    // 5xx: 上游随机故障，不读 body（chunked 连接挂 120s），直接秒回
-    if (res.status >= 500) {
-        throw new AppError("E_PROVIDER_BAD_REQUEST", `Upstream error ${res.status} (body skipped to avoid chunked hang)`);
-    }
-    const text = await res.text().catch(() => "");
-    throw new AppError("E_PROVIDER_BAD_REQUEST", `Upstream error ${res.status}: ${text.slice(0, 200)}`);
+    throw new AppError("E_PROVIDER_BAD_REQUEST", `Upstream error (HTTP ${res.status})`, details);
 }
 async function generateOpenAIImage(config, opts) {
     const prompt = opts.prompt;
@@ -141,15 +239,16 @@ async function generateOpenAIImage(config, opts) {
     }
     // 启用 2 次重试,应对上游偶发的 EOF / 524(Cloudflare 100s 超时)。
     // retries=0 时所有偶发失败一次过即死,指数退避代码是死代码。
-    const res = await fetchWithRetry(url, {
+    return fetchWithRetry(url, {
         method: "POST",
         headers,
         body,
-    }, config.timeoutMs, 2);
-    if (!res.ok) {
-        await handleProviderError(res);
-    }
-    return imageFromOpenAIResponse(res);
+    }, config.timeoutMs, async (res, signal) => {
+        if (!res.ok) {
+            await handleProviderError(res);
+        }
+        return imageFromOpenAIResponse(res, signal);
+    }, 2);
 }
 export async function generateImage(config, opts) {
     return generateOpenAIImage(config, opts);

package/dist/task-response.js

@@ -0,0 +1,45 @@
+const POLL_RETRY_AFTER_MS = 1_000;
+export function taskSubmissionResponse(task, outputFilename) {
+    return {
+        accepted: true,
+        terminal: false,
+        status: "submitted",
+        task_id: task.id,
+        poll_required: true,
+        retry_after_ms: POLL_RETRY_AFTER_MS,
+        effective_prompt: task.effectivePrompt,
+        prompt_stats: task.promptStats,
+        message: `已接受异步生成任务：${outputFilename}。这不代表图片已生成；必须调用 check_image_task，直到 status 为 done 或 failed。`,
+    };
+}
+export function taskStatusResponse(task) {
+    const response = {
+        task_id: task.id,
+        status: task.status,
+        terminal: task.status === "done" || task.status === "failed",
+    };
+    if (task.effectivePrompt) {
+        response.effective_prompt = task.effectivePrompt;
+    }
+    if (task.promptStats) {
+        response.prompt_stats = task.promptStats;
+    }
+    if (task.status === "done") {
+        response.success = true;
+        response.saved_path = task.savedPath;
+    }
+    else if (task.status === "failed") {
+        response.success = false;
+        response.error = task.errorCode;
+        response.message = task.error;
+        if (task.errorDetails) {
+            response.details = task.errorDetails;
+        }
+    }
+    else {
+        response.accepted = true;
+        response.poll_required = true;
+        response.retry_after_ms = POLL_RETRY_AFTER_MS;
+    }
+    return response;
+}

package/package.json

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