Asepritemcp

🚀 Aseprite MCP Tools v2.0

Aseprite MCP Tools v2.0 是一款強大的 Python MCP（模型上下文協議）服務器，用於與 Aseprite 進行編程式交互。它具備增強的錯誤處理、配置管理、批處理等功能！

點擊查看日語版 | macOS 安裝指南

🚀 快速開始

Aseprite MCP Tools v2.0 提供了一系列強大的功能，可幫助你更高效地與 Aseprite 進行交互。你可以創建精靈、添加圖層和幀、繪製各種圖形、管理調色板、批量處理文件等。

✨ 主要特性

v2.0 新增特性

• 🛡️ 全面的錯誤處理：自定義異常，提供詳細且可操作的錯誤信息
• 🔧 配置管理：基於 Pydantic 的設置，支持 JSON/YAML 格式
• 📝 高級日誌記錄：結構化日誌記錄，包含性能指標
• 🎨 調色板管理：創建、應用和提取調色板
• ⚡ 批處理：並行處理多個文件
• 🏗️ Lua 腳本生成器：生成簡潔、類型安全的 Lua 腳本
• 🔒 增強的安全性：輸入驗證和路徑遍歷保護
• 🧪 全面的測試覆蓋：完整的單元測試

核心繪圖工具

• 畫布操作：創建精靈、添加圖層和幀
• 繪圖工具：繪製像素、線條、矩形、圓形和填充操作
• 導出工具：支持多種格式導出，支持縮放和圖層

新調色板工具（v2.0）

• 預設調色板：GameBoy、NES、PICO - 8、CGA、單色、棕褐色
• 自定義調色板：創建和應用自定義配色方案
• 調色板提取：從現有圖像中提取顏色
• 顏色重映射：替換精靈中的顏色

批處理（v2.0）

• 批量調整大小：按比例調整多個精靈的大小
• 批量導出：將多個文件轉換為不同格式
• 批量應用調色板：將調色板應用於多個文件
• 自定義腳本：對文件集運行 Lua 腳本

📦 安裝指南

要求

• Python 3.13+
• Aseprite（需單獨安裝）

Claude 桌面配置

使用 UV（推薦）

{
  "mcpServers": {
    "aseprite": {
      "command": "/opt/homebrew/bin/uv",
      "args": [
        "--directory",
        "/path/to/aseprite-mcp",
        "run",
        "-m",
        "aseprite_mcp"
      ],
      "env": {
        "ASEPRITE_PATH": "/path/to/aseprite"
      }
    }
  }
}

使用 Python

{
  "mcpServers": {
    "aseprite": {
      "command": "python",
      "args": ["-m", "aseprite_mcp"],
      "cwd": "/path/to/aseprite-mcp",
      "env": {
        "ASEPRITE_PATH": "/path/to/aseprite"
      }
    }
  }
}

安裝依賴

pip install -r requirements.txt

💻 使用示例

基礎用法

# 創建一個新的精靈
await create_canvas(320, 240, "my_sprite.aseprite")

# 繪製像素
await draw_pixels("my_sprite.aseprite", [
    {"x": 10, "y": 10, "color": "FF0000"},  # 紅色
    {"x": 11, "y": 10, "color": "00FF00"},  # 綠色
    {"x": 12, "y": 10, "color": "0000FF"}   # 藍色
])

# 繪製圖形
await draw_rectangle("my_sprite.aseprite", 50, 50, 100, 80, "FFFF00", fill=True)
await draw_circle("my_sprite.aseprite", 160, 120, 30, "FF00FF", fill=False)
await draw_line("my_sprite.aseprite", 0, 0, 320, 240, "FFFFFF", thickness=2)

# 填充區域
await fill_area("my_sprite.aseprite", 100, 100, "00FFFF", tolerance=10)

高級用法

圖層和幀管理

# 添加一個新的圖層
await add_layer("my_sprite.aseprite", "Background")

# 添加動畫幀
await add_frame("my_sprite.aseprite", after_frame=0)

調色板操作

# 應用預設調色板
await apply_preset_palette("my_sprite.aseprite", "gameboy")
# 可用預設：gameboy, gameboy-pocket, nes, pico-8, cga, monochrome, sepia

