内容
# img-gen-mcp
`img-gen-mcp` 是一个本地优先的MCP服务器，用于图像生成、编辑、异步作业、批量运行、背景去除、优化、最终资产交付和可选的ACP风格自动化。
它现在包括工作流感知的图像指导、持久化工作流状态、显式步骤跟踪和可选的ACP HTTP表面，以便迭代图像作业可以在重启后存活并支持完整的自动化流程。
它结合了：
- OpenRouter优先的图像生成
- Kilo Gateway支持
- OpenAI和Gemini图像生成
- 提供商自动选择和模型驱动路由
- 异步任务提交和轮询
- 批量图像生成用于提示扫描和变体
- 通过OpenAI兼容的端点和本地桥接器（适用于MLX、ComfyUI、Draw Things和llama.cpp兼容服务器）进行本地图像生成
- 用于远程部署的Streamable HTTP传输
- MCP上分层的可选ACP风格HTTP自动化路由
- 使用`rmbg`、`imgly`和共享的Docker支持的`withoutbg`守护进程进行本地背景清理
- 使用`sharp`进行网页优化
- 生成前确定性提示增强
## 功能
- `generate_image` 用于OpenRouter优先生成，带有响应归一化
- `kilo_generate_image` 用于Kilo Gateway路由
- 通过`provider=auto`或模型驱动推理进行提供商自动选择
- `list_image_models` 用于提供商/模型发现，带有警告和功能提示
- `get_provider_status` 用于后端就绪性和本地启动指导
- `get_model_capabilities` 用于紧凑的功能摘要
- `edit_image` 用于提示驱动的图像编辑
- OpenAI兼容端点和本地桥接器（如MLX、ComfyUI和Draw Things）的本地提供商支持
- 异步生成工作流的`submit_task`和`get_task`
- `batch_generate_image` 用于一次请求中运行多个提示
- 用于迭代交互式作业的`create_workflow`、`update_workflow`、`get_workflow`和`finalize_workflow`
- 用于显式工作流生命周期跟踪的`add_workflow_step`和`close_workflow_step`
- 用于在重启后继续持久化工作流的`resume_workflow`
- 用于图像支持的后续指导的`analyze_image_result`和`suggest_next_step`
- 用于专业分析帮助的`inspect_cutout`和`compare_variants`
- `background_remove` 用于本地剪切和共享的本地withoutBG守护进程
- `resize_image`和`auto_crop` 用于确定性本地变换
- `optimize_image` 用于网络就绪的重新编码和压缩
- `finalize_image` 用于一次性本地工作流，可以去除背景、修剪、裁剪和调整大小
- 用于后处理质量控制的alpha统计和多背景检查表
- 生成前的提示增强
- 背景去除/最终完成后自动进行网络优化
- 通过`IMAGE_MCP_DEBUG=1`启用调试模式
## 发布说明
- 工作流记录现在持久化到`.image-mcp-workflows.json`并可以在重启后恢复。
- `add_workflow_step`和`close_workflow_step`可用于显式工作流生命周期跟踪。
- `analyze_image_result`和`suggest_next_step`现在检查实际图像文件以获取结构化指导。
## 资产工作流
对于SVG样式的图标、徽标、收藏夹图标和游戏精灵，请使用`docs/public/asset-workflows.md`中内置的资产工作流指导。
这使得存储库对于npm/GitHub用户来说是自包含的，无需他们安装额外的市场技能。
## 安装
```bash
npm install -g img-gen-mcp
```
如果您从本地checkout运行而不是npm，请将MCP客户端指向`node /absolute/path/to/img-gen-mcp/server.js`而不是`npx`。
## 配置
为您的设置使用正确的启动命令：
- 本地checkout：`node /absolute/path/to/img-gen-mcp/server.js`
- 已发布的软件包：`npx -y img-gen-mcp`
- HTTP传输：`npx -y img-gen-mcp http`
在MCP客户端中设置以下环境变量：
- `IMAGE_MCP_DEFAULT_PROVIDER` - 默认提供商（如果未提供）
- `IMAGE_MCP_DEFAULT_MODEL` - 默认模型（如果未提供）
- `IMAGE_MCP_PROJECT_OUTPUT_DIR` - 可选的项目特定输出根目录
- `IMAGE_MCP_DEFAULT_BG_BACKEND` - 默认本地清理后端（`rmbg`、`imgly`或`withoutbg`）
- `WITHOUTBG_DAEMON_URL` - 本地守护进程URL，默认为`http://127.0.0.1:8765`
- `WITHOUTBG_AUTOSTART=1` - 按需自动启动共享的withoutBG Docker守护进程
- `IMAGE_MCP_DEFAULT_BG_ALPHA_THRESHOLD` - 更严格的徽标/标题资产默认掩码
- `IMAGE_MCP_PROMPT_ENHANCE=0` - 禁用确定性提示增强
- `IMAGE_MCP_DEBUG=1` - 包括详细的工具错误和提供商有效载荷
本地模型环境变量：
- `IMAGE_MCP_LOCAL_PROVIDER` - 选择`openai-compatible`、`comfyui`、`drawthings`或`mlx`
- `IMAGE_MCP_LOCAL_ENDPOINT` - 本地HTTP基准URL
- `IMAGE_MCP_LOCAL_MODEL` - 本地模型slug
- `IMAGE_MCP_LOCAL_AUTOSTART=1` - 选择本地服务启动
- `IMAGE_MCP_LOCAL_BOOTSTRAP=1` - 选择引导帮助模式
- `IMAGE_MCP_LOCAL_TIMEOUT_MS` - 本地端点请求超时
- `IMAGE_MCP_LOCAL_API_KEY` - 可选的本地身份验证令牌
传输和运行时标志：
- `IMAGE_MCP_TRANSPORT=http` - 选择Streamable HTTP传输
- `IMAGE_MCP_HTTP_HOST` - HTTP传输的主机，默认为`127.0.0.1`
- `IMAGE_MCP_HTTP_PORT` - HTTP传输的端口，默认为`3333`
- `IMAGE_MCP_ACP=1` - 在HTTP传输上启用可选的ACP风格自动化表面
- `IMAGE_MCP_ACP_PATH` - ACP路由前缀，默认为`/acp`
本地checkout的示例MCP配置：
```jsonc
{
"mcp": {
"img-gen-mcp": {
"type": "local",
"command": ["npx", "-y", "img-gen-mcp"],
"enabled": true,
"environment": {
"IMAGE_MCP_DEFAULT_PROVIDER": "openrouter",
"IMAGE_MCP_DEFAULT_MODEL": "openai/gpt-image-1",
"IMAGE_MCP_DEFAULT_BG_BACKEND": "imgly",
"WITHOUTBG_DAEMON_URL": "http://127.0.0.1:8765",
"WITHOUTBG_AUTOSTART": "1"
}
}
}
}
```
已发布软件包的示例MCP配置：
```jsonc
{
"mcp": {
"img-gen-mcp": {
"type": "local",
"command": ["npx", "-y", "img-gen-mcp"],
"enabled": true,
"environment": {
"IMAGE_MCP_DEFAULT_PROVIDER": "openrouter",
"IMAGE_MCP_DEFAULT_MODEL": "openai/gpt-image-1",
"IMAGE_MCP_DEFAULT_BG_BACKEND": "imgly",
"WITHOUTBG_DAEMON_URL": "http://127.0.0.1:8765",
"WITHOUTBG_AUTOSTART": "1"
}
}
}
}
```
本地示例：
```jsonc
{
"mcp": {
"img-gen-mcp": {
"type": "local",
"command": ["npx", "-y", "img-gen-mcp"],
"enabled": true,
"environment": {
"IMAGE_MCP_LOCAL_PROVIDER": "mlx",
"IMAGE_MCP_LOCAL_ENDPOINT": "http://127.0.0.1:8000/v1",
"IMAGE_MCP_LOCAL_MODEL": "qwen3.5",
"IMAGE_MCP_LOCAL_AUTOSTART": "1"
}
}
}
}
```
有关Kilo、Cursor和通用MCP客户端的现成示例，请参见`docs/public/clients.md`。
## ACP 自动化
`img-gen-mcp` 可以为需要任务和工作流原语以及MCP工具的自动化客户端公开一个可选的ACP风格HTTP表面。
启用它：
```bash
IMAGE_MCP_TRANSPORT=http IMAGE_MCP_ACP=1 npm start
```
路由概述：
- `GET /acp/health`
- `GET /acp/agent`
- `GET /acp/tools`
- `POST /acp/tools/:tool_name`
- `POST /acp/tasks`
- `GET /acp/tasks/:task_id`
- `POST /acp/tasks/:task_id/cancel`
- `POST /acp/workflows`
- `GET /acp/workflows/:workflow_id`
- `POST /acp/workflows/:workflow_id/steps`
- `PATCH /acp/workflows/:workflow_id/steps/:step_id`
- `POST /acp/workflows/:workflow_id/finalize`
ACP层重用相同的MCP工具实现和工作流持久性。MCP仍然是主要协议，而ACP是在其上的可选自动化层。
该软件包在`skills/`下提供了捆绑的技能，以便其他用户可以在安装软件包或浏览存储库时重用相同的工作流指导。
使用`npm run test:acp`在本地测试ACP路由。
## 已发布软件包
软件包版本为`0.11.0`。
发布到GitHub后，您可以通过以下方式手动发布到npm：
```bash
npm publish
```
如果您想在发布前验证发布工件，请运行：
```bash
npm pack --dry-run
```
## 指导
- 当您希望服务器根据模型slug推断后端时，请使用`provider=auto`。
- 对于长时间运行的生成，当您的客户端更喜欢轮询时，请使用`submit_task`。
- 当您希望在不重新配置客户端的情况下获得多个提示变体时，请使用`batch_generate_image`。
- 在排查本地运行时问题之前，请使用`get_provider_status`，这样您可以看到预期的端点和启动提示。
- 当您希望服务器打印已配置的本地适配器的设置指导时，请使用`IMAGE_MCP_LOCAL_BOOTSTRAP=1`。
- 当您希望服务器返回工作流ID和建议的下一步骤而不是在一次工具调用后停止时，请使用工作流工具。
- 使用`npm run test:workflow`运行工作流持久性回归测试。
工作流工具：
- `create_workflow`
- `update_workflow`
- `get_workflow`
- `resume_workflow`
- `finalize_workflow`
- `analyze_image_result`
- `inspect_cutout`
- `compare_variants`
- `suggest_next_step`
## 应用程序模型访问
`img-gen-mcp` 无法直接使用Cursor、Claude Code或Codex内置的图像模型。
它只能使用作为单独提供商或本地HTTP端点公开给它的模型源。
| 客户端 | 直接使用内置应用图像模型？ | 有效方法 |
|---|---|---|
| Cursor | 否 | 将`IMAGE_MCP_LOCAL_ENDPOINT`指向本地图像服务器或桥接器 |
| Claude Code | 否 | 将`IMAGE_MCP_LOCAL_ENDPOINT`指向本地图像服务器或桥接器 |
| Codex | 否 | 将`IMAGE_MCP_LOCAL_ENDPOINT`指向本地图像服务器或桥接器 |
| MLX / 本地服务器 | 是，如果作为端点公开 | 设置`IMAGE_MCP_LOCAL_PROVIDER=mlx`或`openai-compatible` |
如果您想要零云设置，请使用本地后端，如macOS上的MLX-VLM或OpenAI兼容的本地服务器，如llama.cpp、LM Studio、ComfyUI或Draw Things桥接器。
对于本地适配器，该软件包支持显式的`input_mode`、`input_image`和`reference_image`流程，以便图像到图像和编辑工作流可以直接传递文件或URL。
## 工作流程
典型的流程是:
1. 生成图像
2. 如有需要，去除背景
3. 在多个背景上检查剪切结果
4. 为网络优化最终资产
5. 保存并发送最终的PNG/WebP/JPEG/AVIF
对于复杂生成工作，建议采用模型优先的流程：选择模型，让`provider=auto`解析后端，然后使用异步轮询或批量生成，如果您的客户端需要更好的控制。
## 常见用途
- 徽标
- 图标
- 标题艺术
- 产品摄影
- 现实主题剪切
- 透明PNG交付
## 模型
支持的OpenRouter图像模型包括：
- `microsoft/mai-image-2.5`
- `openai/gpt-image-1`
- `openai/gpt-5-image-mini`
- `openai/gpt-5.4-image-2`
- `x-ai/grok-imagine-image-quality`
- `google/gemini-2.5-flash-image`
- `google/gemini-2.5-flash-image-preview`
- `google/gemini-3-pro-image-preview`
- `sourceful/riverflow-v2.5-fast`
- `sourceful/riverflow-v2.5-pro`
- `sourceful/riverflow-v2.5-fast:free`
- `sourceful/riverflow-v2-fast`
- `sourceful/riverflow-v2-pro`
- `recraft/recraft-v4.1-utility`
- `recraft/recraft-v4.1-vector`
- `recraft/recraft-v4.1-utility-pro`
- `recraft/recraft-v4.1-pro-vector`
- `recraft/recraft-v3`
- `black-forest-labs/flux.2-pro`
- `black-forest-labs/flux.2-flex`
推荐默认值：
- 写实作品：`microsoft/mai-image-2.5`或`openai/gpt-image-1`
- 快速风格化作品：`x-ai/grok-imagine-image-quality`
- 徽标/矢量类作品：`recraft/recraft-v4.1-vector`
- 广泛提示遵循的通用用途：`sourceful/riverflow-v2.5-pro`
## 本地后端
- `openai-compatible` 用于任何`/v1`样式的本地服务器
- `mlx` 用于macOS本地模型包装器
- `comfyui` 用于工作流驱动的生成
- `drawthings` 用于运行的macOS应用程序桥接器
- `llama.cpp` 用于轻量级本地OpenAI兼容端点
## 背景去除后端
- `rmbg` - 最快的轻量级本地清理
- `imgly` - 更高质量的本地清理
- `withoutbg` - 共享的Docker支持的本地守护进程，用于更硬的边缘、毛发和透明剪切
启动共享守护进程：
```bash
docker compose -f withoutbg-daemon/docker-compose.yml up -d
```
如果设置了`WITHOUTBG_AUTOSTART=1`，MCP将尝试在需要`backend=withoutbg`时自动启动它。
## 网络优化
`background_remove`和`finalize_image`在清理后会自动运行网络优化传递。
直接使用`optimize_image`时，您可以明确控制：
- PNG用于透明剪切
- WebP用于不透明资产
- JPEG用于平面网页图像
- AVIF用于激进压缩
## 文档
- 公共文档位于`docs/public/`
- Wiki-ready页面位于`docs/wiki/`
- 迁移说明和设置详细信息在发布时记录在那里
- `list_image_models`、`get_provider_status`和`get_model_capabilities`工具在发布面向的API表面中作为文档记录
## 故障排除
- 如果`withoutbg`未运行，请启用`WITHOUTBG_AUTOSTART=1`或手动启动守护进程。
- 如果模型列表看起来不正确，请显式设置`IMAGE_MCP_DEFAULT_MODEL`。
- 如果图像生成失败并出现提供者特定的错误，请在MCP环境中验证提供者API密钥。
- 如果您需要原始响应详细信息，请设置`IMAGE_MCP_DEBUG=1`。
