image-mcp

lk888 (gpt-image-2) 图像生成 MCP server · 文生图 + 图生图 · 双 transport (stdio + HTTP) · MySQL 使用量统计 · OSS 持久化 用于 Claude Code / 任何 MCP 客户端做 UI 形态对照、参考稿、概念草图。

1. 它是什么

• 协议:Model Context Protocol (MCP),工具被任何 MCP 客户端(Claude Code / Claude Desktop / Cursor 等)调用
• 能力:一个工具 generate_image — 调 lk888 /v1/media/generate 异步任务,出图后下载 → 上传 OSS → 落 MySQL → 把图直接 base64 返给客户端
• 存储:OSS 永久持久化(预签名 URL,1h),本地是 fallback;MySQL 一张 mcp_usage 表统计每次调用的 size/quality/cost/duration
• transport:
  • stdio 本地直连(Claude Code 拉起本地进程)
  • http 远程(ECS + Nginx + Bearer 鉴权,任何 MCP 客户端都能连)

2. 一次性准备(只跑一次)

2.1 RDS 建库

mysql -h rm-bp1126b6e6ibav2uxzo.mysql.rds.aliyuncs.com -P 3306 -u error_boot -p \
  -e "CREATE DATABASE IF NOT EXISTS \`image2-mcp\` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

库名带连字符,SQL 里必须反引号转义。表 mcp_usage server 启动会自动 CREATE TABLE IF NOT EXISTS,不需要手建。

2.2 白名单

把"本机公网 IP"和"ECS 公网 IP 47.98.87.96"加进 RDS 白名单(阿里云控制台 → 数据安全性 → 白名单)。

2.3 凭据 — 与 errorbook 共享 .env,只追加独有 key

复用思路:RDS_* / ALIYUN_AK/SK 这些"轮换困难"的凭据已经在 errorbook 的 .env.prod / .env.local 里了,image-mcp 不重新定义,通过 docker compose 多 --env-file 叠加引用。

文件	位置	内容
共享基础 .env	本地 D:\workplace\superpower-dev\.env.local / .env.prod,ECS /opt/errorbook/.env.prod	RDS_HOST / RDS_USERNAME / RDS_PASSWORD / ALIYUN_ACCESS_KEY_ID/SECRET 等(errorbook 已有,不动)
image-mcp 增量	本地 D:\workplace\superpower-dev\image-mcp\.env.local / .env.prod,ECS /opt/image-mcp/.env.prod	LK888_KEY / MCP_AUTH_TOKEN / RDS_DB=image2-mcp / IMAGE_MCP_ACR_IMAGE / NGINX_PORT 等(参考 .env.example)

键名对齐说明:

• ✅ RDS_USERNAME(不是 RDS_USER)— 对齐 errorbook .env
• ✅ RDS_DB 独立 key,值 = image2-mcp — 错开 errorbook 的 RDS_DATABASE=ai_errorbook_v2
• ✅ IMAGE_MCP_ACR_IMAGE 独立 key — 错开 errorbook 的 ACR_IMAGE
• ✅ NGINX_PORT 默认 8080,避开 errorbook nginx 占的 80

3. 工具签名

generate_image(
  prompt: str,                               # 必填,中英文皆可
  images: list[str] | None = None,           # 参考图 URL(最多 10);空=文生图,非空=图生图
  size: "1024x1024" | "1024x1536" | "1536x1024" |
        "2048x2048" | "2048x1152" | "3840x2160" | "2160x3840" | "auto" = "1024x1536",
  quality: "low" | "medium" | "high" | "auto" = "medium",
  background: "opaque" | "transparent" = "opaque",
  n: int = 1,                                # 1~4
) -> [ImageContent (base64 PNG), TextContent (元信息 + OSS URL)]

每次调用会落一条 mcp_usage 记录:ts / task_id / mode (t2i|i2i) / size / quality / duration_s / cost_usd / status / result_url / oss_key / oss_url / local_path。

4. 本地跑

4.1 stdio 模式(Claude Code 直连)

claude_desktop_config.json(Windows 在 %APPDATA%\Claude\):

{
  "mcpServers": {
    "image-mcp": {
      "command": "D:/workplace/superpower-dev/image-mcp/.venv/Scripts/python.exe",
      "args": ["-m", "image_mcp.server"],
      "env": {
        "PYTHONPATH": "D:/workplace/superpower-dev/image-mcp/src",
        "LK888_KEY": "sk-...",
        "RDS_HOST": "rm-bp1126b6e6ibav2uxzo.mysql.rds.aliyuncs.com",
        "RDS_USERNAME": "error_boot",
        "RDS_PASSWORD": "...",
        "RDS_DB": "image2-mcp",
        "ALIYUN_ACCESS_KEY_ID": "...",
        "ALIYUN_ACCESS_KEY_SECRET": "..."
      }
    }
  }
}

stdio 模式 env 直接写 claude_desktop_config.json 是 Claude Code 唯一的注入方式 — 这份配置在用户 AppData 下,不入项目 git。如果嫌重复,也可以把 env 留空,改用 dotenv 自动加载(让 server 启动时读 D:\workplace\superpower-dev\.env.local)。

