imageforge-mcp 0.4.0 → 0.6.0

package/README.md

@@ -2,20 +2,20 @@
 
 English | [中文](#中文说明)
 
-A lightweight TypeScript MCP server for generating and editing images with OpenAI `gpt-image-2`, and for text-to-image generation with Zhipu BigModel image models.
+A lightweight TypeScript MCP server for image generation across 22 first-party providers, plus OpenAI image editing.
 
-- OpenAI text-to-image requests use `POST /v1/images/generations`; Zhipu uses `POST /api/paas/v4/images/generations`.
+- Provider adapters follow each vendor's documented synchronous or submit-and-poll REST contract.
 - OpenAI image editing and reference-image generation use multipart `POST /v1/images/edits`.
 - Generated images are returned as native MCP `image` content blocks and can optionally be saved locally.
 
 ## Features
 
-- OpenAI model: `gpt-image-2`
-- Zhipu models: `glm-image`, `cogview-4-250304`, `cogview-4`, `cogview-3-flash`
-- MCP tools: `generate_image` and `edit_image`
+- 22 provider IDs: `openai`, `zhipu`, `minimax`, `google`, `xai`, `stability`, `ideogram`, `recraft`, `tencent`, `baidu`, `playground`, `bfl`, `luma`, `krea`, `runway`, `leonardo`, `bria`, `freepik`, `alibaba`, `volcengine`, `kling`, and `hidream`
+- MCP tools: `generate_image`, `list_image_providers`, and `edit_image`
 - Text-to-image generation
 - Image generation guided by one or more reference images
 - Zhipu text-to-image generation with optional server-side watermark control
+- MiniMax text-to-image and single-subject reference generation
 - Editing one or more existing images
 - Local absolute paths and HTTP(S) URLs as image inputs
 - PNG, JPEG, and WebP input and output
@@ -27,16 +27,15 @@ A lightweight TypeScript MCP server for generating and editing images with OpenA
 
 ## Provider capability matrix
 
-| Capability | OpenAI | Zhipu |
+| Group | Providers | Execution |
 | --- | --- | --- |
-| Text-to-image | Yes | Yes |
-| Reference-image generation | Yes, through `reference_images` | No; the tool returns an error before reading files or sending a request |
-| Image editing | Yes, through `edit_image` | No |
-| Models | `gpt-image-2` | `glm-image`, `cogview-4-250304`, `cogview-4`, `cogview-3-flash` |
-| Quality values | `auto`, `low`, `medium`, `high` | `glm-image`: `auto`, `hd`; other models: `auto`, `standard`, `hd` |
-| `watermark_enabled` | Ignored without error | Forwarded only when explicitly supplied |
-| `output_format` | Sent to the provider | Ignored; MIME type is detected from the downloaded image |
-| Provider response | Base64 image data | Temporary image URL, downloaded immediately by ImageForge |
+| Existing compatibility | OpenAI, Zhipu, MiniMax | Synchronous |
+| Additional synchronous APIs | Google Gemini, xAI, Stability AI, Ideogram, Recraft, Tencent Hunyuan, Baidu Qianfan, Playground, Volcengine Ark | Synchronous |
+| Task APIs | Black Forest Labs, Luma, Krea, Runway, Leonardo, Bria, Freepik/Magnific, Alibaba Model Studio, Kling, HiDream | Submit once, then poll read-only status endpoints |
+
+Call `list_image_providers` for the authoritative model list, default model, reference modes and limits, required environment-variable names, documentation URL, and contract-verification state. New 0.6.0 adapters are implemented from official documentation and covered by mocks; they are not represented as live credential verification.
+
+`generate_image` keeps the existing common fields and adds `reference_mode` (`auto`, `content`, `style`, or `character`), `aspect_ratio`, `resolution`, `negative_prompt`, and `seed`. Unsupported combinations fail before provider access. `edit_image` remains OpenAI-only.
 
 ## Zhipu BigModel support
 
@@ -62,6 +61,20 @@ Zhipu returns one temporary image URL. ImageForge downloads it immediately and r
 
 See the [official Zhipu image generation API](https://docs.bigmodel.cn/api-reference/%E6%A8%A1%E5%9E%8B-api/%E5%9B%BE%E5%83%8F%E7%94%9F%E6%88%90) for current provider-side size, quality, watermark, and account-policy rules.
 
+## MiniMax support
+
+ImageForge calls `POST /v1/image_generation` with Bearer authentication, requests one Base64 image, and returns the MIME detected from the decoded bytes. It supports `image-01` and `image-01-live`; MiniMax credentials never fall back to OpenAI or Zhipu variables.
+
+- `image-01`: `size` becomes explicit `width` and `height`; each must be 512–2048 and divisible by 8, with at least `1024×1024` total pixels.
+- `image-01-live`: `size` is reduced to an exact supported aspect ratio. Unsupported ratios fail before the request.
+- `quality` must be `auto`; the provider has no quality field.
+- Output is JPEG. Omit `output_format` or set it to `jpeg`; `png` and `webp` fail before the request because ImageForge does not transcode images.
+- `reference_images` accepts at most one PNG/JPEG under 10 MB. ImageForge safely loads it and sends a Base64 Data URL as a `character` subject reference.
+- `watermark_enabled` maps to `aigc_watermark` only when explicitly supplied.
+- Paid requests are never retried automatically and are never switched to another provider.
+
+See the [official MiniMax image-generation guide](https://platform.minimaxi.com/docs/guides/image-generation) for current provider behavior.
+
 ## OpenAI-compatible CPA and gateway support
 
 ImageForge MCP works with OpenAI and with CPA, relay, or proxy services that implement a compatible OpenAI Images API. This includes deployments based on projects such as **New API**, **CLI Proxy API**, and similar OpenAI-compatible gateways.
@@ -78,7 +91,7 @@ A gateway that only implements `/v1/images/generations` can be used for text-to-
 ## Requirements
 
 - Node.js 22 or later
-- An OpenAI API key or a compatible gateway token; a Zhipu API key is needed only when using the `zhipu` provider
+- A credential for the selected provider; see `.env.example` or `list_image_providers`
 
 ## Install and build
 
@@ -108,7 +121,7 @@ For production use, start the published npm package with `npx`. No repository cl
 }
 ```
 
-`-y` allows `npx` to download or update the package without an interactive install prompt. Pin a specific version when reproducible deployments are required, for example `"imageforge-mcp@0.4.0"`.
+`-y` allows `npx` to download or update the package without an interactive install prompt. Pin a specific version when reproducible deployments are required, for example `"imageforge-mcp@0.6.0"`.
 
 For a Zhipu-default MCP server, use an independent credential and provider configuration:
 
@@ -117,7 +130,7 @@ For a Zhipu-default MCP server, use an independent credential and provider confi
   "mcpServers": {
     "imageforge-zhipu": {
       "command": "npx",
-      "args": ["-y", "imageforge-mcp@0.4.0"],
+      "args": ["-y", "imageforge-mcp@0.6.0"],
       "env": {
         "IMAGEFORGE_PROVIDER": "zhipu",
         "ZHIPU_API_KEY": "your-zhipu-token",
@@ -130,6 +143,26 @@ For a Zhipu-default MCP server, use an independent credential and provider confi
 
 `ZHIPU_BASE_URL` is optional and defaults to `https://open.bigmodel.cn/api/paas/v4`. `ZHIPU_IMAGE_MODEL` is optional and defaults to `glm-image`. Zhipu credentials never fall back to OpenAI variables, and OpenAI credentials never fall back to Zhipu variables. A per-call `provider`, `api_key`, `base_url`, or `model` overrides the corresponding environment configuration.
 
+For a MiniMax-default server:
+
+```json
+{
+  "mcpServers": {
+    "imageforge-minimax": {
+      "command": "npx",
+      "args": ["-y", "imageforge-mcp@0.6.0"],
+      "env": {
+        "IMAGEFORGE_PROVIDER": "minimax",
+        "MINIMAX_API_KEY": "your-minimax-token",
+        "MINIMAX_IMAGE_MODEL": "image-01"
+      }
+    }
+  }
+}
+```
+
+`MINIMAX_BASE_URL` defaults to `https://api.minimaxi.com/v1`; `MINIMAX_IMAGE_MODEL` defaults to `image-01`. MiniMax credentials are isolated from OpenAI and Zhipu credentials.
+
 `OPENAI_BASE_URL` is optional. When it is unset, ImageForge MCP uses the official OpenAI endpoint `https://api.openai.com/v1`. Set it only when using New API, CLI Proxy API, or another OpenAI-compatible gateway:
 
 ```json
@@ -140,6 +173,8 @@ The value must point to the gateway's `/v1` root. ImageForge MCP appends `/image
 
 `IMAGEFORGE_INPUT_CONCURRENCY` optionally controls how many local or remote input images are loaded at once. It defaults to `4`, must be a positive integer, and is capped at the per-call limit of `16` input images. The combined input size remains capped at 200 MB.
 
+Task-based providers submit a paid generation request exactly once and then poll read-only status endpoints. `IMAGEFORGE_ASYNC_TIMEOUT_MS` defaults to `300000` and accepts 30000–600000; `IMAGEFORGE_POLL_INTERVAL_MS` defaults to `2000` and accepts 500–10000. Polling honors numeric `Retry-After` values within the same bounds. ImageForge does not use webhooks, retry a paid create call, or fall back to another provider.
+
 DNS safety checks are enabled by default. Set `IMAGEFORGE_SKIP_DNS_SAFETY_CHECKS=true` only when private-network or DNS-proxy image URLs must be supported. This disables non-public address rejection and DNS pinning for every redirect hop, which can expose the MCP process to SSRF. HTTP(S)-only URLs, the credential restriction, redirect limit, size limits, and image signature validation remain enforced. Accepted true values are `true`, `1`, `yes`, and `on`; false values are `false`, `0`, `no`, and `off`.
 
 Do not commit real API keys to Git or write them into shared configuration files.
@@ -153,7 +188,7 @@ Create a project-scoped `.codex/config.toml` using paths that match your machine
 command = "/absolute/path/to/node"
 args = ["/absolute/path/to/ImageForgeMCP/dist/index.js"]
 cwd = "/absolute/path/to/ImageForgeMCP"
-env_vars = ["OPENAI_API_KEY", "OPENAI_BASE_URL", "OPENAI_IMAGE_MODEL", "ZHIPU_API_KEY", "ZHIPU_BASE_URL", "ZHIPU_IMAGE_MODEL", "IMAGEFORGE_PROVIDER", "IMAGEFORGE_INPUT_CONCURRENCY", "IMAGEFORGE_SKIP_DNS_SAFETY_CHECKS"]
+env_vars = ["OPENAI_API_KEY", "OPENAI_BASE_URL", "OPENAI_IMAGE_MODEL", "ZHIPU_API_KEY", "ZHIPU_BASE_URL", "ZHIPU_IMAGE_MODEL", "MINIMAX_API_KEY", "MINIMAX_BASE_URL", "MINIMAX_IMAGE_MODEL", "IMAGEFORGE_PROVIDER", "IMAGEFORGE_INPUT_CONCURRENCY", "IMAGEFORGE_SKIP_DNS_SAFETY_CHECKS"]
 startup_timeout_sec = 10
 tool_timeout_sec = 300
 enabled = true
@@ -181,9 +216,12 @@ export ZHIPU_IMAGE_MODEL="glm-image"
 # Optional: export ZHIPU_BASE_URL="https://open.bigmodel.cn/api/paas/v4"
 ```
 
+For MiniMax, export `IMAGEFORGE_PROVIDER=minimax`, `MINIMAX_API_KEY`, and optionally `MINIMAX_IMAGE_MODEL=image-01` or `image-01-live`.
+
 Codex loads project-scoped `.codex/config.toml` only for trusted projects. After adding or changing the MCP configuration, restart Codex or open a new task, then use `/mcp verbose` to confirm that `imageforge_dev` exposes:
 
 - `generate_image`
+- `list_image_providers`
 - `edit_image`
 
 After changing the TypeScript source, rebuild `dist/index.js` and restart the task using the MCP server:
@@ -199,18 +237,18 @@ See the [official Codex MCP documentation](https://developers.openai.com/codex/m
 | Parameter | Required | Default | Description |
 | --- | --- | --- | --- |
 | `prompt` | Yes | - | Image description |
-| `model` | No | Environment or provider default | OpenAI: `gpt-image-2`; Zhipu: `glm-image`, `cogview-4-250304`, `cogview-4`, `cogview-3-flash` |
-| `base_url` | No | `OPENAI_BASE_URL` or `ZHIPU_BASE_URL` | Per-call provider API base URL override |
-| `api_key` | No | `OPENAI_API_KEY` or `ZHIPU_API_KEY` | Per-call provider credential override; environment variables are preferred |
-| `provider` | No | `IMAGEFORGE_PROVIDER`, then `openai` | `openai` or `zhipu` |
+| `model` | No | Environment or provider default | OpenAI: `gpt-image-2`; Zhipu models above; MiniMax: `image-01`, `image-01-live` |
+| `base_url` | No | Provider environment variable or official default | Per-call provider API base URL override |
+| `api_key` | No | Provider-specific API key | Per-call provider credential override; environment variables are preferred |
+| `provider` | No | `IMAGEFORGE_PROVIDER`, then `openai` | `openai`, `zhipu`, or `minimax` |
 | `size` | No | `1024x1024` | Output size requested from the provider |
-| `quality` | No | `auto` | OpenAI: `auto/low/medium/high`; `glm-image`: `auto/hd`; other Zhipu models: `auto/standard/hd` |
-| `output_format` | No | `png` | `png`, `jpeg`, or `webp` |
+| `quality` | No | `auto` | OpenAI and Zhipu values above; MiniMax accepts only `auto` |
+| `output_format` | No | `png`; MiniMax: `jpeg` | OpenAI: `png/jpeg/webp`; Zhipu ignores it; MiniMax accepts only `jpeg` |
 | `output_path` | No | - | Local save path; relative paths resolve from the MCP working directory |
-| `watermark_enabled` | No | - | Sent only to Zhipu when set; `false` may require watermark-removal account permission. Unsupported providers ignore it |
-| `reference_images` | No | - | OpenAI reference images as local absolute paths or HTTP(S) URLs; Zhipu rejects this parameter |
+| `watermark_enabled` | No | - | Sent to Zhipu or mapped to MiniMax `aigc_watermark` only when explicitly supplied |
+| `reference_images` | No | - | OpenAI: 1–16; MiniMax: one PNG/JPEG under 10 MB; Zhipu rejects it |
 
-Without `reference_images`, the tool uses `/images/generations`. With OpenAI reference images, it uploads them as multipart `image[]` files to `/images/edits`.
+For OpenAI, calls without `reference_images` use `/images/generations`; reference images use multipart `/images/edits`. MiniMax always uses `/image_generation` and maps its single reference to `subject_reference`.
 
 Zhipu supports synchronous text-to-image only. It rejects `reference_images` before reading the referenced files or making a request, does not support `edit_image`, and ignores `output_format`. No Authorization header is sent to the image CDN, and the returned MCP MIME type is based on the downloaded image bytes.
 
@@ -254,6 +292,33 @@ Faster CogView request using provider-standard quality:
 
 Common Zhipu failures are returned as tool errors with the HTTP status and a provider response excerpt of at most 500 characters. Authentication failures must be fixed rather than retried; HTTP 429 with business code `1113` means the account balance is insufficient, while other 429 codes can indicate rate, model-load, or account-plan limits. ImageForge does not automatically retry paid generation requests. See the [official Zhipu error-code reference](https://docs.bigmodel.cn/cn/faq/api-code) for current business-code meanings.
 
+MiniMax text-to-image:
+
+```json
+{
+  "provider": "minimax",
+  "model": "image-01",
+  "prompt": "A quiet coastal village at sunrise, cinematic light, no text",
+  "size": "1536x1024",
+  "output_format": "jpeg",
+  "output_path": "outputs/minimax-village.jpeg"
+}
+```
+
+MiniMax single-subject reference generation:
+
+```json
+{
+  "provider": "minimax",
+  "model": "image-01",
+  "prompt": "Keep the reference character and place them in a quiet library, natural light",
+  "reference_images": ["/absolute/path/to/character.jpg"],
+  "output_format": "jpeg"
+}
+```
+
+MiniMax requires exactly one `reference_images` entry for this mode. `image-01-live` converts `size` to an exact supported aspect ratio instead of sending custom dimensions.
+
 ## `edit_image`
 
 `edit_image` uses the same model, API, output, and local-save parameters as `generate_image`, but requires `input_images`:
@@ -271,6 +336,22 @@ When `output_path` is supplied, ImageForge MCP returns the native MCP image cont
 
 Some OpenAI-compatible gateways may return dimensions different from the requested `size`; the actual returned file dimensions are authoritative.
 
+## Maintainer release script
+
+Run the release workflow from a Git checkout of this repository:
+
+```bash
+# Read-only checks; allows a dirty worktree but prints a warning.
+bash script/release.sh
+
+# Actual npm publication.
+bash script/release.sh --publish
+```
+
+The default check mode verifies version consistency, Git whitespace, TypeScript build, all tests, production dependency audit, the npm file list, npm publication dry-run, npm authentication when available, and whether the current version already exists in the Registry. If the version exists but its Registry shasum differs from the local package, the check fails and requires a version bump.
+
+`--publish` additionally requires branch `main`, a clean worktree, local `HEAD` equal to `origin/main`, an authenticated npm account, and an unpublished package version. It publishes with public access and the `latest` tag, then waits for the exact version and `latest` tag to become visible in the Registry and prints the Registry shasum. The script intentionally does not change versions, create commits, push Git branches, create tags, retry a failed publication, or overwrite an existing npm version.
+
 ## Verification
 
 ```bash
@@ -288,19 +369,19 @@ Tests use a local HTTP mock. They do not call a real image API or incur generati
 
 # 中文说明
 
-ImageForge MCP 是一个轻量的 TypeScript MCP 图片生成与编辑服务，支持通过 OpenAI Images API 调用 `gpt-image-2`，并支持通过智谱 BigModel API 进行文生图。
+ImageForge MCP 是一个轻量的 TypeScript MCP 图片生成与编辑服务，支持 22 个原厂生图 Provider，并保留 OpenAI 图片编辑能力。
 
-- OpenAI 纯文本生图调用 `POST /v1/images/generations`；智谱调用 `POST /api/paas/v4/images/generations`。
+- 各 Provider 按官方同步接口或“提交任务后轮询”REST 契约调用。
 - OpenAI 图片编辑和参考图生图调用 multipart `POST /v1/images/edits`。
 - 生成结果以原生 MCP `image` 内容块返回，也可以同时保存到本地。
 
 ## 功能
 
-- OpenAI 模型：`gpt-image-2`
-- 智谱模型：`glm-image`、`cogview-4-250304`、`cogview-4`、`cogview-3-flash`
-- MCP 工具：`generate_image`、`edit_image`
+- 22 个 Provider ID：`openai`、`zhipu`、`minimax`、`google`、`xai`、`stability`、`ideogram`、`recraft`、`tencent`、`baidu`、`playground`、`bfl`、`luma`、`krea`、`runway`、`leonardo`、`bria`、`freepik`、`alibaba`、`volcengine`、`kling`、`hidream`
+- MCP 工具：`generate_image`、`list_image_providers`、`edit_image`
 - 支持纯文本生图
 - 支持一张或多张参考图引导生图
+- 支持 MiniMax 单张主体参考图生图
 - 支持一张或多张图片编辑
 - 输入图片支持本地绝对路径和 HTTP(S) URL
 - 输入与输出支持 PNG、JPEG、WebP
@@ -312,16 +393,15 @@ ImageForge MCP 是一个轻量的 TypeScript MCP 图片生成与编辑服务，
 
 ## 供应商能力矩阵
 
-| 能力 | OpenAI | 智谱 |
+| 分组 | Provider | 执行方式 |
 | --- | --- | --- |
-| 文生图 | 支持 | 支持 |
-| 参考图生图 | 支持，通过 `reference_images` | 不支持；会在读取文件和发送请求前明确报错 |
-| 图片编辑 | 支持，通过 `edit_image` | 不支持 |
-| 模型 | `gpt-image-2` | `glm-image`、`cogview-4-250304`、`cogview-4`、`cogview-3-flash` |
-| quality | `auto`、`low`、`medium`、`high` | `glm-image`：`auto`、`hd`；其他模型：`auto`、`standard`、`hd` |
-| `watermark_enabled` | 静默忽略 | 仅显式传入时转发 |
-| `output_format` | 发送给供应商 | 忽略，以下载图片的真实 MIME 为准 |
-| 供应商响应 | Base64 图片数据 | 临时图片 URL，由 ImageForge 立即下载 |
+| 现有兼容 | OpenAI、智谱、MiniMax | 同步 |
+| 新增同步接口 | Google Gemini、xAI、Stability AI、Ideogram、Recraft、腾讯混元、百度千帆、Playground、火山方舟 | 同步 |
+| 任务型接口 | Black Forest Labs、Luma、Krea、Runway、Leonardo、Bria、Freepik/Magnific、阿里 Model Studio、Kling、HiDream | 创建一次，随后只读轮询 |
+
+调用 `list_image_providers` 可查询权威模型列表、默认模型、参考图模式和上限、环境变量名、官方文档地址与合约验证状态。0.6.0 新增适配器均按官方文档和 Mock 合约测试实现，不宣称已经使用真实密钥验收。
+
+`generate_image` 在原参数上新增 `reference_mode`（`auto`、`content`、`style`、`character`）、`aspect_ratio`、`resolution`、`negative_prompt` 和 `seed`；不支持的组合会在访问供应商前失败。`edit_image` 仍仅支持 OpenAI。
 
 ## 智谱 BigModel 支持
 
@@ -347,6 +427,20 @@ ImageForge 使用 Bearer 认证调用智谱官方图片生成接口，各模型
 
 智谱服务端当前尺寸、质量、水印和账号政策应以[官方图片生成 API 文档](https://docs.bigmodel.cn/api-reference/%E6%A8%A1%E5%9E%8B-api/%E5%9B%BE%E5%83%8F%E7%94%9F%E6%88%90)为准。
 
+## MiniMax 支持
+
+ImageForge 使用 Bearer 认证调用 `POST /v1/image_generation`，固定请求一张 Base64 图片，并根据解码后的真实图片内容返回 MIME。支持 `image-01` 和 `image-01-live`，MiniMax 密钥不会回退到 OpenAI 或智谱配置。
+
+- `image-01`：将 `size` 转为 `width`、`height`，宽高须在 512–2048、均为 8 的倍数，且总像素不少于 `1024×1024`。
+- `image-01-live`：将 `size` 约分为精确支持的宽高比；不支持的比例在请求前失败。
+- `quality` 仅接受 `auto`。
+- 输出仅支持 JPEG；省略 `output_format` 或传 `jpeg`，传 `png`/`webp` 会在请求前失败，不做本地转码。
+- `reference_images` 最多一张 PNG/JPEG 且小于 10 MB，安全加载后以 `character` 主体 Data URL 发送。
+- `watermark_enabled` 仅显式传入时映射为 `aigc_watermark`。
+- 不自动重试收费请求，也不自动切换供应商。
+
+供应商行为以 [MiniMax 官方图片生成指南](https://platform.minimaxi.com/docs/guides/image-generation)为准。
+
 ## OpenAI 兼容 CPA 与网关
 
 ImageForge MCP 不仅支持 OpenAI 官方接口，也支持实现了 OpenAI Images API 兼容协议的 CPA、中转或代理服务，包括基于 **New API**、**CLI Proxy API** 等项目部署的 OpenAI 兼容网关。
@@ -363,7 +457,7 @@ ImageForge MCP 不仅支持 OpenAI 官方接口，也支持实现了 OpenAI Imag
 ## 环境要求
 
 - Node.js 22 或更高版本
-- OpenAI API Key，或 OpenAI 兼容 CPA/网关签发的令牌
+- 所选 Provider 的凭据；完整变量名见 `.env.example` 或 `list_image_providers`
 
 ## 安装与构建
 
@@ -393,7 +487,7 @@ npm run build
 }
 ```
 
-`-y` 允许 `npx` 在没有交互式安装提示的情况下下载或更新包。如果部署需要固定版本，可将包名写成 `"imageforge-mcp@0.4.0"`。
+`-y` 允许 `npx` 在没有交互式安装提示的情况下下载或更新包。如果部署需要固定版本，可将包名写成 `"imageforge-mcp@0.6.0"`。
 
 如果希望 MCP 默认使用智谱，应使用独立的智谱凭据与供应商配置：
 
@@ -402,7 +496,7 @@ npm run build
   "mcpServers": {
     "imageforge-zhipu": {
       "command": "npx",
-      "args": ["-y", "imageforge-mcp@0.4.0"],
+      "args": ["-y", "imageforge-mcp@0.6.0"],
       "env": {
         "IMAGEFORGE_PROVIDER": "zhipu",
         "ZHIPU_API_KEY": "你的智谱令牌",
@@ -415,6 +509,26 @@ npm run build
 
 `ZHIPU_BASE_URL` 可选，默认值为 `https://open.bigmodel.cn/api/paas/v4`；`ZHIPU_IMAGE_MODEL` 可选，默认值为 `glm-image`。智谱与 OpenAI 的环境密钥不会互相回退。单次调用传入的 `provider`、`api_key`、`base_url` 或 `model` 优先于对应环境变量。
 
+MiniMax 默认配置示例：
+
+```json
+{
+  "mcpServers": {
+    "imageforge-minimax": {
+      "command": "npx",
+      "args": ["-y", "imageforge-mcp@0.6.0"],
+      "env": {
+        "IMAGEFORGE_PROVIDER": "minimax",
+        "MINIMAX_API_KEY": "你的-MiniMax-令牌",
+        "MINIMAX_IMAGE_MODEL": "image-01"
+      }
+    }
+  }
+}
+```
+
+`MINIMAX_BASE_URL` 默认 `https://api.minimaxi.com/v1`，`MINIMAX_IMAGE_MODEL` 默认 `image-01`。MiniMax、OpenAI 与智谱凭据互不回退。
+
 `OPENAI_BASE_URL` 是可选配置。不设置时，ImageForge MCP 默认使用 OpenAI 官方接口 `https://api.openai.com/v1`。只有使用 New API、CLI Proxy API 或其他 OpenAI 兼容网关时才需要设置：
 
 ```json
@@ -425,6 +539,8 @@ npm run build
 
 `IMAGEFORGE_INPUT_CONCURRENCY` 可选，用于控制同时加载的本地或远程输入图片数量。默认值为 `4`，必须是正整数，并直接受单次最多 `16` 张输入图片的限制。单次调用的输入图片合计大小仍固定限制为 200 MB。
 
+任务型 Provider 只提交一次收费生图请求，之后仅轮询只读状态接口。`IMAGEFORGE_ASYNC_TIMEOUT_MS` 默认 `300000`、范围 30000–600000；`IMAGEFORGE_POLL_INTERVAL_MS` 默认 `2000`、范围 500–10000。轮询会在同一边界内遵循数值型 `Retry-After`。ImageForge 不使用 webhook、不重试收费创建请求，也不回退到其他 Provider。
+
 DNS 安全检查默认启用。只有确实需要访问私有网络地址或 DNS 代理生成的图片地址时，才应设置 `IMAGEFORGE_SKIP_DNS_SAFETY_CHECKS=true`。启用后，每次重定向都不再执行非公网地址拦截和 DNS 地址固定，可能使 MCP 进程面临 SSRF 风险。HTTP(S) 协议限制、URL 凭据限制、重定向次数、图片大小和图片魔数校验仍然有效。真值支持 `true`、`1`、`yes`、`on`，假值支持 `false`、`0`、`no`、`off`。
 
 不要把真实 API Key 写入 Git 或其他共享配置文件。
@@ -438,7 +554,7 @@ DNS 安全检查默认启用。只有确实需要访问私有网络地址或 DNS
 command = "/你的/node/绝对路径"
 args = ["/你的/ImageForgeMCP/绝对路径/dist/index.js"]
 cwd = "/你的/ImageForgeMCP/绝对路径"
-env_vars = ["OPENAI_API_KEY", "OPENAI_BASE_URL", "OPENAI_IMAGE_MODEL", "ZHIPU_API_KEY", "ZHIPU_BASE_URL", "ZHIPU_IMAGE_MODEL", "IMAGEFORGE_PROVIDER", "IMAGEFORGE_INPUT_CONCURRENCY", "IMAGEFORGE_SKIP_DNS_SAFETY_CHECKS"]
+env_vars = ["OPENAI_API_KEY", "OPENAI_BASE_URL", "OPENAI_IMAGE_MODEL", "ZHIPU_API_KEY", "ZHIPU_BASE_URL", "ZHIPU_IMAGE_MODEL", "MINIMAX_API_KEY", "MINIMAX_BASE_URL", "MINIMAX_IMAGE_MODEL", "IMAGEFORGE_PROVIDER", "IMAGEFORGE_INPUT_CONCURRENCY", "IMAGEFORGE_SKIP_DNS_SAFETY_CHECKS"]
 startup_timeout_sec = 10
 tool_timeout_sec = 300
 enabled = true
@@ -466,9 +582,12 @@ export ZHIPU_IMAGE_MODEL="glm-image"
 # 可选：export ZHIPU_BASE_URL="https://open.bigmodel.cn/api/paas/v4"
 ```
 
+使用 MiniMax 时导出 `IMAGEFORGE_PROVIDER=minimax`、`MINIMAX_API_KEY`，并按需设置 `MINIMAX_IMAGE_MODEL=image-01` 或 `image-01-live`。
+
 Codex 只会加载已信任项目中的 `.codex/config.toml`。新增或修改 MCP 配置后，需要重新启动 Codex 或新建任务，再使用 `/mcp verbose` 确认 `imageforge_dev` 提供以下工具：
 
 - `generate_image`
+- `list_image_providers`
 - `edit_image`
 
 修改 TypeScript 源码后，需要重新构建并重启使用该 MCP 的任务：
@@ -484,18 +603,18 @@ npm run build
 | 参数 | 必填 | 默认值 | 说明 |
 | --- | --- | --- | --- |
 | `prompt` | 是 | - | 图片描述 |
-| `model` | 否 | 环境变量或供应商默认值 | OpenAI：`gpt-image-2`；智谱：`glm-image`、`cogview-4-250304`、`cogview-4`、`cogview-3-flash` |
-| `base_url` | 否 | `OPENAI_BASE_URL` 或 `ZHIPU_BASE_URL` | 单次调用覆盖对应供应商 API 地址 |
-| `api_key` | 否 | `OPENAI_API_KEY` 或 `ZHIPU_API_KEY` | 单次调用覆盖对应供应商密钥；推荐使用环境变量 |
-| `provider` | 否 | `IMAGEFORGE_PROVIDER`，再默认 `openai` | `openai` 或 `zhipu` |
+| `model` | 否 | 环境变量或供应商默认值 | OpenAI：`gpt-image-2`；智谱模型见上；MiniMax：`image-01`、`image-01-live` |
+| `base_url` | 否 | 供应商环境变量或官方默认值 | 单次调用覆盖对应供应商 API 地址 |
+| `api_key` | 否 | 供应商独立密钥 | 单次调用覆盖对应供应商密钥；推荐使用环境变量 |
+| `provider` | 否 | `IMAGEFORGE_PROVIDER`，再默认 `openai` | `openai`、`zhipu` 或 `minimax` |
 | `size` | 否 | `1024x1024` | 请求提供商输出的图片尺寸 |
-| `quality` | 否 | `auto` | OpenAI：`auto/low/medium/high`；`glm-image`：`auto/hd`；其他智谱模型：`auto/standard/hd` |
-| `output_format` | 否 | `png` | `png`、`jpeg`、`webp` |
+| `quality` | 否 | `auto` | OpenAI 与智谱取值见上；MiniMax 仅接受 `auto` |
+| `output_format` | 否 | `png`；MiniMax 为 `jpeg` | OpenAI：`png/jpeg/webp`；智谱忽略；MiniMax 仅接受 `jpeg` |
 | `output_path` | 否 | - | 本地保存路径；相对路径按 MCP 工作目录解析 |
-| `watermark_enabled` | 否 | - | 仅智谱显式传入时发送；`false` 可能需要账号去水印权限。不支持的供应商静默忽略 |
-| `reference_images` | 否 | - | OpenAI 参考图，支持本地绝对路径和 HTTP(S) URL；智谱会明确拒绝 |
+| `watermark_enabled` | 否 | - | 显式传入时发送给智谱，或映射为 MiniMax `aigc_watermark` |
+| `reference_images` | 否 | - | OpenAI：1–16 张；MiniMax：单张小于 10 MB 的 PNG/JPEG；智谱拒绝 |
 
-不传 `reference_images` 时调用 `/images/generations`；OpenAI 传入参考图时，将图片作为 multipart `image[]` 文件上传到 `/images/edits`。
+OpenAI 不传 `reference_images` 时调用 `/images/generations`，传入参考图时调用 multipart `/images/edits`。MiniMax 始终调用 `/image_generation`，并把单张参考图映射为 `subject_reference`。
 
 智谱首版仅支持同步文生图，不支持参考图和 `edit_image`。传入 `reference_images` 时会在读取参考文件和发起请求前明确报错；`output_format` 对智谱不生效。下载图片时不携带 Authorization，最终 MCP MIME 类型以实际图片内容为准。
 
@@ -539,6 +658,33 @@ CogView 使用供应商标准质量快速生成：
 
 智谱失败会作为 MCP 工具错误返回，包含 HTTP 状态和最多 500 个字符的供应商错误摘要。认证失败必须修正配置而不是重试；HTTP 429 且业务错误码为 `1113` 表示账户欠费，其他 429 错误也可能表示限流、模型繁忙或套餐限制。ImageForge 不会自动重试可能产生费用的生图请求。业务错误码的当前含义以[智谱官方错误码文档](https://docs.bigmodel.cn/cn/faq/api-code)为准。
 
+MiniMax 文生图示例：
+
+```json
+{
+  "provider": "minimax",
+  "model": "image-01",
+  "prompt": "日出时宁静的海滨村庄，电影光线，无文字",
+  "size": "1536x1024",
+  "output_format": "jpeg",
+  "output_path": "outputs/minimax-village.jpeg"
+}
+```
+
+MiniMax 单主体参考图示例：
+
+```json
+{
+  "provider": "minimax",
+  "model": "image-01",
+  "prompt": "保持参考人物特征，将人物置于安静的图书馆，自然光",
+  "reference_images": ["/参考人物图片的绝对路径/character.jpg"],
+  "output_format": "jpeg"
+}
+```
+
+该模式的 `reference_images` 必须恰好一张；`image-01-live` 会把 `size` 转成精确支持的宽高比，而不是发送自定义尺寸。
+
 ## `edit_image`
 
 `edit_image` 与 `generate_image` 使用相同的模型、API、输出和本地保存参数，但 `input_images` 必填：
@@ -556,6 +702,22 @@ CogView 使用供应商标准质量快速生成：
 
 部分 OpenAI 兼容网关可能不会严格遵循请求中的 `size`，应以实际返回文件的尺寸为准。
 
+## 维护者发布脚本
+
+发布流程应在本仓库的 Git checkout 中执行：
+
+```bash
+# 只读检查；工作区不干净时会警告，但继续检查。
+bash script/release.sh
+
+# 实际发布到 npm。
+bash script/release.sh --publish
+```
+
+默认检查模式会验证版本一致性、Git 空白、TypeScript 构建、全部测试、生产依赖审计、npm 打包文件列表、npm 发布 dry-run、可用时的 npm 登录状态，以及当前版本是否已经存在于 Registry。如果版本已存在但 Registry shasum 与本地包不一致，检查会失败并要求先升级版本号。
+
+`--publish` 还会强制要求当前分支为 `main`、工作区干净、本地 `HEAD` 与 `origin/main` 完全一致、npm 已登录且版本尚未发布；随后以 public access 和 `latest` tag 发布，等待 Registry 可查询到准确版本和 `latest` tag，再输出 Registry shasum。脚本不会修改版本号、创建 Git 提交、推送分支、创建 Tag、自动重试失败发布或覆盖已存在的 npm 版本。
+
 ## 验证
 
 ```bash

package/dist/externalProviders.d.ts

@@ -0,0 +1,71 @@
+import { type LoadedImage } from "./imageInput.js";
+export declare const EXTERNAL_PROVIDER_IDS: readonly ["google", "xai", "stability", "ideogram", "recraft", "tencent", "baidu", "playground", "bfl", "luma", "krea", "runway", "leonardo", "bria", "freepik", "alibaba", "volcengine", "kling", "hidream"];
+export type ExternalProviderId = typeof EXTERNAL_PROVIDER_IDS[number];
+export type ReferenceMode = "auto" | "content" | "style" | "character";
+type Quality = "auto" | "low" | "medium" | "high" | "standard" | "hd";
+type OutputFormat = "png" | "jpeg" | "webp";
+export interface ExternalImageConfig {
+    provider: ExternalProviderId;
+    apiKey: string;
+    baseUrl: string;
+    model: string;
+}
+export interface ExternalGeneratedImage {
+    data: Buffer;
+    mimeType: "image/png" | "image/jpeg" | "image/webp";
+}
+interface ExternalRequestInput {
+    prompt: string;
+    config: ExternalImageConfig;
+    size: string;
+    quality: Quality;
+    outputFormat?: OutputFormat;
+    watermarkEnabled?: boolean;
+    inputImages?: LoadedImage[];
+    referenceMode?: ReferenceMode;
+    aspectRatio?: string;
+    resolution?: string;
+    negativePrompt?: string;
+    seed?: number;
+    fetchImpl?: typeof fetch;
+    downloadFetchImpl?: typeof fetch;
+}
+interface ProviderDefinition {
+    id: ExternalProviderId;
+    name: string;
+    docsUrl: string;
+    baseUrl: string;
+    baseUrlEnv: string;
+    apiKeyEnv: string;
+    modelEnv: string;
+    defaultModel: string;
+    models: readonly string[];
+    referenceModes: readonly ReferenceMode[];
+    maxReferences: number;
+    async: boolean;
+}
+export declare function isExternalProvider(value: string): value is ExternalProviderId;
+export declare function externalProviderDefinitions(): readonly ProviderDefinition[];
+export declare function resolveExternalConfig(input: {
+    provider: ExternalProviderId;
+    apiKey?: string;
+    baseUrl?: string;
+    model?: string;
+}): ExternalImageConfig;
+export declare function requestExternalImage(input: ExternalRequestInput): Promise<ExternalGeneratedImage>;
+export declare function externalCapabilities(): {
+    provider: "google" | "xai" | "stability" | "ideogram" | "recraft" | "tencent" | "baidu" | "playground" | "bfl" | "luma" | "krea" | "runway" | "leonardo" | "bria" | "freepik" | "alibaba" | "volcengine" | "kling" | "hidream";
+    name: string;
+    default_model: string;
+    models: string[];
+    reference_modes: ReferenceMode[];
+    max_reference_images: number;
+    async: boolean;
+    credential_environment_variables: string[];
+    base_url_environment_variable: string;
+    model_environment_variable: string;
+    docs_url: string;
+    implementation_basis: string;
+    live_verified: boolean;
+}[];
+export {};