Animagine MCP

MCP动画引擎

FastMCP服务器 动画引擎XL 4.0 图像生成体验，提供快速验证、优化、解释和检查点/LoRA管理工具。

对于AI代理：此存储库包括全面的markdown文档 02-behavior/, 03-contracts/, 04-quality/，以及 05-implementation/ 目录。这些文件包含针对AI代理消费优化的详细规范、行为规则、提示分类和实现指南。如果你正在构建人工智能驱动的工作流程，或者需要结构化的指导来进行快速工程，请查看这些资源。

对于人类：欢迎！一些友好的提醒： - 不提交AI代理文件 (.cursor/, .claude/, .copilot/等等）——这些已经在里面了 .gitignore - 在讨论中保持尊重 --我们都是来学习和共同建设的 - 互相帮助 --分享你的知识，提出问题，并做出贡献 让我们一起创造奇迹吧！ 🎨

______________________________________________________________________

目录

• 概述
• 快速入门指南

- - 选项1b：仅限REST API - 选项2：本地安装 - 选项3：交互式REPL - MCP客户端配置

• 核心工具
• 使用示例
• REST API
• 高级指南

- GPU加速 - - 模型管理 - 环境变量 - 性能优化

• AI代理资源
• 仓库的规划
• 贡献者指南

- 开发设置 - 代码的风格 - 拉取请求流程 - 测试指南

• 支持
• 许可证

______________________________________________________________________

概述

Animagine MCP通过以下方式展示了强大的工具 FastMCP （MCP协议）和 快速API （REST API）：

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

主要特点：

• 双重API支持：对AI代理使用MCP协议，或对web/应用程序集成使用REST API
• 规范提示，以实现一致的结构、类别覆盖率和标签排序
• 与本地检查点和LoRA资产集成
• GPU加速图像生成，支持CUDA
• Docker就绪，具有全面的GPU配置
• 带有Swagger UI的交互式API文档

选择您的界面

备注：该平台可以生成NSFW材料。选择这样做并拥有由此产生的内容是调用者的责任。

______________________________________________________________________

快速入门指南

选项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 Startup ===
Checking directories...
  ✓ /app/checkpoints
  ✓ /app/loras
  ✓ /app/outputs
Verifying Animagine XL 4.0 model...
  ✓ Model already cached
Checking GPU status...
  ✓ GPU Available: NVIDIA GeForce RTX 3090
  ✓ CUDA Version: 12.1
=== Starting Animagine MCP Server ===

步骤4：访问服务

REST API:

• API文件：http://localhost:8000/docs（Swagger用户界面）
• 备选文件：http://localhost:8000/redoc（ReDoc）
• 健康检查： curl http://localhost:8000/health

MCP服务器 （适用于克劳德桌面、光标等）：

• MCP客户端可用的Stdio端点
• 看 MCP客户端配置

快速Docker命令

环境变量

看 医生.md 供完整配置参考 用于将MCP客户端连接到Docker容器。

______________________________________________________________________

选项1b：仅限REST API

如果您只想在不支持MCP协议的情况下使用REST API：

# Run the API server directly (requires local 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：激活虚拟环境

窗户：

.venv\Scripts\activate

Linux/macOS：

source .venv/bin/activate

步骤3：安装依赖项

pip install -e .

步骤4：启动MCP服务器

animagine-mcp

步骤5：验证它是否正在运行

服务器现在通过默认端点上的FastMCP公开工具。

______________________________________________________________________

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

在不运行完整服务器的情况下以交互方式测试MCP工具。

快速开始

# From project root (no installation needed)
python repl.py

# Or if installed
animagine-repl

REPL接口

╔═══════════════════════════════════════════════════════════════════╗
║                    Animagine MCP REPL                             ║
║                  Interactive Tool Testing                         ║
╠═══════════════════════════════════════════════════════════════════╣
║  Commands:                                                        ║
║    help              - Show help message                          ║
║    tools             - List available tools                       ║
║    tool        - Show tool details                          ║
║    exit              - Exit the 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              # List all tools
python repl.py --tool validate     # Show tool details
python repl.py -e "list_models()"  # Execute single command
python repl.py --debug             # Enable debug mode

______________________________________________________________________

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"
      }
    }
  }
}

配置选项

地点 .mcp.json

根据您的MCP客户：

• 克劳德桌面版: ~/.config/claude/mcp.json （Linux/Mac）或 %APPDATA%\Claude\mcp.json （Windows）
• VS Code：项目根目录或工作区设置
• 其他客户：检查客户文件

______________________________________________________________________

核心工具

同样强大的工具可以通过以下方式获得 两者 MCP协议和REST API：

提示工具

模型工具

生成工具

使用REST API

有关REST API的详细文档，请参阅 API毫米 其中包括：

