mcp-image-studio

通用的 MCP server，对接任何 OpenAI Images API 兼容的网关（OpenAI 官方、xje96 之类聚合网关），通过 prompt 模板版本化 + 用户评分驱动 prompt 进化。

Tools

| Tool | 用途 | |---|---| | generate_image | 直接 prompt 文生图 | | edit_image | 基于本地图改色/微调（图生图） | | apply_template | 套模板生图（推荐入口；模板自带 action 与变量） | | list_templates | 列出所有内置 / 用户模板 | | rate_last_generation | good/ok/bad 给上次生图打分（驱动进化） | | list_samples | 浏览历史生图 + 评分 | | propose_template_revision | 基于差评样本生成新版本模板草案（写到 proposals/，人审 merge） |

安装与启动（发布版）

npx -y mcp-image-studio

配置

作为 MCP server 使用时，推荐在客户端配置里传入环境变量：

IMAGE_API_BASE_URL=https://api.xje96.uk/v1   # 或 https://api.openai.com/v1
IMAGE_API_KEY=sk-...
IMAGE_MODEL=gpt-image-2

可选项见 .env.example（输出目录、模板目录、UA、路径白名单等）。默认 output dir = 调用时的 process.cwd()。

Claude Code 集成

把它注册成 MCP server。例如在 ~/.claude/.mcp.json（或项目级 .mcp.json）：

{
  "mcpServers": {
    "image-studio": {
      "command": "npx",
      "args": ["-y", "mcp-image-studio"],
      "env": {
        "IMAGE_API_BASE_URL": "https://api.xje96.uk/v1",
        "IMAGE_API_KEY": "sk-...",
        "IMAGE_MODEL": "gpt-image-2"
      }
    }
  }
}

也可以全局安装后使用：

npm install -g mcp-image-studio
mcp-image-studio

对应 MCP 配置：

{
  "mcpServers": {
    "image-studio": {
      "command": "mcp-image-studio",
      "args": [],
      "env": {
        "IMAGE_API_BASE_URL": "https://api.xje96.uk/v1",
        "IMAGE_API_KEY": "sk-...",
        "IMAGE_MODEL": "gpt-image-2"
      }
    }
  }
}

本地开发

git clone https://github.com/mrsxs/mcp-image-studio.git
cd mcp-image-studio
npm install
npm run build
node dist/server.js

开发期热加载：

{
  "mcpServers": {
    "image-studio-dev": {
      "command": "npx",
      "args": ["tsx", "/Users/you/mcp-image-studio/src/server.ts"],
      "env": { "...": "..." }
    }
  }
}

使用流程（典型）

1. apply_template { template: "white_studio_product", vars: { color: "light blue", item: "men's dress shirt" } }
   → { sample_id: "...", output_path: "/cwd/generated-xxx.png" }
2. (人眼看图后)
   rate_last_generation { score: "bad", comment: "出现了 3 件衬衫合影，不是单件" }
3. 累积几次差评后：
   propose_template_revision { template: "white_studio_product", draft_prompt?: "..." }
   → 返回 proposals/white_studio_product-v2-xxxx.yaml 路径
4. 人审通过：把它复制到 ~/.config/mcp-image-studio/templates/ 即生效（覆盖 builtin）

模板格式

参考 templates/white_studio_product.yaml：

name: white_studio_product
version: 1
action: generate            # generate | edit
description: ...
required_vars: [item]
optional_vars: [color, extra]
prompt: |
  A single {color} {item}, ...
size: 1024x1024
notes: ...

• {var} 自动替换为传入变量；missing optional 变成空串
• 用户目录（IMAGE_TEMPLATES_DIR，默认 ~/.config/mcp-image-studio/templates）同名 YAML 会覆盖 builtin
• 同 origin 内同 name 取 version 最大者

路径白名单

防止 MCP 越权读写。默认允许：

• process.cwd()
• IMAGE_OUTPUT_DIR
• IMAGE_SAMPLES_DIR（生图记录）
• IMAGE_TEMPLATES_DIR（用户模板）
• 内置 templates 目录
• proposals 目录

可用 IMAGE_PATH_WHITELIST=path1,path2,... 追加（逗号分隔，支持 ~/）。

进化机制

每次 generate/edit/apply_template 自动落一条 samples/{sample_id}.json：

{
  "sample_id": "2026-05-09T...",
  "action": "generate",
  "template_name": "white_studio_product",
  "template_version": 1,
  "template_vars": { "color": "light blue", "item": "shirt" },
  "prompt": "(rendered)",
  "output_path": "/cwd/generated-xxx.png",
  "elapsed_ms": 56321,
  "rating": { "score": "bad", "comment": "...", "rated_at": "..." }
}

propose_template_revision 会把同模板的 bad 样本 + 它们的 comment 当上下文喂给 chat LLM，让它生成新版 YAML 草案。草案不会自动启用，必须你 review + 拷贝到用户模板目录才生效。

License

MIT