Files
agent/mcp/image_task/README.md
T
kicer d6b949969f image_task 图生图改走 /images/edits:下载参考图后 multipart 上传
- 文生图仍走 /images/generations,图生图改走 /images/edits(原先错发到 generations 的 images 数组)
- X-Image-Task-Base-Url 统一剥离末尾 /images/generations 或 /images/edits,端点由模式决定
- 参考图先下载成字节再以 multipart 上传:60s 独立超时、20MB 流式上限、校验 image/*
- 同步 README / mcp README / package.json 说明
2026-10-25 10:13:47 +08:00

15 KiB
Raw Blame History

MCP Image Task

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

cd /root/workspace/tools/agent
docker compose up -d --build mcp_image_task

服务容器名 mcp_image_task,默认不占宿主机端口,由 agent 走 agent-mcp-net 按容器名访问。 要从宿主机 curl 调试,自行给该服务加 ports 映射。

# 不占端口的健康检查
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": "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 <base>/images/generations;
  • 传一个公网 URL → 图生图 / 编辑,服务先把这张图拉下来,再以 multipart 上传到 POST <base>/images/edits。

本地图片先用 mint_public_link 换成公网 URL,再传给 image。

尺寸、质量、模型、上游地址都不是工具参数:它们属于部署策略,由调用方在 header 里固定, 避免 AI 乱填尺寸档位或模型名白烧额度。尺寸/质量直接走上游默认值。

返回

op=create 成功时立即返回 task_id(生成已转入后台):

{
  "content": [
    { "type": "text", "text": "Model: CogView-4\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:带上已等待秒数 elapsed,建议等待 min(30, 3 + floor(elapsed / 5)) 秒后再查;
  • SUCCESS:单个 text 块,摘要后跟图片 URL(单图直接给 Image URL:,多图按 Image N: 逐行列出);elapsed 为从 create 到完成的总耗时:
{
  "content": [
    { "type": "text", "text": "task_id: <uuid>\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 <key>,原样作为上游 Bearer token
X-Image-Task-Base-Url ✅ 上游 base URL(完整 http(s) 地址,如 https://<host>/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 上传:

POST <base>/images/edits
Content-Type: multipart/form-data; boundary=...

model=<header 里的模型>
prompt=<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 取图。


配置示例

智谱与网关走同一套协议,只换地址与模型:

  - name: image_task
    url: "http://mcp_image_task:3000/mcp"
    headers:
      Authorization: "Bearer <KEY>"
      X-Image-Task-Base-Url: "https://open.bigmodel.cn/api/paas/v4"
      X-Image-Task-Model: "CogView-4"
    mode: skill
  - 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

错误响应

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

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. 文生图(三个 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://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 单一开关:不传 = 文生图(/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 左右。需要长期使用请自行转存。