README_ja.md•9.68 kB
# Aseprite MCP Tools v2.0
[English version](README.md) | [macOSセットアップガイド](SETUP_MACOS_JA.md)
Asepriteとプログラムで対話するための強力なPython MCP（Model Context Protocol）サーバーです。エラーハンドリング、設定管理、バッチ処理などの機能を強化しました！
## 🚀 v2.0の新機能
- **🛡️ 包括的なエラーハンドリング**: 詳細で実用的なエラーメッセージを持つカスタム例外
- **🔧 設定管理**: JSON/YAMLサポート付きのPydanticベースの設定
- **📝 高度なロギング**: パフォーマンスメトリクスを含む構造化ログ
- **🎨 パレット管理**: カラーパレットの作成、適用、抽出
- **⚡ バッチ処理**: 複数ファイルの並列処理
- **🏗️ Luaスクリプトビルダー**: クリーンで型安全なLuaスクリプト生成
- **🔒 セキュリティ強化**: 入力検証とパストラバーサル保護
- **🧪 完全なテストカバレッジ**: 包括的な単体テスト
## 📋 機能
### コア描画ツール
- **キャンバス操作**: スプライトの作成、レイヤーとフレームの追加
- **描画ツール**: ピクセル、線、矩形、円、塗りつぶし操作
- **エクスポートツール**: スケーリングとレイヤーサポート付きの各種形式へのエクスポート
### 新しいパレットツール (v2.0)
- **プリセットパレット**: GameBoy、NES、PICO-8、CGA、モノクロ、セピア
- **カスタムパレット**: カスタムカラースキームの作成と適用
- **パレット抽出**: 既存の画像から色を抽出
- **色の再マッピング**: スプライト全体の色を置換
### バッチ処理 (v2.0)
- **バッチリサイズ**: アスペクト比を維持しながら複数のスプライトをリサイズ
- **バッチエクスポート**: 複数ファイルを異なる形式に変換
- **バッチパレット適用**: 複数ファイルにパレットを適用
- **カスタムスクリプト**: ファイルセットでLuaスクリプトを実行
## 🔧 インストール
### 必要条件
- Python 3.13以上
- Aseprite（別途インストールが必要）
### Claude Desktop設定
#### UV使用（推奨）
```json
{
"mcpServers": {
"aseprite": {
"command": "/opt/homebrew/bin/uv",
"args": [
"--directory",
"/path/to/aseprite-mcp",
"run",
"-m",
"aseprite_mcp"
],
"env": {
"ASEPRITE_PATH": "/path/to/aseprite"
}
}
}
}
```
#### Python使用
```json
{
"mcpServers": {
"aseprite": {
"command": "python",
"args": ["-m", "aseprite_mcp"],
"cwd": "/path/to/aseprite-mcp",
"env": {
"ASEPRITE_PATH": "/path/to/aseprite"
}
}
}
}
```
### 依存関係のインストール
```bash
pip install -r requirements.txt
```
## ⚙️ 設定
### 環境変数
```bash
export ASEPRITE_PATH="/Applications/Aseprite.app/Contents/MacOS/aseprite"
export ASEPRITE_MCP_LOG_LEVEL="INFO"
```
### 設定ファイル (config.json)
```json
{
"aseprite_path": "/path/to/aseprite",
"canvas": {
"max_width": 10000,
"max_height": 10000
},
"batch": {
"max_parallel_jobs": 4,
"continue_on_error": true
},
"log_level": "INFO",
"security": {
"allowed_directories": ["/home/user/sprites"],
"max_file_size": 104857600
}
}
```
### 設定ファイル (config.yaml)
```yaml
aseprite_path: /path/to/aseprite
canvas:
max_width: 10000
max_height: 10000
default_color_mode: RGBA
batch:
max_parallel_jobs: 4
continue_on_error: true
log_level: INFO
security:
allowed_directories:
- /home/user/sprites
max_file_size: 104857600
```
## 📖 使用例
### 基本的な描画操作
```python
# 新しいスプライトを作成
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)
```
### レイヤーとフレーム管理
```python
# 新しいレイヤーを追加
await add_layer("my_sprite.aseprite", "Background")
# アニメーションフレームを追加
await add_frame("my_sprite.aseprite", after_frame=0)
```
### パレット操作
```python
# プリセットパレットを適用
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" # 青を黄色に
})
```
### エクスポート操作
```python
# 単一ファイルをエクスポート
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")
```
### バッチ処理
```python
# 複数のスプライトをリサイズ
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 # 設定例
```
### エラーハンドリング
```python
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スクリプトビルダー
```python
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コードを返す
```
## 🧪 テスト
全テストを実行:
```bash
pytest tests/ -v
```
特定のテストを実行:
```bash
pytest tests/test_validation.py -v
```
デモスクリプトを実行:
```bash
python examples/demo_improvements.py
```
## 📝 ロギング
ログに含まれる内容:
- 操作追跡
- パフォーマンスメトリクス
- コンテキスト付きエラー詳細
- 構造化JSON出力（オプション）
ログ例:
```
2024-06-11 10:30:45 - aseprite_mcp - INFO - Operation: create_canvas
2024-06-11 10:30:45 - aseprite_mcp - INFO - Canvas created successfully
2024-06-11 10:30:45 - aseprite_mcp - INFO - Performance: create_canvas took 0.234s
```
## 🤝 コントリビューション
1. リポジトリをフォーク
2. 機能ブランチを作成
3. コーディング規約に従う:
- 型ヒントを使用
- 入力検証を追加
- エラーハンドリングを含める
- 単体テストを作成
- ドキュメントを更新
4. プルリクエストを提出
## 📄 ライセンス
MITライセンス - 詳細はLICENSEファイルを参照
## 🙏 クレジット
- オリジナル実装: Divyansh Singh
- v2.0改善: エラーハンドリング、設定、バッチ処理などの強化
## 📚 追加リソース
- [Aseprite APIドキュメント](https://www.aseprite.org/api/)
- [MCPドキュメント](https://modelcontextprotocol.io/)
- [IMPROVEMENTS.md](IMPROVEMENTS.md) - v2.0の詳細な変更点