MCP Animaginexl

🚀 Animagine MCP

Animagine MCP 是一个用于 Animagine XL 4.0 图像生成体验的 FastMCP 服务器，它提供提示验证、优化、解释以及检查点/LoRA 管理工具。

面向 AI 智能体：本仓库的 02-behavior/、03-contracts/、04-quality/ 和 05-implementation/ 目录中包含全面的 Markdown 文档。这些文件包含了详细的规范、行为规则、提示分类法以及为 AI 智能体使用而优化的实现指南。如果你正在构建由 AI 驱动的工作流，或者需要提示工程的结构化指导，请查看这些资源。

面向人类用户：欢迎！以下是一些友好提示：

• 请勿提交 AI 智能体文件（.cursor/、.claude/、.copilot/ 等）——这些文件已包含在 .gitignore 中。
• 在讨论中保持尊重——我们都在这里共同学习和构建。
• 互相帮助——分享你的知识、提出问题并回馈社区。

让我们一起创造出惊人的成果吧！🎨

🚀 快速开始

选择你的接口

接口类型	适用场景	端口
MCP 服务器	Claude Desktop、Cursor 等 MCP 客户端	stdio
REST API	网页应用、命令行工具、移动应用	8000
REPL	交互式测试和开发	stdin/stdout

⚠️ 重要提示

此平台可以生成不适宜内容。选择生成此类内容并拥有生成结果的责任由调用者承担。

选项 1：Docker（推荐）

这是开启 GPU 加速的最快方式。

包含内容

• 自动设置：自动创建目录（checkpoints/、loras/、outputs/）。
• 预下载模型：构建过程中下载 Animagine XL 4.0（约 6GB）。
• GPU 加速：使用 CUDA 12.1 和优化的 PyTorch。
• REST API：在端口 8000 上运行 FastAPI 服务器，并提供交互式文档。

前提条件

• 安装 Docker 和 Docker Compose。
• 安装 NVIDIA GPU 驱动（可使用 nvidia-smi 验证）。
• 安装 NVIDIA 容器工具包（安装指南）。
• 约 15GB 磁盘空间（用于 Docker 镜像和模型）。

步骤

步骤 1：克隆仓库

git clone https://github.com/gabrielalmir/mcp-animaginexl.git
cd mcp-animaginexl

步骤 2：构建并启动容器

docker-compose up -d

⚠️ 重要提示

首次构建会下载 Animagine XL 4.0（约 6GB），根据网络连接情况可能需要 10 - 20 分钟。后续构建将使用缓存层。

步骤 3：验证启动情况（查看日志）

docker-compose logs -f

你应该会看到以下输出：

=== Animagine MCP 启动 ===
检查目录...
  ✓ /app/checkpoints
  ✓ /app/loras
  ✓ /app/outputs
验证 Animagine XL 4.0 模型...
  ✓ 模型已缓存
检查 GPU 状态...
  ✓ GPU 可用：NVIDIA GeForce RTX 3090
  ✓ CUDA 版本：12.1
=== 启动 Animagine MCP 服务器 ===

步骤 4：访问服务

REST API：

• API 文档：http://localhost:8000/docs（Swagger UI）
• 替代文档：http://localhost:8000/redoc（ReDoc）
• 健康检查：curl http://localhost:8000/health

MCP 服务器（适用于 Claude Desktop、Cursor 等）：

• MCP 客户端可使用标准输入输出端点。
• 请参阅 MCP 客户端配置。

常用 Docker 命令

命令	描述
docker-compose up -d	启动服务器
docker-compose down	停止服务器
docker-compose logs -f	查看日志
docker-compose exec animagine-mcp bash	进入容器 shell
docker-compose build --no-cache	从头开始重新构建

环境变量

变量	描述	默认值
SKIP_MODEL_DOWNLOAD	启动时跳过模型验证	false

选项 1b：仅使用 REST API

如果你只想使用 REST API 而不使用 MCP 协议支持，可以执行以下操作：

# 直接运行 API 服务器（需要本地安装 Python 3.11+）
pip install -e .
animagine-api

API 将在 http://localhost:8000 上可用，并在 /docs 提供完整文档。

选项 2：本地安装

适用于开发或没有 Docker 的系统。

前提条件

• Python >= 3.11
• 支持 CUDA 的 GPU（推荐）
• 安装 git 和 pip

步骤

步骤 1：克隆仓库并创建虚拟环境

git clone https://github.com/gabrielalmir/mcp-animaginexl.git
cd mcp-animaginexl
python -m venv .venv

步骤 2：激活虚拟环境

Windows：

.venv\Scripts\activate

Linux/macOS：

source .venv/bin/activate

步骤 3：安装依赖

pip install -e .

步骤 4：启动 MCP 服务器

animagine-mcp

步骤 5：验证服务器是否运行 服务器现在通过 FastMCP 在默认端点上提供工具。

选项 3：交互式 REPL（测试）

