照 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 同步改成通用描述
114 lines
6.2 KiB
Markdown
114 lines
6.2 KiB
Markdown
# 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 调试脚本。
|