Metadata-Version: 2.4
Name: image-generate-mcp-remote
Version: 0.9.6
Summary: Remote MCP server for image generation
Project-URL: Homepage, https://github.com/zztdandan/image-generate-mcp-remote
Project-URL: Repository, https://github.com/zztdandan/image-generate-mcp-remote
Project-URL: Issues, https://github.com/zztdandan/image-generate-mcp-remote/issues
License: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: httpx>=0.28.0
Requires-Dist: mcp[cli]>=1.12.0
Requires-Dist: pydantic-settings>=2.10.0
Requires-Dist: pydantic>=2.11.0
Requires-Dist: python-dotenv>=1.1.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=1.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.12.0; extra == 'dev'
Description-Content-Type: text/markdown

# image-generate-mcp-remote

一个基于 UV + Python 的远程 MCP 图片生成服务，统一封装 OpenAI Images 兼容接口与 Gemini `generateContent` 生图接口。

> 本子项目运行时复用工作区根目录 `.venv`。在本目录执行 `uv` 命令时，会通过工作区环境注入使用统一虚拟环境。

> 注意，timeout为关键参数，生成图片一般需要3分钟/张，mcp工具默认重试3次，故最多可能12分钟出一张图（渠道不稳定情况下），如果不设置超时，默认为30秒，一定生成不了图片。
> 文档推荐将 MCP 客户端 `timeout` 显式设置为 `500000` 毫秒（500 秒）；这是常规重试场景下的推荐值，同时请知悉极端情况下最长仍可能到 12 分钟。

## 项目能力

- 提供 `gpt_image_2_official` 工具，兼容 OpenAI Images 风格的文生图与参考图编辑
- 提供 `nano_banana_2_official` 工具，兼容 Gemini `generateContent` 风格的文生图与参考图编辑
- 提供 `gpt-image-2-url` 工具，兼容 `https://www.right.codes/draw/v1/images/generations` 并自动下载返回图片 URL
- 提供 `list_image_tools_catalog` 工具，用于输出当前服务的默认配置、有效模型与非敏感环境变量信息
- 提供 `skills/gpt-icon-generate/SKILL.md` 图标生成技能，约定规则网格图标板生成、校验和切图流程
- 默认 `official` 工具网关已切换为官方地址

## 默认上游配置

### OpenAI Images 兼容

- 默认 `BASE_URL`：`https://api.openai.com/v1`
- 默认模型：`gpt-image-2`
- 典型接口：
  - `POST /v1/images/generations`
  - `POST /v1/images/edits`

### Gemini 原生兼容

- 默认 `BASE_URL`：`https://generativelanguage.googleapis.com`
- 默认模型：`gemini-3.1-flash-image-preview`
- 典型接口：
  - `POST /v1beta/models/{model}:generateContent`

## 通过 uv / PyPI 安装使用

`uv` 本身没有单独的“官方包仓库”，常规做法是把包发布到 `PyPI`，然后让用户通过 `uv` 直接下载运行。

当前发布链路会把 GitHub Release 对应版本自动发布到 `PyPI`。

- PyPI 项目名：`image-generate-mcp-remote`
- 推荐安装到工具目录：`uv tool install image-generate-mcp-remote`
- 推荐阅读真实部署与 MCP 配置导览：`./SYSTEMD_DEPLOYMENT_GUIDE.md`

例如，安装 `v0.9.6` 后可用于远端 MCP 服务部署或供 MCP 客户端以 `stdio` 模式拉起：

```bash
# 安装为全局工具
uv tool install image-generate-mcp-remote

# 指定版本
uv tool install --refresh image-generate-mcp-remote==0.9.6
```

## 从源码安装与启动

### 1. 安装依赖

```bash
uv sync
cp .env.example .env
```

### 2. 配置环境变量

至少填写你要使用的工具对应 API Key：

- `IMG_GEN_GPT_IMAGE_2_OFFICIAL_API_KEY`
- `IMG_GEN_NANO_BANANA_2_OFFICIAL_API_KEY`

### 3. 启动服务

```bash
# Streamable HTTP（默认）
uv run image-generate-mcp-remote --transport streamable-http --host 127.0.0.1 --port 3001

# SSE
uv run image-generate-mcp-remote --transport sse --host 127.0.0.1 --port 3001
```

