aseprite-mcp 0.4.1__tar.gz

aseprite_mcp-0.4.1/.env.example

@@ -0,0 +1,20 @@
+# 使用者自行安装的 Aseprite；环境变量优先于 .env。
+ASEPRITE_PATH=C:/path/to/Aseprite.exe
+# core（默认）：9 个实时核心入口，无连接时返回明确错误。
+# cli：115 个上游兼容工具 + cli_execute；all：二者合并。
+ASEPRITE_MCP_TOOL_PROFILE=core
+# 可选基础动画能力集；留空保持默认9项，animation增加apply_animation。
+ASEPRITE_MCP_CAPABILITY_SETS=
+# 原始 Lua 仅在显式启用 CLI 时额外开放。
+ASEPRITE_MCP_ENABLE_RAW_LUA=0
+# 实时监听默认固定端口；命令行 --host/--port 优先于环境变量。
+ASEPRITE_MCP_HOST=127.0.0.1
+ASEPRITE_MCP_PORT=8765
+ASEPRITE_MCP_MAX_MESSAGE_BYTES=8388608
+ASEPRITE_MCP_MAX_OPERATIONS=256
+ASEPRITE_MCP_MAX_PIXELS=262144
+ASEPRITE_MCP_MAX_PNG_BYTES=4194304
+ASEPRITE_MCP_TIMEOUT_SECONDS=30
+ASEPRITE_MCP_MAX_BATCH_SECONDS=0.25
+ASEPRITE_MCP_DEDUP_ENTRIES=256
+ASEPRITE_MCP_DEDUP_TTL_SECONDS=120

aseprite_mcp-0.4.1/.gitignore

@@ -0,0 +1,26 @@
+# Local software and personal state
+/Aseprite/
+/.work/
+/.env
+/.env.*
+/.pypirc
+!/.env.example
+/.mcp.json
+/.codex/
+/.agents/
+# Python, test and build outputs
+/.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+/build/
+/dist/
+*.egg-info/
+/coverage.xml
+/.coverage
+# Legacy test outputs left at the project root; keep licensed test assets trackable.
+# OS and editor state
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/

aseprite_mcp-0.4.1/.python-version

@@ -0,0 +1 @@
+3.13

aseprite_mcp-0.4.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Divyansh Singh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

aseprite_mcp-0.4.1/PKG-INFO

@@ -0,0 +1,180 @@
+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 官方无隶属关系。

aseprite_mcp-0.4.1/README.en.md