• 完整端点参考
• 请求/响应示例
• cURL示例
• Python客户端示例
• 性能调优指南

快速开始:

# List available models
curl http://localhost:8000/api/v1/models

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

# Interactive documentation
open http://localhost:8000/docs

______________________________________________________________________

使用示例

示例1：验证提示

# Validate before generation
result = validate_prompt(
    prompt="1girl, blue hair, school uniform",
    width=832,
    height=1216
)
print(result)  # Shows issues and suggestions

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

# Convert description to optimized tags
result = optimize_prompt(
    description="A beautiful anime girl with long silver hair standing in a flower field at sunset"
)
print(result["optimized_prompt"])

示例3：生成图像

# Generate with default settings
result = generate_image(
    prompt="1girl, silver hair, flower field, sunset, masterpiece, best quality",
    steps=28,
    guidance_scale=5.0
)
print(f"Image saved to: {result['image_path']}")

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

# List available models first
models = list_models()
print(models["checkpoints"])
print(models["loras"])

# Generate with custom models
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毫米.

快速参考

基础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加速

GPU加速提供 速度快10-50倍 与CPU相比。

需求

• NVIDIA GPU（建议使用GTX 1060或更高版本）
• 已安装CUDA驱动程序
• 适用于Docker：NVIDIA容器运行时

验证GPU设置

# Check NVIDIA driver
nvidia-smi

# Check PyTorch GPU support (in container or local env)
python -c "import torch; print(torch.cuda.is_available())"

GPU性能提示

1. 预加载检查点 为了减少第一代延迟：

   load_checkpoint("default")  # Pre-loads Animagine XL 4.0

1. 监控GPU使用情况 在生成过程中：

   watch -n 1 nvidia-smi

1. 优化内存 对于大型型号：

   # Set in environment
   export PYTORCH_CUDA_ALLOC_CONF="max_split_size_mb:512"

看 GPU_SETUP.md 以获取详细的GPU配置。

______________________________________________________________________

Docker配置

有三种Docker Compose配置可供选择：

切换配置

# GPU (default)
docker-compose up -d

# Advanced GPU
docker-compose -f docker-compose.gpu.yml up -d

# CPU-only
docker-compose -f docker-compose.cpu.yml up -d

自定义端口

编辑 docker-compose.yml:

ports:
  - "8001:8000"  # Change 8001 to desired port

资源限制

deploy:
  resources:
    limits:
      memory: 8G  # Increase for larger models

看 医生.md 获取全面的Docker文档。

______________________________________________________________________

模型管理

添加检查点

地方 .safetensors 或 .ckpt 文件在 ./checkpoints/:

cp my_model.safetensors ./checkpoints/

添加LoRA

将LoRA文件放入 ./loras/:

cp my_lora.safetensors ./loras/

验证模型

models = list_models()
print("Checkpoints:", models["checkpoints"])
print("LoRAs:", models["loras"])
print("Currently loaded:", models["currently_loaded"])

______________________________________________________________________

环境变量

设置变量

当地：

export CUDA_VISIBLE_DEVICES=0
animagine-mcp

Docker（in docker-compose.yml):

environment:
  CUDA_VISIBLE_DEVICES: "0,1"  # Use GPUs 0 and 1

______________________________________________________________________

性能优化

GPU推荐设置

速度与质量的权衡

使用LCM-LoRA提高速度

# 4-8x faster generation with LCM
result = generate_image(
    prompt="1girl, masterpiece",
    loras=["custom_lora.safetensors"],
    steps=8,  # Reduced from 28
    guidance_scale=1.5  # Reduced from 5.0
)

______________________________________________________________________

AI代理资源

该存储库包括针对AI代理和自动化工作流程优化的全面文档。

文档结构

面向AI代理开发人员

这些资源旨在用于：

• 提示工程：Animagine XL 4.0提示的详细分类和规则
• 自动化管道：与CI/CD或批处理集成的结构化合同
• 质量保证：评价标准和负面提示策略
• MCP集成：用于构建MCP兼容客户端的接口规范

快速链接

# View behavior specifications
cat 02-behavior/model-behavior-spec.md

# View prompt rules and taxonomy
cat 02-behavior/prompt-rulebook.md
cat 02-behavior/prompt-taxonomy.yaml

# View MCP interface contract
cat 03-contracts/mcp-interface-contract.md

# View quality guidelines
cat 04-quality/prompt-cookbook.md

与AI编码助手一起使用

使用AI编码助手（Claude、Cursor、Copilot等）时，您可以参考以下文档：

"Read 02-behavior/prompt-rulebook.md and help me create a valid Animagine prompt"
"Based on 03-contracts/mcp-interface-contract.md, implement a client for this MCP"
"Use 04-quality/negative-prompt-strategy.md to improve my negative prompts"

