mcp-duojie-image 0.15.2 → 0.16.0

package/README.md

@@ -48,10 +48,9 @@ Optional parameters:
 | `aspect_ratio` | preset or custom `W:H` | `1:1` | Presets `1:1` \| `3:2` \| `2:3` \| `16:9` \| `9:16`, or any custom ratio such as `9:21`; custom ratios get neutral canvas-ratio prompt guidance (no art-direction wording) and an exact local crop |
 | `reference_images` | string[] | - | Local references used to create a new image |
 | `input_images` | object[] | - | Structured local image inputs with `path`, optional `role`, and optional `note` |
-| `use_case` | string | - | Prompt taxonomy slug, for example `product-mockup` or `background-extraction` |
 | `asset_type` | string | - | Where the asset will be used |
 | `constraints` | string | - | Must-keep or must-avoid constraints |
-| `format` | `png` \| `jpg` \| `jpeg` | `png` | Output format; content is encoded to match the extension |
+| `format` | `png` \| `jpg` \| `jpeg` \| `webp` | `png` | Output format; content is encoded to match the extension |
 | `overwrite` | boolean | `false` | Overwrite existing file |
 | `negative_prompt` | string | - | Content to avoid |
 | `reference_max_side` | number | `512` / `256` | Default 512 for one generation reference and 256 for multiple |
@@ -131,10 +130,16 @@ Done response:
   "task_id": "uuid",
   "status": "done",
   "saved_path": "D:/images/output.png",
-  "effective_prompt": "Primary request: ..."
+  "model": "gpt-image-2.5",
+  "aspect_ratio": "9:21",
+  "saved_dimensions": "864x2016"
 }
 ```
 
+Polling responses carry only the status fields above plus
+`poll_required`/`retry_after_ms`; process metadata such as `effective_prompt`
+and `prompt_stats` is returned once, on the submission response.
+
 Failed response:
 
 ```json
