imageforge-mcp 0.3.0 → 0.4.0

package/README.md

@@ -2,26 +2,66 @@
 
 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 generating and editing images with OpenAI `gpt-image-2`, and for text-to-image generation with Zhipu BigModel image models.
 
-- 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`.
+- 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`
 - 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
 - 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 |
+| --- | --- | --- |
+| 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 |
+
+## 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.
+
 ## 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 +78,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
+- An OpenAI API key or a compatible gateway token; a Zhipu API key is needed only when using the `zhipu` provider
 
 ## Install and build
 
@@ -49,25 +89,58 @@ 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"
+      }
+    }
+  }
+}
+```
+
+`-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"`.
+
+For a Zhipu-default MCP server, use an independent credential and provider configuration:
+
+```json
+{
+  "mcpServers": {
+    "imageforge-zhipu": {
+      "command": "npx",
+      "args": ["-y", "imageforge-mcp@0.4.0"],
+      "env": {
+        "IMAGEFORGE_PROVIDER": "zhipu",
+        "ZHIPU_API_KEY": "your-zhipu-token",
+        "ZHIPU_IMAGE_MODEL": "glm-image"
       }
     }
   }
 }
 ```
 
-`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.
+`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.
+
+`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 +153,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", "IMAGEFORGE_PROVIDER", "IMAGEFORGE_INPUT_CONCURRENCY", "IMAGEFORGE_SKIP_DNS_SAFETY_CHECKS"]
 startup_timeout_sec = 10
 tool_timeout_sec = 300
 enabled = true
@@ -93,11 +166,21 @@ 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"
+```
+
 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 +199,60 @@ 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: `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` |
 | `size` | No | `1024x1024` | Output size requested from the provider |
-| `quality` | No | `auto` | `auto`, `low`, `medium`, or `high` |
+| `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` |
 | `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 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 |
+
+Without `reference_images`, the tool uses `/images/generations`. With OpenAI reference images, it uploads them as multipart `image[]` files to `/images/edits`.
+
+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"
+}
+```
 
-Without `reference_images`, the tool uses `/images/generations`. With reference images, it uploads them as multipart `image[]` files to `/images/edits`.
+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.
 
 ## `edit_image`
 
@@ -136,7 +263,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.
 
@@ -161,26 +288,65 @@ 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 Images API 调用 `gpt-image-2`，并支持通过智谱 BigModel API 进行文生图。
 
-- 纯文本生图调用 `POST /v1/images/generations`。
-- 图片编辑和参考图生图调用 multipart `POST /v1/images/edits`。
+- OpenAI 纯文本生图调用 `POST /v1/images/generations`；智谱调用 `POST /api/paas/v4/images/generations`。
+- 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`
 - MCP 工具：`generate_image`、`edit_image`
 - 支持纯文本生图
 - 支持一张或多张参考图引导生图
 - 支持一张或多张图片编辑
 - 输入图片支持本地绝对路径和 HTTP(S) URL
 - 输入与输出支持 PNG、JPEG、WebP
-- 最多 16 张输入图片，每张不超过 50 MB
+- 最多 16 张输入图片，每张不超过 50 MB，单次调用合计不超过 200 MB
 - 支持通过 `output_path` 保存到本地，并自动创建父目录
-- URL 安全校验，拒绝访问环回、链路本地和私有网络地址
+- URL 安全校验，拒绝非公网地址，并将校验后的 DNS 地址固定到实际连接
+- 输入图片加载并发受控
 - stdio Transport
 
+## 供应商能力矩阵
+
+| 能力 | OpenAI | 智谱 |
+| --- | --- | --- |
+| 文生图 | 支持 | 支持 |
+| 参考图生图 | 支持，通过 `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 立即下载 |
+
+## 智谱 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)为准。
+
 ## OpenAI 兼容 CPA 与网关
 
 ImageForge MCP 不仅支持 OpenAI 官方接口，也支持实现了 OpenAI Images API 兼容协议的 CPA、中转或代理服务，包括基于 **New API**、**CLI Proxy API** 等项目部署的 OpenAI 兼容网关。
@@ -208,25 +374,58 @@ 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"
+      }
+    }
+  }
+}
+```
+
+`-y` 允许 `npx` 在没有交互式安装提示的情况下下载或更新包。如果部署需要固定版本，可将包名写成 `"imageforge-mcp@0.4.0"`。
+
+如果希望 MCP 默认使用智谱，应使用独立的智谱凭据与供应商配置：
+
+```json
+{
+  "mcpServers": {
+    "imageforge-zhipu": {
+      "command": "npx",
+      "args": ["-y", "imageforge-mcp@0.4.0"],
+      "env": {
+        "IMAGEFORGE_PROVIDER": "zhipu",
+        "ZHIPU_API_KEY": "你的智谱令牌",
+        "ZHIPU_IMAGE_MODEL": "glm-image"
       }
     }
   }
 }
 ```
 
-`OPENAI_BASE_URL` 默认是 `https://api.openai.com/v1`。使用 New API、CLI Proxy API 或其他 OpenAI 兼容网关时，应填写到 `/v1` 为止；服务会根据请求追加 `/images/generations` 或 `/images/edits`。
+`ZHIPU_BASE_URL` 可选，默认值为 `https://open.bigmodel.cn/api/paas/v4`；`ZHIPU_IMAGE_MODEL` 可选，默认值为 `glm-image`。智谱与 OpenAI 的环境密钥不会互相回退。单次调用传入的 `provider`、`api_key`、`base_url` 或 `model` 优先于对应环境变量。
+
+`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 +438,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", "IMAGEFORGE_PROVIDER", "IMAGEFORGE_INPUT_CONCURRENCY", "IMAGEFORGE_SKIP_DNS_SAFETY_CHECKS"]
 startup_timeout_sec = 10
 tool_timeout_sec = 300
 enabled = true
@@ -252,11 +451,21 @@ 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"
+```
+
 Codex 只会加载已信任项目中的 `.codex/config.toml`。新增或修改 MCP 配置后，需要重新启动 Codex 或新建任务，再使用 `/mcp verbose` 确认 `imageforge_dev` 提供以下工具：
 
 - `generate_image`