这里不再单列 `stdio` 的独立启动命令；对本项目而言，`stdio` 的意义在于由 MCP 客户端按配置拉起，而不是人工单独启动。真正的 MCP 配置导览请直接看 `./SYSTEMD_DEPLOYMENT_GUIDE.md`。

## 当前实际部署（systemd --user）

本项目当前真正使用中的远端 MCP 服务，不是 `stdio` 直连，而是 `systemd --user` 托管的 `streamable-http` 服务。

- 服务名：`image-generate-mcp.service`
- unit 文件位置模式：`~/.config/systemd/user/image-generate-mcp.service`
- 工作目录：部署目录 `<deploy-root>`
- 环境文件：`<deploy-root>/.env`
- 当前接入地址：`http://127.0.0.1:25235/mcp`

部署、更新、修改环境变量、重启服务、OpenCode MCP JSON 配置的完整说明见：

- `./SYSTEMD_DEPLOYMENT_GUIDE.md`

对于当前这个远端服务，需要特别注意：

- 改 OpenCode MCP JSON 里的 `env`，不会改变已启动服务的环境变量
- 要改服务配置，必须修改 `<deploy-root>/.env` 或 `image-generate-mcp.service`
- 改 `.env` 后执行 `systemctl --user restart image-generate-mcp.service`
- 改 `.service` 后执行 `systemctl --user daemon-reload && systemctl --user restart image-generate-mcp.service`

## MCP 配置方式

以下配置示例均为当前项目可直接使用的正确写法。

如果你关注的是真实远端部署、systemd 托管、客户端如何接入在线 MCP 服务，建议优先阅读 `./SYSTEMD_DEPLOYMENT_GUIDE.md`；本节仅保留最常见配置摘要。

### 方式一：stdio 直连（推荐本地开发）

适用于大多数支持本地命令启动 MCP Server 的客户端。

```json
{
  "mcpServers": {
    "image-generate-mcp-remote": {
      "command": "uv",
      "args": [
        "run",
        "image-generate-mcp-remote",
        "--transport",
        "stdio"
      ],
      "timeout": 500000,
      "cwd": "/absolute/path/to/image-generate-mcp-remote",
      "env": {
        "IMG_GEN_GPT_IMAGE_2_OFFICIAL_API_KEY": "sk-xxxx",
        "IMG_GEN_GPT_IMAGE_2_OFFICIAL_BASE_URL": "https://api.openai.com/v1",
        "IMG_GEN_GPT_IMAGE_2_OFFICIAL_MODEL": "gpt-image-2",
        "IMG_GEN_GPT_IMAGE_2_OFFICIAL_SUPPORTED_MODELS": "gpt-image-2",
        "IMG_GEN_NANO_BANANA_2_OFFICIAL_API_KEY": "sk-xxxx",
        "IMG_GEN_NANO_BANANA_2_OFFICIAL_BASE_URL": "https://generativelanguage.googleapis.com",
        "IMG_GEN_NANO_BANANA_2_OFFICIAL_MODEL": "gemini-3.1-flash-image-preview",
        "IMG_GEN_NANO_BANANA_2_OFFICIAL_SUPPORTED_MODELS": "gemini-3.1-flash-image-preview",
        "IMAGE_OUTPUT_DIR": "storage/images",
        "IMAGE_BASE_URL": "",
        "IMAGE_HTTP_TIMEOUT_SECONDS": "180",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}
```

### 方式二：Streamable HTTP 远程接入

先启动服务：

```bash
uv run image-generate-mcp-remote --transport streamable-http --host 127.0.0.1 --port 3001
```

服务默认 MCP 路径为：`/mcp`

```json
{
  "mcpServers": {
    "image-generate-mcp-remote": {
      "url": "http://127.0.0.1:3001/mcp",
      "timeout": 500000
    }
  }
}
```

上面的 `timeout` 不要省略。注意，timeout为关键参数，生成图片一般需要3分钟/张，mcp工具默认重试3次，故最多可能12分钟出一张图（渠道不稳定情况下），如果不设置超时，默认为30秒，一定生成不了图片。文档示例推荐值为 `500000` 毫秒（500 秒），用于覆盖常规重试场景。

