# flow-mcp — Google Flow MCP Server

Google Flow 的独立 MCP server(从 [media-gen-mcp](https://github.com/wangdong233/media-gen-mcp) 分离):**0 积分 AI 生图** + 计费视频生成(Veo / abra),全部经**你本机的 Chrome 会话**(CDP 页面上下文)驱动 —— 无 API key、无配额、不走第三方转发。

- 生图 / 图片放大 / 上传 / 状态查询 / 下载 / 删除 / 分享 / 取消 / 角色实体:**全部 0 积分**
- 生视频:**消耗 Google Flow 积分**(abra 7-20 / veo lite 10 / fast 20 / quality 100 每条;1080p 超分 0)—— 工具描述里显式警示,默认只在用户点名时使用

## 安装

前置(一次性):

1. 本机安装 [lasso](https://www.npmjs.com/package/lasso-mcp)(CC 全交互抓手中的 Chrome 启动器)
2. 启动带 CDP 的 Chrome 并登录 labs.google:

```bash
lasso launch-chrome --port 9223 --mode visible   # 首次:窗口出现,完成 Google 登录(2FA 同)
# 之后每天只需:hidden 模式静默驻留
lasso launch-chrome --port 9223
```

3. 在该 Chrome 打开 https://labs.google/fx/tools/flow 任意项目页(保持运行)

接入 Claude Code:

```bash
claude mcp add flow-mcp -- node /path/to/flow-mcp/dist/index.js
# 或发布后:npx flow-mcp-server
```

与 media-gen-mcp 可同时接入,互不冲突(见下方「与 media-gen-mcp 共存」)。

## 工具(4 个)

| 工具 | 积分 | 用途 |
|---|---|---|
| `flow_generate_image` | **0** | 文生图 / 图生图(底图+参考图)/ 2K 放大。NARWHAL(Nano Banana 2,默认)/ HARBOR_SEAL / GEM_PIX_2(Nano Banana Pro)。支持 `aspect`(16:9/9:16/1:1/3:4/4:3)与 `seed` 精确复现 |
| `flow_generate_video` | 🔴 **计费** | 视频提交(t2v/i2v/r2v/首尾帧/延长/编辑/超分)。**只提交不等待**,立刻返回 mediaId 句柄 |
| `flow_status` | **0** | 一站式自省:积分余额 / 实时模型目录(每个 key 的积分价与耗时)/ 媒体列表 / 单媒体状态与下载 / 批量删除 / 公开分享链接 / 取消生成中任务。**也是视频句柄的轮询路径** |
| `flow_entity` | **0** | 角色实体:建角色卡 / 绑 30 选 1 预设语音 / 绑形象图 |

典型流程:

```
flow_status                                    # 先看:余额 + 目录(per-key creditsAtServiceTier)
flow_generate_image(prompt=..., aspect="16:9") # 0 积分生图,产出落盘并回传 mediaId+seed
flow_generate_video(model="abra_t2v_8s", ...)  # 🔴 计费提交 → 返回 mediaId 句柄(不阻塞)
flow_status(mediaId="...")                     # 轮询(0 积分;in_progress 会给 retry_after_seconds)
flow_status(mediaId="...", download=true)      # completed 后落盘 mp4
```

## 配置(与 media-gen-mcp 共享一个文件)

配置文件:`~/.media-gen-mcp/config.json`(两包读同一份 —— 「同一功能的不同实现渠道」在一个文件里统一开/关)。目录名沿用历史名,**勿改**(Flow 项目 ID 永久记录在 `~/.media-gen-mcp/flow-project.json`,改名会孤儿化)。

```json
{
  "flow": {
    "enabled": true,
    "imageRouting": "prefer",
    "videoRouting": "explicit-only",
    "toolDeadlineMs": 110000
  },
  "providers": {
    "flow": { "cdpPort": 9223 }
  }
}
```

| 字段 | 默认 | 作用 |
|---|---|---|
| `flow.enabled` | `true` | `false` = S000 门禁:4 个工具**仍注册**,但调用即刻返回 `[flow] S000` 结构化错误(自带修复指引)。改配置后须重启会话 |
| `flow.imageRouting` | `"prefer"` | `prefer` = 生图工具描述注入「0 积分优先」引导(软路由);`on-demand` = 仅当用户点名 Flow 时使用 |
| `flow.videoRouting` | `"explicit-only"` | `explicit-only`(积分红线)= 视频工具仅在用户显式要求 Flow/Veo/abra 时使用;`prefer` = 作为首选(仍警示计费) |
| `flow.toolDeadlineMs` | `110000` | 单次工具调用硬上限(防卡死;超时返回 `[flow] S410`,生成在服务端继续,可经 `flow_status` 找回) |
| `providers.flow.cdpPort` | `9223` | CDP 端口(与 `lasso launch-chrome --port` 一致) |
| `providers.flow.projectId` | (缺省) | 缺省读 `flow-project.json` 的永久项目(推荐 —— 项目 ID 永久复用) |
| `providers.flow.models.video.default` | (无) | 刻意无内置默认:视频计费,必须显式传 `model` 或在此显式配置 |

完整示例见 [`config.example.json`](./config.example.json)。

### 与 media-gen-mcp 共存

- 两包**共享** `~/.media-gen-mcp/config.json`;media-gen 自己的 `imageProviderPriority` / `videoProviderPriority` 链只在它包内生效
- 分离后的跨包优先级 = 本包工具描述软路由(`imageRouting`/`videoRouting` 引导 Claude 选 `flow_generate_image` 优先)+ `enabled` 总闸 —— 不存在跨包硬重定向(物理上两包互不可见,诚实设计)
- `flow-project.json` / `flow-entities.json` 归本包;media-gen 侧摘除 Flow 后不再读写

## 错误码速查(`[flow] S<code>`)

| 码 | 含义 | 处置 |
|---|---|---|
| `S000` | 配置已禁用 | 按错误里的指引把 `flow.enabled` 改回 `true`,重启会话 |
| `S100` | CDP 不可连 | `lasso launch-chrome --port 9223` |
| `S101` | 无 labs.google 页面 | 在该 Chrome 打开 Flow 项目页 |
| `S102` | 未登录 | 在该 Chrome 完成 labs.google 登录 |
| `S104` | reCAPTCHA 失败 | 停留在 Flow 页面重试 |
| `S1xx` 其余 | 环境前置 | 环境就绪后重试;生图可回落其他图像工具 |
| `S2xx` | 页面 fetch 失败 | 看 message 内的上游响应片段 |
| `S300/S301/S303` | 模型/参数/模式校验 | 按 message 指引换 key 或参数(提交前拦截,零消耗) |
| `S400` | mediaId 不在本项目 | 不带参数调 `flow_status` 查看全部 media |
| `S402` | 下载不完整 | 直接重试 |
| `S410` | 工具层截止(防卡死) | 生成仍在服务端进行;`flow_status` 不带参数找回 |

## 环境要求

- Node.js ≥ 18
- 本机 Chrome(经 lasso 以 `--remote-debugging-port=9223` 启动)并登录 labs.google
- FFmpeg 随包自带(ffmpeg-static;仅用于产物合法性自检,缺失时自动降级为提示)

## License

MIT