# Relay Image MCP

本项目用于解决 **Codex 接入中转站后，无法使用内置 OpenAI 图片生成模型** 的场景。它通过独立的 MCP 图片工具调用显式配置的中转图片 API，让文生图和图片编辑可以继续在 Codex 中完成，并核对实际输出。

项目提供 stdio MCP 服务、独立命令行和可安装的 Agent Skill，也可用于其他支持 MCP 的客户端。它不会修改 Codex 内置工具的权限或账号套餐；能否使用指定模型，取决于中转站是否真正提供对应的图片接口与模型。已有文本对话可用，不代表图片接口也一定可用。

支持文字生成图片、文字加图片编辑、最多 5 张参考图，以及尺寸、比例、质量、背景和文件格式参数。返回的原图保持原始字节，检查结果会区分请求规格与实际结果。

## 适用范围

这个项目需要一个支持下列协议的图片服务：

- 文生图：`POST <base_url>/images/generations`，JSON 请求体。
- 带图请求：`POST <base_url>/images/edits`，图片以 `images: [{"image_url": "data:image/png;base64,..."}]` 放入 JSON 请求体。
- 响应包含 `b64_json` 图片数据，支持 JSON 响应或完成事件形式的 SSE。

**编辑接口使用 JSON 数据，不是通用的 multipart 上传接口。** 仅支持 multipart 的服务不能直接使用。项目不会下载响应中的远程图片 URL，也不会自动改用其他协议、服务或模型。

支持 `gpt-image-2`、`gpt-image-2.5-sunburst` 和 `gpt-image-2.5-flare`，以及两个 Image-2.5 型号的 `-2026-09-08` 日期快照。这些标识与参数通过本地校验，不代表所配置服务一定提供对应模型或完整能力。

### Image-2.5 支持与验证

