# ImageForge MCP

English | [中文](#中文说明)

A lightweight TypeScript MCP server for image generation across 22 first-party providers, plus OpenAI image editing.

- 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

- 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
- 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
- URL validation against non-public network targets, with DNS addresses pinned to the actual connection
- Bounded input loading concurrency
- stdio transport

## Provider capability matrix

| Group | Providers | Execution |
| --- | --- | --- |
| 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 known models, built-in default models, reference modes and limits, required environment-variable names, documentation URLs, and contract-verification state. The `models` list is informational, not exhaustive; `model_allowlist_enforced: false` means unlisted model names are accepted. New 0.6.0 adapters are implemented from official documentation and covered by mocks; they are not represented as live credential verification.

Model selection uses the first nonblank value in this order: the tool's `model` argument, the selected provider's model environment variable (for example `OPENAI_IMAGE_MODEL`), then its built-in default. To use your configured model, omit `model`. An explicit name such as `gpt-image-2.5` or a gateway alias overrides the environment and is not replaced with a known model. Model availability is decided by your provider; accepting a name does not guarantee that the model supports the adapter's API or parameters.

`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

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.

Compatibility depends on the gateway implementation rather than its product name:

- Text-to-image requires `POST /v1/images/generations`.
- Reference-image generation and editing require multipart `POST /v1/images/edits` with `image[]` file forwarding.
- Responses must include Base64 image data in `data[0].b64_json`.
- The gateway must accept the requested/configured model name and the Images API request format. `gpt-image-2` is the built-in fallback, not a required model name.

A gateway that only implements `/v1/images/generations` can be used for text-to-image generation, but not for reference-image generation or editing.

## Requirements

- Node.js 22 or later
- A credential for the selected provider; see `.env.example` or `list_image_providers`

## Install and build

```bash
npm install
npm run build
```

## MCP client configuration

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": "npx",
      "args": ["-y", "imageforge-mcp"],
      "env": {
        "OPENAI_API_KEY": "your-token",
        "OPENAI_IMAGE_MODEL": "gpt-image-2",
        "IMAGEFORGE_PROVIDER": "openai",
        "IMAGEFORGE_INPUT_CONCURRENCY": "4",
        "IMAGEFORGE_REQUEST_TIMEOUT_MS": "300000"
      }
    }
  }
}
```

`-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.2"`.

For a Zhipu-default MCP server, use an independent credential and provider configuration:

```json
{
  "mcpServers": {
    "imageforge-zhipu": {
      "command": "npx",
      "args": ["-y", "imageforge-mcp@0.6.2"],
      "env": {
        "IMAGEFORGE_PROVIDER": "zhipu",
        "ZHIPU_API_KEY": "your-zhipu-token",
        "ZHIPU_IMAGE_MODEL": "glm-image",
        "IMAGEFORGE_REQUEST_TIMEOUT_MS": "300000"
      }
    }
  }
}
```

`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.2"],
      "env": {
        "IMAGEFORGE_PROVIDER": "minimax",
        "MINIMAX_API_KEY": "your-minimax-token",
        "MINIMAX_IMAGE_MODEL": "image-01",
        "IMAGEFORGE_REQUEST_TIMEOUT_MS": "300000"
      }
    }
  }
}
```

`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.

Provider HTTP requests (generation, editing, task submission, and each status poll) default to a 300-second timeout. Override it with `IMAGEFORGE_REQUEST_TIMEOUT_MS=300000` in the MCP server environment. Unset or blank values use the default; other values must be decimal integers from 1 to 2147483647 milliseconds, otherwise the request fails before it is sent. Status polls are also capped by the remaining async deadline. This setting does not change the 30-second image download timeout, upstream gateway limits, or the MCP client tool timeout. Set the client timeout above the expected full operation duration; reconnect the MCP server after changing its environment.

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.

Timeout settings apply to different parts of an operation:

| Setting | Default | Scope |
| --- | --- | --- |
| `IMAGEFORGE_REQUEST_TIMEOUT_MS` | `300000` ms | Each provider HTTP request, including reading the response body |
| `IMAGEFORGE_ASYNC_TIMEOUT_MS` | `300000` ms | Polling window after an async task is submitted and its status URL is obtained |
| Image download timeout | `30000` ms | Each remote image download request; independent of provider request timeouts |
| MCP client tool timeout | Client-specific | The entire tool call, including input loading, generation/polling, and output handling |

For example, to allow a provider request up to 10 minutes, set `"IMAGEFORGE_REQUEST_TIMEOUT_MS": "600000"` in the MCP client's `env` object. For synchronous generation, allow more than 600 seconds in the client (for example, Codex `tool_timeout_sec = 660`). For async providers, budget for submission, polling, and downloads together. Increasing ImageForge's timeout does not extend a gateway's own deadline or prevent an upstream 504.

Set this variable in the MCP server environment, not in `generate_image` or `edit_image` arguments. `.env.example` is a configuration template; ImageForge does not automatically load a `.env` file. Either use the client's `env` configuration or export the variable before starting a client that forwards it.

After changing the configuration, restart or reconnect the MCP server. To use local source changes, run `npm run build` and launch the rebuilt `dist/index.js` as shown below. An `npx imageforge-mcp` process uses the published npm package, so a local build does not update it. `IMAGEFORGE_REQUEST_TIMEOUT_MS` is available starting in 0.6.2. Older releases with the fixed 120-second timeout do not recognize it; upgrade to 0.6.2 or later, or use a local build.

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.

## Codex local development configuration

Create a project-scoped `.codex/config.toml` using paths that match your machine:

```toml
[mcp_servers.imageforge_dev]
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", "MINIMAX_API_KEY", "MINIMAX_BASE_URL", "MINIMAX_IMAGE_MODEL", "IMAGEFORGE_PROVIDER", "IMAGEFORGE_INPUT_CONCURRENCY", "IMAGEFORGE_SKIP_DNS_SAFETY_CHECKS", "IMAGEFORGE_REQUEST_TIMEOUT_MS"]
startup_timeout_sec = 10
tool_timeout_sec = 360
enabled = true
required = false
```

Export the environment variables before starting Codex:

```bash
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"
export IMAGEFORGE_REQUEST_TIMEOUT_MS="300000"

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`
- `list_image_providers`
- `edit_image`

After changing the TypeScript source, rebuild `dist/index.js` and restart the task using the MCP server:

```bash
npm run build
```

See the [official Codex MCP documentation](https://developers.openai.com/codex/mcp) for all configuration options.

## `generate_image`

| Parameter | Required | Default | Description |
| --- | --- | --- | --- |
| `prompt` | Yes | - | Image description |
| `model` | No | Environment or provider default | Any provider model name; overrides the environment. Known examples: OpenAI `gpt-image-2`, Zhipu models above, MiniMax `image-01` / `image-01-live`. No model allowlist. |
| `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 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 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"
}
```

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`:

| Parameter | Required | Description |
| --- | --- | --- |
| `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. 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.

When `output_path` is supplied, ImageForge MCP returns the native MCP image content block, saves the decoded image, and includes the final absolute path in a text content block. Missing parent directories are created automatically. Existing files are not overwritten.

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
npm test
npm run check
```

Tests use a local HTTP mock. They do not call a real image API or incur generation charges.

## License

[MIT](./LICENSE)

---

# 中文说明

ImageForge MCP 是一个轻量的 TypeScript MCP 图片生成与编辑服务，支持 22 个原厂生图 Provider，并保留 OpenAI 图片编辑能力。

- 各 Provider 按官方同步接口或“提交任务后轮询”REST 契约调用。
- OpenAI 图片编辑和参考图生图调用 multipart `POST /v1/images/edits`。
- 生成结果以原生 MCP `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
- 最多 16 张输入图片，每张不超过 50 MB，单次调用合计不超过 200 MB
- 支持通过 `output_path` 保存到本地，并自动创建父目录
- URL 安全校验，拒绝非公网地址，并将校验后的 DNS 地址固定到实际连接
- 输入图片加载并发受控
- stdio Transport

## 供应商能力矩阵

| 分组 | Provider | 执行方式 |
| --- | --- | --- |
| 现有兼容 | 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` 可查询已适配模型、内置默认模型、参考图模式和上限、环境变量名、官方文档地址与合约验证状态。`models` 仅为参考清单，并非完整列表；`model_allowlist_enforced: false` 表示接受清单之外的模型名称。0.6.0 新增适配器均按官方文档和 Mock 合约测试实现，不宣称已经使用真实密钥验收。

模型按第一个非空值选择，优先级为：工具传入的 `model` → 对应供应商的模型环境变量（如 `OPENAI_IMAGE_MODEL`）→ 内置默认模型。要使用已配置的模型，请省略 `model`。显式传入 `gpt-image-2.5` 或网关自定义别名时，会覆盖环境变量，不会被替换为清单内的模型。模型是否可用由供应商决定；接受模型名称不代表该模型一定兼容当前适配器使用的接口和参数。

