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 開發
• 所有貢獻者和社區成員