imageforge-mcp 0.3.0 → 0.5.0

package/README.md

@@ -2,26 +2,82 @@
 
 English | [中文](#中文说明)
 
-A lightweight TypeScript MCP server for generating and editing images with `gpt-image-2` through the OpenAI Images API.
+A lightweight TypeScript MCP server for image generation with OpenAI, Zhipu BigModel, and MiniMax, plus OpenAI image editing.
 
-- Text-to-image requests use `POST /v1/images/generations`.
-- Image editing and reference-image generation use multipart `POST /v1/images/edits`.
+- OpenAI text-to-image requests use `POST /v1/images/generations`; Zhipu uses `POST /api/paas/v4/images/generations`; MiniMax uses `POST /v1/image_generation`.
+- 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
 
-- Model: `gpt-image-2`
+- OpenAI model: `gpt-image-2`
+- Zhipu models: `glm-image`, `cogview-4-250304`, `cogview-4`, `cogview-3-flash`
+- MiniMax models: `image-01`, `image-01-live`
 - MCP tools: `generate_image` 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
-- Up to 16 input images, with a 50 MB limit per image
+- Up to 16 input images, with a 50 MB limit per image and a 200 MB combined limit
 - Optional local output path with automatic parent-directory creation
-- Safe URL validation against loopback, link-local, and private network targets
+- URL validation against non-public network targets, with DNS addresses pinned to the actual connection
+- Bounded input loading concurrency
 - stdio transport
 
+## Provider capability matrix
+
+| Capability | OpenAI | Zhipu | MiniMax |
+| --- | --- | --- | --- |
+| Text-to-image | Yes | Yes | Yes |
+| Reference-image generation | Yes, 1–16 images | No; fails before reading files or sending a request | Yes, exactly one PNG/JPEG subject reference under 10 MB |
+| Image editing | Yes, through `edit_image` | No | No |
+| Models | `gpt-image-2` | `glm-image`, `cogview-4-250304`, `cogview-4`, `cogview-3-flash` | `image-01`, `image-01-live` |
+| Quality values | `auto`, `low`, `medium`, `high` | `glm-image`: `auto`, `hd`; other models: `auto`, `standard`, `hd` | `auto` only |
+| `watermark_enabled` | Ignored without error | Forwarded only when explicitly supplied | Mapped to `aigc_watermark` when explicitly supplied |
+| `output_format` | Sent to the provider | Ignored; actual MIME is authoritative | JPEG only; other values fail before the request |
+| Provider response | Base64 image data | Temporary image URL, downloaded immediately | Base64 image data |
+
+## Zhipu BigModel support
+
+ImageForge calls the official Zhipu image generation endpoint with Bearer authentication. The supported models and ImageForge behavior are:
+
+| Model | ImageForge quality values | Notes |
+| --- | --- | --- |
+| `glm-image` | `auto`, `hd` | Prompt is limited to 1,000 characters before the request is sent |
+| `cogview-4-250304` | `auto`, `standard`, `hd` | Text-to-image only |
+| `cogview-4` | `auto`, `standard`, `hd` | Text-to-image only |
+| `cogview-3-flash` | `auto`, `standard`, `hd` | Text-to-image only |
+
+`quality: "auto"` is an ImageForge compatibility value: it omits the `quality` field and lets Zhipu apply the model default. ImageForge validates only the `WIDTHxHEIGHT` shape of `size`; Zhipu remains authoritative for each model's supported dimensions and pixel limits. The MCP-level default remains `1024x1024` for compatibility across providers.
+
+Zhipu returns one temporary image URL. ImageForge downloads it immediately and returns native MCP image content after validating the actual PNG, JPEG, or WebP signature. The download always enforces public-address checks, DNS pinning, redirect revalidation, a 30-second timeout, and a 50 MB limit, even when `IMAGEFORGE_SKIP_DNS_SAFETY_CHECKS` is enabled for user-supplied OpenAI input images. Provider credentials are never forwarded to the image URL.
+
+`watermark_enabled` follows these rules:
+
+- Omitted: ImageForge does not send the field, so the Zhipu account/model default applies.
+- `true`: requests Zhipu's explicit and implicit watermarks.
+- `false`: requests Zhipu to disable watermarks; the account must have the required watermark-removal authorization. ImageForge never removes or edits a watermark locally.
+- OpenAI: the same unified parameter is silently ignored.
+
+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.
@@ -38,7 +94,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 token issued by a compatible CPA/gateway
+- A credential for the selected provider: OpenAI/gateway, Zhipu, or MiniMax
 
 ## Install and build
 
@@ -49,25 +105,78 @@ npm run build
 
 ## MCP client configuration
 
-Inject credentials through the MCP client environment:
+For production use, start the published npm package with `npx`. No repository clone or local build is required. Inject credentials through the MCP client environment:
 
 ```json
 {
   "mcpServers": {
     "imageforge": {
-      "command": "node",
-      "args": ["/absolute/path/to/ImageForgeMCP/dist/index.js"],
+      "command": "npx",
+      "args": ["-y", "imageforge-mcp"],
       "env": {
-        "OPENAI_BASE_URL": "https://your-openai-compatible-gateway.example/v1",
         "OPENAI_API_KEY": "your-token",
-        "OPENAI_IMAGE_MODEL": "gpt-image-2"
+        "OPENAI_IMAGE_MODEL": "gpt-image-2",
+        "IMAGEFORGE_PROVIDER": "openai",
+        "IMAGEFORGE_INPUT_CONCURRENCY": "4"
       }
     }
   }
 }
 ```
 
-`OPENAI_BASE_URL` defaults to `https://api.openai.com/v1`. Set it to the `/v1` root of your New API, CLI Proxy API, or other OpenAI-compatible gateway. ImageForge MCP appends `/images/generations` or `/images/edits` as required.
+`-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.5.0"`.
+
+For a Zhipu-default MCP server, use an independent credential and provider configuration:
+
+```json
+{
+  "mcpServers": {
+    "imageforge-zhipu": {
+      "command": "npx",
+      "args": ["-y", "imageforge-mcp@0.5.0"],
+      "env": {
+        "IMAGEFORGE_PROVIDER": "zhipu",
+        "ZHIPU_API_KEY": "your-zhipu-token",
+        "ZHIPU_IMAGE_MODEL": "glm-image"
+      }
+    }
+  }
+}
+```
+
+`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.5.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
+"OPENAI_BASE_URL": "https://your-openai-compatible-gateway.example/v1"
+```
+
+The value must point to the gateway's `/v1` root. ImageForge MCP appends `/images/generations` or `/images/edits` as required.
+
+`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.
+
+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.
 
@@ -80,7 +189,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"]
+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
@@ -93,11 +202,23 @@ Export the environment variables before starting Codex:
 export OPENAI_API_KEY="your-gateway-token"
 export OPENAI_BASE_URL="https://your-openai-compatible-gateway.example/v1"
 export OPENAI_IMAGE_MODEL="gpt-image-2"
+export IMAGEFORGE_INPUT_CONCURRENCY="4"
 
 cd /absolute/path/to/ImageForgeMCP
 codex app
 ```
 
+For a Zhipu-default development process, export the Zhipu variables instead of the OpenAI credential/model variables:
+
+```bash
+export IMAGEFORGE_PROVIDER="zhipu"
+export ZHIPU_API_KEY="your-zhipu-token"
+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`
@@ -116,16 +237,87 @@ See the [official Codex MCP documentation](https://developers.openai.com/codex/m
 | Parameter | Required | Default | Description |
 | --- | --- | --- | --- |
 | `prompt` | Yes | - | Image description |
-| `model` | No | Environment or `gpt-image-2` | Only `gpt-image-2` is accepted |
-| `base_url` | No | `OPENAI_BASE_URL` | Per-call API base URL override |
-| `api_key` | No | `OPENAI_API_KEY` | Per-call credential override; environment variables are preferred |
+| `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` | `auto`, `low`, `medium`, or `high` |
-| `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 |
-| `reference_images` | No | - | Reference images as local absolute paths or HTTP(S) URLs |
+| `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 |
+
+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.
+
+Zhipu `glm-image` without an explicit quality or watermark override:
+
+```json
+{
+  "provider": "zhipu",
+  "model": "glm-image",
+  "prompt": "A hand-painted lakeside village at sunrise, warm light, no text",
+  "size": "1280x1280",
+  "quality": "auto"
+}
+```
+
+Zhipu `glm-image` requesting no provider watermark:
+
+```json
+{
+  "provider": "zhipu",
+  "model": "glm-image",
+  "prompt": "A clean studio product render on a neutral background, no text",
+  "size": "1280x1280",
+  "quality": "hd",
+  "watermark_enabled": false,
+  "output_path": "outputs/zhipu-product.png"
+}
+```
+
+Faster CogView request using provider-standard quality:
+
+```json
+{
+  "provider": "zhipu",
+  "model": "cogview-4",
+  "prompt": "A colorful editorial illustration of a modern city park, no text",
+  "size": "1024x1024",
+  "quality": "standard"
+}
+```
+
+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"
+}
+```
 
-Without `reference_images`, the tool uses `/images/generations`. With reference images, it uploads them as multipart `image[]` files to `/images/edits`.
+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`
 
@@ -136,7 +328,7 @@ Without `reference_images`, the tool uses `/images/generations`. With reference
 | `prompt` | Yes | Editing instructions |
 | `input_images` | Yes | 1–16 local absolute paths or HTTP(S) URLs |
 
-Local images are read directly. URL images are downloaded and validated before upload. URLs resolving to loopback, link-local, or private addresses are rejected.
+Local images are read directly. URL images are downloaded and validated before upload. Every redirect target is revalidated, non-public addresses are rejected, and the validated DNS results are pinned to the actual connection to prevent DNS rebinding between validation and download.
 
 Configuration precedence is: tool arguments, environment variables, then built-in defaults.
 
@@ -144,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
@@ -161,26 +369,81 @@ 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`。
+ImageForge MCP 是一个轻量的 TypeScript MCP 图片生成与编辑服务，支持 OpenAI、智谱 BigModel 和 MiniMax 生图，并保留 OpenAI 图片编辑能力。
 
-- 纯文本生图调用 `POST /v1/images/generations`。
-- 图片编辑和参考图生图调用 multipart `POST /v1/images/edits`。
+- OpenAI 纯文本生图调用 `POST /v1/images/generations`；智谱调用 `POST /api/paas/v4/images/generations`；MiniMax 调用 `POST /v1/image_generation`。
+- OpenAI 图片编辑和参考图生图调用 multipart `POST /v1/images/edits`。
 - 生成结果以原生 MCP `image` 内容块返回，也可以同时保存到本地。
 
 ## 功能
 
-- 模型：`gpt-image-2`
+- OpenAI 模型：`gpt-image-2`
+- 智谱模型：`glm-image`、`cogview-4-250304`、`cogview-4`、`cogview-3-flash`
+- MiniMax 模型：`image-01`、`image-01-live`
 - MCP 工具：`generate_image`、`edit_image`
 - 支持纯文本生图
 - 支持一张或多张参考图引导生图
+- 支持 MiniMax 单张主体参考图生图
 - 支持一张或多张图片编辑
 - 输入图片支持本地绝对路径和 HTTP(S) URL
 - 输入与输出支持 PNG、JPEG、WebP
-- 最多 16 张输入图片，每张不超过 50 MB
+- 最多 16 张输入图片，每张不超过 50 MB，单次调用合计不超过 200 MB
 - 支持通过 `output_path` 保存到本地，并自动创建父目录
-- URL 安全校验，拒绝访问环回、链路本地和私有网络地址
+- URL 安全校验，拒绝非公网地址，并将校验后的 DNS 地址固定到实际连接
+- 输入图片加载并发受控
 - stdio Transport
 
+## 供应商能力矩阵
+
+| 能力 | OpenAI | 智谱 | MiniMax |
+| --- | --- | --- | --- |
+| 文生图 | 支持 | 支持 | 支持 |
+| 参考图生图 | 支持 1–16 张 | 不支持；读取文件或请求前失败 | 支持单张 PNG/JPEG 主体参考图，小于 10 MB |
+| 图片编辑 | 支持，通过 `edit_image` | 不支持 | 不支持 |
+| 模型 | `gpt-image-2` | `glm-image`、`cogview-4-250304`、`cogview-4`、`cogview-3-flash` | `image-01`、`image-01-live` |
+| quality | `auto`、`low`、`medium`、`high` | `glm-image`：`auto`、`hd`；其他模型：`auto`、`standard`、`hd` | 仅 `auto` |
+| `watermark_enabled` | 静默忽略 | 仅显式传入时转发 | 显式传入时映射为 `aigc_watermark` |
+| `output_format` | 发送给供应商 | 忽略，以真实 MIME 为准 | 仅 JPEG，其他值在请求前失败 |
+| 供应商响应 | Base64 图片数据 | 临时图片 URL，由 ImageForge 立即下载 | Base64 图片数据 |
+
+## 智谱 BigModel 支持
+
+ImageForge 使用 Bearer 认证调用智谱官方图片生成接口，各模型在当前实现中的规则如下：
+
+| 模型 | ImageForge 接受的 quality | 说明 |
+| --- | --- | --- |
+| `glm-image` | `auto`、`hd` | 请求前限制提示词最多 1000 个字符 |
+| `cogview-4-250304` | `auto`、`standard`、`hd` | 仅支持文生图 |
+| `cogview-4` | `auto`、`standard`、`hd` | 仅支持文生图 |
+| `cogview-3-flash` | `auto`、`standard`、`hd` | 仅支持文生图 |
+
+`quality: "auto"` 是 ImageForge 的兼容值，表示不向智谱发送 `quality`，由智谱使用对应模型的默认质量。ImageForge 对 `size` 只校验 `宽x高` 格式，具体尺寸、整除要求和像素上限以智谱接口为准；为了保持供应商间兼容，MCP 层默认尺寸仍为 `1024x1024`。
+
+智谱返回一张图片的临时 URL，ImageForge 会立即下载，并在验证实际内容为 PNG、JPEG 或 WebP 后返回原生 MCP 图片内容。即使用户为了 OpenAI 输入图设置了 `IMAGEFORGE_SKIP_DNS_SAFETY_CHECKS`，智谱结果图下载仍强制执行公网地址检查、DNS 固定、重定向复核、30 秒超时和 50 MB 限制，且不会把供应商认证信息转发给图片地址。
+
+`watermark_enabled` 规则：
+
+- 不传：ImageForge 不发送该字段，使用智谱账号或模型默认行为。
+- `true`：请求智谱添加显式水印和隐式数字水印。
+- `false`：请求智谱关闭水印，账号必须具备相应去水印权限；ImageForge 不会在本地擦除或修改水印。
+- OpenAI：统一参数会被静默忽略。
+
+智谱服务端当前尺寸、质量、水印和账号政策应以[官方图片生成 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 兼容网关。
@@ -197,7 +460,7 @@ ImageForge MCP 不仅支持 OpenAI 官方接口，也支持实现了 OpenAI Imag
 ## 环境要求
 
 - Node.js 22 或更高版本
-- OpenAI API Key，或 OpenAI 兼容 CPA/网关签发的令牌
+- 所选供应商对应的 OpenAI/网关、智谱或 MiniMax 密钥
 
 ## 安装与构建
 
@@ -208,25 +471,78 @@ npm run build
 
 ## MCP 客户端配置
 
-推荐通过 MCP 客户端环境变量注入密钥：
+生产环境推荐直接通过 `npx` 启动 npm 官方包，无需克隆仓库或在本地构建。通过 MCP 客户端环境变量注入密钥：
 
 ```json
 {
   "mcpServers": {
     "imageforge": {
-      "command": "node",
-      "args": ["/absolute/path/to/ImageForgeMCP/dist/index.js"],
+      "command": "npx",
+      "args": ["-y", "imageforge-mcp"],
       "env": {
-        "OPENAI_BASE_URL": "https://你的-OpenAI-兼容网关域名/v1",
         "OPENAI_API_KEY": "你的令牌",
-        "OPENAI_IMAGE_MODEL": "gpt-image-2"
+        "OPENAI_IMAGE_MODEL": "gpt-image-2",
+        "IMAGEFORGE_PROVIDER": "openai",
+        "IMAGEFORGE_INPUT_CONCURRENCY": "4"
       }
     }
   }
 }
 ```
 
-`OPENAI_BASE_URL` 默认是 `https://api.openai.com/v1`。使用 New API、CLI Proxy API 或其他 OpenAI 兼容网关时，应填写到 `/v1` 为止；服务会根据请求追加 `/images/generations` 或 `/images/edits`。
+`-y` 允许 `npx` 在没有交互式安装提示的情况下下载或更新包。如果部署需要固定版本，可将包名写成 `"imageforge-mcp@0.5.0"`。
+
+如果希望 MCP 默认使用智谱，应使用独立的智谱凭据与供应商配置：
+
+```json
+{
+  "mcpServers": {
+    "imageforge-zhipu": {
+      "command": "npx",
+      "args": ["-y", "imageforge-mcp@0.5.0"],
+      "env": {
+        "IMAGEFORGE_PROVIDER": "zhipu",
+        "ZHIPU_API_KEY": "你的智谱令牌",
+        "ZHIPU_IMAGE_MODEL": "glm-image"
+      }
+    }
+  }
+}
+```
+
+`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.5.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
+"OPENAI_BASE_URL": "https://你的-OpenAI-兼容网关域名/v1"
+```
+
+地址应填写到网关的 `/v1` 根路径为止，服务会根据请求追加 `/images/generations` 或 `/images/edits`。
+
+`IMAGEFORGE_INPUT_CONCURRENCY` 可选，用于控制同时加载的本地或远程输入图片数量。默认值为 `4`，必须是正整数，并直接受单次最多 `16` 张输入图片的限制。单次调用的输入图片合计大小仍固定限制为 200 MB。
+
+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 或其他共享配置文件。
 
@@ -239,7 +555,7 @@ npm run build
 command = "/你的/node/绝对路径"
 args = ["/你的/ImageForgeMCP/绝对路径/dist/index.js"]
 cwd = "/你的/ImageForgeMCP/绝对路径"
-env_vars = ["OPENAI_API_KEY", "OPENAI_BASE_URL", "OPENAI_IMAGE_MODEL"]
+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
@@ -252,11 +568,23 @@ required = false
 export OPENAI_API_KEY="你的网关令牌"
 export OPENAI_BASE_URL="https://你的-OpenAI-兼容网关域名/v1"
 export OPENAI_IMAGE_MODEL="gpt-image-2"
+export IMAGEFORGE_INPUT_CONCURRENCY="4"
 
 cd /你的/ImageForgeMCP/绝对路径
 codex app
 ```
 
+如果本地开发进程默认使用智谱，应改为导出智谱配置，不要复用 OpenAI 密钥或模型变量：
+
+```bash
+export IMAGEFORGE_PROVIDER="zhipu"
+export ZHIPU_API_KEY="你的智谱令牌"
+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`
@@ -275,16 +603,87 @@ npm run build
 | 参数 | 必填 | 默认值 | 说明 |
 | --- | --- | --- | --- |
 | `prompt` | 是 | - | 图片描述 |
-| `model` | 否 | 环境变量或 `gpt-image-2` | 仅接受 `gpt-image-2` |
-| `base_url` | 否 | `OPENAI_BASE_URL` | 单次调用覆盖 API 地址 |
-| `api_key` | 否 | `OPENAI_API_KEY` | 单次调用覆盖密钥；推荐使用环境变量 |
+| `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` | `auto`、`low`、`medium`、`high` |
-| `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 工作目录解析 |
-| `reference_images` | 否 | - | 参考图数组，支持本地绝对路径和 HTTP(S) URL |
+| `watermark_enabled` | 否 | - | 显式传入时发送给智谱，或映射为 MiniMax `aigc_watermark` |
+| `reference_images` | 否 | - | OpenAI：1–16 张；MiniMax：单张小于 10 MB 的 PNG/JPEG；智谱拒绝 |
+
+OpenAI 不传 `reference_images` 时调用 `/images/generations`，传入参考图时调用 multipart `/images/edits`。MiniMax 始终调用 `/image_generation`，并把单张参考图映射为 `subject_reference`。
+
+智谱首版仅支持同步文生图，不支持参考图和 `edit_image`。传入 `reference_images` 时会在读取参考文件和发起请求前明确报错；`output_format` 对智谱不生效。下载图片时不携带 Authorization，最终 MCP MIME 类型以实际图片内容为准。
+
+智谱 `glm-image`，不覆盖供应商默认质量和水印行为：
+
+```json
+{
+  "provider": "zhipu",
+  "model": "glm-image",
+  "prompt": "日出时分的手绘湖畔村庄，暖色光线，无文字",
+  "size": "1280x1280",
+  "quality": "auto"
+}
+```
+
+智谱 `glm-image` 请求关闭供应商水印：
+
+```json
+{
+  "provider": "zhipu",
+  "model": "glm-image",
+  "prompt": "中性背景上的干净棚拍产品渲染，无文字",
+  "size": "1280x1280",
+  "quality": "hd",
+  "watermark_enabled": false,
+  "output_path": "outputs/zhipu-product.png"
+}
+```
+
+CogView 使用供应商标准质量快速生成：
+
+```json
+{
+  "provider": "zhipu",
+  "model": "cogview-4",
+  "prompt": "色彩丰富的现代城市公园编辑插画，无文字",
+  "size": "1024x1024",
+  "quality": "standard"
+}
+```
+
+智谱失败会作为 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"
+}
+```
 
-不传 `reference_images` 时调用 `/images/generations`；传入参考图时，将图片作为 multipart `image[]` 文件上传到 `/images/edits`。
+MiniMax 单主体参考图示例：
+
+```json
+{
+  "provider": "minimax",
+  "model": "image-01",
+  "prompt": "保持参考人物特征，将人物置于安静的图书馆，自然光",
+  "reference_images": ["/参考人物图片的绝对路径/character.jpg"],
+  "output_format": "jpeg"
+}
+```
+
+该模式的 `reference_images` 必须恰好一张；`image-01-live` 会把 `size` 转成精确支持的宽高比，而不是发送自定义尺寸。
 
 ## `edit_image`
 
@@ -295,7 +694,7 @@ npm run build
 | `prompt` | 是 | 编辑指令 |
 | `input_images` | 是 | 1–16 张输入图片，支持本地绝对路径或 HTTP(S) URL |
 
-本地图片会直接读取；URL 图片会经过下载和安全校验后再上传。解析到环回、链路本地或私有地址的 URL 会被拒绝。
+本地图片会直接读取；URL 图片会经过下载和安全校验后再上传。每次重定向都会重新校验目标地址，非公网地址会被拒绝，同时会将校验后的 DNS 结果固定到实际连接，防止校验与下载之间发生 DNS Rebinding。
 
 配置优先级为：工具参数、环境变量、内置默认值。
 
@@ -303,6 +702,22 @@ npm run build
 
 部分 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