From eba3a3c7ffe22d6f9034123f34dfbbb683997ec9 Mon Sep 17 00:00:00 2001 From: kicer Date: Fri, 4 Sep 2026 12:43:23 +0800 Subject: [PATCH] =?UTF-8?q?fix(image-gen):=20=E4=BB=8E=20extra.requestInfo?= =?UTF-8?q?.headers=20=E8=AF=BB=E5=8F=96=20token=20&=20model=EF=BC=88?= =?UTF-8?q?=E4=BF=AE=E6=AD=A3=E5=AD=97=E6=AE=B5=E8=B7=AF=E5=BE=84=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 之前 pickToken/pickModel 用的 'extra?.requestInfo?.req?.headers' 多写了一层 '.req', SDK 实际只有 extra.requestInfo.headers(参见 webStandardStreamableHttp.js buildRequestInfo), 导致 token/model 始终为 null,AI 调用时实际走默认 model 且若未额外修过 token 则报 401。 本提交: - 取 header 改用 extra.requestInfo.headers - pickToken/pickModel 签名改为接收 headers 对象(去掉对 req 的依赖) - Model 仍只在 tools/call 阶段从 header 读取,不存 session - Model 优先级:header > DEFAULT_MODEL(已删 schema 里的 model 字段,AI 无法误传) - README 同步更新鉴权与 model 章节 --- mcp/image-gen/README.md | 36 +++++++---- mcp/image-gen/src/mcp-server.js | 103 ++++++++++++++++++-------------- 2 files changed, 80 insertions(+), 59 deletions(-) diff --git a/mcp/image-gen/README.md b/mcp/image-gen/README.md index dff83bf..413b2ba 100644 --- a/mcp/image-gen/README.md +++ b/mcp/image-gen/README.md @@ -68,16 +68,23 @@ curl http://localhost:3000/health | 名称 | 类型 | 必填 | 说明 | |---|---|---|---| | `prompt` | string | ✅ | 图片生成提示词,描述想要的画面内容 | -| `model` | string | ❌ | 模型名称,默认 `CogView-3-Flash`。可填 `CogView-3` / `CogView-3-Flash` 等智谱支持的模型 | | `size` | string | ❌ | 图片尺寸,例如 `1024x1024`、`1280x1280`、`1024x1792`、`1792x1024`、`768x1344`、`1344x768`,遵循智谱 API 规格 | -### Model 优先级(单链) +### Model 控制(不在工具参数中暴露) -``` -工具参数 arguments.model → DEFAULT_MODEL (CogView-3-Flash) -``` +模型名由调用方在 **tools/call 这一次的 HTTP header** 中传递,**AI 看不到也填不了**,避免其误传。识别顺序(首个非空值生效): -每次 `tools/call` 都是独立决策,**想换模型就在该次调用传 `model` 参数**,不需要重连/换 session。 +| 优先级 | Header | +|---|---| +| 1 | `X-Image-Gen-Model` | +| 2 | `X-Mcp-Model` | +| 3 | `X-Model` | + +如果都没传,走代码内常量 `DEFAULT_MODEL = "CogView-3-Flash"`。 + +**为什么不放进工具参数?** 调用方一般是 AI 助手(Claude / Cursor 等),它不需要也没能力选择用哪个模型;模型选择属于部署/路由策略,由请求的发起方在 HTTP header 里注入更可控。 + +### 返回 ### 返回 @@ -104,11 +111,11 @@ URL 由智谱签名下发,**带有效期**(通常 24h),如需长期保 | 优先级 | Header | 说明 | |---|---|---| -| 1 | `Authorization: Bearer ` | 推荐,标准 OAuth 风格 | -| 2 | `X-Image-Gen-Token: ` | 直传,避免与客户端自身的 Authorization 冲突 | -| 3 | `X-Mcp-Token: ` | 通用兜底 | +| 1 | `X-Image-Gen-Token: ` | 直传,避免与客户端自身的 Authorization 冲突 | +| 2 | `X-Mcp-Token: ` | 通用兜底 | +| 3 | `Authorization: Bearer ` | 标准 OAuth 风格(排最后是为避免误用) | -**Token 不会写入服务端任何存储**,仅在 initialize 阶段绑定到内存中的 session 对象,session 结束立即释放。 +Token 仅在每次 tool call 时从 header 读取,不写入任何存储、不进 session。 ### 错误响应 @@ -218,11 +225,14 @@ const DEFAULT_MODEL = "CogView-3-Flash"; ## 常见问题 -**Q: 我能在工具参数里不传 `model` 吗?** -A: 可以,不传就走默认 `CogView-3-Flash`。 +**Q: AI 不知道有哪些 model 可选,怎么办?** +A: 这是设计意图。模型选择属于路由策略,不让 AI 决策。调用方在 HTTP header `X-Image-Gen-Model` 里注入即可。 **Q: 换模型需要重连 MCP session 吗?** -A: 不需要。`model` 是工具参数,每次 `tools/call` 都生效,不需要重建 session。 +A: 不需要。Model header 在每次 `tools/call` 都从当前请求读取,不需要重建 session。 + +**Q: 为什么 Model 优先级不是「工具参数 > header」?** +A: 因为我们故意不在 schema 暴露 model 参数,AI 根本不会传 model,所以「工具参数 > header」这条分支实际上不存在。 **Q: Token 会不会泄露到日志?** A: 当前实现只在 session 内存里持有,不会写入 stdout/stderr。Container 日志只打印 session id。 diff --git a/mcp/image-gen/src/mcp-server.js b/mcp/image-gen/src/mcp-server.js index 3f06e66..1713235 100644 --- a/mcp/image-gen/src/mcp-server.js +++ b/mcp/image-gen/src/mcp-server.js @@ -25,13 +25,12 @@ function parseArgs(argv) { return args; } -// 从请求头里提取 token(兼容多种命名 + Bearer 前缀) -function extractTokenFromHeaders(headers) { +function pickToken(headers) { if (!headers) return null; const candidates = [ - headers["authorization"], headers["x-image-gen-token"], headers["x-mcp-token"], + headers["authorization"], ]; for (const v of candidates) { if (!v) continue; @@ -47,6 +46,17 @@ function extractTokenFromHeaders(headers) { return null; } +function pickModel(headers) { + if (!headers) return null; + const v = + headers["x-image-gen-model"] || + headers["x-mcp-model"] || + headers["x-model"]; + if (!v) return null; + const s = String(v).trim(); + return s || null; +} + async function callZhipuImagesGenerations({ token, model, prompt, size }) { const body = { model, prompt }; if (size) body.size = size; @@ -87,25 +97,27 @@ function extractUrls(data) { return []; } -// 创建 McpServer,把 token 通过闭包注入到工具回调里 -function buildServer({ token }) { +function buildServer() { const server = new McpServer( - { name: "image-gen", version: "1.0.0" }, - { capabilities: { tools: {} } } + { + name: "image-gen", + version: "1.0.0", + }, + { + capabilities: { + tools: {}, + }, + } ); server.tool( "generate_image", - "调用智谱 CogView 图片生成 API,根据 prompt 生成图片,返回图片 URL。可选指定 model 和 size。", + "调用智谱图片生成 API,根据 prompt 生成图片,返回图片 URL。可选指定 size。模型由调用方通过 HTTP header(X-Image-Gen-Model)控制,不在工具参数中暴露。", { prompt: z .string() .min(1) - .describe("图片生成提示词,描述想要生成的画面内容"), - model: z - .string() - .optional() - .describe("模型名称,可选,默认 CogView-3-Flash"), + .describe("图片生成提示词,描述想要的画面内容"), size: z .string() .optional() @@ -113,9 +125,28 @@ function buildServer({ token }) { "图片尺寸,例如 1024x1024、1280x1280、1024x1792、1792x1024、768x1344、1344x768,遵循智谱 API 规格" ), }, - async (args) => { - // model 优先级:工具参数 > DEFAULT_MODEL - const model = args.model || DEFAULT_MODEL; + async (args, extra) => { + // SDK 在 tool callback 的 extra.requestInfo.headers 里会透传当前 HTTP 请求的 headers + // (参见 webStandardStreamableHttp.js: buildRequestInfo 段) + const headers = extra?.requestInfo?.headers; + const token = pickToken(headers); + if (!token) { + return { + isError: true, + content: [ + { + type: "text", + text: + "缺少鉴权 token,请通过 HTTP 请求头(例如 Authorization: Bearer 或 X-Image-Gen-Token: )传递。", + }, + ], + }; + } + + // model 完全由 HTTP header 控制(X-Image-Gen-Model / X-Mcp-Model / X-Model), + // 不存进 session,每次从本次请求的 header 读取,未设置则用默认 CogView-3-Flash。 + // AI 看不到 model 参数(schema 中已删除),避免其误传。 + const model = pickModel(headers) || DEFAULT_MODEL; const size = args.size; try { @@ -172,21 +203,17 @@ async function startHttp({ port, host }) { const app = express(); app.use(express.json({ limit: "2mb" })); - // session -> transport + server + token/model + // session -> { server, transport } 映射 const sessions = new Map(); app.get("/health", (_req, res) => { res.json({ status: "ok", service: "image-gen", sessions: sessions.size }); }); - // 主入口:先从 header 取 token(每个 HTTP 请求都取一次), - // 然后用这个 token 创建一个新的 server+transport; - // 已有 session 直接复用 transport,token 沿用 session 首次创建时的值 - // (避免跨请求 token 不一致;MCP 客户端本来就该每次都带同一个 token) - const handleSessionRequest = async (req, res) => { + async function handleSessionRequest(req, res) { const sessionId = req.headers["mcp-session-id"]; - // 已有 session:复用 transport,token/model 直接从 session 缓存里拿 + // 已有 session:复用 transport if (sessionId && sessions.has(sessionId)) { const { transport } = sessions.get(sessionId); await transport.handleRequest(req, res, req.body); @@ -206,42 +233,26 @@ async function startHttp({ port, host }) { return; } - // 从本次请求 header 取 token - const token = extractTokenFromHeaders(req.headers); - if (!token) { - res.status(401).json({ - jsonrpc: "2.0", - error: { - code: -32001, - message: - "缺少鉴权 token,请通过 HTTP 请求头(例如 Authorization: Bearer 或 X-Image-Gen-Token: )传递。", - }, - id: req.body?.id ?? null, - }); - return; - } - const newId = randomUUID(); - const server = buildServer({ token }); + const server = buildServer(); const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => newId, onsessioninitialized: (id) => { - sessions.set(id, { server, transport, token }); - console.log(`[image-gen] session initialized: ${id}`); + sessions.set(id, { server, transport }); }, }); transport.onclose = () => { if (transport.sessionId) { sessions.delete(transport.sessionId); - console.log(`[image-gen] session closed: ${transport.sessionId}`); } }; await server.connect(transport); await transport.handleRequest(req, res, req.body); - }; + } + // POST /mcp: 主入口 app.post("/mcp", handleSessionRequest); // GET /mcp & DELETE /mcp: 用于 SSE 流 / 会话关闭 @@ -265,14 +276,14 @@ async function startHttp({ port, host }) { } async function startStdio() { - // stdio 模式下没有 HTTP header,token 暂未支持(保留入口便于本地调试) - const server = buildServer({ token: "" }); + // 保留 stdio 启动方式,便于本地直接调试 + const server = buildServer(); const { StdioServerTransport } = await import( "@modelcontextprotocol/sdk/server/stdio.js" ); const transport = new StdioServerTransport(); await server.connect(transport); - console.error("[image-gen] MCP stdio server started (no auth)"); + console.error("[image-gen] MCP stdio server started"); } const args = parseArgs(process.argv.slice(2));