______________________________________________________________________

仓库的规划

mcp-animaginexl/
├── src/animagine_mcp/          # Core package
│   ├── contracts/              # Data schemas and errors
│   ├── diffusion/              # Diffusion pipeline wrapper
│   ├── prompt/                 # Prompt processing tools
│   ├── server.py               # FastMCP server definition
│   └── repl.py                 # Interactive REPL module
├── checkpoints/                # Model checkpoints (.safetensors) [auto-created]
├── loras/                      # LoRA modifiers [auto-created]
├── outputs/                    # Generated images [auto-created]
├── 02-behavior/                # Behavior specifications
├── 03-contracts/               # Interface contracts
├── 04-quality/                 # Quality guidelines
├── 05-implementation/          # Implementation notes
├── .mcp.json.example           # MCP client config template
├── Dockerfile                  # GPU-optimized container
├── docker-entrypoint.sh        # Container startup script
├── docker-compose.yml          # Default GPU config
├── docker-compose.gpu.yml      # Advanced GPU config
├── docker-compose.cpu.yml      # CPU-only fallback
├── repl.py                     # Interactive REPL (run directly)
├── pyproject.toml              # Project metadata
└── README.md                   # This file

______________________________________________________________________

贡献者指南

我们欢迎捐款！以下是如何开始。

开发设置

第一步：分叉和克隆

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

步骤2：创建开发环境

python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

步骤3：使用开发依赖项进行安装

pip install -e ".[dev]"

步骤4：创建特征分支

git checkout -b feature/your-feature-name

______________________________________________________________________

代码的风格

我们遵循这些惯例：

Python风格

• 格式化器: black 使用默认设置
• 代码检查工具: ruff 用于快速脱毛
• 键入提示：所有公共活动都需要
• 文档字符串：所有公共API均采用谷歌风格

运行格式化

# Format code
black src/

# Lint code
ruff check src/

# Fix auto-fixable issues
ruff check --fix src/

预承诺（推荐）

# Install pre-commit hooks
pip install pre-commit
pre-commit install

# Run on all files
pre-commit run --all-files

______________________________________________________________________

拉取请求流程

1.提交前

• \[\]代码遵循样式指南
• \[\]本地测试通过
• \[\]文件已更新（如适用）
• \[\]提交消息清晰且具有描述性

2.PR模板

使用此模板进行PR描述：

## Summary
Brief description of changes.

## Changes
- Change 1
- Change 2

## Testing
How was this tested?

## Related Issues
Fixes #123

3.审查过程

1. 将PR提交至 main 分支
2. 自动检查运行（抽检、测试）
3. 维护人员审查代码
4. 处理反馈（如有）
5. PR批准后合并

4.提交消息格式

type: short description

Longer description if needed.

Fixes #123

类型： feat, fix, docs, style, refactor, test, chore

示例：

feat: add batch generation support
fix: resolve CUDA OOM error with large images
docs: update GPU setup instructions

______________________________________________________________________

测试指南

运行测试

# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=src/animagine_mcp

# Run specific test file
pytest tests/test_prompt.py

写作测试

# tests/test_prompt.py
import pytest
from animagine_mcp.prompt import validate_prompt

def test_validate_prompt_basic():
    """Test basic prompt validation."""
    result = validate_prompt("1girl, blue hair, masterpiece")
    assert result.is_valid
    assert len(result.issues) == 0

def test_validate_prompt_missing_quality():
    """Test validation catches missing quality tags."""
    result = validate_prompt("1girl, blue hair")
    assert not result.is_valid
    assert any("quality" in issue.lower() for issue in result.issues)

测试类别

______________________________________________________________________

贡献领域

在找工作吗？以下是一些领域：

好的第一个问题

• 文档改进
• 增加测试覆盖率
• 修正拼写错误或澄清评论

特色创意

• 其他快速优化策略
• 新的LoRA管理功能
• 性能基准测试工具
• Web UI前端

文档

• 特定用例教程
• 视频演练
• 翻译文件

______________________________________________________________________

支持

获取帮助

1. 检查现有问题：搜索
2. 阅读文档：检查 DOCKER.md, GPU_SETUP.md，以及此README
3. 打开新问题：包括：

- 问题描述 - 重现步骤 - 预期行为与实际行为 - 系统信息（操作系统、GPU、Python版本） - 相关日志（忽略敏感内容）

社区

• GitHub问题讨论
• 错误和功能请求问题

______________________________________________________________________

许可证

本项目根据以下条款获得许可 许可证.

______________________________________________________________________

致谢

• 动画XL 通过Cagliostro实验室
• FastMCP 对于MCP框架
• 扩散器 通过拥抱脸
• 所有贡献者和社区成员