@@ -0,0 +1,163 @@
+<div align="center">
+
+# Aseprite MCP
+
+**Make AI your pixel art collaborator**
+
+Draw, edit, and preview pixel art together in Aseprite through the Model Context Protocol.
+
+[中文](README.md) · **English**
+
+[![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 connects an MCP-compatible AI client to Aseprite. Describe a change in natural language, let AI edit your document and inspect the image preview, then continue drawing yourself—even on an unsaved canvas.
+
+Built on [diivi/aseprite-mcp](https://github.com/diivi/aseprite-mcp), this project adds a live Lua extension while retaining the upstream CLI file tools.
+
+> The current version is a **0.4.1 TestPyPI test release**. Real integration testing covers Windows + Aseprite 1.3.7 / API 28, with 208 tests passing in the [latest full regression run](docs/progress/P3-M2.md). macOS, Linux, and other Aseprite versions have not been validated.
+
+## Quickstart
+
+### 1. Prepare the server and extension
+
+You need your own installation of **Aseprite 1.3.7 / API 28**, **Python 3.13+**, [uv](https://docs.astral.sh/uv/getting-started/installation/), and an MCP client that supports stdio.
+
+After obtaining this project's source, run these commands from the repository root:
+
+```powershell
+uv sync --locked --python 3.13
+uv run --locked python scripts/build_release.py --out-dir dist
+```
+
+### 2. Install the Aseprite extension
+
+In **Edit → Preferences → Extensions → Add Extension**, select the generated `dist/aseprite-mcp-live-0.4.1.aseprite-extension`. Install and enable it, then restart Aseprite.
+
+### 3. Configure your MCP client
+
+This example uses the `mcpServers` configuration format. Replace `C:/path/to/aseprite-mcp` with the absolute path to your checkout. For other clients, use their equivalent stdio configuration.
+
+```json
+{
+  "mcpServers": {
+    "aseprite": {
+      "command": "uv",
+      "args": [
+        "--directory", "C:/path/to/aseprite-mcp",
+        "run", "--locked", "aseprite-mcp"
+      ],
+      "env": {
+        "ASEPRITE_MCP_TOOL_PROFILE": "core"
+      }
+    }
+  }
+}
+```
+
+Restart your client and open Aseprite. Allow the extension's local WebSocket access when prompted. It connects automatically to `127.0.0.1:8765`; no connection file is needed.
+
+Try asking: **“Inspect the open canvas, tell me which layers it has, and show me a preview.”**
+
+<details>
+<summary><b>Standalone installation, ports, and connection diagnostics</b></summary>
+
+- For wheel installation without a source checkout, `ASEPRITE_PATH` configuration, and manual extension installation, see the [Windows installation guide](docs/INSTALL.md) (Chinese).
+- Your MCP client starts the server. Run one server per port. If the client cannot find `uv`, use `Get-Command uv` to find its absolute path.
+- Open **File → Scripts → MCP: Connect / Settings** to check the connection or change the port. The server's `--port` argument must match the extension setting.
+- Upgrade the server and extension together; see the [installation and upgrade guide](docs/INSTALL.md).
+
+</details>
+
+## Features
+
+| Feature | What you can do |
+|---|---|
+| **Live collaboration** | Read and edit open documents, including unsaved canvases, while taking turns with AI |
+| **Pixels and layers** | Create RGB canvases, add regular layers, adjust opacity, and draw pixels and rectangles in batches |
+| **Visual feedback** | Return canvas previews as PNG images directly to MCP clients that support image content |
+| **Undo and redo** | Undo an editing batch in one step and continue using Aseprite's native history |
+| **Basic animation (optional)** | Append or delete frames, set frame durations, and create or manage animation tags |
+| **CLI file tools** | Enable disk-based processing separately for batch workflows using retained upstream tools |
+| **Automatic connection** | Let the extension wait for the server and reconnect after a server restart |
+
+## Components
+
+The system consists of two components:
+
+1. **Python MCP server**: communicates with your AI client over stdio, handles tool calls, and returns text or images.
+2. **Aseprite Lua extension**: connects to the server over a local WebSocket and reads or modifies documents in the editor's memory.
+
+Live edits target an explicit document and revision. Switching the active window does not redirect an edit to another canvas. CLI tools operate on disk files; a failed live connection returns an error rather than falling back to CLI.
+
+## Usage
+
+Open or create a canvas in Aseprite, then describe your goal:
+
+| Example prompt | Purpose |
+|---|---|
+| “Read this document's dimensions, layers, and frames, and show me a preview first.” | Inspect your canvas |
+| “Create a 32×32 RGB canvas and draw a small sword using pixels and rectangles.” | Start from scratch |
+| “Add a highlights layer to this document, place a few light pixels, and preview the result.” | Edit in layers |
+| “Undo the last batch of changes and show me the result.” | Review and adjust |
+| “Append two frames, set the first three frames to 180 milliseconds, and create a walk tag.” | Basic animation; enable it first |
+
+Edits do not save automatically. Explicitly request saving to an `.aseprite` or `.ase` file when ready; replacing an existing file requires an explicit overwrite parameter. Undo and redo act on the document's latest history, which may include your manual edits.
+
+### Enable basic animation
+
+Add this setting to your MCP client's `env` configuration and restart the server:
+
+```json
+{
+  "ASEPRITE_MCP_CAPABILITY_SETS": "animation"
+}
+```
+
+The matching 0.4.1 server and extension expose the additional `apply_animation` tool. Appended frames copy the last frame, and frame numbers start at 1. See the [capability guide](docs/development/CAPABILITIES.md) for scope and parameters.
+
+### Tool profiles
+
+Set `ASEPRITE_MCP_TOOL_PROFILE` in your client environment:
+
+| Value | Available tools |
+|---|---|
+| `core` (default) | 9 live core tools, or 10 with animation enabled |
+| `cli` | 116 disk-based tools; configure Aseprite with `ASEPRITE_PATH`; no live connection |
+| `all` | 125 live and CLI tools combined, or 126 with animation enabled |
+
+The CLI tool count does not describe live feature coverage. See the [installation guide](docs/INSTALL.md) for configuration and [.env.example](.env.example) for operation limits.
+
+## Current limitations
+
+- Live drawing targets regular editable RGB layers. Unsupported edits involving non-RGB documents, locked layers, background layers, reference layers, or Tilemaps are explicitly rejected.
+- Palettes, effects, tweening, and Tilemaps have not been migrated to live tools.
+- Large operations may exceed pixel, image-copy, or execution-time budgets. Use smaller batches; if a write's outcome is unknown, read the current state before proceeding.
+- The server listens only on local loopback addresses. Keep CLI file edits separate from editor-memory edits and avoid concurrent writes to the same disk file.
+
+## Troubleshooting
+
+| Problem | Suggested fix |
+|---|---|
+| Extension is disconnected | Check that the MCP client started the server, the extension is enabled, and the ports match |
+| Port is already in use | Stop the duplicate server, or change both the server's `--port` and the extension's port |
+| Document is missing or revision conflicts | Read the document list and information again; old session and document IDs expire after reconnecting |
+| Preview image is not displayed | Check that your client supports MCP image content, and reduce the preview region or scale |
+
+See the [troubleshooting guide](docs/TROUBLESHOOTING.md) for error details and recovery steps.
+
+## Documentation and contributing
+
+[Installation](docs/INSTALL.md) · [Capabilities](docs/development/CAPABILITIES.md) · [Testing](docs/TESTING.md) · [Building and releasing](docs/RELEASING.md) · [Contributing](CONTRIBUTING.md)
+
+For maintenance, start with the [execution plan](EXECUTION_PLAN.md), [project structure](docs/PROJECT_STRUCTURE.md), and [architecture](docs/development/ARCHITECTURE.md). Detailed documentation is currently in Chinese.
+
+## Acknowledgments and license
+
+Thanks to [diivi/aseprite-mcp](https://github.com/diivi/aseprite-mcp) for the upstream tools and tests. The imported revision and adaptation history are documented in [third-party sources](docs/THIRD_PARTY.md).
+
+This project uses the [MIT license](LICENSE) and preserves upstream copyright. Aseprite is installed separately and is not distributed with this project. This is a third-party integration and is not affiliated with the Aseprite team.

aseprite_mcp-0.4.1/README.md

@@ -0,0 +1,163 @@
+<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 官方无隶属关系。

aseprite_mcp-0.4.1/aseprite_mcp/__init__.py

@@ -0,0 +1,8 @@
+"""Aseprite MCP - Model Context Protocol implementation for Aseprite."""
+
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("aseprite")
+
+__version__ = "0.4.1"
+__author__ = "Divyansh Singh"

aseprite_mcp-0.4.1/aseprite_mcp/__main__.py

@@ -0,0 +1,20 @@
+import argparse
+
+from .core.config import RuntimeConfig
+from .server import create_server
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description="Aseprite MCP stdio server with automatic local editor connection")
+    parser.add_argument("--host", help="Loopback listener (default: 127.0.0.1; overrides ASEPRITE_MCP_HOST)")
+    parser.add_argument("--port", type=int, help="Listener port (default: 8765; overrides ASEPRITE_MCP_PORT)")
+    args = parser.parse_args(argv)
+    try:
+        config = RuntimeConfig.from_env(host=args.host, port=args.port)
+    except ValueError as exc:
+        parser.error(str(exc))
+    create_server(config=config).run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

aseprite_mcp-0.4.1/aseprite_mcp/backends/__init__.py

@@ -0,0 +1 @@
+"""Explicit backends; a live failure never falls back to disk."""