@@ -275,16 +484,60 @@ 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`；智谱：`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` |
 | `size` | 否 | `1024x1024` | 请求提供商输出的图片尺寸 |
-| `quality` | 否 | `auto` | `auto`、`low`、`medium`、`high` |
+| `quality` | 否 | `auto` | OpenAI：`auto/low/medium/high`；`glm-image`：`auto/hd`；其他智谱模型：`auto/standard/hd` |
 | `output_format` | 否 | `png` | `png`、`jpeg`、`webp` |
 | `output_path` | 否 | - | 本地保存路径；相对路径按 MCP 工作目录解析 |
-| `reference_images` | 否 | - | 参考图数组，支持本地绝对路径和 HTTP(S) URL |
+| `watermark_enabled` | 否 | - | 仅智谱显式传入时发送；`false` 可能需要账号去水印权限。不支持的供应商静默忽略 |
+| `reference_images` | 否 | - | OpenAI 参考图，支持本地绝对路径和 HTTP(S) URL；智谱会明确拒绝 |
+
+不传 `reference_images` 时调用 `/images/generations`；OpenAI 传入参考图时，将图片作为 multipart `image[]` 文件上传到 `/images/edits`。
+
+智谱首版仅支持同步文生图，不支持参考图和 `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"
+}
+```
 
-不传 `reference_images` 时调用 `/images/generations`；传入参考图时，将图片作为 multipart `image[]` 文件上传到 `/images/edits`。
+智谱失败会作为 MCP 工具错误返回，包含 HTTP 状态和最多 500 个字符的供应商错误摘要。认证失败必须修正配置而不是重试；HTTP 429 且业务错误码为 `1113` 表示账户欠费，其他 429 错误也可能表示限流、模型繁忙或套餐限制。ImageForge 不会自动重试可能产生费用的生图请求。业务错误码的当前含义以[智谱官方错误码文档](https://docs.bigmodel.cn/cn/faq/api-code)为准。
 
 ## `edit_image`
 
@@ -295,7 +548,7 @@ npm run build
 | `prompt` | 是 | 编辑指令 |
 | `input_images` | 是 | 1–16 张输入图片，支持本地绝对路径或 HTTP(S) URL |
 
-本地图片会直接读取；URL 图片会经过下载和安全校验后再上传。解析到环回、链路本地或私有地址的 URL 会被拒绝。
+本地图片会直接读取；URL 图片会经过下载和安全校验后再上传。每次重定向都会重新校验目标地址，非公网地址会被拒绝，同时会将校验后的 DNS 结果固定到实际连接，防止校验与下载之间发生 DNS Rebinding。
 
 配置优先级为：工具参数、环境变量、内置默认值。
 

package/dist/imageInput.d.ts

@@ -1,10 +1,40 @@
+import { type LookupFunction } from "node:net";
+import { type Dispatcher } from "undici";
 export declare const MAX_INPUT_IMAGES = 16;
 export declare const MAX_IMAGE_BYTES: number;
+export declare const MAX_TOTAL_IMAGE_BYTES: number;
+export declare const DEFAULT_INPUT_CONCURRENCY = 4;
 export interface LoadedImage {
     data: Buffer;
     fileName: string;
     mimeType: "image/png" | "image/jpeg" | "image/webp";
 }
-export declare function loadRemoteImage(source: string, fetchImpl?: typeof fetch): Promise<LoadedImage>;
-export declare function loadLocalImage(source: string): Promise<LoadedImage>;
-export declare function loadImages(sources: string[]): Promise<LoadedImage[]>;
+interface ResolvedAddress {
+    address: string;
+    family: number;
+}
+interface ImageByteBudget {
+    readonly remaining: number;
+    reserve(bytes: number): void;
+    release(bytes: number): void;
+}
+interface RemoteRequestInit extends RequestInit {
+    dispatcher?: Dispatcher;
+}
+export type AddressResolver = (hostname: string) => Promise<ResolvedAddress[]>;
+export type RemoteFetch = (input: URL, init: RemoteRequestInit) => Promise<Response>;
+export interface LoadImagesOptions {
+    concurrency?: number;
+    maxTotalBytes?: number;
+    fetchImpl?: RemoteFetch;
+    resolveImpl?: AddressResolver;
+    skipDnsSafetyChecks?: boolean;
+}
+export declare function isPublicAddress(address: string): boolean;
+export declare function createPinnedLookup(addresses: ResolvedAddress[]): LookupFunction;
+export declare function loadRemoteImage(source: string, fetchImpl?: RemoteFetch, resolveImpl?: AddressResolver, budget?: ImageByteBudget, skipDnsSafetyChecks?: boolean): Promise<LoadedImage>;
+export declare function loadLocalImage(source: string, budget?: ImageByteBudget): Promise<LoadedImage>;
+export declare function resolveInputConcurrency(value?: string | number | undefined): number;
+export declare function resolveSkipDnsSafetyChecks(value?: string | boolean | undefined): boolean;
+export declare function loadImages(sources: string[], options?: LoadImagesOptions): Promise<LoadedImage[]>;
+export {};