# Image Gen MCP

[English](README.en.md)

Image Gen MCP 是一个品牌中立、可自托管的图片生成与编辑 MCP server，同时提供 Codex plugin 与 `image-gen` Skill。Agent 可以直接用自然语言生成图片、编辑本地参考图，或按顺序组合多张参考图；结果会保存到本地，并同时以 MCP 图片内容和结构化元数据返回。

## 为什么使用

- **一个稳定工具**：Agent 始终调用 `generate_image`，底层 provider 可配置切换。
- **生成与编辑统一**：支持纯文本生成、单参考图和最多 12 张有序参考图。
- **本地结果可追踪**：返回绝对路径、真实 MIME、格式、大小、provider、model、request ID 与 revised prompt（若上游提供）。
- **默认安全**：凭据不进入工具参数；校验参考图魔数与大小；输出防路径穿越且默认不覆盖；URL 结果默认仅允许公网 HTTPS。
- **标准 MCP**：使用官方 SDK，可由支持 stdio MCP 的客户端调用，不局限于某个 Agent 产品。

## 让 Agent 使用

配置好环境变量并启用 MCP server 后，可以直接说：

- “生成一张夜间列车穿过雪原的电影海报，保存为 `night-train.png`。”
- “编辑 `/path/to/photo.jpg`：保留人物与构图，把背景改成雨天街道。”
- “依次参考这三张图：第一张控制构图，第二张控制色彩，第三张控制材质。”

Skill 会调用 `mcp__image_gen__generate_image`。也可由任意 MCP 客户端直接调用 `generate_image`，传入 `prompt`，并按需使用 `reference_image`、`reference_images`、`provider`、`model`、`size`、`quality`、`output_format`、`output_directory`、`filename`、`overwrite` 与 `action`。

## 两种协议

### `openai-images`（默认）

遵循标准 OpenAI-compatible Images API：无参考图时向 `/images/generations` 发送 JSON；有参考图时向 `/images/edits` 发送 multipart。解析标准 `b64_json`，也支持经过安全下载策略校验的 `url` 结果。适合直接提供 Images API 的服务。

### `openai-responses`

向 `/responses` 发起非流式请求，把提示词和参考图 data URL 放入输入内容，并启用 `image_generation` tool。只解析最终输出中明确的 `image_generation_call.result`。`action` 可设为 `auto`、`generate` 或 `edit`。这里的 `model` 是 Responses 主控制模型，不一定等于 Images API 的图片模型，可用 `IMAGE_GEN_RESPONSES_MODEL` 单独设置。

## 最小配置

```sh
export IMAGE_GEN_API_KEY="your-key"
export IMAGE_GEN_MODEL="your-model"
npm start
```

常用配置包括 `IMAGE_GEN_PROVIDER`、`IMAGE_GEN_BASE_URL`、`IMAGE_GEN_RESPONSES_MODEL`、`IMAGE_GEN_OUTPUT_DIR` 与 `IMAGE_GEN_TIMEOUT_MS`。`OPENAI_API_KEY`、`OPENAI_BASE_URL` 是低优先级兼容别名。也可以用 `IMAGE_GEN_ENV_FILE` 指向严格的 `KEY=value` 文件；该文件不会作为 shell 脚本执行。完整占位示例见 `.env.example`。

默认输出目录是 `~/Pictures/Image Gen`。已有同名文件不会被覆盖，除非工具调用显式传入 `overwrite: true`。

## 兼容性边界

“OpenAI-compatible”仅表示本项目实现这里描述的标准 Images 或 Responses 请求/响应形状。它不保证任意图片厂商只填写 API key 就能兼容；字段、模型能力、参考图数量和输出格式仍由所配置服务决定。不兼容的协议应通过新的 provider adapter 接入，而不是伪装成现有协议。

当前版本一次调用固定请求并返回一张最终图片，不处理流式 partial image。自动重试仅适用于网络错误、HTTP 429 和 5xx；400、401、403 不重试。

## 隐私与网络

**参考图片及提示词会发送给你配置的外部 provider。** 请先确认服务方的数据政策，并不要发送未经授权的敏感图片。API key 不在 MCP 工具 schema 中，但仍应由客户端安全管理环境变量。

上游返回图片 URL 时，默认要求公网 HTTPS，并阻断 loopback、link-local 与私网地址，同时限制重定向、下载大小和超时。只有连接可信的内部兼容服务时才应显式设置 `IMAGE_GEN_ALLOW_PRIVATE_URLS=true`。

## 故障排查

- `CONFIG_ERROR`：检查 API key、model、base URL 与严格 env 文件格式。
- `INVALID_IMAGE`：确认参考图是普通 PNG/JPEG/WebP 文件，扩展名与内容一致且未超限。
- `FILE_EXISTS`：换用文件名，或明确允许覆盖。
- `AUTH_ERROR` / `RATE_LIMITED` / `UPSTREAM_ERROR`：检查 provider 凭据、配额和服务状态。
- `UNSAFE_URL`：上游 URL 未满足默认公网 HTTPS 策略。

开发与安全说明见 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [SECURITY.md](SECURITY.md)。