gpt-image-mcp 0.2.1 → 0.3.0

package/README.md

@@ -6,58 +6,7 @@
 
 需要 Node.js 22 或更高版本，以及具有所选模型调用权限和可用额度的 OpenAI 或兼容服务商 API 密钥。支持 Linux、macOS 和 Windows。无需手动安装，通过 `npx` 自动下载运行。
 
-### Claude Code
-
-一条命令完成配置（仅当前项目生效）：
-
-```sh
-claude mcp add image-gen -- npx -y gpt-image-mcp
-```
-
-不同作用域：
-
-| 命令 | 作用域 |
-| --- | --- |
-| `claude mcp add image-gen -- npx -y gpt-image-mcp` | 当前项目，仅自己可见 |
-| `claude mcp add --scope project image-gen -- npx -y gpt-image-mcp` | 写入 `.mcp.json`，团队共享 |
-| `claude mcp add --scope user image-gen -- npx -y gpt-image-mcp` | 全局，跨项目生效 |
-
-添加后需要设置环境变量。编辑对应配置文件，在 `image-gen` 下添加 `env` 字段：
-
-```json
-{
-  "env": {
-    "OPENAI_API_KEY": "你的 API 密钥",
-    "OPENAI_BASE_URL": "https://你的服务商/v1",
-    "IMAGE_GEN_MODEL": "服务商提供的图片模型名称",
-    "IMAGE_GEN_OUTPUT_DIR": "~/pictures"
-  }
-}
-```
-
-仅 `OPENAI_API_KEY` 必填，其余按需配置。详见下方[配置](#配置)章节。
-
-### Claude Desktop
-
-编辑 `claude_desktop_config.json`（macOS 路径 `~/Library/Application Support/Claude/claude_desktop_config.json`）：
-
-```json
-{
-  "mcpServers": {
-    "image-gen": {
-      "command": "npx",
-      "args": ["-y", "gpt-image-mcp"],
-      "env": {
-        "OPENAI_API_KEY": "你的 API 密钥"
-      }
-    }
-  }
-}
-```
-
-### Cursor
-
-在项目根目录创建 `.cursor/mcp.json`：
+MCP 配置（适用于 Claude Code、Claude Desktop、Cursor 等支持 MCP 的客户端）：
 
 ```json
 {
@@ -66,53 +15,19 @@ claude mcp add image-gen -- npx -y gpt-image-mcp
       "command": "npx",
       "args": ["-y", "gpt-image-mcp"],
       "env": {
-        "OPENAI_API_KEY": "你的 API 密钥"
+        "OPENAI_API_KEY": "你的 API 密钥",
+        "OPENAI_BASE_URL": "https://你的服务商/v1",
+        "IMAGE_GEN_MODEL": "服务商提供的图片模型名称",
+        "IMAGE_GEN_OUTPUT_DIR": "~/pictures"
       }
     }
   }
 }
 ```
 
-### OpenAI Codex
-
-在 `.codex/config.toml` 中配置，需要写全 `npx` 的绝对路径（运行 `which npx` 获取）：
-
-```toml
-[mcp_servers.image-gen]
-command = "/你的npx路径/bin/npx"
-args = ["-y", "gpt-image-mcp"]
-
-[mcp_servers.image-gen.env]
-OPENAI_API_KEY = "你的 API 密钥"
-```
-
-### Windows 补充
-
-Windows 上如果客户端无法直接启动 npx，可将 `command` 和 `args` 改为：
-
-```json
-{
-  "command": "cmd",
-  "args": ["/d", "/c", "npx", "-y", "gpt-image-mcp"]
-}
-```
-
-### 全局安装（可选）
-
-如果希望避免首次启动的下载等待，也可以全局安装后直接使用命令名：
-
-```sh
-npm install --global gpt-image-mcp
-```
-
-安装后将配置中的 `"command"` 改为 `"gpt-image-mcp"`，去掉 `"args"`。
-
-### 通用说明
+仅 `OPENAI_API_KEY` 必填，其余按需配置。详见下方[配置](#配置)章节。
 
-- 锁定版本可将 `args` 改为 `["-y", "gpt-image-mcp@0.2.1"]`
-- 工具执行超时建议设为至少 360 秒，具体配置字段由客户端决定；服务自身的 API 超时默认为 300 秒
-- 服务启动后会等待 MCP 输入，直接在终端运行时没有欢迎输出属于正常行为
-- 日志只写入 stderr，stdout 保留给 MCP 协议
+首次启动会自动下载依赖，之后使用缓存。工具执行超时建议设为至少 360 秒；服务自身的 API 超时默认为 300 秒。
 
 ## 配置
 
@@ -124,6 +39,8 @@ npm install --global gpt-image-mcp
 | `IMAGE_GEN_OUTPUT_DIR` | 用户主目录下的 `gpt-image-mcp/images` | 输出根目录，支持本机绝对路径或 `~/`；自动按本地日期创建 `yyyy/MM/dd` 子目录 |
 | `IMAGE_GEN_TIMEOUT_MS` | `300000` | API 请求超时，单位毫秒，必须为不小于 1000 的整数 |
 | `IMAGE_GEN_RESPONSE_FORMAT` | `b64_json` | API 返回图片的方式：`b64_json`（返回 Base64 数据）或 `url`（返回下载地址，服务自动下载保存）。默认 `b64_json` 时不向 API 发送此参数，仅配置 `url` 时才显式发送。部分代理对新模型（如 `gpt-image-2.5-sunburst`）可能不支持此参数，遇到 `unknown_parameter` 错误时请保持默认值 |
+| `IMAGE_GEN_DEFAULT_SIZE` | `auto` | 全局默认分辨率，格式为 `WIDTHxHEIGHT`（如 `1024x1024`）。不填或留空时使用 `auto`，由 API 自行决定。宽高需为 16 的倍数，比例不超过 3:1，总像素 655360~8294400。单次调用仍可通过 `size` 参数覆盖 |
+| `IMAGE_GEN_DEFAULT_QUALITY` | `auto` | 全局默认质量：`auto`、`low`、`medium`、`high`、`xhigh`、`max`。不填或留空时使用 `auto`，由 API 自行决定。单次调用仍可通过 `quality` 参数覆盖 |
 
 `OPENAI_BASE_URL` 填写 API 根地址；未配置、空字符串或纯空格均使用官方端点。只有地址不包含路径时自动补 `/v1`，已有路径则按用户配置保留，避免破坏代理前缀或其他版本。尾部斜杠会去除，不会重复追加 `/v1`。
 

package/dist/config.js

@@ -36,11 +36,32 @@ export function readConfig(env = process.env) {
     if (responseFormat !== "b64_json" && responseFormat !== "url") {
         throw new Error("IMAGE_GEN_RESPONSE_FORMAT 仅支持 b64_json 或 url。");
     }
+    const defaultSize = parseDefaultSize(env.IMAGE_GEN_DEFAULT_SIZE?.trim());
+    const validQualities = ["auto", "low", "medium", "high", "xhigh", "max"];
+    const defaultQuality = (env.IMAGE_GEN_DEFAULT_QUALITY?.trim() || "auto");
+    if (!validQualities.includes(defaultQuality)) {
+        throw new Error(`IMAGE_GEN_DEFAULT_QUALITY 仅支持 ${validQualities.join("、")}。`);
+    }
     return {
-        apiKey, baseURL, model, timeout, responseFormat,
+        apiKey, baseURL, model, timeout, responseFormat, defaultSize, defaultQuality,
         outputDir: outputDir ? localPath(outputDir) : path.join(homedir(), "gpt-image-mcp", "images"),
     };
 }
+/** 校验 IMAGE_GEN_DEFAULT_SIZE：空值返回 "auto"，否则必须满足 WIDTHxHEIGHT 约束。 */
+function parseDefaultSize(value) {
+    if (!value)
+        return "auto";
+    const match = /^(\d+)x(\d+)$/.exec(value);
+    if (!match)
+        throw new Error("IMAGE_GEN_DEFAULT_SIZE 格式必须为 WIDTHxHEIGHT（如 1024x1024）。");
+    const w = Number(match[1]), h = Number(match[2]);
+    if (w % 16 !== 0 || h % 16 !== 0 || w <= 0 || h <= 0
+        || Math.max(w, h) / Math.min(w, h) > 3
+        || w * h < 655_360 || w * h > 8_294_400) {
+        throw new Error("IMAGE_GEN_DEFAULT_SIZE 宽高需为 16 的倍数，比例不超过 3:1，总像素 655360~8294400。");
+    }
+    return value;
+}
 /** 仅为无路径地址补 /v1；显式路径代表用户选择，不能猜测并改写。 */
 function normalizeBaseURL(value) {
     let url;

package/dist/images.js

@@ -56,9 +56,11 @@ export class ImageService {
      * @throws 上游请求失败、结果不可解析或本地保存失败时抛出错误。
      */
     async generate(input, signal) {
+        const size = input.size === "auto" ? this.config.defaultSize : input.size;
+        const quality = input.quality === "auto" ? this.config.defaultQuality : input.quality;
         const response = await this.client.images.generate({
-            model: this.config.model, prompt: input.prompt, size: input.size,
-            quality: input.quality, output_format: input.format, n: 1,
+            model: this.config.model, prompt: input.prompt, size,
+            quality, output_format: input.format, n: 1,
             background: input.background,
             moderation: input.moderation,
             ...(this.config.responseFormat === "url" && { response_format: "url" }),
@@ -94,9 +96,11 @@ export class ImageService {
                 throw new Error("遮罩必须是带透明通道的 PNG，且尺寸与第一张原图一致。");
             }
         }
+        const size = input.size === "auto" ? this.config.defaultSize : input.size;
+        const quality = input.quality === "auto" ? this.config.defaultQuality : input.quality;
         const response = await this.client.images.edit({
-            model: this.config.model, prompt: input.prompt, size: input.size,
-            quality: input.quality, output_format: input.format, n: 1,
+            model: this.config.model, prompt: input.prompt, size,
+            quality, output_format: input.format, n: 1,
             background: input.background,
             image: images.map((image) => image.upload), mask: mask?.upload,
             ...(this.config.responseFormat === "url" && { response_format: "url" }),

package/dist/index.js

@@ -8,7 +8,7 @@ import { createServer } from "./server.js";
 try {
     const args = process.argv.slice(2);
     if (args.length === 1 && args[0] === "--help") {
-        process.stdout.write("gpt-image-mcp\n\n用法：\n  gpt-image-mcp          启动本地 stdio MCP 服务\n  gpt-image-mcp --check  检查模型列表接口，不发送生图请求\n  gpt-image-mcp --help   显示帮助\n\n配置：OPENAI_API_KEY、OPENAI_BASE_URL、IMAGE_GEN_MODEL、IMAGE_GEN_OUTPUT_DIR、IMAGE_GEN_TIMEOUT_MS、IMAGE_GEN_RESPONSE_FORMAT\n");
+        process.stdout.write("gpt-image-mcp\n\n用法：\n  gpt-image-mcp          启动本地 stdio MCP 服务\n  gpt-image-mcp --check  检查模型列表接口，不发送生图请求\n  gpt-image-mcp --help   显示帮助\n\n配置：OPENAI_API_KEY、OPENAI_BASE_URL、IMAGE_GEN_MODEL、IMAGE_GEN_OUTPUT_DIR、IMAGE_GEN_TIMEOUT_MS、IMAGE_GEN_RESPONSE_FORMAT、IMAGE_GEN_DEFAULT_SIZE、IMAGE_GEN_DEFAULT_QUALITY\n");
     }
     else if (args.length === 1 && args[0] === "--check") {
         const config = readConfig();

package/dist/server.js

@@ -50,7 +50,7 @@ async function toolResult(operation) {
  */
 export function createServer(config, client = createApiClient(config)) {
     const service = new ImageService(client, config);
-    const server = new McpServer({ name: "gpt-image-mcp", version: "0.1.0" });
+    const server = new McpServer({ name: "gpt-image-mcp", version: "0.3.0" });
     const annotations = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true };
     server.registerTool("check_endpoint", {
         title: "端点检查",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gpt-image-mcp",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "支持文生图、图片编辑和参考风格生成的本地 MCP 服务",
   "license": "MIT",
   "author": "WainZeng",