# MetaRouter Media MCP

把 MetaRouter 的生图接口和 HappyHorse 视频接口接入 Codex 或其他支持 MCP 的客户端。安装后，你可以直接用自然语言让 Codex 生成、编辑图片，也可以提交文生视频、图生视频、参考图生视频和视频编辑任务。

这个项目从零实现，服务地址固定为 `https://metarouters.org`，不会把 API Key 发送到用户指定的第三方地址。

## 支持的工具

| MCP 工具 | 用途 |
| --- | --- |
| `image_generate` | 文生图，一次生成 1–4 张图片 |
| `image_edit` | 根据提示词编辑一张本地图片 |
| `image_batch_edit` | 对多张本地图片逐张执行同一种编辑 |
| `image_multi_reference` | 以 2–10 张图片作为同一次生成的参考图 |
| `video_generate` | 提交 HappyHorse 文生视频、图生视频、参考图生视频或视频编辑任务 |
| `video_status` | 查询任务；可轮询等待完成并安全下载 MP4 |
| `video_download` | 下载已完成任务返回的受信任 HTTPS 视频 URL |
| `server_info` | 查看当前模型、保存目录和安全设置，不返回密钥 |

默认模型是 `gpt-image-2`。当尺寸达到约 4K 时会自动选择 `gpt-image-2-pro`，也可以在调用时显式指定模型。

HappyHorse 支持 `happyhorse-1.0-t2v`、`happyhorse-1.0-i2v`、`happyhorse-1.0-r2v` 和 `happyhorse-1.0-video-edit`。除纯文生视频外，上游当前要求素材使用公网 HTTPS URL，不接受本地路径或 Base64。

## 快速安装到 Codex

要求：

- Python 3.10 或更高版本
- 已安装 Codex 桌面端或 Codex CLI
- 一个可用的 MetaRouter API Key

克隆仓库并运行安装器：

```powershell
git clone https://github.com/cimicimi9090/mcp-pic-metarouters.git
cd mcp-pic-metarouters
python install.py
```

安装器会：

1. 隐藏输入 API Key；
2. 调用 `https://metarouters.org/v1/models` 验证密钥及图片/视频模型；
3. 安装 Python 依赖；
4. 备份并更新 `~/.codex/config.toml`；
5. 将图片和视频默认保存到 `~/Pictures/MetaRouter`。

安装完成后重启 Codex。先尝试：

```text
调用 metarouter-image 的 server_info
```

然后可以直接说：

```text
调用 image_generate，生成一张 1536x1024 的写实产品图：
白色摄影棚里悬浮着一台银色未来主义路由器，柔和轮廓光，高级商业摄影。
```

也可以直接说：

```text
调用 video_generate，使用 happyhorse-1.0-t2v 生成 5 秒、720P、16:9 的视频：
澳门雨夜，一辆未来主义电动跑车驶过霓虹街道，电影级运镜。
提交后继续调用 video_status，wait=true，等待完成。
```

## Codex 手动配置

不使用安装器时，可以先安装当前项目：

```powershell
python -m pip install -e .
```

然后在 `~/.codex/config.toml` 中添加以下配置。请把路径和密钥替换为你自己的值：

```toml
[mcp_servers.metarouter-image]
command = "C:/Path/To/python.exe"
args = ["D:/Path/To/mcp-pic-metarouters/server.py"]
startup_timeout_sec = 30
tool_timeout_sec = 900

[mcp_servers.metarouter-image.env]
METAROUTER_API_KEY = "sk-your-metarouter-key"
METAROUTER_IMAGE_MODEL = "gpt-image-2"
METAROUTER_IMAGE_PRO_MODEL = "gpt-image-2-pro"
METAROUTER_VIDEO_MODEL = "happyhorse-1.0-t2v"
METAROUTER_SAVE_DIR = "C:/Users/you/Pictures/MetaRouter"
METAROUTER_SAVE_DIR_ROOT = "C:/Users/you/Pictures/MetaRouter"
METAROUTER_TRUSTED_VIDEO_HOSTS = "metarouters.org"
```

## 使用示例

文生图：

```text
调用 image_generate：
- prompt：一张极简蓝紫渐变的 SaaS 产品封面，中心是抽象字母 M，干净留白
- size：1024x1024
- n：1
```

编辑本地图片：

```text
调用 image_edit：
- image_path：C:/Users/you/Pictures/source.png
- prompt：保留主体构图，把背景改成夜晚的东京街头，增加自然霓虹反光
- size：1536x1024
```

多参考图：

