星战科技xingzhan.cloud
返回市场
阿斯佩尔特MCP

阿斯佩尔特MCP

作者：ext-sakamoro10 星标更新：2025-06-21
安装使用来源：spider==github.com

项目介绍

Aseprite MCP Tools v2.0

日语版 | macOS 安装指南

一个强大的Python MCP（模型上下文协议）服务器，用于与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

⚙️ 配置

环境变量

export ASEPRITE_PATH="/Applications/Aseprite.app/Contents/MacOS/aseprite"
export ASEPRITE_MCP_LOG_LEVEL="INFO"

配置文件（config.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）

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

📖 使用示例

基本绘图操作

# 创建一个新的精灵
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改进：增强的错误处理、配置、批处理等

📚 额外资源