Files
kicer 3139108838 refactor(video_task): 改成通用 OpenAI 兼容形态,不绑定任何厂商
照 image_task 的口径:Base-Url / 模型 / 凭据全部由调用方每个请求用 header 带入
(X-Video-Task-Base-Url / X-Video-Task-Model / Authorization),服务端不存密钥、
不预设默认模型、不认任何厂商专有字段。

- 提交 POST {base}/videos/generations(wait=false,立刻回 task_id)
- 查询 GET  {base}/videos/{task_id}
- 缺 header 同步报错,不打上游
- 上游只需回 task_id/id 与 status(completed 时带 videos[].url)
- presets.json 与 README 同步改成通用描述
2026-11-17 16:28:44 +08:00

114 lines
6.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# MCP 服务集合
四个 MCP(Model Context Protocol)服务,各占一个目录,由仓库根 `docker-compose.yml` 统一编排:
| 目录 | 容器名 | 作用 | 容器内端口 | MCP 端点 |
|---|---|---|---|---|
| `web_search/` | `mcp_web_search` | 网页搜索(默认免费 Parallel / Exa,可换成自建 `/search` 上游) | `3000` | `POST /` |
| `image_task/` | `mcp_image_task` | 图片生成 / 编辑(文生图走 `/images/generations`,图生图走 `/images/edits`,单工具 op=create/get) | `3000` | `POST /mcp` |
| `video_task/` | `mcp_video_task` | 视频生成(任意 OpenAI 兼容 `/videos` 上游,异步,单工具 op=create/get) | `3000` | `POST /mcp` |
| `asr/` | `mcp_asr` | 语音转文字(上游 OpenAI 兼容 `/audio/transcriptions`),**额外带一个给输入框用的 `POST /transcribe`** | `3000` | `POST /mcp` |
**这些服务一个宿主机端口都不占**——它们只挂在 `agent-mcp-net` 上,由 `agent-core` / `agent-executor`
按容器名访问。所以整台服务器对外只需要开 agent-core 那一个端口(`AGENT_PORT`,默认 8090)。
## 部署
它们和 `agent-core` / `agent-executor` / `wxbot` 同属一个 compose 项目,无需单独启动,也没有先后顺序:
```bash
cd /root/workspace/tools/agent
docker compose up -d --build
```
`config.yml` 里的地址与容器名一一对应:
```yaml
mcp_servers:
- name: web_search
url: "http://mcp_web_search:3000/"
# 可选:换成自己的搜索接口(不配 = 内置免费后端 Parallel / Exa)
# headers:
# Authorization: Bearer <key>
# X-Web-Search-Base-Url: "https://<host>/v1"
- name: image_task
url: "http://mcp_image_task:3000/mcp"
- name: video_task
url: "http://mcp_video_task:3000/mcp"
# 可选:语音转写(低频,建议 skill 模式,不占每轮工具表)
- name: asr
url: "http://mcp_asr:3000/mcp"
headers:
Authorization: Bearer <key> # 免鉴权的自建服务可省
X-ASR-Base-Url: "https://<host>/v1"
X-ASR-Model: "whisper-1"
mode: skill
```
服务没起来时,core 只在启动日志里告警,不影响 Web 主流程,但对应工具不会下发给模型。工具发现只在启动时做一次,失败后会自动按 2s / 20s / 1min 重试 3 次;三次都失败则需重启 core。四个服务都配了 `/health` 健康检查,`docker ps` 可直接看状态。
> 从旧的「agent + mcp 双仓库」部署升级:先在旧 mcp 仓库目录 `docker compose down`(只需一次,否则同名容器与网络会冲突),再 `up` 本栈。
`image_task` / `video_task` 的 token **不由服务端保存**——每个请求从 `Authorization` header 读取
(agent 侧配在 `config.yml` 的 `mcp_servers[].headers`)。`video_task` 走任意 OpenAI 兼容的 videos 上游:
提交 `/videos/generations`、查询 `/videos/{task_id}`,地址与模型由 `X-Video-Task-Base-Url` /
`X-Video-Task-Model` 指定(两者都必填);
`image_task` 走任意 OpenAI 兼容的 images 上游:文生图 `/images/generations`、图生图 `/images/edits`,
上游地址与模型分别由 `X-Image-Task-Base-Url` / `X-Image-Task-Model` 指定(两者都必填)。
所以这两个服务不用配任何密钥。
`web_search` 同理:默认走内置免费后端(Parallel → Exa,无需 key);想换成自己的搜索接口,
就在这段 headers 里写 `X-Web-Search-Base-Url`(容器拼 `/search`)与可选的 `Authorization`。
一旦配了地址就以它为准——**失败直接报错,不会静默退回免费后端**(否则 key 过期 / 地址写错
只会表现为「结果质量突然变差」)。
`asr` 同理:上游的 key / base_url / model 全部由调用方随请求 header 带入
(`Authorization` / `X-ASR-Base-Url` / `X-ASR-Model`,agent 侧配在 `config.yml` 的
`mcp_servers[name=asr].headers`)。输入框那条路(`agent-core` → `POST /transcribe`)不经过 MCP 调用,
但 core 同样会从那段 `headers` 取值转发过去,所以两边只有一处配置。容器自己不存任何平台密钥,
也不预设任何厂商——任何 OpenAI 兼容的 `/audio/transcriptions` 都能用。
### 调试端口
本栈默认不给 MCP 服务映射宿主机端口(它们只在 `agent-mcp-net` 内网可达)。要从宿主机直连,
自行在 `docker-compose.yml` 给对应服务加 `ports` 即可。
## 图片是怎么到上游的(只有 video_task 关心)
上游生成视频前要**自己来拉参考图**,它不带 cookie、不带 `Authorization`。这套链路里**没有任何人上传文件**:
```
AI ──调用 agent 内置的「公开临时 URL」工具(直接传文件路径)──► 拿到一条短命公网 URL
│
▼
AI 把拿到的 URL 当 image_url 交给 video_task:3000/mcp(转发为上游的 image 字段)
│
▼
上游 ──匿名 GET──► agent 侧提供的公开临时 URL
那个文件始终躺在 agent 的任务目录里,零拷贝
```
- 签发与托管全在 agent 侧(它已集成为一个 tool,AI 直接调用即可,不需要 curl 任何内网入口)。
- 链接短命:到期或 agent 重启后失效;上游只在提交任务那一刻拉一次图,完全够用。
- mcp 这三家一个端口都不露,唯一公网可达的东西只有 agent 自己。
## 端口与安全
| 服务 | 公网暴露 | 说明 |
|---|---|---|
| `mcp_web_search` | 无 | 服务端无鉴权,**永远不要映射出去**(会被白嫖搜索额度;配了自定义上游时还会把你的 key 白送出去);agent 走内网访问 |
| `mcp_image_task` | 无 | token 由调用方自带,暴露后可被拿去消耗你的上游图片额度 |
| `mcp_video_task` | 无 | 它需要的公开临时 URL 由 agent 侧集成的工具提供,自己不占端口 |
| `mcp_asr` | 无 | `/mcp` 与 `/transcribe` 都无鉴权,只能由 core 经内网调用;它不存密钥(上游参数随请求带入) |
## 单独调试
```bash
cd /root/workspace/tools/agent
docker compose up -d --build mcp_web_search
# 不占端口的健康检查
docker exec mcp_web_search node -e "fetch('http://localhost:3000/health').then(r=>r.text()).then(console.log)"
```
各目录下的 `README.md` 有该服务的工具说明、header 覆盖项与 curl 调试脚本。