# SeeAny Product Visuals

让 WorkBuddy、Codex、Claude Code、Cursor 等支持 MCP 的 AI Agent，直接调用 SeeAny 的电商商品视觉生成能力。

> 给 AI Agent 装上商品视觉创作能力。

SeeAny Product Visuals 是面向 AI Agent 的电商商品视觉生成 MCP。Agent 可以通过它完成一条可追踪的商品图工作流：识别当前模型能力、上传商品参考图、润色提示词、预估费用、创建出图任务、等待任务完成，并把结果下载到本地。使用者不需要在对话中复制 API 请求、轮询任务状态或手动下载图片。

## 这个 MCP 能做什么

- **商品白底主图**：基于文字或商品参考图生成干净、聚焦主体的电商主图。
- **商品场景图**：把商品放入摄影棚、家居、户外、节日营销等视觉场景。
- **材质与细节图**：生成突出纹理、结构、工艺和卖点的商品特写。
- **参考图驱动生成**：上传本地商品图，并在后续任务中通过 `asset_id` 使用它。
- **AI 提示词润色**：把简单需求整理成包含构图、光线、材质、背景和约束的生产级提示词。
- **费用预估**：在真实生成前，根据模型、分辨率和数量返回估算费用；询价不会预扣费用。
- **异步任务管理**：创建任务后查询或等待状态，避免 Agent 因超时而重复提交付费任务。
- **结果落盘**：把完成的图片下载到指定本地目录，并返回可继续用于代码或设计工作的文件路径。
- **两阶段安全生成**：先返回完整方案与费用，再由用户确认执行；重复使用同一 `plan_id` 会恢复已有任务，避免超时后重复提交。

## 适合哪些场景

- 电商独立站、Amazon、Shopify、Temu 等商品主图和详情页素材
- 新品概念图、广告创意图、社交媒体商品视觉
- 同一商品的不同背景、构图、比例和视觉方向测试
- 在开发流程中让 Agent 自动生成占位图、演示图或真实营销素材
- 将 SeeAny 出图能力接入自动化脚本、IDE Agent 或内部内容生产流程

下面这些能力**尚未作为独立 MCP 工具开放**：视频生成、虚拟试穿、局部重绘、背景移除/替换和图片文字精确编辑。Agent 不应把商品图生成工具描述成这些专用能力。

## 工作方式

```text
Agent
  └─ 规划商品视觉（不创建付费任务）
      └─ 展示参数与预计费用
          └─ 用户确认
              └─ 执行、等待并下载结果
```

普通请求推荐调用 `seeany_plan_product_visual`，确认方案后再调用 `seeany_create_product_visual`。高级调用方仍然可以使用上传、润色、询价、生成、查询和下载等底层工具精细控制流程。

## 11 个 MCP 工具

| MCP 工具 | 作用 | 主要结果 | 是否可能产生费用 |
| --- | --- | --- | --- |
| `seeany_plan_product_visual` | 整理需求、验证本地参考图并生成执行计划 | `plan_id`、生产提示词、参数与预计费用 | 否，不创建生成任务 |
| `seeany_create_product_visual` | 确认后执行计划、等待任务并下载结果 | `job_id`、状态与本地文件路径 | Live 模式会产生费用 |
| `seeany_get_capabilities` | 查询模型、比例、分辨率和当前运行模式 | 模型与能力列表 | 否 |
| `seeany_get_account` | 判断 MCP 当前处于 Demo 还是 Live 模式 | 鉴权与模式信息 | 否 |
| `seeany_upload_asset` | 上传本地商品参考图 | `asset_id`、图片 URL | 通常否 |
| `seeany_refine_prompt` | 用 AI 润色商品图提示词 | 优化后的提示词 | Live 模式可能收费 |
| `seeany_quote_generation` | 生成前估算费用 | 预计价格或 Demo 积分 | 否，不预扣费用 |
| `seeany_generate_product_image` | 创建商品图异步任务 | `job_id`、初始状态 | Live 模式会产生费用 |
| `seeany_get_generation` | 查询单个任务的最新状态 | 状态、输出 URL、错误信息 | 否 |
| `seeany_wait_generation` | 轮询任务直到完成或超时 | 最终状态和输出列表 | 否 |
| `seeany_download_assets` | 下载任务生成的图片 | 本地文件路径 | 否 |

当前图片任务支持：

- 用途：`white_background`、`scene`、`detail`
- 模型：`seeany-quality`、`seeany-fast`
- 数量：每个任务 1–4 张
- 比例：自动、1:1、3:4、4:5、9:16、2:3、16:9、4:3、5:4、3:2、21:9
- 分辨率：1K、2K、4K，具体可用范围以 `seeany_get_capabilities` 返回结果为准

## Demo 与 Live 模式

### Demo 模式

未设置 `SEEANY_API_KEY` 时自动启用：

- 不访问 SeeAny 付费 API
- 不产生真实费用
- 返回模拟任务、状态和示例输出，用于验证 MCP 安装与 Agent 调用链
- Demo 结果不是模型真实生成结果，不能用于评价实际出图质量

也可以显式设置 `SEEANY_MCP_MODE=demo` 强制使用 Demo 模式。

### Live 模式

设置 `SEEANY_API_KEY` 后，MCP 会调用 `https://api.seeany.com`：