@@ -264,7 +269,6 @@ edges (icons clean; extreme fur edges may show slight color fringe — add
 ```text
 generate_image(
   prompt="A futuristic city at sunset",
-  use_case="stylized-concept",
   asset_type="website hero",
   constraints="no text, no watermark",
   size="2K",

package/dist/index.js

@@ -4,18 +4,18 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { createRequire } from "node:module";
 import { loadConfig } from "./config.js";
-import { ASPECT_RATIOS, CUSTOM_ASPECT_RATIO_PATTERN, DEFAULT_GENERATION_REFERENCE_MAX_SIDE, DEFAULT_MULTI_REFERENCE_MAX_SIDE, IMAGE_SIZES, editImage, generateImage, mapOpenAISize, } from "./provider.js";
+import { CUSTOM_ASPECT_RATIO_PATTERN, DEFAULT_GENERATION_REFERENCE_MAX_SIDE, DEFAULT_MULTI_REFERENCE_MAX_SIDE, IMAGE_SIZES, editImage, generateImage, mapOpenAISize, } from "./provider.js";
 import { saveImage } from "./saver.js";
 import { AppError } from "./errors.js";
 import { DEFAULT_IMAGE_MODEL, IMAGE_MODEL_IDS, MODEL_GUIDANCE } from "./models.js";
 import { createTask, getTask, updateTask, waitForAllTasks } from "./task-queue.js";
 import { setServerVersion, taskStatusResponse, taskSubmissionResponse, waitAllTasksResponse, } from "./task-response.js";
-import { PROMPT_USE_CASES, REFERENCE_IMAGE_ROLES, preparePrompt, } from "./prompt.js";
+import { REFERENCE_IMAGE_ROLES, preparePrompt, } from "./prompt.js";
 import { OUTPUT_FORMATS, fitImageToSize, readDimensions, } from "./image-processing.js";
 const require = createRequire(import.meta.url);
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const notifier = require("node-notifier");
-export const SERVER_VERSION = "0.15.1";
+export const SERVER_VERSION = "0.16.0";
 function notify(title, message) {
     try {
         notifier.notify({ title, message, sound: false });
@@ -59,7 +59,6 @@ async function submitImageTask(args, operation) {
             prompt: args.prompt,
             editTarget: args.edit_target,
             negativePrompt: args.negative_prompt,
-            useCase: args.use_case,
             assetType: args.asset_type,
             constraints: args.constraints,
             inputImages: args.input_images,
@@ -151,56 +150,52 @@ async function submitImageTask(args, operation) {
     return toolText(taskSubmissionResponse(getTask(task.id) ?? task, args.output_filename));
 }
 const structuredReferences = z.array(z.object({
-    path: z.string().min(1).describe("Local reference image path"),
+    path: z.string().min(1).describe("Image path"),
     role: z.enum(REFERENCE_IMAGE_ROLES).optional().describe("How the reference guides the result"),
-    note: z.string().optional().describe("Short role-specific instruction"),
-})).optional().describe("Structured references; do not combine with reference_images");
+    note: z.string().optional().describe("Role-specific instruction"),
+})).optional().describe("Structured references; don't combine with reference_images");
 const commonFields = {
-    prompt: z.string().min(1).describe("What the image should show; be specific about subject, style, and composition"),
+    prompt: z.string().min(1).describe("What to render: subject, style, composition"),
     output_dir: z.string().describe("Absolute output directory"),
     output_filename: z.string().describe("Filename without extension"),
-    use_case: z.enum(PROMPT_USE_CASES).optional().describe("Optional request category, e.g. product-mockup or ui-mockup; shapes prompt formatting"),
     asset_type: z.string().optional().describe("Where the image will be used"),
-    constraints: z.string().optional().describe("Must-keep or must-avoid constraints"),
-    size: z.enum(IMAGE_SIZES).optional().describe("Pixel tier. Default 1K"),
+    constraints: z.string().optional().describe("Must-keep or must-avoid rules"),
+    size: z.enum(IMAGE_SIZES).optional().describe("Default 1K"),
     model: z.enum(IMAGE_MODEL_IDS).optional().describe(MODEL_GUIDANCE),
-    aspect_ratio: z.union([
-        z.enum(ASPECT_RATIOS),
-        z.string().regex(new RegExp(CUSTOM_ASPECT_RATIO_PATTERN)),
-    ]).optional()
-        .describe("Preset 1:1 | 3:2 | 2:3 | 16:9 | 9:16, or any custom W:H such as 9:21. Default 1:1; the saved file always matches the requested ratio exactly"),
+    aspect_ratio: z.string().regex(new RegExp(CUSTOM_ASPECT_RATIO_PATTERN), "aspect_ratio must be W:H with 1-4 digit positive parts, e.g. 1:1, 16:9, 9:21").optional()
+        .describe("W:H, e.g. 1:1, 16:9, 9:21. Default 1:1; output file matches exactly"),
     format: z.enum(OUTPUT_FORMATS).optional().describe("Default png"),
-    overwrite: z.boolean().optional().describe("Default false; an existing file with the same name fails the task"),
+    overwrite: z.boolean().optional().describe("Default false; same-name file fails"),
     negative_prompt: z.string().optional().describe("Content to avoid"),
     reference_max_side: z.number().int().min(256).max(3840).optional()
-        .describe(`Longest side for uploaded inputs. generate defaults: ${DEFAULT_GENERATION_REFERENCE_MAX_SIDE} for one reference, ${DEFAULT_MULTI_REFERENCE_MAX_SIDE} for multiple; edit default 1024`),
-    preserve_reference_detail: z.boolean().optional().describe("Upload inputs without resizing; less stable"),
-    silent: z.boolean().optional().describe("Disable the desktop notification"),
+        .describe(`Resize cap for reference uploads; default ${DEFAULT_GENERATION_REFERENCE_MAX_SIDE} (single) / ${DEFAULT_MULTI_REFERENCE_MAX_SIDE} (multi), edit 1024`),
+    preserve_reference_detail: z.boolean().optional().describe("Upload references unresized (less stable)"),
+    silent: z.boolean().optional().describe("Skip desktop notification"),
 };
 const referenceFields = {
     reference_images: z.array(z.string()).optional()
-        .describe("Optional local reference image paths used as guidance for a new image; never edited in place"),
+        .describe("Local image paths guiding the result; never edited in place"),
     input_images: structuredReferences,
 };
 server.registerTool("generate_image", {
-    description: "Create a new image from a text prompt, optionally guided by reference images for style, identity, composition, or material. Use this by default for new visuals; for a small change to an existing image, use edit_image instead; if intent is unclear, ask the user first. Usage: returns a task_id immediately — poll check_image_task until status is done (saved_path holds the output file) or failed; after submitting several tasks, call wait_all_tasks once to wait for all of them instead of polling one by one.",
+    description: "Create a new image from a text prompt, optionally guided by reference images (style, identity, composition, material). To modify an existing image use edit_image. Async: returns task_id — poll with check_image_task / wait_all_tasks.",
     inputSchema: z.object({
         ...commonFields,
         ...referenceFields,
     }),
 }, async (args) => submitImageTask(args, "generate"));
 server.registerTool("edit_image", {
-    description: "Apply a small, explicit change to one existing image (e.g. remove an object, change a color) while preserving everything else. Requires exactly one edit_target. For new images or restyled variants, use generate_image instead. Usage: returns a task_id immediately — poll check_image_task until status is done (saved_path holds the output file) or failed; after submitting several tasks, call wait_all_tasks once to wait for all of them instead of polling one by one.",
+    description: "Apply a small explicit change (e.g. remove an object, recolor) to one existing image, preserving everything else; requires exactly one edit_target. For new images or restyled variants use generate_image. Async: returns task_id — poll with check_image_task / wait_all_tasks.",
     inputSchema: z.object({
         ...commonFields,
-        edit_target: z.string().min(1).describe("The single existing image to modify"),
+        edit_target: z.string().min(1).describe("Existing image to modify"),
         ...referenceFields,
     }),
 }, async (args) => submitImageTask(args, "edit"));
 server.registerTool("check_image_task", {
-    description: "Poll an async generate_image or edit_image task. Keep polling while poll_required=true; status done returns saved_path, status failed returns error details.",
+    description: "Poll an image task until terminal: done → saved_path; failed → error.",
     inputSchema: z.object({
-        task_id: z.string().min(1).describe("Task id returned by generate_image or edit_image"),
+        task_id: z.string().min(1).describe("Task id from generate_image/edit_image"),
     }),
 }, async (args) => {
     const task = getTask(args.task_id);
@@ -213,10 +208,10 @@ server.registerTool("check_image_task", {
 const DEFAULT_WAIT_TIMEOUT_SECONDS = 300;
 const MAX_WAIT_TIMEOUT_SECONDS = 600;
 server.registerTool("wait_all_tasks", {
-    description: "Wait for every in-flight generate_image/edit_image task to finish, then return all results in one response — each done task carries saved_path, each failed task its error. Use this after submitting a batch instead of polling check_image_task per task. Returns immediately when nothing is running; on timeout returns completed results plus still-pending task ids — just call again to keep waiting.",
+    description: "Wait for all in-flight image tasks and return all results at once. Immediate when none are running; on timeout returns partial results — call again.",
     inputSchema: z.object({
         timeout_seconds: z.number().int().min(1).max(MAX_WAIT_TIMEOUT_SECONDS).optional()
-            .describe(`Max seconds to block, default ${DEFAULT_WAIT_TIMEOUT_SECONDS}, upper bound ${MAX_WAIT_TIMEOUT_SECONDS}. On timeout partial results are returned; call again to continue waiting`),
+            .describe(`Block at most this long, default ${DEFAULT_WAIT_TIMEOUT_SECONDS}, max ${MAX_WAIT_TIMEOUT_SECONDS}`),
     }),
 }, 
 // 长阻塞期间客户端取消 (extra.signal) 时以当前快照返回, 后台任务不受影响

package/dist/models.js

@@ -23,5 +23,5 @@ export const DEFAULT_IMAGE_MODEL = "gpt-image-2.5";
 export function isImageModelId(value) {
     return value in IMAGE_MODELS;
 }
-/** 供 model 参数 describe 使用的单句版模型选择说明 */
-export const MODEL_GUIDANCE = `Default ${DEFAULT_IMAGE_MODEL} (balanced). Alternatives: gpt-image-2.5-flare (fastest, for drafts and previews), gpt-image-2.5-sunburst (best quality, slowest). If the user has not specified a model, ask which one to use before calling.`;
+/** 供 model 参数 describe 使用的精简版模型选择说明；"未指定时先询问"的规则由 AGENTS.md 承担 */
+export const MODEL_GUIDANCE = `Default gpt-image-2.5 (balanced); flare = fastest, drafts; sunburst = best quality, slowest`;

package/dist/prompt.js

@@ -6,27 +6,6 @@ export const REFERENCE_IMAGE_ROLES = [
     "composition_reference",
     "insert_source",
 ];
-export const PROMPT_USE_CASES = [
-    "photorealistic-natural",
-    "product-mockup",
-    "ui-mockup",
-    "infographic-diagram",
-    "scientific-educational",
-    "ads-marketing",
-    "productivity-visual",
-    "logo-brand",
-    "illustration-story",
-    "stylized-concept",
-    "historical-scene",
-    "text-localization",
-    "identity-preserve",
-    "precise-object-edit",
-    "lighting-weather",
-    "background-extraction",
-    "style-transfer",
-    "compositing",
-    "sketch-to-render",
-];
 function compactLines(lines) {
     return lines.filter((line) => Boolean(line?.trim())).join("\n");
 }
@@ -112,7 +91,6 @@ export function preparePrompt(opts) {
         ? `Avoid: ${opts.negativePrompt.trim()}`
         : undefined;
     const prompt = compactLines([
-        opts.useCase ? `Use case: ${opts.useCase}` : undefined,
         opts.assetType ? `Asset type: ${opts.assetType}` : undefined,
         operationPrompt(opts.operation, Boolean(references?.length)),
         imageLines(imageInputs),

package/dist/task-response.js

@@ -23,6 +23,8 @@ export function taskSubmissionResponse(task, outputFilename) {
         ...(serverVersion ? { version: serverVersion } : {}),
     };
 }
+// 提交响应带全量元数据 (一次性); 轮询是高频路径, taskStatusResponse 只保留
+// 终态高信号字段, effective_prompt/prompt_stats 等过程元数据不在轮询中重复注入。
 export function taskStatusResponse(task) {
     const response = {
         task_id: task.id,
@@ -32,32 +34,14 @@ export function taskStatusResponse(task) {
     if (serverVersion) {
         response.version = serverVersion;
     }
-    if (task.effectivePrompt) {
-        response.effective_prompt = task.effectivePrompt;
-    }
-    if (task.promptStats) {
-        response.prompt_stats = task.promptStats;
-    }
-    if (task.resolvedIntent) {
-        response.resolved_intent = task.resolvedIntent;
-    }
-    if (task.model) {
-        response.model = task.model;
-    }
-    if (task.requestedSize) {
-        response.size = task.requestedSize;
-    }
-    if (task.aspectRatio) {
-        response.aspect_ratio = task.aspectRatio;
-    }
-    if (task.targetDimensions) {
-        response.target_dimensions = task.targetDimensions;
-    }
     if (task.status === "done") {
         response.success = true;
         response.saved_path = task.savedPath;
-        if (task.upstreamDimensions) {
-            response.upstream_dimensions = task.upstreamDimensions;
+        if (task.model) {
+            response.model = task.model;
+        }
+        if (task.aspectRatio) {
+            response.aspect_ratio = task.aspectRatio;
         }
         if (task.savedDimensions) {
             response.saved_dimensions = task.savedDimensions;

package/package.json

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