内容
# 宇宙想象 MCP
用于 AI 图像生成的 MCP 服务器。包装本地 ComfyUI 作为可流式传输的 HTTP MCP 服务器。与任何兼容 MCP 的机器人客户端配合使用。
## 功能
- **可流式传输的 HTTP** — MCP `2024-11-05` 协议，带有 Bearer 认证
- **同步生成** — `generate_image` 阻塞并直接返回图像 URL
- **后台队列** — 接受多个请求，一次处理一个
- **幂等键** — 安全重试，无重复
- **玩家感知** — 从 MCP 初始化握手读取 `player_id`
- **生成历史** — SQLite，带有 `since` 过滤器用于增量查询
- **健康端点** — 报告后端状态、队列深度、运行时间
- **图像服务** — 用于生成图像的内置静态文件服务器
- **空闲看门狗** — 5 分钟不活动后停止 ComfyUI 以释放 VRAM
- **温暖启动** — MCP 服务器启动时，ComfyUI 在后台启动
- **Discord webhook** — 可选的生成通知
## 先决条件
- Python 3.11+
- [ComfyUI](https://github.com/comfyanonymous/ComfyUI) 已本地安装
- 至少下载了一个模型（例如 Flux、SDXL、SD3 等）
## 设置
```bash
# 1. 克隆仓库
git clone https://github.com/BAWES-Universe/universe-imagine-mcp.git
cd universe-imagine-mcp
# 2. 创建虚拟环境
python3 -m venv .venv
source .venv/bin/activate
# 3. 安装依赖
pip install -r requirements.txt
# 4. 配置
cp .env.example .env
# 编辑 .env — 至少设置 DESIGNER_MCP_TOKEN 和 PUBLIC_URL_BASE
# 设置 MODEL_UNET、MODEL_CLIP、MODEL_VAE 以匹配您的 ComfyUI 模型
# 5. 运行
python3 designer_mcp.py
```
## 配置
所有配置都在 `.env` 中：
| 变量 | 默认值 | 描述 |
| --- | --- | --- |
| `DESIGNER_MCP_TOKEN` | — | MCP 认证的 Bearer Token（必填） |
| `PUBLIC_URL_BASE` | — | 图像服务的公共基准 URL（必填） |
| `HOST` | `0.0.0.0` | 监听地址 |
| `PORT` | `8003` | MCP 服务器端口 |
| `COMFYUI_URL` | `http://127.0.0.1:8188` | ComfyUI API URL |
| `COMFYUI_DIR` | `~/ComfyUI` | ComfyUI 安装目录 |
| `DB_PATH` | `./imagine.db` | SQLite 数据库路径 |
| `OUTPUT_DIR` | `~/ComfyUI/output` | ComfyUI 输出目录 |
| `DISCORD_WEBHOOK_URL` | — | Discord webhook，用于生成通知（可选） |
| `MODEL_UNET` | `flux-2-klein-4b-fp8.safetensors` | UNet 模型文件名 |
| `MODEL_CLIP` | `Qwen3-4B-Q4_K_M.gguf` | CLIP 模型文件名 |
| `MODEL_VAE` | `flux2_klein_vae.safetensors` | VAE 模型文件名 |
## 工具
### `generate_image(prompt, width=512, height=512, idempotency_key="")` → JSON
根据文本提示生成图像。阻塞直到完成（通常 3-15 秒）并直接返回图像 URL。图像由机器人自动发送到对话中。
使用 `idempotency_key` 安全重试，无重复 — 相同键 = 缓存结果。
### `get_generation(generation_id)` → JSON
通过 ID 检索过去生成的完整记录。
### `list_generations(limit=10, since="")` → JSON 数组
列出调用玩家的最近生成。可选地按 ISO 8601 时间戳过滤。
### `get_generation_status(generation_id)` → JSON（旧版）
旧版轮询工具，为保持向后兼容性而保留。当前的 `generate_image` 是同步的，直接返回 URL — 不需要轮询。
## DNS 绑定 — 猴子补丁
服务器包含对 FastMCP 内置 DNS 绑定检查的猴子补丁（参见 `designer_mcp.py` 第 23-33 行）。在通过反向代理或 Cloudflare 隧道运行时需要此补丁，其中传入的 `Host` 头（例如 `imagine.yourdomain.com`）与 `localhost` 不匹配。
**如果您在反向代理后面运行：** 补丁是安全的，因为认证由 `BearerAuthMiddleware` 处理。保留它。
**如果您仅在本地运行（无隧道/代理）：** 完全删除补丁 — 从 `designer_mcp.py` 中删除第 23-33 行。
补丁：
```python
from mcp.server.transport_security import TransportSecurityMiddleware
_orig_validate = TransportSecurityMiddleware.validate_request
async def _patched_validate(self, request, is_post=False):
return None # 跳过 Host 头验证
TransportSecurityMiddleware.validate_request = _patched_validate
```
## 连接到宇宙机器人
通过管理员 API 在机器人上注册 MCP 服务器：
```json
POST /api/bots/{botId}/mcp-servers
{
"serverUrl": "https://your-domain.com/mcp",
"transport": "streamable-http",
"authType": "bearer",
"authConfig": "your-token"
}
```
玩家 ID 在 MCP 初始化握手过程中自动发送 — 无需额外配置。
## 架构
```
┌─────────────┐ 可流式传输的 HTTP ┌──────────────────┐
│ 机器人 AI │ ◄─────────────────────── │ 想象 MCP │
│ （MCP 客户端）│ /mcp（端口 8003） │ （FastMCP） │
└─────────────┘ │ │
│ ┌────────────┐ │
┌─────────────┐ 静态文件 │ │ 队列（1） │──┼──► _run_generation()
│ 浏览器 │ ◄─────────────────────── │ └────────────┘ │
│ /images/* │ /images（端口 8004） │ │ │
└─────────────┘ │ ▼ │
│ ┌────────────┐ │
curl /health │ │ ComfyUI │ │
─────────► /health（端口 8005） │ │ （端口 8188）│ │
│ └────────────┘ │
└──────────────────┘
```
## 许可证
MIT