```bash
SEEANY_API_KEY=sk-sa-xxxxxxxx
```

Live 模式支持真实上传、提示词润色、商品图生成、任务轮询和下载。生成任务及部分 AI 能力会按 SeeAny 账户配置计费；实际账单以 SeeAny 开发者后台为准。

不要把真实 Key 写入 Git、前端代码、截图或聊天消息。Key 必须位于启动 MCP 进程的本机环境中。

## 快速开始

要求 Node.js 20 或更高版本。

直接启动：

```bash
npx --yes seeany-product-visuals-mcp@latest
```

连接 Codex：

```bash
codex mcp add seeany-product-visuals -- npx --yes seeany-product-visuals-mcp@latest
```

其他 MCP Client 可使用等价配置：

```json
{
  "mcpServers": {
    "seeany-product-visuals": {
      "command": "npx",
      "args": ["--yes", "seeany-product-visuals-mcp@latest"],
      "env": {
        "SEEANY_API_KEY": "由本机安全环境提供，不要提交到仓库"
      }
    }
  }
}
```

只想体验调用流程时，删除 `env` 中的 Key 即可进入 Demo 模式。

## 在 WorkBuddy 中使用

WorkBuddy 可以通过用户级或项目级 MCP 配置直接启动这个 npm 包：

```json
{
  "mcpServers": {
    "seeany-product-visuals": {
      "command": "npx",
      "args": ["--yes", "seeany-product-visuals-mcp@latest"]
    }
  }
}
```

保存后先让 WorkBuddy “使用 SeeAny 规划一张商品图并展示费用，不要直接生成”。完整配置路径、Live 模式和排错步骤见 [WorkBuddy 接入指南](./docs/workbuddy.md)。

如果通过 SkillHub 分发商品视觉工作流，建议让 Skill 调用这个 MCP，而不是由 Agent 自行拼接 SeeAny API。详情见 [SkillHub 发布与旧 Skill 迁移说明](./docs/skillhub.md)。

## 安装为 Codex 插件（MCP + Skill）

插件安装后会同时提供 SeeAny MCP 工具和 `seeany-product-visuals` 商品视觉工作流 Skill。Skill 会优先指导 Agent 使用“规划并询价 → 用户确认 → 执行并下载”的两阶段流程，同时保留底层工具供高级工作流使用。

```bash
codex plugin marketplace add juin20260102-oss/seeany-product-visuals-mcp --sparse .agents/plugins
codex plugin add seeany-product-visuals-mcp@seeany
```

安装或升级后请新开一个 Codex 对话，使最新工具和 Skill 生效。真实出图仍需在本机设置 `SEEANY_API_KEY`。

## 可以怎样向 Agent 提需求

```text
用这张商品图生成一张 1:1 的白底电商主图。先询价，确认后再生成并下载到 ./outputs。
```

```text
把这款香水放进高级黑金摄影棚场景，强调玻璃瓶材质和轮廓光，生成 2 张 4:5 图片。
```

```text
先把我的简单描述润色成适合电商详情页的提示词，然后用快速模型做一张低成本测试图。
```

在 Live 模式中，Agent 应在创建付费任务前展示估算费用；如果任务等待超时，应使用原 `plan_id` 恢复原 `job_id`，而不是重新创建任务。

## 本地开发与测试

```bash
cd mcp-server
npm install
npm run build
npm run smoke
```

`npm run smoke` 强制使用 Demo 模式，不产生真实费用。

执行真实 API 链路验收：

```bash
npm run live-smoke
```

该命令会调用主站 API 并可能产生账户费用。调试 MCP 协议时可运行：

```bash
npm run inspect
```

## SeeAny API 映射

| MCP 工具 | SeeAny API |
| --- | --- |
| `seeany_plan_product_visual` | 本地规划与费用估算，不创建远程生成任务 |
| `seeany_create_product_visual` | 编排上传、生成、状态查询和下载流程 |
| `seeany_upload_asset` | `POST /api/upload/image` |
| `seeany_refine_prompt` | `POST /api/prompt-tools/ai-refine` |
| `seeany_generate_product_image` | `POST /api/ai/smarttask`，`aiTypeId=113`，`aiType=smartImg` |
| `seeany_get_generation` / `seeany_wait_generation` | `GET /api/developer/task/status` |

任务默认采用异步模式。MCP 内存中保存本次进程创建的 `plan_id`、`asset_id` 和 `job_id` 映射；同一进程中重复执行 `plan_id` 不会创建第二条任务。重启 MCP 后，旧的本地映射不会自动恢复。

## 自动测试与发布

GitHub Actions 会在 `main` 分支 Push 和 Pull Request 时，使用 Node.js 20、22、24 执行插件校验、MCP Smoke Test 和 npm 打包检查。

推送与包版本一致的 Git Tag 后，`release.yml` 会验证版本、执行完整测试、发布 npm 包并创建 GitHub Release。当前发布使用仓库加密 Secret `NPM_TOKEN`；后续可迁移到 npm OIDC Trusted Publishing。

## 链接

- SeeAny 开发者文档：https://www.seeany.com/developer
- npm：https://www.npmjs.com/package/seeany-product-visuals-mcp
- GitHub：https://github.com/juin20260102-oss/seeany-product-visuals-mcp
- License：MIT