From 3df3847b88898c3684195a2a7111e5529d730152 Mon Sep 17 00:00:00 2001 From: kicer Date: Wed, 21 Oct 2026 17:22:03 +0800 Subject: [PATCH] =?UTF-8?q?fix(mcp):=20image/video=20=E6=8F=8F=E8=BF=B0?= =?UTF-8?q?=E5=AF=B9=E9=BD=90=E3=80=81=E7=A9=BA=E7=99=BD=E5=8F=82=E6=95=B0?= =?UTF-8?q?=E6=A0=A1=E9=AA=8C=E3=80=81SUCCESS=20=E5=8D=95=E5=9D=97?= =?UTF-8?q?=E8=BE=93=E5=87=BA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 描述:两个工具的 description 统一为 Operations/Examples/Workflow 结构,参数描述改成 "Required for X; omit for Y",并把 image_url 的临时链接指向 mint_public_link。 mode=skill 下模型只能从 description 读契约(skill 的 args 是自由对象),示例才有意义。 校验:handleCreate/handleGet 先 trim 再判空。纯空白 prompt 能过 schema 的 min(1), 此前会让图片白跑一次出图、视频把空白提示词发给上游;纯空白 task_id 则会拼进 上游查询路径,得到一条无从归因的报错。 输出:SUCCESS 不再额外回一个裸 URL 块。core 的 mcp.callTool 只把 text 块 join 成 一段,该块没有消费者,只是让模型看到同一个 URL 两遍。 --- mcp/image_task/README.md | 5 ++- mcp/image_task/src/mcp-server.js | 61 ++++++++++++++++++-------------- mcp/video_task/README.md | 5 ++- mcp/video_task/src/mcp-server.js | 56 +++++++++++++++++------------ 4 files changed, 72 insertions(+), 55 deletions(-) diff --git a/mcp/image_task/README.md b/mcp/image_task/README.md index 9b127d0..a0dc64f 100644 --- a/mcp/image_task/README.md +++ b/mcp/image_task/README.md @@ -110,13 +110,12 @@ docker exec mcp_image_task node -e "fetch('http://localhost:3000/health').then(r `op=get` 按任务状态返回: - `PROCESSING`:提示几秒后再查; -- `SUCCESS`:若干 `text` 块,第一块是摘要,后续每块各包含一张图片的 URL(方便 LLM 直接贴图或下载): +- `SUCCESS`:单个 `text` 块,摘要后跟图片 URL(单图直接给 `Image URL:`,多图按 `Image N:` 逐行列出): ```jsonc { "content": [ - { "type": "text", "text": "task_id: \nmodel: CogView-3-Flash\ntask_status: SUCCESS\nImage 1: https://maas-watermark-prod-new.cn-wlcb.ufileos.com/..." }, - { "type": "text", "text": "https://maas-watermark-prod-new.cn-wlcb.ufileos.com/..." } + { "type": "text", "text": "task_id: \nmodel: CogView-3-Flash\ntask_status: SUCCESS\nImage URL: https://maas-watermark-prod-new.cn-wlcb.ufileos.com/..." } ] } ``` diff --git a/mcp/image_task/src/mcp-server.js b/mcp/image_task/src/mcp-server.js index d9d7ec0..711c26c 100644 --- a/mcp/image_task/src/mcp-server.js +++ b/mcp/image_task/src/mcp-server.js @@ -185,7 +185,10 @@ function runImageTask({ task, token, model, prompt }) { // ===== op=create:提交图片生成(立即返回 task_id,后台执行)===== async function handleCreate({ args, headers, token }) { - if (!args.prompt) { + // schema 只约束了 min(1)," " 这种纯空白能通过校验并白跑一次出图,所以这里 trim 后再判。 + // 顺手用 trim 过的值:上游拿到的 prompt 不带首尾空白。 + const prompt = typeof args.prompt === "string" ? args.prompt.trim() : ""; + if (!prompt) { return { isError: true, content: [{ type: "text", text: 'op=create requires "prompt".' }], @@ -202,13 +205,13 @@ async function handleCreate({ args, headers, token }) { const task = { status: "PROCESSING", model, - prompt: args.prompt, + prompt, createdAt: Date.now(), }; tasks.set(taskId, task); // token/model 在此刻从本次请求 header 捕获进闭包,后台完成前无需再取 - runImageTask({ task, token, model, prompt: args.prompt }); + runImageTask({ task, token, model, prompt }); const summary = `Model: ${model}\n` + @@ -223,14 +226,16 @@ async function handleCreate({ args, headers, token }) { // ===== op=get:查询任务状态(只读本地表,不碰上游)===== async function handleGet({ args }) { - if (!args.task_id) { + // 与 handleCreate 同理:纯空白 task_id 应报"缺参数",而不是得到 Unknown task_id " " 这种含糊错误。 + const taskId = typeof args.task_id === "string" ? args.task_id.trim() : ""; + if (!taskId) { return { isError: true, content: [{ type: "text", text: 'op=get requires "task_id".' }], }; } - const task = tasks.get(args.task_id); + const task = tasks.get(taskId); if (!task) { return { isError: true, @@ -238,7 +243,7 @@ async function handleGet({ args }) { { type: "text", text: - `Unknown task_id "${args.task_id}". ` + + `Unknown task_id "${taskId}". ` + `Finished tasks are kept for 1 hour and are lost on service restart.`, }, ], @@ -251,7 +256,7 @@ async function handleGet({ args }) { { type: "text", text: - `task_id: ${args.task_id}\n` + + `task_id: ${taskId}\n` + `model: ${task.model}\n` + `task_status: PROCESSING\n` + `\n` + @@ -267,25 +272,24 @@ async function handleGet({ args }) { content: [ { type: "text", - text: `task_id: ${args.task_id}\ntask_status: FAIL\nerror: ${task.error}`, + text: `task_id: ${taskId}\ntask_status: FAIL\nerror: ${task.error}`, }, ], }; } - // SUCCESS:输出格式与原同步版 create 一致(摘要块 + 每张图一个 URL 块) - const lines = task.urls.map((u, i) => `Image ${i + 1}: ${u}`).join("\n"); + // SUCCESS:单块输出。旧格式是「摘要块 + 每张图一个裸 URL 块」,但 core 的 mcp.callTool + // 只把 text 块用 \n 拼起来(串前端/微信也不认裸 URL 块),结果就是同一 URL 在模型面前出现两遍。 + const lines = + task.urls.length === 1 + ? `Image URL: ${task.urls[0]}` + : task.urls.map((u, i) => `Image ${i + 1}: ${u}`).join("\n"); const summary = - `task_id: ${args.task_id}\n` + + `task_id: ${taskId}\n` + `model: ${task.model}\n` + `task_status: SUCCESS\n` + `${lines}`; - return { - content: [ - { type: "text", text: summary }, - ...task.urls.map((u) => ({ type: "text", text: u })), - ], - }; + return { content: [{ type: "text", text: summary }] }; } function buildServer() { @@ -303,28 +307,33 @@ function buildServer() { server.tool( "image_task", - `AI image generation. + `AI image generation task. -op=create Submit a new task. Returns a task_id immediately; generation runs in background. - Requires prompt. -op=get Fetch the status of a previously submitted task. Requires task_id. - On SUCCESS, returns the image URLs. +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. -Typical flow: call op=create, then call op=get with the returned task_id until task_status is SUCCESS or FAIL.`, +Examples: +- New image request → \`{"op":"create","prompt":"A cat sitting in a garden"}\` +- Check task result → \`{"op":"get","task_id":""}\` + +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.`, { - op: z.enum(["create", "get"]).describe("Operation to perform."), + op: z + .enum(["create", "get"]) + .describe("Use create to start a new image generation task; use get to check a task by its task_id."), prompt: z .string() .min(1) .optional() .describe( - "Image generation prompt; describe the desired scene in detail. Required when op=create." + "Image generation prompt; describe the desired scene in detail. Required for create; omit for get." ), task_id: z .string() .min(1) .optional() - .describe("task_id returned by op=create. Required when op=get."), + .describe("task_id returned by create. Required for get; omit for create."), }, async (args, extra) => { // SDK 在 tool callback 的 extra.requestInfo.headers 里会透传当前 HTTP 请求的 headers diff --git a/mcp/video_task/README.md b/mcp/video_task/README.md index 781db42..2f29a0d 100644 --- a/mcp/video_task/README.md +++ b/mcp/video_task/README.md @@ -105,12 +105,11 @@ docker exec mcp_video_task node -e "fetch('http://localhost:3000/health').then(r ### 返回(op=get) -- **`SUCCESS`**:返回 `Video URL`(智谱签名 URL,**24h 左右有效**,需及时转存),外加一张 `Cover` 封面图: +- **`SUCCESS`**:单个 `text` 块,含 `Video URL`(智谱签名 URL,**24h 左右有效**,需及时转存),以及 `Cover` 封面图: ```jsonc { "content": [ - { "type": "text", "text": "task_id: ...\nmodel: cogvideox-flash\ntask_status: SUCCESS\nVideo URL: https://...\nCover: https://..." }, - { "type": "text", "text": "https://...video url..." } + { "type": "text", "text": "task_id: ...\nmodel: cogvideox-flash\ntask_status: SUCCESS\nVideo URL: https://...\nCover: https://..." } ] } ``` diff --git a/mcp/video_task/src/mcp-server.js b/mcp/video_task/src/mcp-server.js index 32ac6e0..41a2b58 100644 --- a/mcp/video_task/src/mcp-server.js +++ b/mcp/video_task/src/mcp-server.js @@ -193,7 +193,11 @@ async function queryAsyncResult({ token, id }) { // ---------- op=create 的业务处理 ---------- async function handleCreate({ args, headers, token }) { - if (!args.prompt && !args.image_url) { + // 纯空白 prompt 等同没给:schema 只校验类型/长度,不校验内容。 + // 不 trim 的话,“ ”会被当成合法 prompt 提交(text-to-video 拿到空白提示词, + // image-to-video 则多传一个无意义字段)。 + const prompt = typeof args.prompt === "string" ? args.prompt.trim() : ""; + if (!prompt && !args.image_url) { return { isError: true, content: [ @@ -223,7 +227,7 @@ async function handleCreate({ args, headers, token }) { const data = await submitVideo({ token, model, - prompt: args.prompt, + prompt, image_url: args.image_url, quality, with_audio: args.with_audio ?? false, @@ -258,7 +262,10 @@ async function handleCreate({ args, headers, token }) { // ---------- op=get 的业务处理 ---------- async function handleGet({ args, token }) { - if (!args.task_id) { + // 与 handleCreate 同理:纯空白 task_id 不能直接拼进上游路径, + // 否则会得到一条含编码后空白的上游报错,既无从归因也误导模型。 + const taskId = typeof args.task_id === "string" ? args.task_id.trim() : ""; + if (!taskId) { return { isError: true, content: [{ type: "text", text: 'op=get requires "task_id".' }], @@ -266,7 +273,7 @@ async function handleGet({ args, token }) { } try { - const data = await queryAsyncResult({ token, id: args.task_id }); + const data = await queryAsyncResult({ token, id: taskId }); const status = data.task_status || "UNKNOWN"; if (status === "SUCCESS") { @@ -290,12 +297,9 @@ async function handleGet({ args, token }) { `task_status: SUCCESS\n` + `Video URL: ${v.url}\n` + (v.cover_image_url ? `Cover: ${v.cover_image_url}\n` : ""); - return { - content: [ - { type: "text", text: summary }, - { type: "text", text: v.url }, - ], - }; + // 单块输出:URL 已经写在摘要里,旧版额外回一个裸 URL 块会让模型 + // (core 会把 text 块 join 成一段)看到同一个链接两遍。 + return { content: [{ type: "text", text: summary }] }; } // PROCESSING / FAIL / 其他:原样返回关键字段 @@ -336,43 +340,49 @@ function buildServer() { server.tool( "video_task", - `AI video generation. + `AI video generation task. -op=create Submit a new task. Returns a task_id immediately; generation runs asynchronously. - Requires at least one of prompt or image_url. - - text-to-video: pass prompt only. - - image-to-video: also pass image_url. -op=get Fetch the status of a previously submitted task. Requires task_id. - On SUCCESS, returns the video URL. +Operations: +- \`create\`: Start a new video generation task. Requires at least one of \`prompt\` or \`image_url\`. Returns \`task_id\` immediately; generation runs in background. +- \`get\`: Check an existing task. Requires \`task_id\`. Returns status and, on SUCCESS, the video URL. -Typical flow: call op=create, then call op=get with the returned task_id until task_status is SUCCESS or FAIL.`, +Examples: +- Text-to-video → \`{"op":"create","prompt":"A cat running in a garden"}\` +- Image-to-video → \`{"op":"create","image_url":"https://example.com/cat.jpg","prompt":"The cat runs forward"}\` +- Check task → \`{"op":"get","task_id":""}\` + +Workflow: call \`create\` once, then call \`get\` with the returned \`task_id\` until \`task_status\` is \`SUCCESS\` or \`FAIL\`. Never create duplicate tasks just to check status.`, { - op: z.enum(["create", "get"]).describe("Operation to perform."), + op: z + .enum(["create", "get"]) + .describe( + "Use create to start video generation; use get to check a task by its task_id." + ), prompt: z .string() .max(512) .optional() .describe( - "Video text description (max 512 chars). Used with op=create. When combined with image_url it serves as the motion/action description." + "Video description, max 512 characters. Required for text-to-video; when combined with image_url it describes the motion." ), image_url: z .string() .url() .optional() .describe( - "Reference image for image-to-video. Used with op=create. Must be a publicly reachable URL to a png/jpeg/jpg <= 5MB (for local files, first use the agent's built-in tool to mint a public temporary URL)." + "Reference image for image-to-video: publicly reachable png/jpeg/jpg URL <= 5 MB. For local files, first use the built-in mint_public_link tool to get a public temporary URL." ), with_audio: z .boolean() .optional() .describe( - "Whether to generate AI audio. Used with op=create. Default false." + "Whether to generate AI audio. Used with create; defaults to false." ), task_id: z .string() .min(1) .optional() - .describe("task_id returned by op=create. Required when op=get."), + .describe("task_id returned by create. Required for get; omit for create."), }, async (args, extra) => { const headers = extra?.requestInfo?.headers;