无需运行完整服务器即可交互式测试 MCP 工具。

快速开始

# 从项目根目录运行（无需安装）
python repl.py

# 或者如果已安装
animagine-repl

REPL 界面

╔═══════════════════════════════════════════════════════════════════╗
║                    Animagine MCP REPL                             ║
║                  交互式工具测试                                   ║
╠═══════════════════════════════════════════════════════════════════╣
║  命令:                                                           ║
║    help              - 显示帮助信息                               ║
║    tools             - 列出可用工具                               ║
║    tool <name>       - 显示工具详情                               ║
║    exit              - 退出 REPL                                 ║
╚═══════════════════════════════════════════════════════════════════╝

animagine> validate_prompt("1girl, blue hair, masterpiece")
{
  "is_valid": true,
  "issues": [],
  "suggestions": [...]
}

animagine> optimize_prompt(description="anime girl in a garden")
{
  "optimized_prompt": "1girl, solo, garden, flowers, ..., masterpiece, best quality",
  "actions": [...]
}

CLI 选项

python repl.py --list              # 列出所有工具
python repl.py --tool validate     # 显示工具详情
python repl.py -e "list_models()"  # 执行单个命令
python repl.py --debug             # 启用调试模式

MCP 客户端配置

要将 MCP 客户端（如 Claude Desktop、VS Code 或其他 MCP 兼容工具）连接到该服务器，请创建一个 .mcp.json 配置文件。

.mcp.json 示例

本地安装：

{
  "mcpServers": {
    "animagine": {
      "command": "animagine-mcp",
      "env": {}
    }
  }
}

开发环境（从源代码运行）：

{
  "mcpServers": {
    "animagine": {
      "command": "python",
      "args": ["-m", "animagine_mcp.server"],
      "cwd": "/path/to/mcp-animaginexl",
      "env": {
        "PYTHONPATH": "/path/to/mcp-animaginexl/src"
      }
    }
  }
}

Docker 环境：

{
  "mcpServers": {
    "animagine": {
      "command": "docker",
      "args": ["exec", "-i", "animagine-mcp-server", "animagine-mcp"],
      "env": {}
    }
  }
}

Windows 示例：

{
  "mcpServers": {
    "animagine": {
      "command": "python",
      "args": ["-m", "animagine_mcp.server"],
      "cwd": "C:\\Users\\YourName\\Projects\\mcp-animaginexl",
      "env": {
        "PYTHONPATH": "C:\\Users\\YourName\\Projects\\mcp-animaginexl\\src"
      }
    }
  }
}

配置选项

字段	描述
command	要运行的可执行文件（animagine-mcp、python 或 docker）
args	命令行参数
cwd	工作目录（可选）
env	环境变量（可选）

.mcp.json 的放置位置

根据你的 MCP 客户端不同：

• Claude Desktop：~/.config/claude/mcp.json（Linux/Mac）或 %APPDATA%\Claude\mcp.json（Windows）
• VS Code：项目根目录或工作区设置
• 其他客户端：查看客户端文档

✨ 主要特性

Animagine MCP 通过 FastMCP（MCP 协议）和 FastAPI（REST API）提供强大的工具：

• 提示工具：validate_prompt、optimize_prompt、explain_prompt
• 模型工具：list_models、load_checkpoint、unload_loras
• 生成工具：generate_image、generate_image_from_image

主要特点：

• 双 API 支持：AI 智能体可使用 MCP 协议，网页/应用集成可使用 REST API。
• 对提示进行规范化处理，确保结构一致、类别覆盖全面和标签排序合理。
• 与本地检查点和 LoRA 资产集成。
• 支持 CUDA 的 GPU 加速图像生成。
• 支持 Docker，具备全面的 GPU 配置。
• 提供带有 Swagger UI 的交互式 API 文档。

📦 安装指南

根据不同的使用场景，提供了多种安装方式，具体请参考 快速开始 部分。

💻 使用示例

基础用法

示例 1：验证提示

# 在生成前进行验证
result = validate_prompt(
    prompt="1girl, blue hair, school uniform",
    width=832,
    height=1216
)
print(result)  # 显示问题和建议

示例 2：优化自然语言描述

# 将描述转换为优化后的标签
result = optimize_prompt(
    description="A beautiful anime girl with long silver hair standing in a flower field at sunset"
)
print(result["optimized_prompt"])

示例 3：生成图像

# 使用默认设置生成图像
result = generate_image(
    prompt="1girl, silver hair, flower field, sunset, masterpiece, best quality",
    steps=28,
    guidance_scale=5.0
)
print(f"图像保存路径: {result['image_path']}")

示例 4：使用自定义检查点和 LoRA

# 首先列出可用模型
models = list_models()
print(models["checkpoints"])
print(models["loras"])

# 使用自定义模型生成图像
result = generate_image(
    prompt="1girl, anime style, masterpiece",
    checkpoint="custom_model.safetensors",
    loras=["style_lora.safetensors"],
    lora_scales=[0.8]
)

