imageforge-mcp 0.5.0 → 0.6.1

package/README.md

@@ -2,18 +2,16 @@
 
 English | [中文](#中文说明)
 
-A lightweight TypeScript MCP server for image generation with OpenAI, Zhipu BigModel, and MiniMax, plus OpenAI image editing.
+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`; MiniMax uses `POST /v1/image_generation`.
+- 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`
-- MiniMax models: `image-01`, `image-01-live`
-- 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
@@ -29,16 +27,17 @@ A lightweight TypeScript MCP server for image generation with OpenAI, Zhipu BigM
 
 ## 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 |
+| 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
 
@@ -87,14 +86,14 @@ 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 configured model name must accept `gpt-image-2`.
+- 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: OpenAI/gateway, Zhipu, or MiniMax
+- A credential for the selected provider; see `.env.example` or `list_image_providers`
 
 ## Install and build
 
@@ -124,7 +123,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.5.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:
 
@@ -133,7 +132,7 @@ For a Zhipu-default MCP server, use an independent credential and provider confi
   "mcpServers": {
     "imageforge-zhipu": {
       "command": "npx",
-      "args": ["-y", "imageforge-mcp@0.5.0"],
+      "args": ["-y", "imageforge-mcp@0.6.0"],
       "env": {
         "IMAGEFORGE_PROVIDER": "zhipu",
         "ZHIPU_API_KEY": "your-zhipu-token",
@@ -153,7 +152,7 @@ For a MiniMax-default server:
   "mcpServers": {
     "imageforge-minimax": {
       "command": "npx",
-      "args": ["-y", "imageforge-mcp@0.5.0"],
+      "args": ["-y", "imageforge-mcp@0.6.0"],
       "env": {
         "IMAGEFORGE_PROVIDER": "minimax",
         "MINIMAX_API_KEY": "your-minimax-token",
@@ -176,6 +175,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.
@@ -222,6 +223,7 @@ For MiniMax, export `IMAGEFORGE_PROVIDER=minimax`, `MINIMAX_API_KEY`, and option
 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:
@@ -237,7 +239,7 @@ 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 models above; MiniMax: `image-01`, `image-01-live` |
+| `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` |
@@ -369,18 +371,16 @@ Tests use a local HTTP mock. They do not call a real image API or incur generati
 
 # 中文说明
 
-ImageForge MCP 是一个轻量的 TypeScript MCP 图片生成与编辑服务，支持 OpenAI、智谱 BigModel 和 MiniMax 生图，并保留 OpenAI 图片编辑能力。
+ImageForge MCP 是一个轻量的 TypeScript MCP 图片生成与编辑服务，支持 22 个原厂生图 Provider，并保留 OpenAI 图片编辑能力。
 
-- OpenAI 纯文本生图调用 `POST /v1/images/generations`；智谱调用 `POST /api/paas/v4/images/generations`；MiniMax 调用 `POST /v1/image_generation`。
+- 各 Provider 按官方同步接口或“提交任务后轮询”REST 契约调用。
 - OpenAI 图片编辑和参考图生图调用 multipart `POST /v1/images/edits`。
 - 生成结果以原生 MCP `image` 内容块返回，也可以同时保存到本地。
 
 ## 功能
 
-- 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`
+- 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 单张主体参考图生图
@@ -395,16 +395,17 @@ ImageForge MCP 是一个轻量的 TypeScript MCP 图片生成与编辑服务，
 
 ## 供应商能力矩阵
 
-| 能力 | 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 图片数据 |
+| 分组 | 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 支持
 
@@ -453,14 +454,14 @@ ImageForge MCP 不仅支持 OpenAI 官方接口，也支持实现了 OpenAI Imag
 - 纯文本生图需要实现 `POST /v1/images/generations`。
 - 参考图生图和图片编辑需要实现 multipart `POST /v1/images/edits`，并正确转发 `image[]` 文件。
 - 响应需要在 `data[0].b64_json` 中返回 Base64 图片数据。
-- 网关需要接受 `gpt-image-2` 模型名。
+- 网关需要接受实际传入或配置的模型名称与 Images API 请求格式；`gpt-image-2` 是内置回退值，不是强制模型名。
 
 如果网关只实现了 `/v1/images/generations`，仍可用于纯文本生图，但不能使用参考图生图和图片编辑。
 
 ## 环境要求
 
 - Node.js 22 或更高版本
-- 所选供应商对应的 OpenAI/网关、智谱或 MiniMax 密钥
+- 所选 Provider 的凭据；完整变量名见 `.env.example` 或 `list_image_providers`
 
 ## 安装与构建
 
@@ -490,7 +491,7 @@ npm run build
 }
 ```
 
-`-y` 允许 `npx` 在没有交互式安装提示的情况下下载或更新包。如果部署需要固定版本，可将包名写成 `"imageforge-mcp@0.5.0"`。
+`-y` 允许 `npx` 在没有交互式安装提示的情况下下载或更新包。如果部署需要固定版本，可将包名写成 `"imageforge-mcp@0.6.0"`。
 
 如果希望 MCP 默认使用智谱，应使用独立的智谱凭据与供应商配置：
 
@@ -499,7 +500,7 @@ npm run build
   "mcpServers": {
     "imageforge-zhipu": {
       "command": "npx",
-      "args": ["-y", "imageforge-mcp@0.5.0"],
+      "args": ["-y", "imageforge-mcp@0.6.0"],
       "env": {
         "IMAGEFORGE_PROVIDER": "zhipu",
         "ZHIPU_API_KEY": "你的智谱令牌",
@@ -519,7 +520,7 @@ MiniMax 默认配置示例：
   "mcpServers": {
     "imageforge-minimax": {
       "command": "npx",
-      "args": ["-y", "imageforge-mcp@0.5.0"],
+      "args": ["-y", "imageforge-mcp@0.6.0"],
       "env": {
         "IMAGEFORGE_PROVIDER": "minimax",
         "MINIMAX_API_KEY": "你的-MiniMax-令牌",
@@ -542,6 +543,8 @@ MiniMax 默认配置示例：
 
 `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 或其他共享配置文件。
@@ -588,6 +591,7 @@ export ZHIPU_IMAGE_MODEL="glm-image"
 Codex 只会加载已信任项目中的 `.codex/config.toml`。新增或修改 MCP 配置后，需要重新启动 Codex 或新建任务，再使用 `/mcp verbose` 确认 `imageforge_dev` 提供以下工具：
 
 - `generate_image`
+- `list_image_providers`
 - `edit_image`
 
 修改 TypeScript 源码后，需要重新构建并重启使用该 MCP 的任务：
@@ -603,7 +607,7 @@ npm run build
 | 参数 | 必填 | 默认值 | 说明 |
 | --- | --- | --- | --- |
 | `prompt` | 是 | - | 图片描述 |
-| `model` | 否 | 环境变量或供应商默认值 | OpenAI：`gpt-image-2`；智谱模型见上；MiniMax：`image-01`、`image-01-live` |
+| `model` | 否 | 环境变量或供应商默认值 | 任意供应商模型名，优先于环境变量；已适配示例：OpenAI `gpt-image-2`、智谱模型见上、MiniMax `image-01` / `image-01-live`。不设模型白名单。 |
 | `base_url` | 否 | 供应商环境变量或官方默认值 | 单次调用覆盖对应供应商 API 地址 |
 | `api_key` | 否 | 供应商独立密钥 | 单次调用覆盖对应供应商密钥；推荐使用环境变量 |
 | `provider` | 否 | `IMAGEFORGE_PROVIDER`，再默认 `openai` | `openai`、`zhipu` 或 `minimax` |

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 {};