# Visual Generator MCP

外部多模态生成 MCP Server（图片 + 视频），用于在 Tailscale 内网被 MCP Host（例如 eCommerceAgent）接入并调用。

## 目标
- 只负责生成与交付：调用方负责业务语义，本服务负责模型调用与 OSS/CDN URL 返回。
- 工具稳定：`imageGenerate`、`videoGenerate`、`materialWrite` 三块。
- 模式统一：`imageGenerate/videoGenerate` 通过 `generationMode` 区分常规与智能模式。

## 工具（MCP Tools）

### 1) `imageGenerate`（Host 落位点：`visual__imageGenerate`）
- 必填：`vendor`、`modelName`、`prompt`、`storageMode/env/project/referenceType/referenceId`
- 新增：`generationMode`（`normal|smart`，默认 `normal`）
- 当前状态：
  - `generationMode=normal` 已支持
  - `generationMode=smart` 首期预留（未开放）
- 出参：`structuredContent.images[]`（`imageUrl/mimeType/objectKey`）

### 2) `videoGenerate`（Host 落位点：`visual__videoGenerate`）
- 常规必填：`vendor`、`modelName`、`storageMode/env/project/referenceType/referenceId`
- 模式字段：`generationMode`（`normal|smart`，默认 `normal`）
- 模式说明：
  - `normal`：调用方提供完整 prompt 与参数
  - `smart`：先做需求分析与方案生成，再做素材匹配与分段生成（视频优先实施）
- 出参：`structuredContent.videos[]`（`videoUrl/mimeType/objectKey`）

### 3) `materialWrite`（Host 落位点：`visual__materialWrite`）
- 定位：将用户认可素材写入素材库，并自动打标签与权限字段。
- 当前状态：规划中（详见 `docs/plan/plan-intelligent-generation.md`）。

兼容说明（历史调用）：
- 旧工具名 `generate` / `generateVideo` 已废弃，调用方需升级到 `imageGenerate` / `videoGenerate`。

## 快速开始
1) 安装依赖
```bash
npm install
```

2) 配置环境变量
```bash
cp .env.example .env
```

3) 启动 SSE MCP Server
```bash
npm run dev:sse
```

健康检查：
```bash
curl -i http://localhost:3107/health
```

## 接入 eCommerceAgent（示例）
```json
{
  "mcpServers": {
    "visual": {
      "transport": "sse",
      "endpoint": "http://<tailscale-ip>:3107/"
    }
  }
}
```

Verify 后应看到：
- `visual__imageGenerate`
- `visual__videoGenerate`