# opencode-image-mcp

给**不支持生图能力的主模型**（如 DeepSeek）提供"画画"能力的 MCP server。

主模型只需给出文字描述（和可选的参考图路径），本 server 调用第三方生图模型（**通义万相 qwen-image / 豆包 Seedream / 智谱 CogView**）生成图片，下载到本地 `outputs/` 目录，返回本地文件路径——**图片数据不进入主模型上下文**。

## 功能特性

- 🎨 **文生图**：文字描述 → 生成图片
- 🖼️ **图生图**：参考图 + 文字指令 → 风格转换/变体/编辑
- 🔄 **多后端可切换**：qwen-image（阿里云）/ Seedream（火山方舟）/ CogView（智谱）
- 📁 **结果落盘**：生成图片保存到本地 `outputs/`，返回 `file://` 路径
- 🚫 **零 base64 污染**：主模型上下文只接触路径字符串
- 🔁 **自动重试**：429 / 5xx 指数退避重试
- 🤝 **与 vision MCP 协同**：生成的图可直接用 vision MCP 自检质量

## 原理

```
你在对话框输入文字描述（+可选参考图路径）
  ↓
主模型调用 image_generate 工具
  ↓
本 server 调用生图后端（qwen-image / Seedream）
  ↓
生成图片 → 下载到 outputs/ 目录
  ↓
返回 {"images": [{"path": "C:/.../outputs/xxx.png"}], ...}
  ↓
主模型把路径展示给你；配合 vision MCP 可回读检查生成质量
```

**图片字节全程不进入主模型上下文**——只传路径字符串。

## 目录结构

```
opencode-image-mcp/
├── server.py              # MCP server 主程序（stdio 传输）
├── requirements.txt       # Python 依赖
├── .env.example           # 环境变量模板
├── .gitignore
├── LICENSE                # MIT
└── outputs/               # 生成图片输出目录（自动创建）
```

## 安装

### 环境要求
- Python >= 3.10
- opencode
- 至少一个生图后端的 API key

### 安装步骤

```bash
git clone https://github.com/Jsliu28/opencode-image-mcp.git
cd opencode-image-mcp

python -m venv .venv
# Windows:
.\.venv\Scripts\Activate.ps1
# macOS/Linux:
source .venv/bin/activate

pip install -r requirements.txt

cp .env.example .env   # 编辑 .env 填入 API key
```

### 配置 API key

| 标识 | 名称 | API key 环境变量 | 默认模型 |
|------|------|-----------------|----------|
| `wanx` | 通义万相 qwen-image | `DASHSCOPE_API_KEY` | qwen-image-3.0-pro |
| `seedream` | 豆包 Seedream | `ARK_API_KEY` | dola-seedream-5-0-pro-260628 |
| `zhipu` | 智谱 CogView | `ZHIPU_API_KEY` | cogview-4 |

- 通义万相：`https://bailian.console.aliyun.com/`（与 vision MCP 共用 key）
- 火山方舟：`https://console.volcengine.com/ark`
- 智谱：`https://open.bigmodel.cn/`

### 配置到 opencode

编辑 `~/.config/opencode/opencode.json`：

```json
{
  "mcp": {
    "image": {
      "type": "local",
      "command": ["python", "C:/你的路径/opencode-image-mcp/server.py"],
      "enabled": true,
      "environment": {
        "IMAGE_DEFAULT_PROVIDER": "wanx"
      }
    }
  }
}
```

> `python` 不在 PATH 时用虚拟环境解释器绝对路径。API key 在 `.env` 中自动读取。

## 使用示例

```
你：画一只戴帽子的猫，卡通风格
你：画一张 16:9 的风景壁纸
你：把这张图 C:/Users/me/photo.png 变成水彩画风格
你：参考 https://example.com/ref.jpg 生成同风格的海报
```

## 工具说明

### image_generate
文生图 + 图生图（一个工具）。参数：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `prompt` | `string` | ✅ | 图片描述（或对参考图的编辑指令） |
| `input_image_path` | `string` | ❌ | 参考图路径/URL，提供后为图生图 |
| `size` | `string` | ❌ | 尺寸。wanx: `1024*1024` / `720*1280` / `1280*720`；seedream: `1K` / `2K` |
| `provider` | `string` | ❌ | `wanx` / `seedream` / `zhipu`，覆盖默认后端 |
| `model` | `string` | ❌ | 具体模型名（如 `qwen-image-edit-max`） |

### image_list_models
列出可用生图后端、模型、配置状态。

## 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `IMAGE_DEFAULT_PROVIDER` | `wanx` | 默认后端 |
| `DASHSCOPE_API_KEY` | - | 通义万相 key |
| `ARK_API_KEY` | - | 豆包 Seedream key |
| `ZHIPU_API_KEY` | - | 智谱 CogView key |
| `IMAGE_OUTPUT_DIR` | `outputs` | 输出目录 |
| `IMAGE_MAX_RETRIES` | `2` | 失败重试次数 |
| `IMAGE_RETRY_BASE_DELAY` | `1.0` | 重试基础等待（秒） |

## 扩展新的生图后端

项目采用**后端注册表 + 统一函数签名**设计，新增一家后端只需 3 步（在 `server.py` 中）：

1. **注册配置**：在 `PROVIDERS` 字典中添加一个条目（仿照现有条目），指定：
   - `api_key_env`：API key 的环境变量名
   - `task_submit_url`：生图接口地址
   - `models` / `default_model`：文生图模型
   - `i2i_models` / `i2i_default_model`：图生图模型（如支持）
   - `sizes`：可用尺寸列表

2. **实现生成函数**：编写 `_xxx_generate(prompt, model, size, input_image_data, input_image_mime, input_image_url)`，**保持与其他后端相同的参数签名**，内部实现该后端的请求构造与响应解析，最后返回本地文件路径列表（`List[Path]`）。

3. **注册调度**：在 `_generate` 调度函数中添加该 provider 的分支分发。

完成后即可通过 `provider` 参数使用新后端，无需改动 MCP 工具层。参考实现：`_wanx_generate` / `_seedream_generate` / `_zhipu_generate`。

## 常见问题

**Q: 报"后端未配置"？**
A: 检查 `.env` 中对应 key，`image_list_models` 可查看状态。

**Q: 参考图无法读取？**
A: 参考图需为本地绝对路径或可公开访问的 URL，最大 20MB。

**Q: 生成太慢？**
A: qwen-image 同步接口通常 10-30 秒；限流（429）会自动重试。

**Q: 生成的图在哪？**
A: 返回的 `path` 即本地文件位置，默认在项目 `outputs/` 目录。

**Q: 能接其他生图模型吗？**
A: 可以。参考"扩展新的生图后端"章节，在 `server.py` 中按 3 步添加即可（注册表 + 函数 + 调度）。

## License

MIT