Metadata-Version: 2.4
Name: listing-image-mcp
Version: 0.2.0
Summary: 商品生图 MCP：文生图/参考图生图/组图，可插拔后端（mock 零密钥 / Seedream 5.0 lite）
Keywords: ecommerce,image-generation,listing,mcp,seedream
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp<2.0.0,>=1.2.0
Requires-Dist: pillow>=10.0.0
Description-Content-Type: text/markdown

# listing-image-mcp

商品生图 MCP 服务。产出商品主图组（多图类型）+ 详情页图，供智能体在「视觉生成」环节调用。
每张生成图都带 `ai_generated=True` 元信息（合规：AI 生成内容标识）。

## 工具

`generate_image(prompt, reference_image_urls, size, count, watermark, output_format, output_dir)` —— 统一生图入口：

| 模式 | 触发 | 说明 |
|------|------|------|
| 文生图 | reference_image_urls 为空 | 纯文本生成 |
| 单图生图 | 1 张参考图 | 实物图保商品一致 |
| 多图生图 | 2-14 张参考图 | 多张实物图 + 可选爆款构图参考 |
| 组图 | count>1 | 一次生成一组内容关联、风格统一的图 |

## 工作区交付（v0.2 起）

图片写到「工作区」，由环境变量 `WORKSPACE_ROOT`（工作区绝对根目录，平台注入）+ 入参 `output_dir`（工作区相对路径）共同决定。

- `output_dir` 必须是**工作区相对路径**（如 `方案/某商品-视觉素材/主图`），留空则写工作区根；禁止绝对路径。
- 返回每张图的 `file_name` + `workspace_path`（工作区可见相对路径）+ `url` + 尺寸 + `ai_generated` + `reference_used` + `status`。
- 落盘即校验、失败即阻断、禁止 mock 占位输出——拿不到真实图片就诚实报错，不伪造成功。

## 后端（可插拔）

- `mock`（默认）—— 仅本地联调；**交付路径禁用**（`ready()` 恒为 False，未配真实密钥时直接报错）。
- `seedream` —— 字节系 Seedream 5.0 lite（火山方舟）。

## 启动（STDIO MCP）

```bash
uvx listing-image-mcp
```

## 环境变量

| 变量 | 必填 | 说明 |
|------|------|------|
| `WORKSPACE_ROOT` | 工作区交付时 | 工作区绝对根目录（由平台注入），缺省则生成失败 |
| `IMAGE_BACKEND` | 否 | mock（默认，交付禁用）/ seedream |
| `ARK_API_KEY` | seedream 时 | 火山方舟 API Key |
| `ARK_BASE_URL` | 否 | 默认 `https://ark.cn-beijing.volces.com/api/v3` |
| `ARK_MODEL` | 否 | 默认 `doubao-seedream-5-0-lite-260128` |
| `IMAGE_OUTPUT_DIR` | 否 | 后端兜底保存目录，默认 `~/.listing_image_mcp/generated` |
| `IMAGE_MAIN_SIZE` | 否 | 主图默认尺寸，默认 `2048x2048` |
| `IMAGE_DETAIL_SIZE` | 否 | 详情页默认尺寸，默认 `1920x2560` |

## Seedream 5.0 lite 已核实要点

- 端点：`POST {ARK_BASE_URL}/images/generations`
- 模型：`doubao-seedream-5-0-lite-260128`
- 参考图：`image` 字段，单字符串或字符串数组（2-14 张）；接受 URL / base64 data URL / 本地路径（自动转 base64）
- 组图：`sequential_image_generation = "auto"`
- 尺寸：最小 3,686,400 像素（1920x1920），更小会 400，本包自动抬升
- 水印：`watermark=false` 即无平台水印
