Files
agent/mcp/image-gen/README.md
T
kicer 76aa1aa604 feat(image-gen): 移除 header 传 model 的逻辑,仅保留工具参数 → 兜底默认
- 删除 extractModelFromHeaders / X-Image-Gen-Model 等 header 解析路径
- model 优先级简化为单链:arguments.model → DEFAULT_MODEL (CogView-3-Flash)
- 新增 README.md,覆盖启动、客户端配置、工具用法、curl 调试、FAQ
2026-09-04 12:08:54 +08:00

238 lines
8.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# MCP Image Gen
一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的图片生成服务,对接智谱 BigModel 的 `CogView` 系列模型。每次调用通过 HTTP header 传入智谱 API 的 Bearer Token,支持在工具参数中按需切换模型。
- 协议:MCP **Streamable HTTP**(单端点 `/mcp`,支持 SSE 流)
- 上游:[智谱 BigModel Images Generations API](https://open.bigmodel.cn/dev/api#images)
- 默认模型:`CogView-3-Flash`
- 端口:`3000`
- 鉴权:**无服务端密钥**,每次请求必须从 header 携带智谱 token
---
## 快速开始
### 启动(docker-compose)
仓库根目录 `docker-compose.yml` 已包含本服务:
```bash
cd /root/workspace/tools/mcp
docker compose up -d --build mcp-image-gen
```
服务容器名 `mcp-image-gen`,通过反代暴露为 `https://image-gen.ai.foresh.com/mcp`。
直接连容器调试:
```bash
docker exec -it mcp-image-gen sh
# 或本机
curl http://localhost:3000/health
# {"status":"ok","service":"image-gen","sessions":0}
```
### MCP 客户端配置
#### Claude Desktop / Cursor 等支持 `headers` 配置的客户端
```jsonc
// Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
// Cursor: ~/.cursor/mcp.json
{
"mcpServers": {
"image-gen": {
"url": "https://image-gen.ai.foresh.com/mcp",
"headers": {
"Authorization": "Bearer <your-zhipu-api-key>"
}
}
}
}
```
> **重要**:客户端必须在 **每一个 HTTP 请求**(`initialize` / `notifications/initialized` / `tools/call`)都带上 `Authorization` header。配置在 `headers` 里、由客户端自动重发即可。直连模式下 token 不在 session 间共享。
#### 不支持 `headers` 字段的客户端
如果客户端只支持 `command`/`args` 启动方式,可改用 stdio 模式(需自行包一层把 token 注入环境变量,再让工具回调从环境变量读——当前实现 HTTP 模式下不依赖环境变量,需自行扩展)。
---
## 工具:generate_image
调用智谱图片生成接口,返回图片 URL。
### 参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `prompt` | string | ✅ | 图片生成提示词,描述想要的画面内容 |
| `model` | string | ❌ | 模型名称,默认 `CogView-3-Flash`。可填 `CogView-3` / `CogView-3-Flash` 等智谱支持的模型 |
| `size` | string | ❌ | 图片尺寸,例如 `1024x1024`、`1280x1280`、`1024x1792`、`1792x1024`、`768x1344`、`1344x768`,遵循智谱 API 规格 |
### Model 优先级(单链)
```
工具参数 arguments.model → DEFAULT_MODEL (CogView-3-Flash)
```
每次 `tools/call` 都是独立决策,**想换模型就在该次调用传 `model` 参数**,不需要重连/换 session。
### 返回
工具成功时返回若干 `text` 块,第一块是摘要,后续每块各包含一张图片的 URL(方便 LLM 直接贴图或下载):
```jsonc
{
"content": [
{ "type": "text", "text": "模型: CogView-3-Flash\n提示词: ...\n图片 1: https://maas-watermark-prod-new.cn-wlcb.ufileos.com/..." },
{ "type": "text", "text": "https://maas-watermark-prod-new.cn-wlcb.ufileos.com/..." }
]
}
```
URL 由智谱签名下发,**带有效期**(通常 24h),如需长期保存请在收到后及时转存到自己的存储。
失败时返回 `isError: true` 的错误描述。
---
## 鉴权细节
每个 HTTP 请求必须携带智谱 API Token,server 从以下 header 字段按顺序识别,**首个非空值生效**:
| 优先级 | Header | 说明 |
|---|---|---|
| 1 | `Authorization: Bearer <token>` | 推荐,标准 OAuth 风格 |
| 2 | `X-Image-Gen-Token: <token>` | 直传,避免与客户端自身的 Authorization 冲突 |
| 3 | `X-Mcp-Token: <token>` | 通用兜底 |
**Token 不会写入服务端任何存储**,仅在 initialize 阶段绑定到内存中的 session 对象,session 结束立即释放。
### 错误响应
| 场景 | HTTP 状态 | 表现 |
|---|---|---|
| initialize 时缺 token | `401` | JSON-RPC `error.message` 提示补充 header |
| 智谱 API 4xx/5xx | `200`(MCP 工具返回) | `isError: true`,正文含智谱返回的状态码和 body |
| 网络失败 | `200`(MCP 工具返回) | `isError: true`,正文含 `fetch` 错误信息 |
---
## 用 curl 手工调试
MCP Streamable HTTP 不是普通 REST,**必须按顺序**:`initialize` → `notifications/initialized` → `tools/call`。下面用一行版串起来:
```bash
# 把 <your-zhipu-api-key> 替换成你智谱的 API Key
TOKEN="<your-zhipu-api-key>"
# 1. initialize 拿 sessionId
SESSION=$(curl -s -D - -X POST http://localhost:3000/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:3000/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. 列出工具(可选验证)
curl -s -X POST http://localhost:3000/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. 调 generate_image
curl -s -X POST http://localhost:3000/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": 3,
"method": "tools/call",
"params": {
"name": "generate_image",
"arguments": {
"prompt": "一只可爱的小猫咪,坐在阳光明媚的窗台上,背景是蓝天白云",
"size": "1280x1280"
}
}
}'
```
响应是 SSE 格式(`event: message` + `data: {...}`),用 `grep '^data:'` 抽 JSON 即可。
---
## 架构与文件
```
image-gen/
├── 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 + tool
```
### 关键设计
- **每 session 一个 transport + server**:通过 `Mcp-Session-Id` 复用,避免每请求重建
- **Token 闭包注入**:在 Express 入口处从 header 提取 token,闭包传给 `buildServer({ token })`,tool 回调里直接使用;不依赖 SDK 内部字段
- **模型参数单链**:`arguments.model` → `DEFAULT_MODEL`,无 header 干预
- **URL 提取**:`response.data[].url` 为准,若返回 `b64_json` 也会一并返回
### 默认模型
```js
// src/mcp-server.js
const DEFAULT_MODEL = "CogView-3-Flash";
```
修改后 `docker compose up -d --build mcp-image-gen` 即可生效。
---
## 常见问题
**Q: 我能在工具参数里不传 `model` 吗?**
A: 可以,不传就走默认 `CogView-3-Flash`。
**Q: 换模型需要重连 MCP session 吗?**
A: 不需要。`model` 是工具参数,每次 `tools/call` 都生效,不需要重建 session。
**Q: Token 会不会泄露到日志?**
A: 当前实现只在 session 内存里持有,不会写入 stdout/stderr。Container 日志只打印 session id。
**Q: 收到 `Missing valid Mcp-Session-Id` 错误?**
A: 漏发了 `Mcp-Session-Id` header,或调 `tools/call` 前没先 `initialize`。
**Q: URL 多久过期?**
A: 智谱签发 URL 默认 24h 左右,详见响应里的 `Expires` 参数。需要长期使用请自行转存到 OSS/S3。
**Q: 能否限制 `size` 白名单?**
A: 当前透传给智谱 API,不做强制校验。如需加白名单,修改 `src/mcp-server.js` 中 `generate_image` 的 `size` schema 即可。