`generate_image` 在原参数上新增 `reference_mode`（`auto`、`content`、`style`、`character`）、`aspect_ratio`、`resolution`、`negative_prompt` 和 `seed`；不支持的组合会在访问供应商前失败。`edit_image` 仍仅支持 OpenAI。

## 智谱 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 兼容网关。

是否兼容取决于网关实现的接口能力，而不是产品名称：

- 纯文本生图需要实现 `POST /v1/images/generations`。
- 参考图生图和图片编辑需要实现 multipart `POST /v1/images/edits`，并正确转发 `image[]` 文件。
- 响应需要在 `data[0].b64_json` 中返回 Base64 图片数据。
- 网关需要接受实际传入或配置的模型名称与 Images API 请求格式；`gpt-image-2` 是内置回退值，不是强制模型名。

如果网关只实现了 `/v1/images/generations`，仍可用于纯文本生图，但不能使用参考图生图和图片编辑。

## 环境要求

- Node.js 22 或更高版本
- 所选 Provider 的凭据；完整变量名见 `.env.example` 或 `list_image_providers`

## 安装与构建

```bash
npm install
npm run build
```

## MCP 客户端配置

生产环境推荐直接通过 `npx` 启动 npm 官方包，无需克隆仓库或在本地构建。通过 MCP 客户端环境变量注入密钥：

```json
{
  "mcpServers": {
    "imageforge": {
      "command": "npx",
      "args": ["-y", "imageforge-mcp"],
      "env": {
        "OPENAI_API_KEY": "你的令牌",
        "OPENAI_IMAGE_MODEL": "gpt-image-2",
        "IMAGEFORGE_PROVIDER": "openai",
        "IMAGEFORGE_INPUT_CONCURRENCY": "4",
        "IMAGEFORGE_REQUEST_TIMEOUT_MS": "300000"
      }
    }
  }
}
```

`-y` 允许 `npx` 在没有交互式安装提示的情况下下载或更新包。如果部署需要固定版本，可将包名写成 `"imageforge-mcp@0.6.2"`。

如果希望 MCP 默认使用智谱，应使用独立的智谱凭据与供应商配置：

```json
{
  "mcpServers": {
    "imageforge-zhipu": {
      "command": "npx",
      "args": ["-y", "imageforge-mcp@0.6.2"],
      "env": {
        "IMAGEFORGE_PROVIDER": "zhipu",
        "ZHIPU_API_KEY": "你的智谱令牌",
        "ZHIPU_IMAGE_MODEL": "glm-image",
        "IMAGEFORGE_REQUEST_TIMEOUT_MS": "300000"
      }
    }
  }
}
```

`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.2"],
      "env": {
        "IMAGEFORGE_PROVIDER": "minimax",
        "MINIMAX_API_KEY": "你的-MiniMax-令牌",
        "MINIMAX_IMAGE_MODEL": "image-01",
        "IMAGEFORGE_REQUEST_TIMEOUT_MS": "300000"
      }
    }
  }
}
```

