listing-image-mcp

# 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` 即无平台水印