# Agnes Media MCP Server

一个用于 **Claude Desktop** 的本地 MCP 服务器，内置：

- **Agnes Image 2.1 Flash** (`agnes-image-2.1-flash`) — 文生图 / 图生图
- **Agnes Video V2.0** (`agnes-video-v2.0`) — 文生视频 / 图生视频 / 关键帧动画（异步）

接入后，在 Claude Desktop 里用自然语言即可生成图片和视频，结果自动落盘到本地目录。

> 跨平台：服务器由 Node 运行，macOS 与 Windows 均可使用。

## 工具

| 工具 | 说明 |
| --- | --- |
| `agnes_generate_image` | 生成图片。默认文生图；传 `image_urls` 走图生图。结果落盘 + 内嵌预览。 |
| `agnes_generate_video` | 创建视频任务并短等待（默认 45s）。若在等待窗口内完成则直接下载 mp4；否则立即返回 `video_id` 交给状态工具轮询。默认文生视频；传 `image_url` 图生视频；传 `keyframe_urls` 关键帧过渡。 |
| `agnes_get_video_status` | 按 `video_id` 查询视频任务状态；`download:true` 在完成时下载 mp4。 |

**视频时长**：`seconds = num_frames / frame_rate`。`num_frames` 必须 ≤ 441 且满足 `8n+1`（如 81≈3s、121≈5s、241≈10s、441≈18s @ 24fps）。

**为什么视频要两步**：视频生成通常需要数分钟，超过单次 MCP 请求的超时（约 60s）。因此 `agnes_generate_video` 只在客户端超时预算内（`wait_seconds`，默认 45s、上限 50s）内联等待——快的视频一次返回；慢的立即交回 `video_id`，用 `agnes_get_video_status`（`download:true`）每隔约 15s 轮询直到 `completed` 即可拿到文件。

## 安装与构建

```bash
npm install
npm run build
```

生成 `dist/index.js`。

## 配置（环境变量）

| 变量 | 必填 | 默认 | 说明 |
| --- | --- | --- | --- |
| `AGNES_API_KEY` | 是 | — | Agnes AI API Key |
| `AGNES_OUTPUT_DIR` | 否 | 系统图片/视频文件夹 | 覆盖输出根目录（设置后图片→`<dir>/images`、视频→`<dir>/videos`） |
| `AGNES_BASE_URL` | 否 | `https://apihub.agnes-ai.com` | API 网关地址 |

**默认落盘位置**：不设 `AGNES_OUTPUT_DIR` 时，图片保存到**系统"图片"文件夹**、视频保存到**系统"视频"文件夹**，各自放在 `AgnesOutputs/` 子目录下。Windows 上会读取真实的已知文件夹路径（支持重定向，如 `H:\用户文件\图片`）；macOS/Linux 回退到 `~/Pictures`、`~/Videos`。

**网络重试**：所有 API 调用与文件下载都带自动重试（网络失败或 429/5xx 时等 2 秒重试，共 4 次尝试），以应对偶发的网络抖动。

## 接入 Claude Desktop

编辑 Claude Desktop 配置文件：

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`(不同版本的路径可能不一样）

加入（把路径换成本机 `dist/index.js` 的**绝对路径**）：

```json
{
  "mcpServers": {
    "agnes-media": {
      "command": "node",
      "args": ["/绝对路径/图片和视频MCP/dist/index.js"],
      "env": {
        "AGNES_API_KEY": "你的Key",
        "AGNES_OUTPUT_DIR": "可选自定义输出目录"
      }
    }
  }
}
```

> Windows 下 `args` 路径示例：`"C:\\Users\\you\\projects\\图片和视频MCP\\dist\\index.js"`（反斜杠需转义，或用正斜杠）。

保存后**完全重启 Claude Desktop**。连接成功后即可对 Claude 说：“生成一张 16:9 的霓虹灯城市壁纸”。

## 本地调试

用官方 MCP Inspector 手动调用工具：

```bash
AGNES_API_KEY=你的Key npm run inspect
```

在 Inspector 里：

1. `agnes_generate_image` — `prompt` 任意，`size: "2K"`, `ratio: "16:9"` → 检查系统「图片」文件夹下 `AgnesOutputs/` 出图。
2. `agnes_generate_video` — `num_frames: 121, frame_rate: 24` → 等待轮询完成，检查系统「视频」文件夹下 `AgnesOutputs/` 出 mp4。
3. `agnes_get_video_status` — 传上一步的 `video_id`。

## 注意事项

- **日志走 stderr**，stdout 专供 MCP 协议，请勿改动。
- 视频为异步生成，可能需要数分钟；服务器会阻塞轮询（默认间隔 5s、超时 10 分钟）。超时后可用 `agnes_get_video_status` 继续查询。
- 图生图不需要 `tags`；`response_format` 由服务器自动放进 `extra_body`。
- 定价当前为 $0（图片 / 视频），可放心联调。