`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。

供应商 HTTP 请求（生图、编辑、任务提交以及每次状态轮询）默认超时为 300 秒。可在 MCP 服务进程环境中设置 `IMAGEFORGE_REQUEST_TIMEOUT_MS=300000` 覆盖，单位为毫秒。未设置或空白值使用默认值；其他值必须为 1–2147483647 的十进制整数，否则会在发送请求前报错。每次轮询还受异步任务剩余时限约束。该设置不改变图片下载的 30 秒超时、上游网关限制或 MCP 客户端工具超时。客户端超时应大于预计的完整操作耗时；修改环境变量后需要重新连接 MCP 服务。

任务型 Provider 只提交一次收费生图请求，之后仅轮询只读状态接口。`IMAGEFORGE_ASYNC_TIMEOUT_MS` 默认 `300000`、范围 30000–600000；`IMAGEFORGE_POLL_INTERVAL_MS` 默认 `2000`、范围 500–10000。轮询会在同一边界内遵循数值型 `Retry-After`。ImageForge 不使用 webhook、不重试收费创建请求，也不回退到其他 Provider。

各层超时的作用范围如下：

| 设置 | 默认值 | 作用范围 |
| --- | --- | --- |
| `IMAGEFORGE_REQUEST_TIMEOUT_MS` | `300000` 毫秒 | 每次供应商 HTTP 请求，包含读取响应体的时间 |
| `IMAGEFORGE_ASYNC_TIMEOUT_MS` | `300000` 毫秒 | 异步任务提交完成、取得状态地址后的轮询窗口 |
| 图片下载超时 | `30000` 毫秒 | 每次远程图片下载请求，与供应商请求超时独立 |
| MCP 客户端工具超时 | 取决于客户端 | 整次工具调用，包含输入加载、生图或轮询、输出处理 |

例如，需要允许单次供应商请求等待 10 分钟时，在 MCP 客户端的 `env` 对象中设置 `"IMAGEFORGE_REQUEST_TIMEOUT_MS": "600000"`。同步生图的客户端等待时间应大于 600 秒，例如 Codex 配置 `tool_timeout_sec = 660`；异步供应商还需合计预留任务提交、轮询和图片下载的耗时。增加 ImageForge 超时不会延长网关自身的时限，也不能阻止上游返回 504。

该变量应传入 MCP 服务进程环境，不是 `generate_image` 或 `edit_image` 的调用参数。`.env.example` 只是配置模板，ImageForge 不会自动加载 `.env` 文件。可以通过客户端的 `env` 配置直接传入，或在启动客户端前导出变量，并确保客户端向 MCP 进程转发它。

修改配置后，需要重启或重新连接 MCP 服务。要使用本地源码改动，先执行 `npm run build`，再按下方示例启动重新构建的 `dist/index.js`。`npx imageforge-mcp` 使用的是 npm 已发布包，本地构建不会更新该进程。`IMAGEFORGE_REQUEST_TIMEOUT_MS` 从 0.6.2 开始支持。仍写死 120 秒超时的旧版本不识别该变量，需要升级到 0.6.2 或更高版本，或使用本地构建。

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 或其他共享配置文件。

## Codex 本地开发配置

根据本机路径创建项目级 `.codex/config.toml`：

```toml
[mcp_servers.imageforge_dev]
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", "MINIMAX_API_KEY", "MINIMAX_BASE_URL", "MINIMAX_IMAGE_MODEL", "IMAGEFORGE_PROVIDER", "IMAGEFORGE_INPUT_CONCURRENCY", "IMAGEFORGE_SKIP_DNS_SAFETY_CHECKS", "IMAGEFORGE_REQUEST_TIMEOUT_MS"]
startup_timeout_sec = 10
tool_timeout_sec = 360
enabled = true
required = false
```

启动 Codex 前设置环境变量：

```bash
export OPENAI_API_KEY="你的网关令牌"
export OPENAI_BASE_URL="https://你的-OpenAI-兼容网关域名/v1"
export OPENAI_IMAGE_MODEL="gpt-image-2"
export IMAGEFORGE_INPUT_CONCURRENCY="4"
export IMAGEFORGE_REQUEST_TIMEOUT_MS="300000"

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`
- `list_image_providers`
- `edit_image`

修改 TypeScript 源码后，需要重新构建并重启使用该 MCP 的任务：

```bash
npm run build
```

完整配置说明见 [Codex MCP 官方文档](https://developers.openai.com/codex/mcp)。

## `generate_image`

| 参数 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `prompt` | 是 | - | 图片描述 |
| `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 与智谱取值见上；MiniMax 仅接受 `auto` |
| `output_format` | 否 | `png`；MiniMax 为 `jpeg` | OpenAI：`png/jpeg/webp`；智谱忽略；MiniMax 仅接受 `jpeg` |
| `output_path` | 否 | - | 本地保存路径；相对路径按 MCP 工作目录解析 |
| `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"
}
```

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` 必填：

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `prompt` | 是 | 编辑指令 |
| `input_images` | 是 | 1–16 张输入图片，支持本地绝对路径或 HTTP(S) URL |

本地图片会直接读取；URL 图片会经过下载和安全校验后再上传。每次重定向都会重新校验目标地址，非公网地址会被拒绝，同时会将校验后的 DNS 结果固定到实际连接，防止校验与下载之间发生 DNS Rebinding。

配置优先级为：工具参数、环境变量、内置默认值。

传入 `output_path` 时，服务会在返回原生 MCP 图片内容块的同时保存文件，并在文本内容块中返回最终绝对路径。父目录不存在时会自动创建；已有文件不会被覆盖。

部分 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
npm test
npm run check
```

测试使用本地 HTTP mock，不会调用真实图片 API，也不会产生生图费用。

## 许可证

[MIT](./LICENSE)