# MCP Image Task 一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的图片生成 / 编辑服务。 对外只有一个工具 `image_task`,用 `op` 区分动作(`create` / `get`),异步任务契约与 `video_task` 一致。 上游必须是 OpenAI 兼容的 images 端点:文生图走 `/images/generations`,图生图走 `/images/edits` (智谱、各类网关走同一套协议)。`X-Image-Task-Base-Url` / `X-Image-Task-Model` / `Authorization` 三个 header 都必填,服务不存密钥、也不预设厂商或默认模型。 - 协议: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`,**默认不占宿主机端口**,由 agent 走 `agent-mcp-net` 按容器名访问。 要从宿主机 curl 调试,自行给该服务加 `ports` 映射。 ```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": "https://open.bigmodel.cn/api/paas/v4", "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` 是模式开关: - 不传 → **文生图**,请求 `POST /images/generations`; - 传一个公网 URL → **图生图 / 编辑**,服务先把这张图拉下来,再以 multipart 上传到 `POST /images/edits`。 本地图片先用 `mint_public_link` 换成公网 URL,再传给 `image`。 > 尺寸、质量、模型、上游地址都**不是**工具参数:它们属于部署策略,由调用方在 header 里固定, > 避免 AI 乱填尺寸档位或模型名白烧额度。尺寸/质量直接走上游默认值。 ### 返回 `op=create` 成功时立即返回 `task_id`(生成已转入后台): ```jsonc { "content": [ { "type": "text", "text": "Model: CogView-4\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\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` | ✅ | 上游 base URL(完整 `http(s)` 地址,如 `https:///v1`);若已给到 `/images/generations` 或 `/images/edits` 会自动剥回 base,再按模式拼端点 | | `X-Image-Task-Model` | ✅ | 模型名原样透传 | 地址与模型只由 header 决定,AI 看不到也填不了;换模型 = 改 header 后重启 core。 ### 图生图 图生图**不能**走 `/images/generations`,必须走 `/images/edits`。服务会先把 `image` URL 下载成字节 (独立 60s 超时,单图上限 20MB,响应需是 `image/*`,如 png / jpeg / webp / gif / bmp),再以 multipart 上传: ```text POST /images/edits Content-Type: multipart/form-data; boundary=... model=
prompt= image=@<下载到的参考图> # 字段名 image,文件名按 MIME 补扩展名 n=1 response_format=url ``` 选 multipart 而不是 JSON + base64 data URL:参考图已经在本地手里,直接当文件传可省掉 base64 的 1/3 体积膨胀,也避开网关对超大 JSON 体的限制。 ### 请求体 - 文生图:JSON `{ model, prompt, n: 1, response_format: "url" }` → `/images/generations` - 图生图:multipart(字段见上)→ `/images/edits` `size` / `quality` 一律不传,交给上游默认值。两种模式的成功响应都按 `data[0].url` 取图。 --- ## 配置示例 智谱与网关走同一套协议,只换地址与模型: ```yaml - name: image_task url: "http://mcp_image_task:3000/mcp" headers: Authorization: "Bearer " X-Image-Task-Base-Url: "https://open.bigmodel.cn/api/paas/v4" X-Image-Task-Model: "CogView-4" mode: skill ``` ```yaml - name: image_task url: "http://mcp_image_task:3000/mcp" headers: Authorization: "Bearer <网关 KEY>" X-Image-Task-Base-Url: "https://your-gateway.example.com/v1" X-Image-Task-Model: "global:gpt-image-2.5-sunburst" mode: skill ``` --- ## 错误响应 | 场景 | HTTP 状态 | 表现 | |---|---|---| | 缺 `Authorization` | `200`(MCP 工具返回) | `isError: true`,提示补 header | | 缺 `X-Image-Task-Base-Url` / 不是完整 http(s) URL | `200`(MCP 工具返回) | `isError: true`,提示填完整地址 | | 缺 `X-Image-Task-Model` | `200`(MCP 工具返回) | `isError: true`,提示补 header | | `image` 不是公网 http(s) URL | `200`(MCP 工具返回) | `isError: true`,提示只接受公网 URL,不接受文件上传 / base64 | | 参考图下载失败 / 超时(>60s)/ 超过 20MB / 不是图片 | `200`(MCP 工具返回) | 在 `op=get` 中以 `task_status: FAIL` 呈现,错误直述下载环节 | | `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。 > 参考图由服务自己下载后以 multipart 转发给上游,不经过 MCP 请求体。 --- ## 用 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. 文生图(三个 header 都必填) 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://open.bigmodel.cn/api/paas/v4" \ -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. 图生图 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://your-gateway.example.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` 单一开关**:不传 = 文生图(`/images/generations`),传一个公网 URL = 图生图 (下载后 multipart 上传 `/images/edits`);`image` 是单个字符串,只接受公网 `http(s)` URL - **URL 提取**:只接受 `data[].url` 形式的 http(s) URL;上游若回 `b64_json` 则记 `FAIL` 并给出明确错误 --- ## 常见问题 **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: 图生图报错?** A: 图生图走 `/images/edits` + multipart(字段名 `image`)。若上游模型不支持编辑、或网关不认这种入参, 上游会回 4xx,在 `op=get` 里以 `task_status: FAIL` 呈现。换一个支持 `/images/edits` 的模型即可。 **Q: 本地图片怎么传?** A: 先调用 agent 内置的 `mint_public_link` 工具,把会话目录里的文件换成短期公网 URL,再传给 `image`。 本服务不接受文件上传或 base64(MCP 请求体不放图片字节),参考图由服务自己从这个 URL 拉取。 **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 左右。需要长期使用请自行转存。