# 創建自定義調色板
await create_palette("my_sprite.aseprite", [
    "264653", "2A9D8F", "E9C46A", "F4A261", "E76F51"
])

# 從圖像中提取調色板
await extract_palette_from_image("reference.png", max_colors=16)

# 獲取調色板信息
await get_palette_info("my_sprite.aseprite")

# 重映射顏色
await remap_colors("my_sprite.aseprite", {
    "FF0000": "00FF00",  # 紅色到綠色
    "0000FF": "FFFF00"   # 藍色到黃色
})

導出操作

# 導出單個文件
await export_sprite("my_sprite.aseprite", "output.png", scale=2.0)

# 按幀範圍導出
await export_sprite("animation.aseprite", "frames.gif", frame_range="1-10")

# 分別導出每個圖層
await export_layers("my_sprite.aseprite", "layers/", format="png")

批處理

# 調整多個精靈的大小
await batch_resize(
    input_dir="sprites/",
    output_dir="sprites_small/",
    scale=0.5,
    file_pattern="*.aseprite"
)

# 批量導出為 PNG
await batch_export(
    input_dir="sprites/",
    output_dir="exports/",
    format="png",
    scale=2.0
)

# 將調色板應用於多個文件
await batch_apply_palette(
    input_dir="sprites/",
    palette_file="my_palette.aseprite",
    create_backup=True
)

# 對多個文件運行自定義 Lua 腳本
await batch_process_custom(
    input_dir="sprites/",
    lua_script="app.activeSprite:flatten()",
    output_dir="flattened/"
)

🔧 技術細節

項目結構

aseprite-mcp/
├── aseprite_mcp/
│   ├── core/
│   │   ├── commands.py      # Aseprite 命令執行
│   │   ├── config.py        # 配置管理
│   │   ├── exceptions.py    # 自定義異常
│   │   ├── logging.py       # 日誌系統
│   │   ├── lua_builder.py   # Lua 腳本生成器
│   │   └── validation.py    # 輸入驗證
│   └── tools/
│       ├── batch.py         # 批處理
│       ├── canvas.py        # 畫布操作
│       ├── drawing.py       # 繪圖工具
│       ├── export.py        # 導出功能
│       └── palette.py       # 調色板管理
├── tests/                   # 單元測試
├── examples/                # 示例腳本
└── config.example.yaml      # 配置示例

錯誤處理

try:
    result = await create_canvas(-100, 200, "test.aseprite")
except ValidationError as e:
    print(f"驗證失敗: {e}")
except AsepriteError as e:
    print(f"Aseprite 錯誤: {e}")

Lua 腳本生成器

from aseprite_mcp.core.lua_builder import LuaBuilder

builder = LuaBuilder()
builder.create_sprite(200, 200)
builder.begin_transaction()
builder.set_color("FF0000")
builder.for_loop("i", 0, 10)
    builder.draw_pixel("i * 10", "i * 10")
builder.end_loop()
builder.end_transaction()
builder.save_sprite("output.aseprite")

script = builder.build()  # 返回簡潔的 Lua 代碼

🧪 測試

運行所有測試：

pytest tests/ -v

運行特定測試：

pytest tests/test_validation.py -v

運行演示腳本：

python examples/demo_improvements.py

📝 日誌記錄

日誌包括：

• 操作跟蹤
• 性能指標
• 錯誤詳情及上下文
• 結構化 JSON 輸出（可選）

示例日誌：

2024-06-11 10:30:45 - aseprite_mcp - INFO - 操作: create_canvas
2024-06-11 10:30:45 - aseprite_mcp - INFO - 畫布創建成功
2024-06-11 10:30:45 - aseprite_mcp - INFO - 性能: create_canvas 耗時 0.234s

🤝 貢獻

1. 分叉倉庫
2. 創建功能分支
3. 遵循編碼標準：
   • 使用類型提示
   • 添加輸入驗證
   • 包含錯誤處理
   • 編寫單元測試
   • 更新文檔
4. 提交拉取請求

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

🙏 致謝

• 原始實現：Divyansh Singh
• v2.0 改進：增強的錯誤處理、配置管理、批處理等

📚 更多資源

• Aseprite API 文檔
• MCP 文檔
• IMPROVEMENTS.md - v2.0 詳細更改說明