官方当前提供 [GPT Image 2.5 Sunburst](https://developers.openai.com/api/docs/models/gpt-image-2.5-sunburst) 和 [GPT Image 2.5 Flare](https://developers.openai.com/api/docs/models/gpt-image-2.5-flare)。项目把选择的型号作为真实 JSON `model` 字段发送，不会在本地自动换成其他图片模型。

**图片生成是否成功、平台记录的型号、响应中的型号标签，需要分开看。** 2026-09-10 的测试中，Image-2.5 两个型号及其日期快照请求均成功返回可解码图片；随后核对的中转使用记录，将两个日期快照请求记录为对应的 Image-2.5 型号成功调用。

| 请求型号 | 图片结果 | 中转使用记录 | API 响应标签 |
| --- | --- | --- | --- |
| `gpt-image-2.5-sunburst` | 成功返回图片 | 未单独对照 | `gpt-image-2-codex` |
| `gpt-image-2.5-flare` | 成功返回图片 | 未单独对照 | `gpt-image-2-codex` |
| `gpt-image-2.5-sunburst-2026-09-08` | 成功返回图片 | 对应 Image-2.5 型号成功调用 | `gpt-image-2-codex` |
| `gpt-image-2.5-flare-2026-09-08` | 成功返回图片 | 对应 Image-2.5 型号成功调用 | `gpt-image-2-codex` |

**更正此前结论：不能仅凭 API 响应中的另一型号标签，断言中转未执行 Image-2.5。** 平台记录与生成结果支持这两次日期型号请求调用成功。响应标签与平台记录的映射含义仍需服务提供者说明；平台记录和响应标签都不等于对内部实际执行模型的独立审计。公开说明不包含使用记录截图、账号、IP 或计费信息。

尺寸与参数另行验收：四次都请求 1024×1024、quality=low，实际图片均为 1254×1254，响应 quality=auto。这些差异仍成立，但不能用来否定模型调用成功；平台的分辨率或计费档位也不能替代对文件实际像素的检查。以上结果仅代表测试时的这一条接入。

工具使用 `generation_status="succeeded"` 表示已经收到并保存完整图片；`delivery_status` 单独表示请求规格的检查结果。未知或尚未建立映射的型号标签记为 `unverified`，不据此断言后台调用了错误模型。已知型号之间明确不同、或两个可识别回报互相矛盾时，才标记响应型号不符合；这仍只是回报一致性检查。

请求浮动别名后返回对应官方日期快照可视为回报匹配；请求特定日期快照却只返回浮动别名时，不能确认锁定了该版本。严格模式中的错误标记可能表示规格尚未验证或未满足，不等于图片生成请求失败。

## 安装

需要 Python 3.11 或更新版本。运行依赖只有 Pillow；安装时自动获取。

### 从指定版本安装

建议使用独立虚拟环境：

```bash
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install "git+https://github.com/eyaeya/relay-image-mcp.git@v0.3.3"
.venv/bin/relay-image-mcp --help
```

此方式还需要 Git。Windows 的可执行文件位于 `.venv\Scripts\`，例如 `.venv\Scripts\python.exe` 和 `.venv\Scripts\relay-image-mcp.exe`。

### 从 Release 安装

从 [v0.3.3 Release](https://github.com/eyaeya/relay-image-mcp/releases/tag/v0.3.3) 下载 wheel，然后在虚拟环境中安装：

```bash
.venv/bin/python -m pip install /path/to/relay_image_mcp-0.3.3-py3-none-any.whl
```

Release 同时提供源码包及校验和文件。本项目尚未发布到 PyPI；不要使用不带来源的 `pip install relay-image-mcp` 代替以上安装方式。

## 配置服务

程序只读取显式指定的配置与环境变量，不会自动寻找其他应用的账号、登录状态或配置文件。

### 环境变量

在启动程序的进程环境中设置：

```bash
export IMAGE_RELAY_BASE_URL='https://relay.example/v1'
export IMAGE_RELAY_TOKEN='replace-with-your-provider-token'
.venv/bin/relay-image-mcp --status
```

示例域名与 token 均为占位内容。使用已有服务凭据即可，无需为本项目创建另一套凭据。桌面 MCP 客户端不一定继承终端变量，应按客户端的环境变量配置方式提供。

### TOML 配置

创建自己的 `settings.toml`：

```toml
[provider]
base_url = "https://relay.example/v1"
env_key = "IMAGE_RELAY_TOKEN"
```

使用 `--config /path/to/settings.toml` 指定文件，也可设置 `IMAGE_RELAY_CONFIG`；命令行路径优先。若同时设置 `IMAGE_RELAY_BASE_URL` 或 `IMAGE_RELAY_TOKEN`，对应环境变量会覆盖文件中的地址或 token 来源。建议只在文件中引用环境变量，避免保存明文凭据。

如果服务需要自定义鉴权头，可改用：

```toml
[provider]
base_url = "https://relay.example/v1"

[provider.env_http_headers]
x-relay-authorization = "IMAGE_RELAY_AUTHORIZATION"
```

`IMAGE_RELAY_AUTHORIZATION` 的值应包含服务要求的完整头部值。也支持 `[provider.http_headers]` 直接配置头部，但其中的敏感值会成为本地文件中的明文。不要提交自己的配置文件。

远程服务要求 HTTPS；本地回环地址允许 HTTP。服务地址应包含实际 API 前缀，例如 `/v1`，不要附带 `/images/generations`。请求不跟随重定向。

## 在 Codex 中使用

先完成上方服务配置，再将虚拟环境中的可执行文件注册为 MCP：

```bash
codex mcp add relay_image -- /path/to/venv/bin/relay-image-mcp --config /path/to/settings.toml --output-dir /path/to/generated-images
```

也可以在 Codex 的 MCP 配置中手动添加：

```toml
[mcp_servers.relay_image]
command = "/path/to/venv/bin/relay-image-mcp"
args = ["--config", "/path/to/settings.toml", "--output-dir", "/path/to/generated-images"]
startup_timeout_sec = 20
tool_timeout_sec = 1200
```

使用已有中转站凭据，不需要为了这个项目再创建一把 OpenAI 官方 API key。凭据需要按上面的环境变量或 TOML 方式显式提供，程序不会自动读取其他应用的登录文件。重启该 MCP 服务后，可在 Codex 中请求“使用 relay_image 生成图片”或“修改这张图片”。[Codex MCP 配置文档](https://developers.openai.com/codex/mcp/)。

## 接入 MCP 客户端

在客户端的 MCP 配置中添加 stdio 服务。以下为常见配置结构，具体位置以客户端文档为准：

```json
{
  "mcpServers": {
    "relay_image": {
      "command": "/path/to/venv/bin/relay-image-mcp",
      "args": [
        "--config", "/path/to/settings.toml",
        "--output-dir", "/path/to/generated-images"
      ]
    }
  }
}
```

将示例替换为实际绝对路径，确保客户端进程能读取配置和相应鉴权环境变量。Windows 可将 `command` 替换为虚拟环境中的 `.exe` 路径。保存后重新加载该 MCP 服务。

| 工具 | 作用 |
| --- | --- |
| `status` | 查看配置状态、参数范围与运行信息，不发起生图请求 |
| `inspect_image` | 只读检查本地图片的尺寸、格式、哈希与真实 Alpha |
| `generate_image` | 生成或编辑一张图片，保存原图和技术检查报告 |

### 安装 Skill

```bash
.venv/bin/relay-image-mcp --install-skill /path/to/skills/relay-image
```

目标目录应是你的 Agent 支持的技能发现目录中的 `relay-image` 文件夹，且必须尚不存在；安装命令不会覆盖已有内容。该命令复制包内的 `SKILL.md` 和参数参考，不修改 MCP 配置，也不保存凭据。按客户端要求重新加载技能后，可直接提出文生图或改图需求，也可显式使用 `$relay-image`。

## 使用示例

### 文生图

```bash
.venv/bin/relay-image-mcp \
  --config /path/to/settings.toml \
  --output-dir /path/to/generated-images \
  --generate '清晨海边的一间木屋，写实摄影，柔和自然光' \
  --aspect-ratio 16:9 --size max --quality high
```

### 修改图片

```bash
.venv/bin/relay-image-mcp \
  --config /path/to/settings.toml \
  --generate '把杯子改成红色，保持杯子的形状、位置、构图和背景' \
  --reference-image /path/to/cup.png \
  --mode edit --size source --aspect-ratio source --strict
```

`source` 使用第一张参考图的原始像素尺寸或比例。如果尺寸超出支持范围，请选择合适的请求尺寸；程序不会静默缩放或裁切输入图。重复 `--reference-image` 可提供多张参考图；重复 `--reference-roles` 可逐项指定用途，重复 `--preserve` 可添加多项保留要求。

### 请求透明背景

```bash
.venv/bin/relay-image-mcp \
  --config /path/to/settings.toml \
  --generate '单独一株盆栽，透明背景，保留完整花盆和叶片' \
  --image-model gpt-image-2.5-sunburst \
  --background transparent --output-format png --strict
```

此示例要求服务实际支持该模型和透明输出。选择透明参数只代表发送了请求；最终以文件中的 Alpha 和检查结果为准。

### MCP 参数示例

调用 `generate_image`：

```json
{
  "prompt": "把第一张图里的杯子改成第二张图的红色，保留构图和背景",
  "reference_image_paths": ["/path/to/cup.png", "/path/to/color-reference.png"],
  "reference_roles": ["需要修改的杯子图片", "仅作为颜色参考"],
  "preserve": ["杯子形状与位置", "背景与构图"],
  "mode": "edit",
  "size": "2048x2048",
  "aspect_ratio": "1:1",
  "quality": "high",
  "background": "opaque",
  "output_format": "png",
  "strict": true
}
```

本地路径必须真实存在。`preserve` 和 `reference_roles` 会作为文字要求发送给服务，不能保证像素级不变。完整参数见 [参数参考](src/relay_image_mcp/skill/references/parameters.md)。

## 分辨率、质量与验收

默认使用 `size="max"`、`quality="high"`、`image_model="gpt-image-2.5-sunburst"` 和 PNG 输出。不传模型参数时直接请求 Sunburst，不需要在提示词中指定。使用不带日期的型号名称，保持该型号的浮动版本；不会自动改选未来其他名称的模型。明确传入其他受支持型号时仍按用户选择发送。没有参考图且未指定比例时，`max` 按正方形解析；有参考图时使用第一张图的比例。

`max` 会在当前适配器支持的范围内选择符合精确比例的最大画布：单边不超过 3840、总像素不超过 8,294,400、宽高均为 16 的倍数、比例介于 1:3 和 3:1。显式尺寸还要求不少于 655,360 像素。例如 16:9 的最大请求为 3840×2160，1:1 为 2880×2880。这些是请求限制，服务可能施加额外限制或返回不同尺寸。

质量与像素尺寸独立。`gpt-image-2` 接受 `auto/low/medium/high`；两个 `gpt-image-2.5-*` 标识还接受 `xhigh/max`。服务是否支持这些档位、是否真的使用指定模型，不能仅凭请求参数判断。

每次生成会检查实际图片的尺寸、比例、文件格式、Alpha 和哈希；服务回报的模型、质量等字段也会与请求区分呈现。精确尺寸必须一致，比例检查允许 1 像素的等效误差。透明检查要求存在真实非不透明像素，同时图片不能完全不可见。

`strict=true` 在可检查的规格未满足时返回错误状态，同时保留图片和检查报告；命令行此时以退出码 `2` 结束。模型或质量回报不一致也会被标记，缺失字段则标为未验证。严格模式不保证画面内容、人物身份、文字或编辑范围满足提示词，也不把服务自报的模型与质量当成独立证明。出现错误后不会自动重试、切换模型或降低参数。

原图不做放大、缩小、裁切、抠图或重新编码。若需要后处理，应另存处理结果，并与服务返回的原图区分。

## 文件与隐私

可用 `--output-dir` 指定保存目录。在 Unix 系统上，默认使用 `$XDG_DATA_HOME/relay-image-mcp/images`；未设置时使用 `~/.local/share/relay-image-mcp/images`。Windows 默认使用 `%LOCALAPPDATA%\relay-image-mcp\images`。

- 提示词和所选参考图片会发送给你配置的服务，包括为参考图添加的用途和保留要求。
- 默认技术报告不保存提示词、参考图路径或服务改写的提示词，只保留参数、实际图片信息、哈希与检查结果等技术数据。
- 原图保留服务返回的字节，也可能保留其中的 EXIF 或其他元数据。参考图按原始文件发送，因此也可能包含元数据。
- 本地图片、技术报告以及 MCP 客户端记录仍可能包含敏感内容或路径；这不是匿名化工具。分享前应检查实际文件。
- 程序不读取其他应用的账号；凭据由你显式提供。不要提交凭据；分享配置、生成结果或客户端日志前，应检查是否包含敏感内容。

## 开发与测试

```bash
git clone https://github.com/eyaeya/relay-image-mcp.git
cd relay-image-mcp
python3 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/python -m unittest discover -s tests -v
```

测试使用本地数据与模拟服务，不需要远程凭据或付费生图。测试通过不代表某个远程服务支持全部参数。

## 许可证

[MIT](LICENSE)。版本记录见 [CHANGELOG](CHANGELOG.md)。