feat(mcp): image_task 支持 OpenAI 兼容上游与单图编辑
This commit is contained in:
+6
-5
@@ -5,7 +5,7 @@
|
||||
| 目录 | 容器名 | 作用 | 容器内端口 | MCP 端点 |
|
||||
|---|---|---|---|---|
|
||||
| `web_search/` | `mcp_web_search` | 免费网页搜索(Parallel / Exa,无需 key) | `3000` | `POST /` |
|
||||
| `image_task/` | `mcp_image_task` | 智谱 CogView 图片生成(单工具 op=create) | `3000` | `POST /mcp` |
|
||||
| `image_task/` | `mcp_image_task` | 图片生成 / 编辑(智谱原生或任意 OpenAI 兼容 `/images/generations`,单工具 op=create/get) | `3000` | `POST /mcp` |
|
||||
| `video_task/` | `mcp_video_task` | 智谱 CogVideo 视频生成(异步,单工具 op=create/get) | `3000` | `POST /mcp` |
|
||||
|
||||
**这些服务一个宿主机端口都不占**——它们只挂在 `agent-mcp-net` 上,由 `agent-core` / `agent-executor`
|
||||
@@ -37,9 +37,10 @@ mcp_servers:
|
||||
|
||||
> 从旧的「agent + mcp 双仓库」部署升级:先在旧 mcp 仓库目录 `docker compose down`(只需一次,否则同名容器与网络会冲突),再 `up` 本栈。
|
||||
|
||||
`image_task` / `video_task` 需要智谱 token,但 token **不由服务端保存**——每个请求从 header 读取
|
||||
(agent 侧配在 `config.yml` 的 `mcp_servers[].headers`,`init.sh` 会用 `BIGMODEL_KEY` 自动写入)。
|
||||
所以这里不用配任何密钥。
|
||||
`image_task` / `video_task` 的 token **不由服务端保存**——每个请求从 `Authorization` header 读取
|
||||
(agent 侧配在 `config.yml` 的 `mcp_servers[].headers`)。`video_task` 用智谱 token;
|
||||
`image_task` 用对应上游(智谱或 OpenAI 兼容网关)的 token,上游地址与模型分别由
|
||||
`X-Image-Task-Base-Url` / `X-Image-Task-Model` 指定。所以这里不用配任何密钥。
|
||||
|
||||
### 调试端口
|
||||
|
||||
@@ -75,7 +76,7 @@ AI 把拿到的 URL 当 image_url 交给 video_task:3000/mcp
|
||||
| 服务 | 公网暴露 | 说明 |
|
||||
|---|---|---|
|
||||
| `mcp_web_search` | 无 | 服务端无鉴权,**永远不要映射出去**(会被白嫖搜索额度);agent 走内网访问 |
|
||||
| `mcp_image_task` | 无 | token 由调用方自带,暴露后可被拿去消耗你的智谱额度 |
|
||||
| `mcp_image_task` | 无 | token 由调用方自带,暴露后可被拿去消耗你的上游图片额度 |
|
||||
| `mcp_video_task` | 无 | 它需要的公开临时 URL 由 agent 侧集成的工具提供,自己不占端口 |
|
||||
|
||||
## 单独调试
|
||||
|
||||
+191
-93
@@ -1,12 +1,18 @@
|
||||
# MCP Image Task
|
||||
|
||||
一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的图片生成服务,对接智谱 BigModel 的 `CogView` 系列模型。每次调用通过 HTTP header 传入智谱 API 的 Bearer Token。只有一个工具 `image_task`,用 `op` 区分动作(`create` / `get`),对外提供与 `video_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 流)
|
||||
- 上游:[智谱 BigModel Images Generations API](https://open.bigmodel.cn/dev/api#images)
|
||||
- 默认模型:`CogView-3-Flash`
|
||||
- 端口:`3000`
|
||||
- 鉴权:**无服务端密钥**,每次请求必须从 header 携带智谱 token
|
||||
- 端口:容器内 `3000`(**不映射宿主机**,只在 `agent-mcp-net` 内被 agent 访问)
|
||||
- 鉴权:**无服务端密钥**,每次请求从 `Authorization` header 读取上游 key
|
||||
|
||||
---
|
||||
|
||||
@@ -14,16 +20,13 @@
|
||||
|
||||
### 启动(docker-compose)
|
||||
|
||||
仓库根目录 `docker-compose.yml` 已包含本服务:
|
||||
|
||||
```bash
|
||||
cd /root/workspace/tools/agent
|
||||
docker compose up -d --build mcp_image_task
|
||||
```
|
||||
|
||||
服务容器名 `mcp_image_task`,容器内端口 3000,**默认不占宿主端口**:agent 走 `agent-mcp-net`
|
||||
按容器名访问(`http://mcp_image_task:3000/mcp`)。需要从宿主机 curl 调试时,去仓库根
|
||||
`docker-compose.yml` 把 `mcp_image_task` 注释掉的 `ports` 两行打开(默认写的是 8082),调试完记得注释回去。
|
||||
服务容器名 `mcp_image_task`。要从宿主机 curl 调试,把根 `docker-compose.yml` 里
|
||||
`mcp_image_task` 注释掉的 `ports` 两行打开(默认 8082),调试完记得注释回去。
|
||||
|
||||
```bash
|
||||
# 不占端口的健康检查
|
||||
@@ -33,67 +36,55 @@ docker exec mcp_image_task node -e "fetch('http://localhost:3000/health').then(r
|
||||
|
||||
### MCP 客户端配置
|
||||
|
||||
#### Claude Desktop / Cursor 等支持 `headers` 配置的客户端
|
||||
|
||||
```jsonc
|
||||
// Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
|
||||
// Cursor: ~/.cursor/mcp.json
|
||||
{
|
||||
"mcpServers": {
|
||||
"image_task": {
|
||||
"url": "http://localhost:8082/mcp",
|
||||
"headers": {
|
||||
"Authorization": "Bearer <your-zhipu-api-key>"
|
||||
"Authorization": "Bearer <upstream-api-key>",
|
||||
"X-Image-Task-Base-Url": "zhipu",
|
||||
"X-Image-Task-Model": "CogView-4"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> 上面 `url` 里的端口 `8082` 需要先把 compose 里注释的 `ports` 打开(默认不占宿主端口)。
|
||||
|
||||
> **重要**:客户端必须在 **每一个 HTTP 请求**(`initialize` / `notifications/initialized` / `tools/call`)都带上 `Authorization` header。配置在 `headers` 里、由客户端自动重发即可。直连模式下 token 不在 session 间共享。
|
||||
|
||||
#### 不支持 `headers` 字段的客户端
|
||||
|
||||
如果客户端只支持 `command`/`args` 启动方式,可改用 stdio 模式(需自行包一层把 token 注入环境变量,再让工具回调从环境变量读——当前实现 HTTP 模式下不依赖环境变量,需自行扩展)。
|
||||
> 客户端必须在**每一个 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`,然后不断 `op=get` 直到 `task_status` 为 `SUCCESS` 或 `FAIL`。
|
||||
|
||||
| op | 作用 | 说明 |
|
||||
|---|---|---|
|
||||
| `create` | 提交图片生成任务,**立即**返回 `task_id`,生成在后台执行 | 需要 `prompt` |
|
||||
| `create` | 提交图片生成 / 编辑任务,**立即**返回 `task_id`,生成在后台执行 | 需要 `prompt` |
|
||||
| `get` | 查询任务状态;`SUCCESS` 时返回图片 URL | 需要 `task_id` |
|
||||
|
||||
> 上游智谱 images 接口是同步阻塞的;这里的异步是对外的统一形态(对齐 `video_task`),服务内部把同步调用丢到后台跑并回写任务表。
|
||||
> 上游是同步阻塞的;这里的异步是对外统一形态(对齐 `video_task`),服务内部把同步调用丢到后台跑并回写任务表。
|
||||
|
||||
### 参数(AI 可见)
|
||||
|
||||
| 名称 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `op` | `"create"` \| `"get"` | ✅ | 要执行的操作 |
|
||||
| `prompt` | string | op=create 时 ✅ | 图片生成提示词,描述想要的画面内容 |
|
||||
| `prompt` | string | op=create 时 ✅ | 提示词;文生图描述画面,图生图描述要改成什么样 |
|
||||
| `task_id` | string | op=get 时 ✅ | `op=create` 返回的任务 ID |
|
||||
| `image` | string | ❌ | 一张图的公网 `http(s)` URL,用于图生图 / 修图 |
|
||||
|
||||
> 图片尺寸不再透传,走上游默认;尺寸档位与成本/成功率挂钩,AI 传错值经常直接报错。
|
||||
`image` 是模式开关:
|
||||
|
||||
### Model 控制(不在工具参数中暴露)
|
||||
- 不传 → **文生图**;
|
||||
- 传一个公网 URL → **图生图 / 编辑**。
|
||||
|
||||
模型名由调用方在 **tools/call 这一次的 HTTP header** 中传递,**AI 看不到也填不了**,避免其误传。识别顺序(首个非空值生效):
|
||||
本地图片先用 `mint_public_link` 换成公网 URL,再传给 `image`。
|
||||
|
||||
| 优先级 | Header |
|
||||
|---|---|
|
||||
| 1 | `X-Image-Task-Model` |
|
||||
| 2 | `X-Mcp-Model` |
|
||||
| 3 | `X-Model` |
|
||||
|
||||
如果都没传,走代码内常量 `DEFAULT_MODEL = "CogView-3-Flash"`。
|
||||
|
||||
**为什么不放进工具参数?** 调用方一般是 AI 助手(Claude / Cursor 等),它不需要也没能力选择用哪个模型;模型选择属于部署/路由策略,由请求的发起方在 HTTP header 里注入更可控。
|
||||
> 尺寸、质量、模型、上游地址都**不是**工具参数:它们属于部署策略,由调用方在 header 里固定,
|
||||
> 避免 AI 乱填尺寸档位或模型名白烧额度。智谱原生通道也不接受尺寸,直接走上游默认值。
|
||||
|
||||
### 返回
|
||||
|
||||
@@ -102,7 +93,7 @@ docker exec mcp_image_task node -e "fetch('http://localhost:3000/health').then(r
|
||||
```jsonc
|
||||
{
|
||||
"content": [
|
||||
{ "type": "text", "text": "Model: CogView-3-Flash\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." }
|
||||
{ "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." }
|
||||
]
|
||||
}
|
||||
```
|
||||
@@ -115,49 +106,137 @@ docker exec mcp_image_task node -e "fetch('http://localhost:3000/health').then(r
|
||||
```jsonc
|
||||
{
|
||||
"content": [
|
||||
{ "type": "text", "text": "task_id: <uuid>\nmodel: CogView-3-Flash\ntask_status: SUCCESS\nImage URL: https://maas-watermark-prod-new.cn-wlcb.ufileos.com/..." }
|
||||
{ "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),如需长期保存请在收到后及时转存到自己的存储。
|
||||
URL 由上游签名下发,**带有效期**(通常 24h),需要长期保存请及时转存。
|
||||
|
||||
---
|
||||
|
||||
## 鉴权细节
|
||||
## Headers(只有三个)
|
||||
|
||||
每个 HTTP 请求必须携带智谱 API Token,server 从以下 header 字段按顺序识别,**首个非空值生效**:
|
||||
|
||||
| 优先级 | Header | 说明 |
|
||||
| Header | 必填 | 说明 |
|
||||
|---|---|---|
|
||||
| 1 | `X-Image-Task-Token: <token>` | 直传,避免与客户端自身的 Authorization 冲突 |
|
||||
| 2 | `X-Mcp-Token: <token>` | 通用兜底 |
|
||||
| 3 | `Authorization: Bearer <token>` | 标准 OAuth 风格(排最后是为避免误用) |
|
||||
| `Authorization` | ✅ | `Bearer <key>`,原样作为上游 Bearer token |
|
||||
| `X-Image-Task-Base-Url` | ❌ | 别名或完整 URL;缺省 `zhipu` |
|
||||
| `X-Image-Task-Model` | 见下 | 模型名原样透传 |
|
||||
|
||||
Token 仅在每次 tool call 时从 header 读取,不写入任何存储、不进 session。
|
||||
### 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 状态 | 表现 |
|
||||
|---|---|---|
|
||||
| initialize 时缺 token | `401` | JSON-RPC `error.message` 提示补充 header |
|
||||
| op=create 缺 prompt / op=get 缺 task_id | `200`(MCP 工具返回) | `isError: true`,参数提示 |
|
||||
| op=get 查不到任务(ID 错/已过期/服务重启过) | `200`(MCP 工具返回) | `isError: true`,提示 unknown task_id |
|
||||
| 智谱 API 4xx/5xx | `200`(MCP 工具返回) | 在 `op=get` 中以 `isError: true` + `task_status: FAIL` 呈现,正文含智谱返回的状态码和 body |
|
||||
| 网络失败 | `200`(MCP 工具返回) | 同上,`task_status: FAIL`,正文含 `fetch` 错误信息 |
|
||||
| 上游挂住不回(超时 >120s) | `200`(MCP 工具返回) | 同上,`task_status: FAIL`,正文提示 timed out;不会出现永久 PROCESSING 的僵尸任务 |
|
||||
| 缺 `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 不是普通 REST,**必须按顺序**:`initialize` → `notifications/initialized` → `tools/call`。下面用一行版串起来:
|
||||
MCP Streamable HTTP **必须按顺序**:`initialize` → `notifications/initialized` → `tools/call`。
|
||||
|
||||
```bash
|
||||
# 把 <your-zhipu-api-key> 替换成你智谱的 API Key
|
||||
TOKEN="<your-zhipu-api-key>"
|
||||
TOKEN="<upstream-api-key>"
|
||||
|
||||
# 1. initialize 拿 sessionId
|
||||
SESSION=$(curl -s -D - -X POST http://localhost:8082/mcp \
|
||||
@@ -185,19 +264,12 @@ curl -s -X POST http://localhost:8082/mcp \
|
||||
-H "Mcp-Session-Id: $SESSION" \
|
||||
-d '{"jsonrpc": "2.0", "method": "notifications/initialized"}'
|
||||
|
||||
# 3. 列出工具(可选验证)
|
||||
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": 2, "method": "tools/list"}'
|
||||
|
||||
# 4. 调 image_task(op=create,立即返回 task_id)
|
||||
# 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",
|
||||
@@ -212,7 +284,29 @@ curl -s -X POST http://localhost:8082/mcp \
|
||||
}
|
||||
}'
|
||||
|
||||
# 5. 拿上一步返回的 task_id 轮询结果(直到 SUCCESS / FAIL)
|
||||
# 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" \
|
||||
@@ -220,7 +314,7 @@ curl -s -X POST http://localhost:8082/mcp \
|
||||
-H "Mcp-Session-Id: $SESSION" \
|
||||
-d '{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 4,
|
||||
"id": 5,
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"name": "image_task",
|
||||
@@ -250,22 +344,23 @@ image_task/
|
||||
|
||||
### 关键设计
|
||||
|
||||
- **单工具 + `op` 分发**:`image_task(op=create|get)`,与 `video_task` 的服务形态完全一致,agent 侧一套轮询逻辑通吃图片/视频
|
||||
- **同步上游 → 异步契约**:智谱 images 接口只支持同步,所以服务自维护一张任务表来模拟异步:
|
||||
- **单工具 + `op` 分发**:`image_task(op=create|get)`,与 `video_task` 的服务形态一致,agent 侧一套轮询逻辑通吃图片/视频
|
||||
- **同步上游 → 异步契约**:上游同步阻塞,所以服务自维护一张任务表来模拟异步:
|
||||
- `create` 本地生成 `task_id`(`randomUUID`),登记 `PROCESSING`,把同步调用丢后台(fire-and-forget),立即返回
|
||||
- 后台完成时回写 `SUCCESS`(含 URLs)或 `FAIL`(含错误);上游同步调用带 120s 超时(`AbortSignal.timeout`),超时记 `FAIL`,杜绝僵尸 `PROCESSING`
|
||||
- 后台完成时回写 `SUCCESS`(含 URLs)或 `FAIL`(含错误);上游同步调用带 180s 超时(`AbortSignal.timeout`),超时记 `FAIL`,杜绝僵尸 `PROCESSING`
|
||||
- `get` 只读本地表,不碰上游
|
||||
- 表为进程内存 Map:已完成任务保留 1 小时(TTL)、容量上限 1000,每次 `create` 顺带淘汰;**容器重启后任务丢失**,`get` 会报 unknown task_id;**不适用于多副本部署**(表不互通)
|
||||
- token/model 在 `create` 那一刻从请求 header 捕获进闭包,后台完成前不再读取,保持「每请求读 header」的无状态设计
|
||||
- **每 session 一个 transport + server**:通过 `Mcp-Session-Id` 复用,避免每请求重建
|
||||
- **模型参数不入 schema**:model 只从 HTTP header 读取(`X-Image-Task-Model` / `X-Mcp-Model` / `X-Model`),AI 不可见
|
||||
- **URL 提取**:`response.data[].url` 为准,若返回 `b64_json` 也会一并归档进任务表
|
||||
- 表为进程内存 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";
|
||||
const DEFAULT_MODEL = "CogView-3-Flash"; // 仅 Base-Url=zhipu 时生效
|
||||
```
|
||||
|
||||
修改后 `docker compose up -d --build mcp_image_task` 即可生效。
|
||||
@@ -275,31 +370,34 @@ const DEFAULT_MODEL = "CogView-3-Flash";
|
||||
## 常见问题
|
||||
|
||||
**Q: AI 不知道有哪些 model 可选,怎么办?**
|
||||
A: 这是设计意图。模型选择属于路由策略,不让 AI 决策。调用方在 HTTP header `X-Image-Task-Model` 里注入即可。
|
||||
A: 这是设计意图。模型选择属于部署 / 路由策略,由调用方在 `X-Image-Task-Model` 里固定,不让 AI 决策。
|
||||
|
||||
**Q: 换模型需要重连 MCP session 吗?**
|
||||
A: 不需要。Model header 在每次 `tools/call` 都从当前请求读取,不需要重建 session。
|
||||
**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` 保持同一套任务型契约,agent 侧只需维护一种「create 后轮询 get」的调用模式。同步调用被放到后台执行,对 AI 而言表现为标准异步任务。
|
||||
A: 和 `video_task` 保持同一套任务型契约;同时避免一次生图把 core 的 `tools/call` 拖超时。
|
||||
|
||||
**Q: 任务一直 PROCESSING 会不会没完没了?**
|
||||
A: 不会。上游同步调用封顶 120s(`AbortSignal.timeout`),超时直接记 `FAIL`,`get` 会拿到明确的 timed out 错误;不存在僵尸任务。
|
||||
A: 不会。上游调用封顶 180s,超时直接记 `FAIL`。
|
||||
|
||||
**Q: create 之后服务容器重启了,get 会怎样?**
|
||||
A: 任务表在进程内存里,重启即丢失,`get` 会返回 unknown task_id 的 `isError`。需要重新 `create`。图片生成只跑几秒,受影响窗口很小;若将来要上多副本或需要可靠恢复,再把表换成持久化存储。
|
||||
|
||||
**Q: 为什么 get 不需要等上游?**
|
||||
A: `get` 只读本地任务表,上游调用只发生在 `create` 的后台一次,不会因轮询而重复计费/重复生图。
|
||||
|
||||
**Q: 为什么 Model 优先级不是「工具参数 > header」?**
|
||||
A: 因为我们故意不在 schema 暴露 model 参数,AI 根本不会传 model,所以「工具参数 > header」这条分支实际上不存在。
|
||||
A: 任务表在进程内存里,重启即丢失,`get` 会返回 unknown task_id。需要重新 `create`。
|
||||
|
||||
**Q: Token 会不会泄露到日志?**
|
||||
A: 当前实现只在 session 内存里持有,不会写入 stdout/stderr。Container 日志只打印 session id。
|
||||
A: 不会。只从 header 读取,不写入日志。
|
||||
|
||||
**Q: 收到 `Missing valid Mcp-Session-Id` 错误?**
|
||||
A: 漏发了 `Mcp-Session-Id` header,或调 `tools/call` 前没先 `initialize`。
|
||||
|
||||
**Q: URL 多久过期?**
|
||||
A: 智谱签发 URL 默认 24h 左右,详见响应里的 `Expires` 参数。需要长期使用请自行转存到 OSS/S3。
|
||||
A: 上游签发的 URL 通常 24h 左右。需要长期使用请自行转存。
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "mcp_image_task",
|
||||
"version": "1.0.0",
|
||||
"description": "MCP server for image generation via Zhipu BigModel CogView (single tool image_task with op=create)",
|
||||
"description": "MCP server for image generation and editing via Zhipu BigModel CogView or any OpenAI-compatible /images/generations endpoint (single tool image_task with op=create/get)",
|
||||
"type": "module",
|
||||
"main": "src/mcp-server.js",
|
||||
"scripts": {
|
||||
|
||||
@@ -6,8 +6,14 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
|
||||
import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
|
||||
import { z } from "zod";
|
||||
|
||||
const ZHIPU_API_URL =
|
||||
"https://open.bigmodel.cn/api/paas/v4/images/generations";
|
||||
// 上游地址既支持完整 URL,也支持别名。zhipu 走智谱原生协议(body 只有
|
||||
// model/prompt);其余地址一律按 OpenAI 兼容的 /images/generations 协议
|
||||
// (body 加 n / response_format=url)。别名目前只保留 zhipu。
|
||||
const BASE_URL_ALIASES = {
|
||||
zhipu: "https://open.bigmodel.cn/api/paas/v4",
|
||||
};
|
||||
// 只有智谱需要走原生请求体,其余主机一律按 OpenAI 兼容处理。
|
||||
const ZHIPU_HOST_SUFFIX = "bigmodel.cn";
|
||||
const DEFAULT_MODEL = "CogView-3-Flash";
|
||||
|
||||
// 上游同步调用耗时上限(出图几十秒量级,留足余量)。
|
||||
@@ -49,43 +55,102 @@ function parseArgs(argv) {
|
||||
return args;
|
||||
}
|
||||
|
||||
function pickToken(headers) {
|
||||
// 对外只有三个 header:Authorization / X-Image-Task-Base-Url / X-Image-Task-Model。
|
||||
// 不再支持 X-Image-Task-Token、X-Mcp-Token、X-Mcp-Model、X-Model 等旧写法。
|
||||
function pickAuthToken(headers) {
|
||||
if (!headers) return null;
|
||||
const candidates = [
|
||||
headers["x-image-task-token"],
|
||||
headers["x-mcp-token"],
|
||||
headers["authorization"],
|
||||
];
|
||||
for (const v of candidates) {
|
||||
if (!v) continue;
|
||||
const s = String(v).trim();
|
||||
if (!s) continue;
|
||||
if (/^Bearer\s+/i.test(s)) {
|
||||
const t = s.replace(/^Bearer\s+/i, "").trim();
|
||||
if (t) return t;
|
||||
} else {
|
||||
return s;
|
||||
}
|
||||
const s = String(headers["authorization"] || "").trim();
|
||||
if (!s) return null;
|
||||
if (/^Bearer\s+/i.test(s)) {
|
||||
const t = s.replace(/^Bearer\s+/i, "").trim();
|
||||
return t || null;
|
||||
}
|
||||
return null;
|
||||
return s;
|
||||
}
|
||||
|
||||
function pickModel(headers) {
|
||||
function pickHeaderString(headers, name) {
|
||||
if (!headers) return null;
|
||||
const v =
|
||||
headers["x-image-task-model"] ||
|
||||
headers["x-mcp-model"] ||
|
||||
headers["x-model"];
|
||||
if (!v) return null;
|
||||
const v = headers[name];
|
||||
if (v === undefined || v === null) return null;
|
||||
const s = String(v).trim();
|
||||
return s || null;
|
||||
}
|
||||
|
||||
async function callZhipuImagesGenerations({ token, model, prompt }) {
|
||||
const body = { model, prompt };
|
||||
function pickBaseUrl(headers) {
|
||||
return pickHeaderString(headers, "x-image-task-base-url");
|
||||
}
|
||||
|
||||
function pickModel(headers) {
|
||||
return pickHeaderString(headers, "x-image-task-model");
|
||||
}
|
||||
|
||||
// 解析 Base-Url:别名优先,否则必须是 http(s) URL。
|
||||
// 返回 { provider, url }:url 是最终 POST 的完整地址。
|
||||
function resolveEndpoint(rawBase) {
|
||||
const raw = String(rawBase || "zhipu").trim().replace(/\/+$/, "");
|
||||
const alias = BASE_URL_ALIASES[raw.toLowerCase()];
|
||||
const base = alias || raw;
|
||||
|
||||
let host;
|
||||
try {
|
||||
if (!/^https?:\/\//i.test(base)) throw new Error("not http(s)");
|
||||
host = new URL(base).hostname.toLowerCase();
|
||||
} catch {
|
||||
throw new Error(
|
||||
`Invalid X-Image-Task-Base-Url "${raw}": use an alias (${Object.keys(BASE_URL_ALIASES).join(", ")}) ` +
|
||||
"or a full http(s) URL."
|
||||
);
|
||||
}
|
||||
|
||||
// 已经给到 /images/generations 就直接用;否则补在 base 后面。
|
||||
const url = /\/images\/generations$/i.test(base)
|
||||
? base
|
||||
: base + "/images/generations";
|
||||
const provider =
|
||||
host === ZHIPU_HOST_SUFFIX || host.endsWith("." + ZHIPU_HOST_SUFFIX)
|
||||
? "zhipu"
|
||||
: "openai";
|
||||
return { provider, url };
|
||||
}
|
||||
|
||||
// 模型只由 header 决定,AI 看不到也填不了。
|
||||
// zhipu 通道有默认模型;其他通道必须显式给 —— 否则会把 CogView 发到网关,
|
||||
// 换来的只是一个含义不明的 400。
|
||||
function resolveModel(headers, provider) {
|
||||
const model = pickModel(headers);
|
||||
if (model) return model;
|
||||
if (provider === "zhipu") return DEFAULT_MODEL;
|
||||
throw new Error(
|
||||
"X-Image-Task-Model is required when X-Image-Task-Base-Url is not the zhipu alias."
|
||||
);
|
||||
}
|
||||
|
||||
// 一次解析出本次请求的上游、凭据、模型。
|
||||
// 配置问题同步抛错,由 create 直接回给调用方,不登记注定失败的任务。
|
||||
function resolveTarget(headers) {
|
||||
const token = pickAuthToken(headers);
|
||||
if (!token) {
|
||||
throw new Error('Missing Authorization: use "Authorization: Bearer <token>".');
|
||||
}
|
||||
const { provider, url } = resolveEndpoint(pickBaseUrl(headers));
|
||||
return { provider, url, token, model: resolveModel(headers, provider) };
|
||||
}
|
||||
|
||||
async function callImagesGenerations({ provider, url, token, model, prompt, image }) {
|
||||
// 智谱原生只认 model/prompt;OpenAI 兼容通道固定单图,并要求返回 URL
|
||||
// (b64_json 几十 MB,既塞不进任务表也没法给模型看)。尺寸/质量一律不传,
|
||||
// 交给上游默认值 —— 各家(尤其 CogView)对尺寸的限制并不一致。
|
||||
// 传了 image 就是图生图;上游字段是数组,所以这里包一层。
|
||||
const body =
|
||||
provider === "zhipu"
|
||||
? { model, prompt }
|
||||
: Object.assign(
|
||||
{ model, prompt, n: 1, response_format: "url" },
|
||||
image ? { images: [image] } : null
|
||||
);
|
||||
let resp;
|
||||
try {
|
||||
resp = await fetch(ZHIPU_API_URL, {
|
||||
resp = await fetch(url, {
|
||||
method: "POST",
|
||||
headers: {
|
||||
Authorization: `Bearer ${token}`,
|
||||
@@ -110,8 +175,9 @@ async function callZhipuImagesGenerations({ token, model, prompt }) {
|
||||
data = { raw: text };
|
||||
}
|
||||
if (!resp.ok) {
|
||||
const label = provider === "zhipu" ? "Zhipu" : "OpenAI-compatible";
|
||||
const err = new Error(
|
||||
`Zhipu API error: ${resp.status} ${resp.statusText} - ${text}`
|
||||
`${label} API error: ${resp.status} ${resp.statusText} - ${text}`
|
||||
);
|
||||
err.status = resp.status;
|
||||
err.detail = data;
|
||||
@@ -120,15 +186,24 @@ async function callZhipuImagesGenerations({ token, model, prompt }) {
|
||||
return data;
|
||||
}
|
||||
|
||||
// 只认 http(s) URL。b64_json 不再当 URL 存:它会把任务表撑爆,模型也读不了。
|
||||
function extractUrls(data) {
|
||||
if (!data) return [];
|
||||
if (Array.isArray(data.data)) {
|
||||
return data.data
|
||||
.map((it) => it && (it.url || it.b64_json))
|
||||
.filter(Boolean);
|
||||
}
|
||||
if (typeof data.url === "string") return [data.url];
|
||||
return [];
|
||||
const items = Array.isArray(data.data)
|
||||
? data.data
|
||||
: typeof data.url === "string"
|
||||
? [data]
|
||||
: [];
|
||||
return items
|
||||
.map((it) => (it && typeof it.url === "string" ? it.url.trim() : ""))
|
||||
.filter((u) => /^https?:\/\//i.test(u));
|
||||
}
|
||||
|
||||
function hasInlineBase64(data) {
|
||||
return (
|
||||
Array.isArray(data && data.data) &&
|
||||
data.data.some((it) => it && typeof it.b64_json === "string")
|
||||
);
|
||||
}
|
||||
|
||||
// ===== 自维护任务表(异步语义全靠这层模拟) =====
|
||||
@@ -163,13 +238,23 @@ function pruneTasks() {
|
||||
}
|
||||
|
||||
// 后台跑同步上游调用,结果回写任务表(fire-and-forget,不 await)
|
||||
function runImageTask({ task, token, model, prompt }) {
|
||||
callZhipuImagesGenerations({ token, model, prompt })
|
||||
function runImageTask({ task, target, prompt, image }) {
|
||||
callImagesGenerations({
|
||||
provider: target.provider,
|
||||
url: target.url,
|
||||
token: target.token,
|
||||
model: target.model,
|
||||
prompt,
|
||||
image,
|
||||
})
|
||||
.then((data) => {
|
||||
const urls = extractUrls(data);
|
||||
if (urls.length === 0) {
|
||||
task.status = "FAIL";
|
||||
task.error = `Zhipu returned no image URL. Raw response: ${JSON.stringify(data)}`;
|
||||
task.error = hasInlineBase64(data)
|
||||
? "Upstream returned b64_json instead of a URL; this service only returns URLs. " +
|
||||
"Use a model that supports response_format=url."
|
||||
: `Upstream returned no image URL. Raw response: ${JSON.stringify(data)}`;
|
||||
} else {
|
||||
task.status = "SUCCESS";
|
||||
task.urls = urls;
|
||||
@@ -184,7 +269,7 @@ function runImageTask({ task, token, model, prompt }) {
|
||||
}
|
||||
|
||||
// ===== op=create:提交图片生成(立即返回 task_id,后台执行)=====
|
||||
async function handleCreate({ args, headers, token }) {
|
||||
async function handleCreate({ args, headers }) {
|
||||
// schema 只约束了 min(1)," " 这种纯空白能通过校验并白跑一次出图,所以这里 trim 后再判。
|
||||
// 顺手用 trim 过的值:上游拿到的 prompt 不带首尾空白。
|
||||
const prompt = typeof args.prompt === "string" ? args.prompt.trim() : "";
|
||||
@@ -195,26 +280,76 @@ async function handleCreate({ args, headers, token }) {
|
||||
};
|
||||
}
|
||||
|
||||
// model 完全由 HTTP header 控制(X-Image-Task-Model / X-Mcp-Model / X-Model),
|
||||
// 不存进 session,每次从本次请求的 header 读取,未设置则用默认 CogView-3-Flash。
|
||||
// AI 看不到 model 参数(schema 中已删除),避免其误传。
|
||||
const model = pickModel(headers) || DEFAULT_MODEL;
|
||||
// image 是文生图/图生图开关:不传 = 文生图;传一个公网 URL = 修图。
|
||||
// 只接受公网 http(s) URL;本地文件请先由调用方用 mint_public_link 换成公网链接。
|
||||
if (args.image !== undefined && typeof args.image !== "string") {
|
||||
return {
|
||||
isError: true,
|
||||
content: [{ type: "text", text: 'op=create: "image" must be a string.' }],
|
||||
};
|
||||
}
|
||||
const image = typeof args.image === "string" ? args.image.trim() : "";
|
||||
if (image && !/^https?:\/\//i.test(image)) {
|
||||
return {
|
||||
isError: true,
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text:
|
||||
'op=create: "image" must be a public http(s) URL. ' +
|
||||
"For a local file, call mint_public_link first to get a public URL.",
|
||||
},
|
||||
],
|
||||
};
|
||||
}
|
||||
|
||||
// 上游地址、模型、凭据全部来自本次请求的 header(Authorization /
|
||||
// X-Image-Task-Base-Url / X-Image-Task-Model),AI 看不到也填不了。
|
||||
// 配置类错误直接回错,不登记一个必然失败的任务。
|
||||
let target;
|
||||
try {
|
||||
target = resolveTarget(headers);
|
||||
} catch (e) {
|
||||
return {
|
||||
isError: true,
|
||||
content: [{ type: "text", text: e.message }],
|
||||
};
|
||||
}
|
||||
|
||||
// 智谱原生接口不支持图生图;带 image 的请求只能走 OpenAI 兼容端点。
|
||||
if (image && target.provider === "zhipu") {
|
||||
return {
|
||||
isError: true,
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text:
|
||||
'Image editing is not supported by the configured model. ' +
|
||||
'Remove "image" for text-to-image.',
|
||||
},
|
||||
],
|
||||
};
|
||||
}
|
||||
|
||||
pruneTasks();
|
||||
const taskId = randomUUID();
|
||||
const task = {
|
||||
status: "PROCESSING",
|
||||
model,
|
||||
provider: target.provider,
|
||||
model: target.model,
|
||||
prompt,
|
||||
createdAt: Date.now(),
|
||||
};
|
||||
tasks.set(taskId, task);
|
||||
|
||||
// token/model 在此刻从本次请求 header 捕获进闭包,后台完成前无需再取
|
||||
runImageTask({ task, token, model, prompt });
|
||||
// target 与 image 在此刻从本次请求捕获进闭包,后台完成前无需再取
|
||||
runImageTask({ task, target, prompt, image });
|
||||
|
||||
const mode = image ? "edit" : "text-to-image";
|
||||
const summary =
|
||||
`Model: ${model}\n` +
|
||||
`Model: ${target.model}\n` +
|
||||
`Provider: ${target.provider}\n` +
|
||||
`Mode: ${mode}\n` +
|
||||
`task_id: ${taskId}\n` +
|
||||
`task_status: PROCESSING\n` +
|
||||
`\n` +
|
||||
@@ -258,6 +393,7 @@ async function handleGet({ args }) {
|
||||
text:
|
||||
`task_id: ${taskId}\n` +
|
||||
`model: ${task.model}\n` +
|
||||
`provider: ${task.provider}\n` +
|
||||
`task_status: PROCESSING\n` +
|
||||
`\n` +
|
||||
`Call op="get" again in a few seconds.`,
|
||||
@@ -272,7 +408,11 @@ async function handleGet({ args }) {
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text: `task_id: ${taskId}\ntask_status: FAIL\nerror: ${task.error}`,
|
||||
text:
|
||||
`task_id: ${taskId}\n` +
|
||||
`provider: ${task.provider}\n` +
|
||||
`task_status: FAIL\n` +
|
||||
`error: ${task.error}`,
|
||||
},
|
||||
],
|
||||
};
|
||||
@@ -287,6 +427,7 @@ async function handleGet({ args }) {
|
||||
const summary =
|
||||
`task_id: ${taskId}\n` +
|
||||
`model: ${task.model}\n` +
|
||||
`provider: ${task.provider}\n` +
|
||||
`task_status: SUCCESS\n` +
|
||||
`${lines}`;
|
||||
return { content: [{ type: "text", text: summary }] };
|
||||
@@ -307,17 +448,18 @@ function buildServer() {
|
||||
|
||||
server.tool(
|
||||
"image_task",
|
||||
`AI image generation task.
|
||||
`AI image generation and editing task.
|
||||
|
||||
Operations:
|
||||
- \`create\`: Create a new generation task. Requires \`prompt\`. Returns \`task_id\` immediately; generation runs in background.
|
||||
- \`get\`: Check an existing task. Requires \`task_id\`. Returns status and, on SUCCESS, image URLs.
|
||||
- \`create\`: Create a generation task. Requires \`prompt\`. Returns \`task_id\` immediately; generation runs in background. Optionally pass \`image\` for image-to-image editing.
|
||||
- \`get\`: Check a task. Requires \`task_id\`. Returns status and, on SUCCESS, image URLs.
|
||||
|
||||
Examples:
|
||||
- New image request → \`{"op":"create","prompt":"A cat sitting in a garden"}\`
|
||||
- Check task result → \`{"op":"get","task_id":"<task_id from create>"}\`
|
||||
- New image → \`{"op":"create","prompt":"A cat sitting in a garden"}\`
|
||||
- Edit an image → \`{"op":"create","prompt":"Make it snow","image":"https://..."}\`
|
||||
- Check result → \`{"op":"get","task_id":"<task_id from create>"}\`
|
||||
|
||||
Workflow: call \`create\` once, then call \`get\` with the returned \`task_id\` until \`task_status\` is \`SUCCESS\` or \`FAIL\`. Never call \`get\` without a \`task_id\`, and never submit duplicate tasks just to check status.`,
|
||||
Workflow: call \`create\` once, then \`get\` with the returned \`task_id\` until \`task_status\` is \`SUCCESS\` or \`FAIL\`.`,
|
||||
{
|
||||
op: z
|
||||
.enum(["create", "get"])
|
||||
@@ -334,12 +476,20 @@ Workflow: call \`create\` once, then call \`get\` with the returned \`task_id\`
|
||||
.min(1)
|
||||
.optional()
|
||||
.describe("task_id returned by create. Required for get; omit for create."),
|
||||
image: z
|
||||
.string()
|
||||
.min(1)
|
||||
.regex(/^https?:\/\//i)
|
||||
.optional()
|
||||
.describe(
|
||||
"One public image URL to edit; omit for text-to-image. For a local file, call mint_public_link first to get a public URL."
|
||||
),
|
||||
},
|
||||
async (args, extra) => {
|
||||
// SDK 在 tool callback 的 extra.requestInfo.headers 里会透传当前 HTTP 请求的 headers
|
||||
// (参见 webStandardStreamableHttp.js: buildRequestInfo 段)
|
||||
const headers = extra?.requestInfo?.headers;
|
||||
const token = pickToken(headers);
|
||||
const token = pickAuthToken(headers);
|
||||
if (!token) {
|
||||
return {
|
||||
isError: true,
|
||||
@@ -347,7 +497,7 @@ Workflow: call \`create\` once, then call \`get\` with the returned \`task_id\`
|
||||
{
|
||||
type: "text",
|
||||
text:
|
||||
"Missing authentication token.",
|
||||
'Missing Authorization: use "Authorization: Bearer <token>".',
|
||||
},
|
||||
],
|
||||
};
|
||||
@@ -355,7 +505,7 @@ Workflow: call \`create\` once, then call \`get\` with the returned \`task_id\`
|
||||
|
||||
switch (args.op) {
|
||||
case "create":
|
||||
return await handleCreate({ args, headers, token });
|
||||
return await handleCreate({ args, headers });
|
||||
case "get":
|
||||
return await handleGet({ args });
|
||||
default:
|
||||
|
||||
Reference in New Issue
Block a user