### 方式三：SSE 远程接入

先启动服务：

```bash
uv run image-generate-mcp-remote --transport sse --host 127.0.0.1 --port 3001
```

服务默认路径为：

- SSE 入口：`/sse`
- 消息通道：`/messages/`

对于要求分别填写 SSE 地址与消息地址的客户端，可使用：

- `http://127.0.0.1:3001/sse`
- `http://127.0.0.1:3001/messages/`

如果客户端还支持单独配置 MCP tool-call 超时，也应显式设置 `timeout`；文档推荐值为 `500000` 毫秒（500 秒），但在渠道极不稳定时，单张图最长仍可能接近 `12` 分钟。

## 工具列表

### `list_image_tools_catalog`

输出当前服务暴露的图片工具目录，包括：

- 默认网关地址
- 当前有效模型
- 支持模型列表
- 非敏感环境变量生效值

### `gpt_image_2_official`

OpenAI Images 兼容工具。

- `mode=generate` 时调用文生图
- `mode=edit` 时调用参考图编辑 / 图生图
- 默认请求上游：`https://api.openai.com/v1`
- 支持按次调用覆盖 `api_key`、`base_url`、`model`；未显式传入时依次回退到环境变量与代码默认值，其中 `api_key` 没有代码默认值
- 支持显式传入 `timeout_seconds`，默认 `180` 秒
- 支持显式传入 `retry_count`，默认 `3`，表示失败后额外重试 3 次，总尝试次数为 4 次
- 尺寸输入统一为 `image_size` + `aspect_ratio` 两个枚举，不再直接接收裸像素 `size`
- 支持 `send_size` 与 `send_quality`：为 `false` 时不向上游发送对应字段，而是把该要求自动补进 `prompt`
- `gpt_image_2_official` 会根据共享尺寸合同，把枚举对映射成对应 GPT 请求像素尺寸
- 支持解析 `data[0].b64_json` 与 `data[0].url`；若上游返回 `url`，服务端会自动下载并保存到 `save_path`
- 如传入不支持的枚举组合，错误信息会直接列出该工具支持的尺寸预设；也可先调用 `list_image_tools_catalog` 查看 `supported_size_presets`
- 默认支持模型包含 `gpt-image-2` 与 `gpt-image-2-vip`

### `nano_banana_2_official`

Gemini `generateContent` 兼容工具。

- `mode=generate` 时调用文生图
- `mode=edit` 时调用参考图编辑 / 图生图
- 默认请求上游：`https://generativelanguage.googleapis.com`
- 支持按次调用覆盖 `api_key`、`base_url`、`model`；未显式传入时依次回退到环境变量与代码默认值，其中 `api_key` 没有代码默认值
- 鉴权请求头同时发送 `Authorization: Bearer <key>` 与 `x-goog-api-key: <key>` 以兼容更多 Gemini 兼容网关
- 支持显式传入 `timeout_seconds`，默认 `180` 秒
- 支持显式传入 `retry_count`，默认 `3`，表示失败后额外重试 3 次，总尝试次数为 4 次
- 响应解析兼容 `inlineData` / `inline_data` 与 `mimeType` / `mime_type`
- 尺寸输入统一为 `image_size` + `aspect_ratio` 两个枚举，服务会按共享尺寸合同映射到 `imageConfig`
- 共享尺寸合同已同时记录 `gpt` 请求尺寸与 `nano banana` 实际输出尺寸；例如 `2K + 16:9` 对应 `gpt=2048x1152`、`nano=2752x1536`

### `gpt-image-2-url`

URL 返回型 `gpt-image-2` 独立工具。

- 调用接口：`POST /images/generations`
- 默认请求上游：`https://www.right.codes/draw/v1`
- 默认模型：`gpt-image-2-vip`
- 该工具会向上游请求 `response_format=url`，上游返回 `https` 图片地址后，服务端会自动下载该 URL 并保存到 `save_path`；调用方不需要再手动下载
- 入参 `image` 是可选的参考图 URL 列表，不是输出图片 URL
- 返回结果继续复用统一 `ImageToolResult` 结构，保留耗时、token 使用量与上游响应摘要
- 支持显式传入 `timeout_seconds`，默认 `180` 秒
- 支持显式传入 `retry_count`，默认 `3`，表示失败后额外重试 3 次，总尝试次数为 4 次
- 尺寸输入统一为 `image_size` + `aspect_ratio` 两个枚举；该 URL 工具仅接受全部 `1K` 共享组合，加上已实测通过的部分 `2K/4K` 组合
- 如传入不支持的枚举组合，错误信息会直接列出该工具支持的尺寸预设；也可先调用 `list_image_tools_catalog` 查看 `supported_size_presets`