4.2 HTTP 模式(本机调试)

# PowerShell,凭据走 session env
$env:LK888_KEY = "..."; $env:RDS_HOST = "..."; ...; $env:MCP_AUTH_TOKEN = "<32+ chars>"
$env:PYTHONPATH = "src"
.venv\Scripts\python.exe -m image_mcp.server --transport http --port 8765

Claude Code 连远程:

claude mcp add image-mcp --transport http http://127.0.0.1:8765/mcp \
  --header "Authorization: Bearer <token>"

5. 云上部署(参考 superpower/部署空间/部署运维手册.md 风格)

复用 errorbook 后端的 ACR + ECS 链路,新仓库 errorboot/image-mcp。

5.1 本地 build + push 镜像

cd D:\workplace\superpower-dev\image-mcp
docker build -t crpi-4e3qyeiaxmbfzar4.cn-hangzhou.personal.cr.aliyuncs.com/errorboot/image-mcp:latest .
docker push  crpi-4e3qyeiaxmbfzar4.cn-hangzhou.personal.cr.aliyuncs.com/errorboot/image-mcp:latest

首次 push 需要 docker login crpi-4e3qyeiaxmbfzar4.cn-hangzhou.personal.cr.aliyuncs.com(凭据在 ACR 控制台 "访问凭证")。

5.2 ECS 一次性准备

ssh root@47.98.87.96
mkdir -p /opt/image-mcp/deploy
cd /opt/image-mcp

# scp 上去:docker-compose.prod.yml + deploy/nginx.conf
# .env.prod 自己建(只放 image-mcp 独有 key,参考 .env.example;不入 git)

docker login crpi-4e3qyeiaxmbfzar4-vpc.cn-hangzhou.personal.cr.aliyuncs.com

5.3 ECS 拉镜像 + 起服务 — 共享 errorbook .env.prod

cd /opt/image-mcp
docker compose -f docker-compose.prod.yml \
  --env-file /opt/errorbook/.env.prod \    # 复用 errorbook 的 RDS_* / ALIYUN_*
  --env-file ./.env.prod \                 # image-mcp 独有:LK888_KEY / MCP_AUTH_TOKEN / RDS_DB / IMAGE_MCP_ACR_IMAGE
  pull
docker compose -f docker-compose.prod.yml \
  --env-file /opt/errorbook/.env.prod \
  --env-file ./.env.prod \
  up -d
docker compose -f docker-compose.prod.yml \
  --env-file /opt/errorbook/.env.prod \
  --env-file ./.env.prod \
  ps

🔴 铁则升级版:这里和 errorbook 部署手册 §1 的"单 --env-file"铁则有意分歧:image-mcp 走双 --env-file 叠加(后面的覆盖前面的)。共享凭据基础 + 服务独立配置,避免凭据重复定义。

建议沉淀一个 alias 在 ECS ~/.bashrc:

alias img-mcp='docker compose -f /opt/image-mcp/docker-compose.prod.yml --env-file /opt/errorbook/.env.prod --env-file /opt/image-mcp/.env.prod'
# 之后:img-mcp pull / img-mcp up -d / img-mcp ps / img-mcp logs -f image-mcp

5.4 smoke 验证

# Bearer 校验 — 无 token 应 401
curl -s -o /dev/null -w "%{http_code}\n" http://localhost/mcp

# 带正确 token + MCP initialize 应 200 + SSE 流
curl -s -i -X POST http://localhost/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  | head -20

5.5 改代码后重发

docker build -t crpi-4e3qyeiaxmbfzar4.cn-hangzhou.personal.cr.aliyuncs.com/errorboot/image-mcp:latest .
docker push  crpi-4e3qyeiaxmbfzar4.cn-hangzhou.personal.cr.aliyuncs.com/errorboot/image-mcp:latest

ssh root@47.98.87.96 'img-mcp pull && img-mcp up -d'   # 用 §5.3 沉淀的 alias

6. 凭据安全

• 全部走 env(.env.local / .env.prod),源码、git 历史、Docker 镜像里都见不到凭据
• .gitignore 屏蔽 .env*
• push 前 grep:grep -rn "lizhao@\|aliyun.*KEY\|sk-" --include="*.py" --include="*.yml" --include="*.toml" .
• MCP_AUTH_TOKEN 用 32+ 位强随机串(openssl rand -hex 32)
• 密码在对话/截图前永远先脱敏

7. 已知坑

• 库名 image2-mcp 带连字符,所有 SQL 引用必须反引号 `image2-mcp`
• POST 端点是 /mcp(不带尾 slash);带 /mcp/ 会 307 重定向
• dev:h5 / playwright 等浏览器自动化不适用(MCP 协议层,不是 web 页面)
• OSS 是私有 bucket,返回的是预签名 URL,1h 后失效,需要查时重签

8. 待办

• ICP 备案 + 域名 + HTTPS → 解锁微信小程序审核场景调用
• 多 caller 区分(目前 caller 字段恒为 NULL,后期按 token / IP 落)
• 接监控告警(失败率、cost 周报)