Metadata-Version: 2.5
Name: aseprite-mcp
Version: 0.4.1
Summary: Aseprite MCP with explicit CLI and live backend contracts
Author-email: greenlogs <tryz189853302550@gmail.com>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.13
Requires-Dist: httpx>=0.28.1
Requires-Dist: mcp[cli]>=1.6.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: pydantic<3,>=2.11
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: twine>=7.0.0
Requires-Dist: websockets<16,>=15
Description-Content-Type: text/markdown

<div align="center">

# Aseprite MCP

**让 AI 成为你的像素画创作搭档**

通过 Model Context Protocol，在 Aseprite 中与 AI 一起绘制、修改和预览像素画。

**中文** · [English](README.en.md)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python: 3.13+](https://img.shields.io/badge/Python-3.13%2B-blue.svg)](pyproject.toml)

</div>

---

Aseprite MCP 将支持 MCP 的 AI 客户端与 Aseprite 连接起来。你可以用自然语言描述修改，让 AI 直接编辑当前文档并查看图片反馈，再接着手动创作——包括尚未保存的画布。

基于 [diivi/aseprite-mcp](https://github.com/diivi/aseprite-mcp) 改造，新增 Lua 实时扩展，同时保留上游 CLI 文件工具。

> 当前版本为 **0.4.1 TestPyPI 测试版**。已在 Windows + Aseprite 1.3.7 / API 28 完成真实验证，[最近一次完整回归](docs/progress/P3-M2.md)为 208 项通过。macOS、Linux 和其他 Aseprite 版本尚待验证。

## 快速开始

### 1. 准备服务与扩展

需要自行安装的 **Aseprite 1.3.7 / API 28**、**Python 3.13+**、[uv](https://docs.astral.sh/uv/getting-started/installation/) 和支持 stdio 的 MCP 客户端。

获取本项目源码后，在项目根目录运行：

```powershell
uv sync --locked --python 3.13
uv run --locked python scripts/build_release.py --out-dir dist
```

### 2. 安装 Aseprite 扩展

在 **Edit → Preferences → Extensions → Add Extension** 中选择生成的 `dist/aseprite-mcp-live-0.4.1.aseprite-extension`，安装并启用，然后重启 Aseprite。

### 3. 配置 MCP 客户端

下面是采用 `mcpServers` 格式的客户端配置示例。将 `C:/path/to/aseprite-mcp` 替换为项目的绝对路径；其他客户端使用对应的 stdio 配置格式。

```json
{
  "mcpServers": {
    "aseprite": {
      "command": "uv",
      "args": [
        "--directory", "C:/path/to/aseprite-mcp",
        "run", "--locked", "aseprite-mcp"
      ],
      "env": {
        "ASEPRITE_MCP_TOOL_PROFILE": "core"
      }
    }
  }
}
```

重启客户端，打开 Aseprite，按首次权限提示允许扩展使用本机 WebSocket。默认自动连接 `127.0.0.1:8765`，无需选择连接文件。

试着对 AI 说：**“查看当前打开的画布，告诉我有哪些图层，并显示预览。”**

<details>
<summary><b>独立安装、端口设置与连接诊断</b></summary>

- 不依赖源码目录的 wheel 安装、`ASEPRITE_PATH` 配置和手动扩展安装见 [Windows 安装说明](docs/INSTALL.md)。
- 服务由 MCP 客户端启动；同一端口只运行一份服务。客户端找不到 `uv` 时，用 `Get-Command uv` 查询其绝对路径。
- 在 **File → Scripts → MCP: Connect / Settings** 查看连接状态或修改端口。服务参数 `--port` 必须与扩展设置一致。
- 升级时同时更新服务和扩展；详细步骤见[安装与升级](docs/INSTALL.md)。

</details>

## 功能

| 功能 | 你可以做什么 |
|---|---|
| **实时协作** | 读取、编辑已经打开的文档，包括未保存画布，继续与 AI 交替创作 |
| **像素与图层** | 新建 RGB 画布、添加普通图层、调整不透明度、批量绘制像素和矩形 |
| **图片反馈** | 将画布预览作为 PNG 图片直接返回给支持图片内容的 MCP 客户端 |
| **撤销与重做** | 一个编辑批次对应一次撤销，可使用 Aseprite 原生历史继续调整 |
| **基础动画（可选）** | 追加或删除帧、设置帧时长、创建和管理动画标签 |
| **CLI 文件工具** | 单独启用磁盘文件处理，使用已保留的上游工具进行批处理 |
| **自动连接** | 扩展在软件启动后等待服务，服务重启后自动重新连接 |

## 工作方式

系统由两个组件组成：

1. **Python MCP 服务**：与 AI 客户端通过 stdio 通信，处理工具调用并返回文字或图片。
2. **Aseprite Lua 扩展**：通过本机 WebSocket 连接服务，读取和修改编辑器中的内存文档。

实时编辑绑定明确的文档和修订；切换活动窗口不会把修改转移到其他画布。CLI 工具操作磁盘文件，实时连接失败会返回错误，不会自动改用 CLI。

## 使用示例

先在 Aseprite 中打开或新建画布，然后描述目标：

| 示例指令 | 用途 |
|---|---|
| “读取当前文档的尺寸、图层和帧信息，先给我预览。” | 了解画布 |
| “创建一个 32×32 的 RGB 画布，用像素和矩形画一把小剑。” | 从空白开始绘制 |
| “在这个文档中新建高光图层，添加几处浅色像素，完成后预览。” | 分层修改 |
| “撤销刚才那一批修改，再显示结果。” | 检查与调整 |
| “追加两帧，将前三帧设为 180 毫秒，并创建 walk 标签。” | 基础动画，需先启用 |

编辑不会自动保存。需要落盘时，明确要求保存为 `.aseprite` 或 `.ase` 文件；覆盖已有文件需要显式设置覆盖参数。撤销和重做针对文档最新历史，也可能涉及你手动完成的编辑。

### 启用基础动画

在 MCP 客户端的 `env` 中增加以下配置，并重启服务：

```json
{
  "ASEPRITE_MCP_CAPABILITY_SETS": "animation"
}
```

配套 0.4.1 服务和扩展会额外提供 `apply_animation`。追加帧复制末帧，帧号从 1 开始；详细范围与参数见[能力清单](docs/development/CAPABILITIES.md)。

### 工具配置

通过客户端环境变量 `ASEPRITE_MCP_TOOL_PROFILE` 选择：

| 值 | 工具范围 |
|---|---|
| `core`（默认） | 9 个实时核心入口；启用动画后为 10 个 |
| `cli` | 116 个磁盘文件工具；通过 `ASEPRITE_PATH` 配置 Aseprite，不建立实时连接 |
| `all` | 实时与 CLI 合计 125 个；启用动画后为 126 个 |

CLI 工具的数量不代表实时功能数量。完整配置见[安装说明](docs/INSTALL.md)，参数上限见 [.env.example](.env.example)。

## 当前边界

- 实时绘制以普通可编辑 RGB 图层为范围；非 RGB、锁定层、背景层、参考层和 Tilemap 等不支持的编辑会明确拒绝。
- 调色板、特效、补间和 Tilemap 尚未迁移为实时能力。
- 较大的操作可能触发像素、复制或执行时间预算，需缩小批次；不能确定写入结果时，先重新读取状态再操作。
- 服务仅监听本机回环地址。CLI 修改文件与编辑器内存修改分开使用，避免同时写入同一磁盘文件。

## 故障排查

| 问题 | 建议 |
|---|---|
| 扩展未连接 | 确认 MCP 服务已由客户端启动、扩展已启用，双方端口一致 |
| 端口被占用 | 结束重复服务，或同时修改服务 `--port` 与扩展端口 |
| 找不到文档或修订冲突 | 重新读取文档列表与文档信息；重连后旧会话和文档 ID 失效 |
| 没有显示预览图片 | 确认客户端支持 MCP 图片内容，并缩小预览区域或缩放倍数 |

更多错误与恢复步骤见[故障排查](docs/TROUBLESHOOTING.md)。

## 文档与贡献

[安装与使用](docs/INSTALL.md) · [兼容能力](docs/development/CAPABILITIES.md) · [测试说明](docs/TESTING.md) · [构建与发布](docs/RELEASING.md) · [参与贡献](CONTRIBUTING.md)

开发维护入口：[执行计划](EXECUTION_PLAN.md)、[项目结构](docs/PROJECT_STRUCTURE.md)和[架构说明](docs/development/ARCHITECTURE.md)。详细文档目前以中文提供。

## 致谢与许可

感谢 [diivi/aseprite-mcp](https://github.com/diivi/aseprite-mcp) 提供的上游工具与测试基础；实际导入版本和改造记录见[第三方来源](docs/THIRD_PARTY.md)。

本项目采用 [MIT 许可](LICENSE)，保留上游版权。Aseprite 需自行准备，不随项目分发。本项目为第三方集成，与 Aseprite 官方无隶属关系。