## 内置技能

### `gpt-icon-generate`

- 技能文件：`skills/gpt-icon-generate/SKILL.md`
- 用途：批量图标板生成、规则网格校验、透明 PNG 切图、UI 图标库落盘
- 默认链路：优先使用 `gpt_image_2_official` 生成 `2K`、`1:1`、`4x4 / 16` 图标板
- 附带脚本：`skills/gpt-icon-generate/scripts/verify_image_output.py`、`skills/gpt-icon-generate/scripts/plan_icon_sheet_params.py`、`skills/gpt-icon-generate/scripts/split_icon_sheet_connected_bbox.py`

## 环境变量说明

### GPT Image 工具

| 变量名 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `IMG_GEN_GPT_IMAGE_2_OFFICIAL_API_KEY` | 是 | 空 | `gpt_image_2_official` 使用的 API Key |
| `IMG_GEN_GPT_IMAGE_2_OFFICIAL_BASE_URL` | 否 | `https://api.openai.com/v1` | OpenAI Images 官方兼容网关地址 |
| `IMG_GEN_GPT_IMAGE_2_OFFICIAL_MODEL` | 否 | `gpt-image-2` | 默认调用模型 |
| `IMG_GEN_GPT_IMAGE_2_OFFICIAL_SUPPORTED_MODELS` | 否 | `gpt-image-2,gpt-image-2-vip` | 允许调用的模型白名单，逗号分隔 |

### Nano Banana 工具

| 变量名 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `IMG_GEN_NANO_BANANA_2_OFFICIAL_API_KEY` | 是 | 空 | `nano_banana_2_official` 使用的 API Key |
| `IMG_GEN_NANO_BANANA_2_OFFICIAL_BASE_URL` | 否 | `https://generativelanguage.googleapis.com` | Gemini 官方兼容网关地址 |
| `IMG_GEN_NANO_BANANA_2_OFFICIAL_MODEL` | 否 | `gemini-3.1-flash-image-preview` | 默认调用模型 |
| `IMG_GEN_NANO_BANANA_2_OFFICIAL_SUPPORTED_MODELS` | 否 | `gemini-3.1-flash-image-preview` | 允许调用的模型白名单，逗号分隔 |

### 通用变量

| 变量名 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `IMAGE_OUTPUT_DIR` | 否 | `storage/images` | 生成图片的落盘目录 |
| `IMAGE_BASE_URL` | 否 | 空 | 若需要对外暴露图片 URL，可配置对应静态资源基地址 |
| `IMAGE_HTTP_TIMEOUT_SECONDS` | 否 | `180` | 服务端请求上游图片生成接口及下载图片的 HTTP 超时时间，单位秒；远端 MCP 客户端自身也可能有独立 tool-call 超时，需要在客户端侧另行配置，文档推荐 `timeout=500000` 毫秒（500 秒），并可补充说明极端情况下最长可能到 12 分钟 |
| `LOG_LEVEL` | 否 | `INFO` | 日志级别 |

### GPT Image 2 URL 工具

| 变量名 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `IMG_GEN_GPT_IMAGE_2_URL_API_KEY` | 是 | 空 | `gpt-image-2-url` 使用的 API Key |
| `IMG_GEN_GPT_IMAGE_2_URL_BASE_URL` | 否 | `https://www.right.codes/draw/v1` | URL 返回型网关地址 |
| `IMG_GEN_GPT_IMAGE_2_URL_MODEL` | 否 | `gpt-image-2-vip` | 默认调用模型 |
| `IMG_GEN_GPT_IMAGE_2_URL_SUPPORTED_MODELS` | 否 | `gpt-image-2-vip` | 允许调用的模型白名单，逗号分隔 |


## 许可证

本项目采用 `MIT` 许可证，完整文本见 `LICENSE`。
