内容
# ComfyMCP 工作室
ComfyMCP 工作室是一个用于使用 AI 工作流生成 2D 游戏资产的 MCP（模型上下文协议）服务器，由 ComfyUI 提供支持。
## 您将获得
- **基于 ComfyUI 的生成**
- 生产质量的 SDXL/SD1.5 工作流
- **默认高质量输出**
- 在预设分辨率（SDXL 原生）下渲染，然后缩小以获得更清晰的细节
- **一致的角色动画（img2img）**
- 从单个参考图像生成多个姿势
- **使用 ControlNet 的视点控制（俯视 / 侧视 / 前视 / 3/4 视）**
- 生成具有更强相机角度一致性的俯视资产
- **常见游戏风格的预设**
- 图标、角色、图块集、俯视预设、像素预设
- **后处理**
- 调整大小、移除背景、添加轮廓
- **Unity 导出 + 批量生成**
## 要求
- **Python**: 3.10+
- **ComfyUI**: 在本地运行（默认 `127.0.0.1:8188`）
- **Stable Diffusion 检查点**
- 推荐 SDXL（默认配置：`sd_xl_base_1.0.safetensors`）
- **（可选）ControlNet 模型**
- 仅在 `generate_with_viewpoint` / `generate_topdown_asset` 中需要
## 安装
```bash
# 导航到项目
cd path/ComfyAI-MCP-GameAssets
# 创建虚拟环境
python -m venv venv
venv\Scripts\activate
# 安装依赖项
pip install -r requirements.txt
```
## 配置
复制 `.env.example` 到 `.env` 并配置：
```env
BACKEND_TYPE=comfyui
COMFYUI_HOST=127.0.0.1
COMFYUI_PORT=8188
COMFYUI_CHECKPOINT=sd_xl_base_1.0.safetensors
OUTPUT_DIR=./output
UNITY_ASSETS_DIR=C:/Projects/MyGame/Assets
```
## ComfyUI 设置
- **启动 ComfyUI**（示例）：
```bash
python main.py --listen 0.0.0.0 --port 8188
```
- **检查点**
- 确保您的检查点存在于 ComfyUI 中（示例：`ComfyUI/models/checkpoints/`）。
- 此服务器从 `.env` 读取 `COMFYUI_CHECKPOINT`。
## ControlNet 设置（用于视点锁定）
如果您使用视点工具，则必须在以下路径安装 ControlNet 模型：
`ComfyUI/models/controlnet/`
- **SDXL 深度模型（示例）**
- `diffusers_xl_depth_full.safetensors`
在添加模型后重启 ComfyUI。
如果您在调用 `/prompt` 时看到 `HTTP 400 Bad Request`，通常意味着：
- `controlnet_model` 名称错误，或者
- ControlNet 节点/模型未安装/不可用。
## 作为 MCP 服务器运行（Windsurf）
将以下内容添加到您的 MCP 设置中（或从 `mcp_config.json` 复制）：
```json
{
"mcpServers": {
"comfymcp-studio": {
"command": "python",
"args": ["-m", "server.main"],
"cwd": "path/ComfyAI-MCP-GameAssets",
"env": {
"BACKEND_TYPE": "comfyui",
"COMFYUI_HOST": "127.0.0.1",
"COMFYUI_PORT": "8188"
}
}
}
}
```
## 工具
- **`ping`** - 后端健康检查
- **`list_available_presets`** - 列出预设名称 + 配置
- **`generate_sprite`** - 根据提示生成单个图像
- **`generate_icons`** - 批量图标 + 可选图集
- **`generate_tileset`** - 按主题生成可平铺的图块
- **`generate_character`** - 角色生成（基于提示）
- **`generate_character_animations`** - 从参考图像生成 img2img 多姿势动画
- **`generate_with_viewpoint`** - ControlNet 深度引导生成，用于稳定的相机角度
- **`generate_topdown_asset`** - 顶视图资产的便捷包装器（道具、角色、生物、图块、效果）
- **`process_image`** - 调整大小 / 移除背景 / 添加轮廓
- **`create_sprite_atlas`** - 将图像合并到精灵表中
- **`export_to_unity`** - 将输出 PNG 导出到 Unity 项目文件夹
- **`batch_generate`** - 使用提示批量生成
## 预设
您可以通过 `list_available_presets` 列出预设。
### 通用
- **`default`** - 通用游戏资产
- **`icon`** / **`icon_item`** - 游戏图标
- **`character`** / **`character_portrait`** - 角色精灵
- **`tileset`** - 无缝可平铺的纹理
- **`environment`** - 背景/环境艺术
- **`prop`** - 游戏道具（3/4 视）
### 俯视（ControlNet）
- **`topdown_prop`** - 俯视道具
- **`topdown_character`** - 俯视角色
- **`topdown_creature`** - 俯视生物/敌人
- **`topdown_tile`** - 俯视图块
### 效果和 UI
- **`effect`** / **`magic_effect`** - VFX 和法术效果
- **`ui_button`** / **`ui_frame`** - UI 元素
### 生物
- **`creature`** - 幻想生物/怪物
### 特定风格
- **`handpainted`** - 手绘艺术风格
- **`flat_ui`** - 平面设计 UI
- **`isometric`** - 等距游戏资产
- **`pixel_art`** / **`pixel_character`** - 像素艺术风格
- **`pixel_16`** / **`pixel_32`** / **`pixel_64`** - 特定像素大小
## 测试
### 快速烟雾测试
```bash
python test_generate.py --list-presets
python test_generate.py --preset icon --size 256 --steps 20 --seed 42 --save
```
### ControlNet 视点测试
```bash
# 俯视道具（深度 ControlNet）
python test_controlnet.py --tests prop --size 512 --strength 0.95 --save
# 俯视角色（包装器工具）
python test_controlnet.py --tests character --size 512 --strength 1.0 --save
# 同一对象的多视角
python test_controlnet.py --tests multi --views topdown,side,front,3/4 --size 512 --strength 0.90 --save
```
### 角色动画测试（img2img）
```bash
# 需要本地参考图像
python test_character_animation.py --ref path\\to\\reference.png --poses idle,walking,attacking --denoise 0.35 --seed 42 --save
```
## 输出
生成的图像在调用 `save_to_file=true` 的工具时保存在 `OUTPUT_DIR` 下。
典型的文件夹：
- **`output/controlnet/`**
- **`output/icons/`**
- **`output/characters/`**
- **`output/tilesets/`**
## 故障排除
- **`HTTP 400 Bad Request` 来自 ComfyUI `/prompt`**
- 检查 ControlNet 模型文件是否存在于 `ComfyUI/models/controlnet/`
- 验证作为 `controlnet_model` 传递的文件名
- 在安装模型后重启 ComfyUI
- **结果仍然不是俯视**
- 增加 `control_strength`（尝试 `0.90` 到 `1.0`）
- 使用 `preset=topdown_character/topdown_prop`
- **重复/分散的武器/盔甲**
- 在提示中添加明确的约束：`单个角色`、`一把剑`、`一个盾牌`
## 许可证
MIT