```text
调用 image_multi_reference：
- image_paths：两到十张本地 PNG、JPEG 或 WebP 文件
- prompt：使用第一张的构图、第二张的配色和第三张的材质，生成统一的新设计
- size：2048x2048
```

工具返回生成文件的绝对路径，Codex 可以继续读取、展示或交给后续流程处理。

文生视频：

```text
调用 video_generate：
- model：happyhorse-1.0-t2v
- prompt：无人机穿越未来城市峡谷，日落金色逆光，连续电影镜头
- duration：5
- resolution：720P
- ratio：16:9
```

提交后把返回的 `task_id` 交给 `video_status`。设置 `wait=true` 可持续轮询，设置 `download=true` 可在完成后下载。图生视频使用 `happyhorse-1.0-i2v` 并传入一个 `image_url`；参考图生视频使用 `happyhorse-1.0-r2v` 并传入 1–9 个 `reference_image_urls`；视频编辑使用 `happyhorse-1.0-video-edit` 并传入 `video_url`。

若结果视频的域名不在信任列表中，先确认它确实属于 MetaRouter/上游视频 CDN，再把该域名加入 `METAROUTER_TRUSTED_VIDEO_HOSTS` 并重启 Codex。不要使用通配符。

## 环境变量

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `METAROUTER_API_KEY` | 无 | 必填，MetaRouter API Key |
| `METAROUTER_IMAGE_MODEL` | `gpt-image-2` | 常规生图模型 |
| `METAROUTER_IMAGE_PRO_MODEL` | `gpt-image-2-pro` | 大尺寸自动使用的模型 |
| `METAROUTER_VIDEO_MODEL` | `happyhorse-1.0-t2v` | 默认 HappyHorse 视频模型 |
| `METAROUTER_TIMEOUT` | `300` | 请求超时秒数，最小 30 秒 |
| `METAROUTER_SAVE_DIR_ROOT` | `~/Pictures/MetaRouter` | MCP 允许写入的根目录 |
| `METAROUTER_SAVE_DIR` | 与根目录相同 | 默认输出目录，必须位于根目录内 |
| `METAROUTER_INPUT_ROOT` | 不限制 | 可选；设置后只允许读取该目录内的参考图片 |
| `METAROUTER_MAX_INPUT_MB` | `10` | 单张本地输入图片的大小上限 |
| `METAROUTER_MAX_VIDEO_MB` | `1024` | 单个视频的本地下载大小上限 |
| `METAROUTER_TRUSTED_IMAGE_HOSTS` | `metarouters.org` | 允许下载结果图片的 HTTPS 域名，逗号分隔 |
| `METAROUTER_TRUSTED_VIDEO_HOSTS` | `metarouters.org` | 允许下载结果视频的 HTTPS 域名，逗号分隔 |

## 尺寸与计费提醒

- 尺寸格式是 `宽x高`，范围为 256–4096，宽和高都必须是 8 的倍数。
- `image_batch_edit` 会为每张输入图片分别发起一次接口调用，因此每张都会独立计费。
- `image_multi_reference` 会把多张参考图放进同一次编辑请求，是否支持以及具体限制取决于所选上游模型。
- HappyHorse 是异步任务：`video_generate` 只提交任务，实际完成情况使用 `video_status` 查询。
- `video_status(wait=true)` 最长等待 900 秒；超时不会取消任务，可稍后继续查询同一个 `task_id`。
- 视频时长目前为 3–15 秒，分辨率为 720P 或 1080P；具体可用组合以控制台为准。
- 最终可用模型、质量参数、速率限制和计费以 MetaRouter 控制台为准。

## 安全设计

- API 网关在代码中固定为 `https://metarouters.org`，MCP 参数不能覆盖它。
- 只接受 PNG、JPEG 和 WebP 本地输入，并限制单文件大小。
- 默认只能把生成结果写入 `METAROUTER_SAVE_DIR_ROOT` 内部。
- 远程结果只允许从 HTTPS 及受信任域名下载，减少 SSRF 风险。
- 视频 CDN 下载使用独立、无 Authorization 的客户端，不会把 MetaRouter API Key 发给结果域名。
- API 错误会截断和清理后再返回，不会主动输出 Authorization 请求头。
- API Key 保存在本机 Codex 配置中。不要把真实密钥写进仓库、截图、Issue 或日志；如已公开，请立即在控制台撤销并重新生成。

卸载由安装器写入的 Codex 配置：

```powershell
python install.py --reset
```

## 开发与测试

```powershell
python -m pip install -e ".[dev]"
python -m pytest
```

测试不需要真实 API Key，也不会发起计费请求。

## License

[MIT](LICENSE)