====== MCP 生图插件 ======

===== 简介 =====

''mcp-huanyu-image'' 是一个基于 MCP (Model Context Protocol) 的图像生成服务器，通过寰宇智联 API 调用 Gemini 模型生成图片。

支持在 Claude Code、Droid、Cline 等 MCP 客户端中，通过自然语言对话直接生成图片并保存到本地。

===== 功能特性 =====

  * 文本生成图像（Text-to-Image）
  * 参考图像生成（Image-to-Image / 垫图）
  * 自动文件保存，支持重名冲突处理
  * 可配置输出格式和尺寸（512px / 1K / 2K / 4K）
  * 支持宽高比控制（1:1、16:9、9:16 等）
  * 支持负面提示词

===== 安装配置 =====

==== 1. 获取 API Key ====

登录 [[https://huanyuf.top|本站]] 后，在令牌页面创建 API Key（格式：''sk-xxxxx''）。

==== 2. 配置 MCP 客户端 ====

在 MCP 配置文件中添加以下内容：

=== Claude Code ===

编辑 ''~/.claude/settings.json''，在 ''mcpServers'' 中添加：

<code json>
{
  "mcpServers": {
    "huanyu-image": {
      "command": "npx",
      "type": "stdio",
      "args": ["-y", "mcp-huanyu-image"],
      "env": {
        "HUANYU_API_KEY": "sk-你的key"
      }
    }
  }
}
</code>

=== Droid (Factory) ===

编辑项目目录下的 ''.factory/mcp.json''：

<code json>
{
  "mcpServers": {
    "huanyu-image": {
      "command": "npx",
      "type": "stdio",
      "args": ["-y", "mcp-huanyu-image"],
      "env": {
        "HUANYU_API_KEY": "sk-你的key"
      }
    }
  }
}
</code>

=== Cline / VS Code ===

在 Cline 插件的 MCP 配置中添加同样的内容。

==== 3. 重启客户端 ====

配置完成后，重启客户端以加载 MCP 插件。

===== 使用示例 =====

==== 基本用法 ====

配置好后，直接在对话里用自然语言描述你想要的图片：

<code>
"生成一张赛博朋克风格的城市夜景，16:9比例，2K分辨率，保存到 D:\images，文件名叫 cybercity"
</code>

AI 会自动调用 ''generate_image'' 工具，图片异步生成后保存到指定目录。

==== 场景速查表 ====

^ 功能 ^ 说明 ^ 示例 ^
| 纯文本生图 | 从零创作 | "生成一个仙侠风格的宝剑图标" |
| 垫图（参考图） | 基于现有图片风格生成 | "参考 D:\icon\剑.png 的风格，生成盾牌图标" |
| 尺寸控制 | 512px / 1K / 2K / 4K | "2K分辨率，16:9比例" |
| 负面提示词 | 排除不想要的元素 | "不要外发光，不要扁平风格" |
| 批量生成 | 同名自动编号 | 重复生成，自动保存为 xxx_1.png, xxx_2.png |

==== 场景一：纯文本生成图像 ====

<code>
对话：生成一张图标，纯色背景，仙侠风格，游戏图标，
      木质令牌上写着"傀儡"两字，毛笔字，
      1:1比例，保存到 D:\icons，文件名：傀儡
</code>

**提示词技巧：**

❌ **差的提示词**：一个傀儡图标

✅ **好的提示词**：国产仙侠游戏图标，古朴木质令牌，金色毛笔字"傀儡"，立体质感，3D渲染，高品质UI

**提示词结构公式：** ''[风格定位] + [主体描述] + [细节补充] + [质量/技术词]''

==== 场景二：使用参考图生成（垫图） ====

<code>
对话：参考 D:\icons\剑.png 的风格，生成一个盾牌图标，
      保持相同的配色和质感，保存为"盾"
</code>

关键点：
  * 提示词要说明"保持参考图的风格"
  * 只描述**不同的部分**
  * 参考图路径必须是**绝对路径**

==== 场景三：控制输出尺寸 ====

^ 参数 ^ 可选值 ^ 说明 ^
| size | ''512px'', ''1K'', ''2K'', ''4K'' | 图像分辨率 |
| aspect_ratio | ''1:1'', ''16:9'', ''9:16'', ''4:3'' 等 | 宽高比 |

常用组合：
  * 游戏图标：1K + 1:1
  * 横版 Banner：2K + 16:9
  * 竖版海报：2K + 9:16

==== 场景四：批量生成多方案 ====

重复生成同名文件时，自动添加数字后缀：

<code>
第一次 → 宝剑.png
第二次 → 宝剑_1.png
第三次 → 宝剑_2.png
</code>

通过微调提示词生成变体：改变配色、材质、角度、氛围等。

===== 环境变量 =====

^ 变量名 ^ 必填 ^ 默认值 ^ 说明 ^
| ''HUANYU_API_KEY'' | 是 | - | 你的 API Key |
| ''HUANYU_BASE_URL'' | 否 | ''https://api.huanyuf.top'' | API 地址 |
| ''HUANYU_IMAGE_MODEL'' | 否 | ''gemini-3.1-flash-image-openai'' | 生图模型 |

===== 常见问题 =====

**Q: 生成的图片在哪里？**

A: 保存在你指定的 ''output_dir'' 目录下，对话中通过自然语言指定即可。

**Q: 支持哪些图片格式？**

A: 默认 PNG，可通过 ''format'' 参数修改。

**Q: 生成超时怎么办？**

A: 默认超时 300 秒。如果超时，重试即可。大尺寸图片（4K）可能需要较长时间。

===== 相关链接 =====

  * [[https://huanyuf.top/|本站 API 控制台（令牌页面）]]
  * [[学习指南:客户端配置:claude_code指南|Claude Code 配置指南]]
  * [[学习指南:客户端配置:droid指南|Droid 配置指南]]