Asepritemcp

🚀 Aseprite MCP Tools v2.0

このツールは、Asepriteとのプログラムによる対話を行うための強力なPython MCP（Model Context Protocol）サーバーです。エラーハンドリングの強化、設定管理、バッチ処理などの機能を備えています！

日本語版はこちら | macOS Setup Guide

🚀 クイックスタート

Aseprite MCP Tools v2.0は、Asepriteとのプログラムによる対話を可能にする強力なツールです。エラーハンドリングや設定管理、バッチ処理など、多くの機能が強化されています。

✨ 主な機能

2.0の新機能

• 🛡️ 包括的なエラーハンドリング：詳細で実行可能なエラーメッセージを持つカスタム例外
• 🔧 設定管理：JSON/YAMLをサポートするPydanticベースの設定
• 📝 高度なロギング：パフォーマンスメトリクスを含む構造化ロギング
• 🎨 パレット管理：カラーパレットの作成、適用、抽出
• ⚡ バッチ処理：複数のファイルを並列に処理
• 🏗️ Luaスクリプトビルダー：クリーンで型安全なLuaスクリプトの生成
• 🔒 強化されたセキュリティ：入力検証とパストラバーサル保護
• 🧪 完全なテストカバレッジ：包括的な単体テスト

主な機能

コア描画ツール

• キャンバス操作：スプライトの作成、レイヤーとフレームの追加
• 描画ツール：ピクセル、線、矩形、円、塗りつぶし操作
• エクスポートツール：スケーリングとレイヤーサポートを持つ様々な形式へのエクスポート

新しいパレットツール (v2.0)

• プリセットパレット：GameBoy、NES、PICO - 8、CGA、モノクロ、セピア
• カスタムパレット：カスタムカラースキームの作成と適用
• パレット抽出：既存の画像から色を抽出
• 色の再マッピング：スプライト全体で色を置き換え

バッチ処理 (v2.0)

• バッチリサイズ：アスペクト比を維持したまま複数のスプライトをリサイズ
• バッチエクスポート：複数のファイルを異なる形式に変換
• バッチパレット適用：複数のファイルにパレットを適用
• カスタムスクリプト：ファイルセットに対してLuaスクリプトを実行

📦 インストール

必要条件

• Python 3.13+
• Aseprite（別途インストールする必要があります）

Claude Desktopの設定

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.234秒かかりました

🤝 コントリビュート方法

1. リポジトリをフォークする
2. 機能ブランチを作成する
3. コーディング規約に従う：
   • 型ヒントを使用する
   • 入力検証を追加する
   • エラーハンドリングを含める
   • 単体テストを書く
   • ドキュメントを更新する
4. プルリクエストを提出する

📄 ライセンス

MITライセンス - 詳細はLICENSEファイルを参照してください

🙏 クレジット

• オリジナルの実装: Divyansh Singh
• v2.0の改良: エラーハンドリング、設定、バッチ処理などの強化

📚 追加リソース

• Aseprite API Documentation
• MCP Documentation
• IMPROVEMENTS.md - v2.0の詳細な変更点