📚 详细文档

REST API

如需完整的 REST API 文档及详细示例，请参阅 API.md。

快速参考

基础 URL：http://localhost:8000/api/v1

交互式文档：http://localhost:8000/docs

常用端点：

• POST /validate-prompt - 验证提示
• POST /optimize-prompt - 优化提示
• POST /explain-prompt - 解释提示标签
• GET /models - 列出可用模型
• POST /load-checkpoint - 加载检查点
• POST /generate - 生成图像
• POST /generate-img2img - 图像转换

示例：通过 REST API 生成图像

curl -X POST http://localhost:8000/api/v1/generate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "masterpiece, best quality, anime girl, blue hair",
    "steps": 28,
    "guidance_scale": 5.0
  }'

🔧 技术细节

GPU 加速

与 CPU 相比，GPU 加速可使生成速度提高 10 - 50 倍。

要求

• NVIDIA GPU（推荐 GTX 1060 或更新型号）
• 安装 CUDA 驱动
• 对于 Docker：安装 NVIDIA 容器运行时

验证 GPU 设置

# 检查 NVIDIA 驱动
nvidia-smi

# 检查 PyTorch GPU 支持（在容器或本地环境中）
python -c "import torch; print(torch.cuda.is_available())"

GPU 性能提示

1. 预加载检查点 以减少首次生成的延迟：

   load_checkpoint("default")  # 预加载 Animagine XL 4.0
   

2. 监控 GPU 使用情况：

   watch -n 1 nvidia-smi
   

3. 优化内存 以处理大型模型：

   # 在环境中设置
   export PYTORCH_CUDA_ALLOC_CONF="max_split_size_mb:512"
   

详细的 GPU 配置请参阅 GPU_SETUP.md。

Docker 配置

提供三种 Docker Compose 配置：

文件	描述	使用场景
docker-compose.yml	启用 GPU（默认）	使用 NVIDIA GPU 的生产环境
docker-compose.gpu.yml	高级 GPU 设置	多 GPU、性能分析
docker-compose.cpu.yml	仅使用 CPU 的备用方案	开发环境，无 GPU

切换配置

# GPU（默认）
docker-compose up -d

# 高级 GPU
docker-compose -f docker-compose.gpu.yml up -d

# 仅使用 CPU
docker-compose -f docker-compose.cpu.yml up -d

自定义端口

编辑 docker-compose.yml：

ports:
  - "8001:8000"  # 将 8001 更改为所需端口

资源限制

deploy:
  resources:
    limits:
      memory: 8G  # 对于大型模型可增加内存限制

完整的 Docker 文档请参阅 DOCKER.md。

模型管理

添加检查点

将 .safetensors 或 .ckpt 文件放置在 ./checkpoints/ 目录中：

cp my_model.safetensors ./checkpoints/

添加 LoRA

将 LoRA 文件放置在 ./loras/ 目录中：

cp my_lora.safetensors ./loras/

验证模型

models = list_models()
print("检查点:", models["checkpoints"])
print("LoRAs:", models["loras"])
print("当前加载的模型:", models["currently_loaded"])

环境变量

变量	描述	默认值
CUDA_VISIBLE_DEVICES	GPU 设备 ID	0
TORCH_CUDNN_BENCHMARK	启用 cuDNN 自动调优	1
PYTORCH_CUDA_ALLOC_CONF	内存分配配置	max_split_size_mb:512
HF_HOME	Hugging Face 缓存目录	~/.cache/huggingface
HF_HUB_DISABLE_TELEMETRY	禁用 HF 遥测	1

设置变量

本地环境：

export CUDA_VISIBLE_DEVICES=0
animagine-mcp

Docker 环境（在 docker-compose.yml 中）：

environment:
  CUDA_VISIBLE_DEVICES: "0,1"  # 使用 GPU 0 和 1

性能优化

根据 GPU 推荐设置

GPU	显存	推荐步数	批量大小
RTX 3060	12GB	28	1
RTX 3080	10GB	28	1
RTX 3090	24GB	28 - 50	1 - 2
RTX 4090	24GB	28 - 50	2 - 4
A100	40GB+	50+	4+

速度与质量权衡

设置	速度	质量
steps=20	快	好
steps=28	平衡	优
steps=50	慢	极佳

使用 LCM LoRA 提高速度

# 使用 LCM 可使生成速度提高 4 - 8 倍
result = generate_image(
    prompt="1girl, masterpiece",
    loras=["custom_lora.safetensors"],
    steps=8,  # 从 28 减少
    guidance_scale=1.5  # 从 5.0 减少
)

📄 许可证

本项目根据 LICENSE 中指定的条款进行许可。

致谢

• Animagine XL 由 Cagliostro Lab 开发
• FastMCP 提供 MCP 框架
• Diffusers 由 Hugging Face 开发
• 所有贡献者和社区成员