Files
agent/mcp/image_task

MCP Image Task

一个基于 Model Context Protocol (MCP) 的图片生成 / 编辑服务。 对外只有一个工具 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)

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),调试完记得注释回去。

# 不占端口的健康检查
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 客户端配置

{
  "mcpServers": {
    "image_task": {
      "url": "http://localhost:8082/mcp",
      "headers": {
        "Authorization": "Bearer <upstream-api-key>",
        "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(生成已转入后台):

{
  "content": [
    { "type": "text", "text": "Model: CogView-4\nProvider: zhipu\nMode: text-to-image\ntask_id: <uuid>\ntask_status: PROCESSING\n\nImage generation is running in background. Call this tool again with op=\"get\" and task_id=\"<uuid>\" to fetch the result." }
  ]
}

op=get 按任务状态返回:

  • PROCESSING:提示几秒后再查;
  • SUCCESS:单个 text 块,摘要后跟图片 URL(单图直接给 Image URL:,多图按 Image N: 逐行列出):
{
  "content": [
    { "type": "text", "text": "task_id: <uuid>\nmodel: CogView-4\nprovider: zhipu\ntask_status: SUCCESS\nImage URL: https://..." }
  ]
}
  • FAIL:isError: true,正文含 task_status: FAIL 与错误信息(上游 4xx/5xx、无 URL 返回等都会归档到这里)。

URL 由上游签名下发,带有效期(通常 24h),需要长期保存请及时转存。


Headers(只有三个)

Header 必填 说明
Authorization ✅ Bearer <key>,原样作为上游 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:

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]

配置示例

智谱直连(默认)

  - name: image_task
    url: "http://mcp_image_task:3000/mcp"
    headers:
      Authorization: "Bearer <智谱 KEY>"
      X-Image-Task-Model: "CogView-4"
    mode: skill

OpenAI 兼容网关(文生图)

  - 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 兼容网关(图生图 / 修图)

  - 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。

TOKEN="<upstream-api-key>"

# 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 并给出明确错误

默认模型

// 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: 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 左右。需要长期使用请自行转存。