# MCP Image Task 一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的图片生成 / 编辑服务。 对外只有一个工具 `image_task`,用 `op` 区分动作(`create` / `get`),异步任务契约与 `video_task` 一致。 上游支持两种协议,由 `X-Image-Task-Base-Url` 选择: | 通道 | 上游 | 请求体 | |---|---|---| | 智谱原生 | `https://open.bigmodel.cn/api/paas/v4/images/generations` | `{ model, prompt }` | | OpenAI 兼容 | 任意实现 `/images/generations` 的网关(如 `https://wb.ai.foresh.com/v1`) | `{ model, prompt, n: 1, response_format: "url", images? }` | - 协议:MCP **Streamable HTTP**(单端点 `/mcp`,支持 SSE 流) - 端口:容器内 `3000`(**不映射宿主机**,只在 `agent-mcp-net` 内被 agent 访问) - 鉴权:**无服务端密钥**,每次请求从 `Authorization` header 读取上游 key --- ## 快速开始 ### 启动(docker-compose) ```bash cd /root/workspace/tools/agent docker compose up -d --build mcp_image_task ``` 服务容器名 `mcp_image_task`。要从宿主机 curl 调试,把根 `docker-compose.yml` 里 `mcp_image_task` 注释掉的 `ports` 两行打开(默认 8082),调试完记得注释回去。 ```bash # 不占端口的健康检查 docker exec mcp_image_task node -e "fetch('http://localhost:3000/health').then(r=>r.text()).then(console.log)" # {"status":"ok","service":"image_task","sessions":0,"tasks":0} ``` ### MCP 客户端配置 ```jsonc { "mcpServers": { "image_task": { "url": "http://localhost:8082/mcp", "headers": { "Authorization": "Bearer ", "X-Image-Task-Base-Url": "zhipu", "X-Image-Task-Model": "CogView-4" } } } } ``` > 客户端必须在**每一个 HTTP 请求**(`initialize` / `notifications/initialized` / `tools/call`)都带上 > `Authorization`。`X-Image-Task-Base-Url` / `X-Image-Task-Model` 在 `tools/call` 时读取。 --- ## 工具:image_task 典型流程:`op=create` 拿 `task_id`,然后不断 `op=get` 直到 `task_status` 为 `SUCCESS` 或 `FAIL`。 | op | 作用 | 说明 | |---|---|---| | `create` | 提交图片生成 / 编辑任务,**立即**返回 `task_id`,生成在后台执行 | 需要 `prompt` | | `get` | 查询任务状态;`SUCCESS` 时返回图片 URL | 需要 `task_id` | > 上游是同步阻塞的;这里的异步是对外统一形态(对齐 `video_task`),服务内部把同步调用丢到后台跑并回写任务表。 ### 参数(AI 可见) | 名称 | 类型 | 必填 | 说明 | |---|---|---|---| | `op` | `"create"` \| `"get"` | ✅ | 要执行的操作 | | `prompt` | string | op=create 时 ✅ | 提示词;文生图描述画面,图生图描述要改成什么样 | | `task_id` | string | op=get 时 ✅ | `op=create` 返回的任务 ID | | `image` | string | ❌ | 一张图的公网 `http(s)` URL,用于图生图 / 修图 | `image` 是模式开关: - 不传 → **文生图**; - 传一个公网 URL → **图生图 / 编辑**。 本地图片先用 `mint_public_link` 换成公网 URL,再传给 `image`。 > 尺寸、质量、模型、上游地址都**不是**工具参数:它们属于部署策略,由调用方在 header 里固定, > 避免 AI 乱填尺寸档位或模型名白烧额度。智谱原生通道也不接受尺寸,直接走上游默认值。 ### 返回 `op=create` 成功时立即返回 `task_id`(生成已转入后台): ```jsonc { "content": [ { "type": "text", "text": "Model: CogView-4\nProvider: zhipu\nMode: text-to-image\ntask_id: \ntask_status: PROCESSING\n\nImage generation is running in background. Call this tool again with op=\"get\" and task_id=\"\" to fetch the result." } ] } ``` `op=get` 按任务状态返回: - `PROCESSING`:带上已等待秒数 `elapsed`,建议等待 `min(30, 3 + floor(elapsed / 5))` 秒后再查; - `SUCCESS`:单个 `text` 块,摘要后跟图片 URL(单图直接给 `Image URL:`,多图按 `Image N:` 逐行列出);`elapsed` 为从 `create` 到完成的总耗时: ```jsonc { "content": [ { "type": "text", "text": "task_id: \nmodel: CogView-4\nprovider: zhipu\nelapsed: 12s\ntask_status: SUCCESS\nImage URL: https://..." } ] } ``` - `FAIL`:`isError: true`,正文含 `task_status: FAIL`、总耗时 `elapsed` 与错误信息(上游 4xx/5xx、无 URL 返回等都会归档到这里)。 URL 由上游签名下发,**带有效期**(通常 24h),需要长期保存请及时转存。 --- ## Headers(只有三个) | Header | 必填 | 说明 | |---|---|---| | `Authorization` | ✅ | `Bearer `,原样作为上游 Bearer token | | `X-Image-Task-Base-Url` | ❌ | 别名或完整 URL;缺省 `zhipu` | | `X-Image-Task-Model` | 见下 | 模型名原样透传 | ### Base-Url 别名 | 值 | 实际地址 | 协议 | |---|---|---| | `zhipu`(默认) | `https://open.bigmodel.cn/api/paas/v4` | 智谱原生 | 其余值必须是完整的 `http(s)` URL: ```yaml X-Image-Task-Base-Url: "https://wb.ai.foresh.com/v1" ``` - 已经给到 `/images/generations` 全路径就直接用,否则自动补 `/images/generations`。 - 解析后的 host 是 `bigmodel.cn`(含子域)→ 智谱原生请求体;其余 host → OpenAI 兼容请求体。 - 因此把网关地址填进来即可,不需要额外指定“用哪家协议”。 ### 模型 | 场景 | `X-Image-Task-Model` | |---|---| | Base-Url = `zhipu` | 可省略,缺省 `CogView-3-Flash` | | 其他 Base-Url | **必填**(不会把 CogView 误发到网关) | 模型只由 header 决定,AI 看不到也填不了。换模型 = 改 header 后重启 core。 ### 图生图 `image` 只对 OpenAI 兼容通道生效: | Base-Url | 传 `image` | |---|---| | `zhipu` | 直接返回错误:智谱不支持图生图(只做文生图) | | 网关 URL | 上游请求体带 `images: [url]` | ### 请求体差异 | 字段 | 智谱原生 | OpenAI 兼容 | |---|---|---| | `model` / `prompt` | ✅ | ✅ | | `n` | ❌ | 固定 `1` | | `response_format` | ❌ | 固定 `"url"` | | `size` / `quality` | ❌ | ❌(交给上游默认值) | | `images` | ❌ | 传图时带,数组形式 `[url]` | --- ## 配置示例 ### 智谱直连(默认) ```yaml - name: image_task url: "http://mcp_image_task:3000/mcp" headers: Authorization: "Bearer <智谱 KEY>" X-Image-Task-Model: "CogView-4" mode: skill ``` ### OpenAI 兼容网关(文生图) ```yaml - name: image_task url: "http://mcp_image_task:3000/mcp" headers: Authorization: "Bearer <网关 KEY>" X-Image-Task-Base-Url: "https://wb.ai.foresh.com/v1" X-Image-Task-Model: "global:gpt-image-2.5-sunburst" mode: skill ``` ### OpenAI 兼容网关(图生图 / 修图) ```yaml - name: image_task url: "http://mcp_image_task:3000/mcp" headers: Authorization: "Bearer <网关 KEY>" X-Image-Task-Base-Url: "https://wb.ai.foresh.com/v1" X-Image-Task-Model: "cn:hunyuan-image-alpha" mode: skill ``` 同一个网关换模型只改 `X-Image-Task-Model`;换供应商只改 `X-Image-Task-Base-Url`。 --- ## 错误响应 | 场景 | HTTP 状态 | 表现 | |---|---|---| | 缺 `Authorization` | `200`(MCP 工具返回) | `isError: true`,提示补 header | | `X-Image-Task-Base-Url` 非法 | `200`(MCP 工具返回) | `isError: true`,列出可用别名 | | 非 zhipu 通道缺 `X-Image-Task-Model` | `200`(MCP 工具返回) | `isError: true`,提示补 header | | zhipu 通道传了 `image` | `200`(MCP 工具返回) | `isError: true`,提示智谱不支持图生图,改用 OpenAI 兼容端点 | | `image` 不是公网 http(s) URL | `200`(MCP 工具返回) | `isError: true`,提示只接受公网 URL,不接受文件上传 / base64 | | `op=create` 缺 prompt / `op=get` 缺 task_id | `200`(MCP 工具返回) | `isError: true`,参数提示 | | `op=get` 查不到任务 | `200`(MCP 工具返回) | `isError: true`,提示 unknown task_id | | 上游 4xx/5xx | `200`(MCP 工具返回) | 在 `op=get` 中以 `task_status: FAIL` 呈现,正文含上游状态码和 body | | 上游只回 `b64_json` | `200`(MCP 工具返回) | `task_status: FAIL`,提示本服务只接受 URL | | 网络失败 / 超时(>180s) | `200`(MCP 工具返回) | `task_status: FAIL`,不会出现永久 PROCESSING 的僵尸任务 | > JSON 请求体上限保持 2MB:`image` 只接受 URL,不接收文件或 base64。 --- ## 用 curl 手工调试 MCP Streamable HTTP **必须按顺序**:`initialize` → `notifications/initialized` → `tools/call`。 ```bash TOKEN="" # 1. initialize 拿 sessionId SESSION=$(curl -s -D - -X POST http://localhost:8082/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer $TOKEN" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": { "name": "curl", "version": "1.0" } } }' | grep -i '^mcp-session-id:' | awk '{print $2}' | tr -d '\r\n') echo "Session: $SESSION" # 2. notifications/initialized curl -s -X POST http://localhost:8082/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer $TOKEN" \ -H "Mcp-Session-Id: $SESSION" \ -d '{"jsonrpc": "2.0", "method": "notifications/initialized"}' # 3. 文生图(智谱通道;换成网关时补 X-Image-Task-Base-Url / X-Image-Task-Model) curl -s -X POST http://localhost:8082/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer $TOKEN" \ -H "X-Image-Task-Model: CogView-4" \ -H "Mcp-Session-Id: $SESSION" \ -d '{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "image_task", "arguments": { "op": "create", "prompt": "一只可爱的小猫咪,坐在阳光明媚的窗台上,背景是蓝天白云" } } }' # 4. 图生图(OpenAI 兼容通道) curl -s -X POST http://localhost:8082/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer $TOKEN" \ -H "X-Image-Task-Base-Url: https://wb.ai.foresh.com/v1" \ -H "X-Image-Task-Model: global:gpt-image-2.5-sunburst" \ -H "Mcp-Session-Id: $SESSION" \ -d '{ "jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": { "name": "image_task", "arguments": { "op": "create", "prompt": "把背景改成雪夜,其他保持不变", "image": "https://example.com/input.png" } } }' # 5. 轮询结果 curl -s -X POST http://localhost:8082/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer $TOKEN" \ -H "Mcp-Session-Id: $SESSION" \ -d '{ "jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": { "name": "image_task", "arguments": { "op": "get", "task_id": "<上一步返回的 task_id>" } } }' ``` 响应是 SSE 格式(`event: message` + `data: {...}`),用 `grep '^data:'` 抽 JSON 即可。 --- ## 架构与文件 ``` image_task/ ├── Dockerfile # node:22-slim,安装依赖后启动 MCP HTTP server ├── .dockerignore # 排除 node_modules ├── package.json # @modelcontextprotocol/sdk + express + zod ├── README.md # 本文件 └── src/ └── mcp-server.js # 单文件实现:HTTP server + MCP transport + 单工具(op 分发) ``` ### 关键设计 - **单工具 + `op` 分发**:`image_task(op=create|get)`,与 `video_task` 的服务形态一致,agent 侧一套轮询逻辑通吃图片/视频 - **同步上游 → 异步契约**:上游同步阻塞,所以服务自维护一张任务表来模拟异步: - `create` 本地生成 `task_id`(`randomUUID`),登记 `PROCESSING`,把同步调用丢后台(fire-and-forget),立即返回 - 后台完成时回写 `SUCCESS`(含 URLs)或 `FAIL`(含错误);上游同步调用带 180s 超时(`AbortSignal.timeout`),超时记 `FAIL`,杜绝僵尸 `PROCESSING` - `get` 只读本地表,不碰上游 - 表为进程内存 Map:已完成任务保留 1 小时(TTL)、容量上限 1000,每次 `create` 顺带淘汰;**容器重启后任务丢失**,`get` 会报 unknown task_id;**不适用于多副本部署** - token / 上游地址 / 模型在 `create` 那一刻从请求 header 捕获进闭包,后台完成前不再读取 - **每 session 一个 transport + server**:通过 `Mcp-Session-Id` 复用 - **模型 / 上游地址不入 schema**:只从 HTTP header 读取,AI 不可见 - **`image` 单一开关**:不传 = 文生图,传一个公网 URL = 图生图;`image` 是单个字符串,只接受公网 `http(s)` URL - **URL 提取**:只接受 `data[].url` 形式的 http(s) URL;上游若回 `b64_json` 则记 `FAIL` 并给出明确错误 ### 默认模型 ```js // src/mcp-server.js const DEFAULT_MODEL = "CogView-3-Flash"; // 仅 Base-Url=zhipu 时生效 ``` 修改后 `docker compose up -d --build mcp_image_task` 即可生效。 --- ## 常见问题 **Q: AI 不知道有哪些 model 可选,怎么办?** A: 这是设计意图。模型选择属于部署 / 路由策略,由调用方在 `X-Image-Task-Model` 里固定,不让 AI 决策。 **Q: 换模型 / 换供应商要重连 MCP session 吗?** A: 不需要重建 session,但 core 的 `mcp_servers[].headers` 是启动时读取的,改完要 `docker compose restart agent-core`。 **Q: 为什么只支持一张参考图?** A: 当前上游契约只稳定支持单张;`image` 因此是单个 URL 字符串。 **Q: 图生图为什么在 zhipu 通道报错?** A: 智谱原生接口不支持图生图。把 `X-Image-Task-Base-Url` 指向支持 `images` 字段的 OpenAI 兼容网关即可。 **Q: 本地图片怎么传?** A: 先调用 agent 内置的 `mint_public_link` 工具,把会话目录里的文件换成短期公网 URL,再传给 `image`。本服务不接受文件上传或 base64,上游服务器也无法访问你的本地路径。 **Q: 上游是同步接口,为什么对外做成异步?** A: 和 `video_task` 保持同一套任务型契约;同时避免一次生图把 core 的 `tools/call` 拖超时。 **Q: 任务一直 PROCESSING 会不会没完没了?** A: 不会。上游调用封顶 180s,超时直接记 `FAIL`。 **Q: 为什么 PROCESSING 时建议的等待时间会变长?** A: 轮询间隔按 `min(30, 3 + floor(elapsed / 5))` 退避:前期密查尽快拿到结果,后期拉长间隔减少无意义轮询,封顶 30s。 **Q: create 之后服务容器重启了,get 会怎样?** A: 任务表在进程内存里,重启即丢失,`get` 会返回 unknown task_id。需要重新 `create`。 **Q: Token 会不会泄露到日志?** A: 不会。只从 header 读取,不写入日志。 **Q: 收到 `Missing valid Mcp-Session-Id` 错误?** A: 漏发了 `Mcp-Session-Id` header,或调 `tools/call` 前没先 `initialize`。 **Q: URL 多久过期?** A: 上游签发的 URL 通常 24h 左右。需要长期使用请自行转存。