内容
# Aseprite MCP
[](https://github.com/MalloyTheDev/aseprite-mcp/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.python.org/)
[](https://modelcontextprotocol.io)
<p align="center">
<img src="assets/slime.gif" width="170" alt="Animated slime made entirely via Aseprite MCP">
<img src="assets/slime.png" width="170" alt="Slime sprite made entirely via Aseprite MCP">
</p>
<p align="center">
<sub>该史莱姆完全通过MCP工具调用绘制、着色、勾勒和动画 — 无需手动像素操作。</sub>
</p>
一个广泛的 [模型上下文协议](https://modelcontextprotocol.io) 服务器，允许AI代理（Claude Code、Claude Desktop 或任何MCP客户端）**创建和编辑Aseprite精灵** — 绘制像素艺术、构建动画、管理图层/帧/标签/调色板，并导出为PNG/GIF/精灵表格 — 所有操作均无需人工干预。
📖 **完整的工具参考：** [`docs/TOOLS.md`](docs/TOOLS.md) — 每个工具及其参数。
它通过生成 **Lua脚本** 并通过Aseprite的批处理模式 (`aseprite -b --script ...`) 运行，以及Aseprite CLI用于导出。每个操作都会打开一个真正的 `.aseprite` 文件，编辑它并保存 — 因此您的文件在Aseprite GUI中仍然完全可编辑。
- **108种工具** — 包括高级 **工作流** 工具，用于构建和验证整个资产，以及 **批量操作运行器**，可在单个Aseprite进程中应用多个编辑 — 跨精灵、图层、帧、单元格、绘图（包括像素完美和抗锯齿模式）、自定义画笔和对称性、调色板（提取/排序/渐变）、动画标签、切片/9-补丁、效果（渐变/轮廓/阴影/颜色调整）、文本渲染、图块地图、图像盖章、参考/轮廓图层、变换、丰富的导出（按图层/标签、精灵表格、洋葱皮）和GUI伴侣视图，以及 `health_check` 自我测试。
- **沙盒文件访问** — 默认情况下，文件能力范围限定在工作区内（仅限相对路径；绝对路径/上级路径不允许，除非您选择启用）。
- **默认不覆盖** — 输出写入工具拒绝覆盖现有文件；请传递 `overwrite=True` 以有意替换。
- **结构化结果** — 每个工具都返回描述更新精灵的JSON。
- **`render_preview`** 返回PNG，以便代理可以查看其作品并自我纠正。
- **确定性、无状态、鲁棒性** — 每次调用都是隔离的、无头Aseprite运行。
---
## 展示
以下所有内容均 **完全通过MCP工具调用** — 无需手动像素操作。
### 🟢 简单 — 一次调用构建可用的像素艺术
<p align="center">
<img src="docs/assets/showcase/easy_item_sheet.png" width="420" alt="像素艺术物品表格，包含心形、硬币、药水和剑图标">
</p>
<p align="center">
<sub><code>create_rpg_item_sheet</code> 一次调用布局命名物品切片；此处使用绘图工具填充 — 心形 / 硬币 / 药水 / 剑，每个都是一个可导出的切片。</sub>
</p>
### 🟡 中等 — 动画和标签生成
<p align="center">
<img src="docs/assets/showcase/medium_walk8.gif" width="120" alt="动画精灵在八个方向循环">
<img src="docs/assets/showcase/medium_walk8_sheet.png" width="460" alt="八方向行走表格：每个方向一个帧和动画标签">
</p>
<p align="center">
<sub><code>make_8_direction_walk_template</code> 生成帧 <strong>和每个方向的动画标签</strong> （N / NE / E / SE / S / SW / W / NW）— 准备好绘制行走循环。</sub>
</p>
### 🔴 困难 — 完整的流水线：创建 → 动画 → 验证 → 导出
<p align="center">
<img src="docs/assets/showcase/hard_pipeline.gif" width="160" alt="完整的流水线生成的蓝色角色动画 idle bounce">
</p>
<p align="center">
<sub>一次代理运行：<code>create_character_sprite</code> → 绘制 → <code>make_4_frame_idle_animation</code> → <code>validate_sprite_for_game_export</code> → <code>export_game_asset_bundle</code>。</sub>
</p>
```text
validate_sprite_for_game_export → 通过 ✅ （宽度，高度，颜色模式，最小帧数，要求标签）
export_game_asset_bundle → hero.png · hero.gif · hero_sheet.png (+JSON) · hero_idle.gif · manifest.json
```
<details>
<summary>更多示例</summary>
<p align="center">
<img src="assets/slime.gif" width="110" alt="动画弹跳史莱姆">
<img src="assets/skeleton.png" width="110" alt="像素艺术骨骼">
<img src="assets/tilemap_scene.png" width="200" alt="图块地图场景，包含草，泥土，水和石头">
<img src="assets/ramp.png" width="200" alt="从generate_ramp生成的色调偏移阴影渐变">
</p>
<p align="center">
<sub>一个弹跳的史莱姆，一个骨骼，一个图块地图场景由4个绘制的图块和一个色调偏移的<code>generate_ramp</code>调色板。</sub>
</p>
</details>
---
## 要求
- **Aseprite 1.3+** （脚本API）。Steam和独立构建版本均可使用。
- **Python 3.10+**
- **[uv](https://docs.astral.sh/uv/)** （推荐）— 或任何PEP 517安装程序。
## 安装
```bash
git clone https://github.com/MalloyTheDev/aseprite-mcp.git
cd aseprite-mcp
uv sync
```
这会创建一个虚拟环境并安装 `aseprite-mcp` 包及其依赖项。验证它是否可以找到Aseprite并运行测试套件（如果找不到Aseprite，测试会自动跳过）：
```bash
uv run pytest
```
## 配置
所有配置均可通过环境变量（均为可选）进行：
| 变量 | 用途 | 默认值 |
| --- | --- | --- |
| `ASEPRITE_PATH` | `Aseprite.exe` / `aseprite` 的完整路径。 | 自动检测（Steam，独立，PATH）。 |
| `ASEPRITE_MCP_WORKSPACE` | **相对**精灵路径解析的文件夹。 | `<repo>/workspace` |
| `ASEPRITE_MCP_TIMEOUT` | 每次操作的超时时间（秒）。 | `90` |
| `ASEPRITE_MCP_ALLOW_ABSOLUTE` | 允许绝对路径 / 工作区逃逸路径（`1`/`true`启用）。 | 关闭（沙盒） |
在此机器上，Aseprite在 `C:\Program Files (x86)\Steam\steamapps\common\Aseprite\Aseprite.exe` 处被检测到，因此 `ASEPRITE_PATH` 并不严格要求 — 但显式设置是最可靠的。
---
## 注册到MCP客户端
将下面的 `/ABSOLUTE/PATH/TO/aseprite-mcp` 替换为您的克隆的绝对路径。
### Claude Code（CLI）
```bash
claude mcp add aseprite -- uv --directory /ABSOLUTE/PATH/TO/aseprite-mcp run aseprite-mcp
```
要显式设置Aseprite路径（推荐如果自动检测失败）：
```bash
claude mcp add aseprite \
--env ASEPRITE_PATH="/path/to/Aseprite.exe" \
-- uv --directory /ABSOLUTE/PATH/TO/aseprite-mcp run aseprite-mcp
```
### Claude Desktop / 通用MCP客户端（JSON）
将此添加到客户端的MCP服务器配置中（例如 `claude_desktop_config.json`）。 一个现成的模板位于 [`mcp-config.example.json`](mcp-config.example.json) 中（显示Windows风格的路径 — 根据您的操作系统进行调整）：
```json
{
"mcpServers": {
"aseprite": {
"command": "uv",
"args": ["--directory", "C:\\path\\to\\aseprite-mcp", "run", "aseprite-mcp"],
"env": {
"ASEPRITE_PATH": "C:\\Program Files (x86)\\Steam\\steamapps\\common\\Aseprite\\Aseprite.exe",
"ASEPRITE_MCP_WORKSPACE": "C:\\path\\to\\aseprite-mcp\\workspace"
}
}
}
}
```
重启客户端； `aseprite` 服务器及其108种工具将可用。要求代理运行 `health_check` 以确认Aseprite已正确连接。
---
## 高级工作流
除了低级工具之外，少数 **工作流工具** 通过一次调用构建整个资产并返回一个清单（创建的文件、路径、帧、标签、尺寸和建议的下一步骤），以便代理可以继续。它们组合低级工具 — 确定性构建，无需AI生成。
| 工具 | 描述 |
| --- | --- |
| `create_character_sprite` | 透明画布 + 身体/细节图层 + 生成的阴影渐变 + 轮廓占位符。 |
| `make_4_frame_idle_animation` | 将1帧精灵变成4帧idle“bob”循环并添加标签。 |
| `create_tileset_project` | 画布 + 图块地图图层 + 启动图块集（草/泥/水/石头，或您自己的）。 |
| `create_icon_set` | 图标单元格的网格表格，每个单元格内的占位符（`icon_0`，...）。 |
| `create_rpg_item_sheet` | 网格表格，每个物品一个切片（剑/盾/药水/...）。 |
| `make_8_direction_walk_template` | 8方向行走模板 — 每个方向的帧 + 一个标签（N/NE/E/...）。 |
| `export_game_asset_bundle` | PNG + 动画GIF + 精灵表格（+ JSON）+ 按标签的GIF + `manifest.json`。 |
| `export_godot_spriteframes` | Godot 4 `SpriteFrames` 资源（.tres）+ 打包表格 — 每个动画一个动画，按帧时长计时。 |
| `export_slice_metadata` | 引擎无关的 `<sprite>_slices.json` — 碰撞盒/受损盒/碰撞/附加/9切片/枢轴来自切片名称或JSON数据。 |
| `validate_sprite_for_game_export` | 检查精灵是否可用于游戏（尺寸/图块倍数，颜色模式，帧，需要的标签，透明度，调色板预算，导出存在）→ 通过/失败报告。 |
| `validate_asset_spec` / `plan_asset_spec` / `build_asset_from_spec` | 描述资产一次（`aseprite_mcp.asset_spec.v1`），然后验证它，运行计划或构建它（结构仅 — 画布/图层/帧/标签/切片/调色板 + 导出；您绘制艺术）。 |
> "为我创建一个idle动画的英雄和一个游戏准备好的包。"
1. `create_character_sprite("hero", 32, 32, base_color="#3878c8")` — 图层 + 调色板 + 占位符。
2. 在 `body` / `details` 图层上绘制角色（低级工具）。
3. `make_4_frame_idle_animation("hero.aseprite")` — 4帧循环标记为 `idle`。
4. `validate_sprite_for_game_export("hero.aseprite", expected_width=32, required_tags=["idle"])` — 确认它可用于游戏。
5. `export_game_asset_bundle("hero.aseprite", scale=8)` — PNG/GIF/sheet+JSON/manifest在 `hero_bundle/`。
### 工作流清单合同
每个工作流工具都返回一个标准化的 **`workflow_manifest.v1`** 对象（在 [`core/manifest.py`](src/aseprite_mcp/core/manifest.py) 中定义），因此资产层在增长时保持一致。始终存在：`ok`, `schema_version`, `kind`, `created_files[]`, `suggested_next_actions[]`, `warnings[]`。相关时包含：`sprite{}`, `exports[]`, `palette{}`, `animation{}`, `tilemap{}`。文件/导出条目是 `{role, path, format, metadata_path?}`。
```json
{
"ok": true,
"schema_version": "workflow_manifest.v1",
"kind": "character_sprite",
"sprite": { "path": "...", "width": 32, "height": 32, "color_mode": "rgb",
"frames": 1, "layers": ["body", "details"], "tags": [] },
"created_files": [ { "role": "source_sprite", "path": "...", "format": "aseprite" } ],
"palette": { "colors": ["#1b1f2a", "..."], "count": 5 },
"suggested_next_actions": ["Draw the character on the 'body' layer", "..."],
"warnings": []
}
```
---
## 批量操作
`apply_operations` 在单个Aseprite进程中 **原子** 应用精灵的编辑列表 —
**原子** — 打开一次 → 内部运行每个操作 → 仅在所有操作成功时保存。传递 `dry_run=true` 以验证操作列表 **而不启动Aseprite`。
```jsonc
apply_operations("hero.aseprite", [
{"op": "add_layer", "args": {"name": "fg"}},
{"op": "fill_layer", "args": {"layer": "fg", "color": "#1d2b53"}},
{"op": "draw_rectangle", "args": {"layer": "fg", "x": 2, "y": 2, "width": 12, "height": 8, color": "#ff004d"}},
{"op": "add_frame", "args": {"copy_from": 1, "duration_ms": 120}},
{"op": "add_tag", "args": {"name": "idle", "from": 1, "to": 2}}
])
```
如果任何操作失败，整个批次都会回滚，错误会指出失败的操作索引。
v1 操作：图层添加/重命名/可见/不透明度/删除 · 帧添加/复制/持续时间 ·
标签添加/删除 · 绘制 set_pixel/line/rectangle/fill_rectangle/ellipse/fill_ellipse/fill_layer/clear_layer ·
切片添加/删除 · 替换颜色。
---
## 工具目录
相对文件名在工作区内解析（绝对路径需要
`ASEPRITE_MCP_ALLOW_ABSOLUTE=1` — 参见 [安全](#security)）。
帧和调色板感知操作为 **基于1的帧数**，**基于0的调色板索引**。颜色接受 `#RRGGBB`， `#RRGGBBAA`， `r,g,b`， `r,g,b,a`， `index:N`， 或名称
（`black`, `white`, `red`, `green`, `blue`, `yellow`, `cyan`, `magenta`, `transparent`, ...).
### 精灵生命周期
| 工具 | 描述 |
| --- | --- |
| `create_sprite` | 创建并保存新的精灵（`rgb` / `indexed` / `gray`，可选背景）。 |
| `save_sprite_as` | 以新路径保存副本（可选地展平）。 |
| `set_color_mode` | 在`rgb` / `indexed` / `gray`之间转换（带有抖动）。 |
| `resize_canvas` | 在不缩放艺术的情况下更改画布大小（`top_left` / `center`）。 |
| `crop_sprite` | 将画布裁剪到矩形。 |
| `scale_sprite` | 缩放整个精灵（按因子或到尺寸；`nearest` / `bilinear`）。 |
| `flatten_sprite` | 将所有图层合并为一个。 |
| `trim_sprite` | 自动裁剪画布到非透明内容。 |
| `convert_layer_to_background` · `convert_background_to_layer` | 切换不透明的背景图层。 |
### 检查和预览
| 工具 | 描述 |
| --- | --- |
| `get_sprite_info` | 完整的结构化状态：大小，模式，帧，图层树，标签，调色板。 |
| `render_preview` | 将帧渲染为PNG图像，您可以查看（缩放）。 |
| `get_pixels` | 读取区域的合成像素颜色（≤ 64×64每次调用）。 |
| `list_sprites` | 列出工作区中的精灵/图像文件。 |
### 图层
| 工具 | 描述 |
| --- | --- |
| `add_layer` | 添加图层（可选组，不透明度，混合模式，可见性）。 |
| `add_group_layer` | 添加组图层。 |
| `remove_layer` · `rename_layer` | 删除/重命名图层。 |
| `set_layer_properties` | 更新不透明度，混合模式，可见性，可编辑性，名称。 |
| `move_layer` | 重新排序图层（基于1的堆栈索引，1 = 底）。 |
| `duplicate_layer` · `merge_layer_down` | 复制/合并图层向下。 |
### 帧（动画）
| 工具 | 描述 |
| --- | --- |
| `add_frame` | 追加一个帧（空或复制另一个）。 |
| `duplicate_frame` · `remove_frame` | 复制/删除帧。 |
| `set_frame_duration` · `set_all_frame_durations` | 设置每个帧/统一持续时间（毫秒）。 |
### 单元格（图层在帧中的图像）
| 工具 | 描述 |
| --- | --- |
| `get_cel` | 检查单元格（存在，位置，边界，不透明度）。 |
| `set_cel_position` · `set_cel_opacity` | 移动/淡化单元格。 |
| `copy_cel` · `delete_cel` | 在帧之间复制单元格/删除它。 |
### 动画标签
| 工具 | 描述 |
| --- | --- |
| `add_tag` | 用名称，方向，颜色标记帧范围。 |
| `set_tag` · `remove_tag` | 编辑/删除标签。 |
### 绘图
| 工具 | 描述 |
| --- | --- |
| `draw_pixels` | 绘制单个像素（每个像素或共享颜色）。 |
| `draw_line` · `draw_polyline` | 线/连接的段；`pixel_perfect` 和 `antialias` 选项。 |
| `draw_curve` | 二次贝塞尔曲线。 |
| `draw_rectangle` · `draw_ellipse` | 轮廓或填充的矩形/椭圆；椭圆具有 `antialias`。 |
| `fill_area` | 从一个点填充（油漆桶）。 |
| `fill_layer` · `clear_layer` | 填充整个单元格/擦除它为透明。 |
### 笔刷和对称性
| 工具 | 描述 |
| --- | --- |
| `draw_brush` | 在多个点上戳一个自定义笔刷形状（ASCII掩码）。 |
| `stamp_pattern` | 在区域内平铺图像/精灵（带有间距，不透明度和混合）。 |
| `mirror_layer` | 将图层的一半反射到另一半（构建对称艺术）。 |
| `draw_symmetric_pixels` | 绘制具有水平/垂直/4向镜像的像素。 |
### 切片（命名区域/9补丁）
| 工具 | 描述 |
| --- | --- |
| `add_slice` · `set_slice` · `remove_slice` · `list_slices` | 管理切片，可选的9补丁中心，枢轴，颜色和数据。 |
### 效果和颜色调整
| 工具 | 描述 |
| --- | --- |
| `fill_gradient` | 线性/辐射状渐变，多停止，选项贝叶斯抖动。 |
| `fill_checkerboard` | 双色棋盘格图案。 |
| `add_outline` | 艺术周围的像素轮廓（外部/内部，4/8连通性，厚度）。 |
| `add_drop_shadow` | 在艺术下方的新图层上的硬滴影。 |
| `replace_color` | 交换颜色（具有每个通道容忍度）。 |
| `invert_colors` | 反转RGB（保留alpha）。 |
| `adjust_brightness_contrast` · `adjust_hue_saturation` · `desaturate` | 颜色分级。 |
### 文本
| 工具 | 描述 |
| --- | --- |
| `draw_text` | 以清晰的像素渲染文本（内置位图字体或TrueType文件）。 |
### 图块地图（Aseprite 1.3+）
| 工具 | 描述 |
| --- | --- |
| `create_tilemap_layer` | 创建具有图块大小 + 空网格的图块地图图层。 |
| `add_tile` · `fill_tile` · `paint_tile_pixels` | 定义/绘制图块集艺术。 |
| `set_tile` · `set_tiles` · `fill_tilemap` | 在网格上放置图块。 |
| `get_tilemap` | 读取图块索引网格。 |
### 图片盖章
| 工具 | 描述 |
| --- | --- |
| `stamp_file` | 将另一个图像/精灵文件合成到图层上（不透明度，混合模式）。 |
| `draw_image_base64` | 将内联base64图像合成到图层上。 |
### 调色板 Palette
| 工具 | 描述 |
| --- | --- |
| `get_palette` · `set_palette` | 读取 / 替换整个调色板。 |
| `set_palette_color` · `add_palette_color` · `resize_palette` | 编辑单个条目 / 大小。 |
| `load_palette` | 从 `.gpl`/`.pal`/`.png`/`.aseprite` 加载调色板。 |
| `set_transparent_color` | 设置透明索引（索引精灵）。 |
| `extract_palette` | 收集精灵 / 图片中使用的唯一颜色。 |
| `sort_palette` | 按色调 / 亮度 / 饱和度 / 值排序（重新映射索引像素）。 |
| `generate_ramp` | 从基色构建色调偏移阴影渐变。 |
### 变换与导出 Transform & export
| 工具 | 描述 |
| --- | --- |
| `flip_sprite` · `rotate_sprite` | 翻转（水平 / 垂直）/ 旋转（90 / 180 / 270）整个精灵。 |
| `export_png` | 将一帧导出为扁平的 PNG（缩放）。 |
| `export_gif` | 将动画导出为动画 GIF。 |
| `export_tag_gif` | 仅导出命名标签的帧为 GIF。 |
| `export_spritesheet` | 将帧打包到表格中（+ JSON 元数据；图层 / 标签过滤器和拆分）。 |
| `export_frames` | 将每帧导出到其自己的文件（`{frame}` 模式）。 |
| `export_layer` · `export_layers` | 将一层 / 每个图层导出到单独的文件。 |
| `export_tags` | 将每个动画标签的帧导出到单独的文件。 |
| `export_onion_skin` | 渲染一个带有邻近帧幽灵的帧。 |
| `import_image` | 从扁平图片构建可编辑的 `.aseprite`。 |
### 参考 / 描摹 Reference / rotoscope
| 工具 | 描述 |
| --- | --- |
| `add_reference_layer` | 添加一个带有参考图片的调暗、锁定图层以供描摹。 |
| `import_reference_sequence` | 导入一系列图片作为每帧参考（描摹）。 |
### 批处理操作 Batch operations
| 工具 | 描述 |
| --- | --- |
| `apply_operations` | 原子性地将多个编辑应用于一个精灵，以单个进程运行（`dry_run` 仅验证）。参见 [批处理操作](#batch-operations)。 |
### GUI 同步模式 GUI companion mode
| 工具 | 描述 |
| --- | --- |
| `open_in_editor` | 在 Aseprite GUI 窗口中打开精灵（非阻塞）以查看编辑。 |
| `gui_available` | 报告 Aseprite GUI 是否可启动。 |
### 健康检查与自测试 Health & self-test
| 工具 | 描述 |
| --- | --- |
| `health_check` | 自测试：Aseprite 找到？ 版本，工作区，工具数量，以及实际创建 + 导出往返。 |
---
## 实时查看（GUI 同步模式）
服务器 **无界面** 编辑文件，但您可以在真正的 Aseprite 窗口中查看工作。调用 `open_in_editor("sprite.aseprite")`，Aseprite 在一个普通的，非阻塞窗口中打开它。当代理继续使用其他工具保存编辑时，Aseprite 检测到磁盘上的更改，并提供重新加载（或自动重新加载，取决于您的 Aseprite 首选项）- 编辑出现在无需重新打开的情况下。
**这是什么，不是什么：** Aseprite 的 Lua 脚本沙盒没有网络或计时器，因此服务器无法 *流式传输* 实时画布到 GUI 帧。上述同步视图（打开一次 → 无界面编辑 → Aseprite 重新加载）是稳健的，受支持的工作流程。代理自己的“眼睛”仍然是 `render_preview`，它直接返回一个 PNG 以便检查。
---
## 示例代理工作流程
> “为我制作一个 32×32 的行走黏液动画。”
1. `create_sprite("slime.aseprite", 32, 32, "rgb")`
2. `fill_layer` 背景，`add_layer("slime")`，使用 `draw_ellipse`/`fill_area`/`draw_pixels` 绘制身体。
3. `add_frame(copy_from=1)` 几次；使用 `set_cel_position` 微调身体以创建弹跳。
4. `set_all_frame_durations(120)` 和 `add_tag("walk", 1, 3, "pingpong")`。
5. `render_preview` 检查，迭代，然后 `export_gif("slime.gif", scale=8)`。
---
## 工作原理
```
客户端 (Claude) ──MCP──> aseprite-mcp (FastMCP, Python)
│ 构建 Lua 正文 + 参数表
▼
luagen.assemble_script ──> 临时 .lua
│ （前奏：JSON 编码器，颜色 / 像素
│ 助手，绘图基元，信息）
▼
Aseprite.exe -b --script 临时 .lua
│ 打印 @@ASEMCP@@<json> （或 @@ASEMCP_ERR@@）
▼
运行程序解析信号 ──> 字典返回客户端
```
绘图基元（线，矩形，椭圆，洪水填充）确定性地在 Lua 中实现，并在目标单元格的整个画布副本上运行，因此坐标始终在精灵空间中，结果在运行间相同。导出使用 Aseprite CLI 的原生标志（`--sheet`，`--scale`，`--data`，...）。
### 项目布局
```
src/aseprite_mcp/
app.py FastMCP 实例 + 用法说明
config.py 定位 Aseprite，工作区，路径解析
luagen.py Python->Lua 序列化 + 共享 Lua 前奏 + 脚本组装
runner.py 运行 run_lua() / run_cli()，解析信号 JSON
server.py 导入所有工具模块，main()
tools/ 每个域一个模块：精灵，检查，图层，帧，标签，
单元格，绘图，画笔，效果，文本，图块地图，图像，调色板，
切片，变换，导出，参考（+ common.py）
docs/TOOLS.md 完整的自动生成工具参考
scripts/ gen_tool_docs.py（重新生成 docs/TOOLS.md）
tests/ pytest 套件（自动跳过没有 Aseprite）
```
## 安全
此服务器向 AI 代理提供 **文件能力**，因此默认情况下访问权限是范围限定的：
- **工作区沙盒路径。** 相对文件名在 `ASEPRITE_MCP_WORKSPACE` 下解析（默认为 `<repo>/workspace`）。绝对路径和通过 `..` （或指向工作区外部的符号链接）逃离工作区的路径 **被拒绝**，除非您设置 `ASEPRITE_MCP_ALLOW_ABSOLUTE=1`。
- **默认情况下不覆盖。** 输出写入工具（`create_sprite`，`save_sprite_as`，`export_*`，`export_game_asset_bundle`）拒绝覆盖现有文件；请传递 `overwrite=True` 以故意替换它。多文件导出验证每个目标文件，如果任何目标文件已经存在，则在写入任何内容之前它们会失败。
- **无 Shell，无注入。** Aseprite 使用列表形式的参数调用（从不 Shell），并且每个用户值都通过转义的 `ARG` 表输入到生成的 Lua 中 - 用户输入永远不会连接到 Lua 源代码。
- **自带 Aseprite。** 服务器仅运行它指向的 Aseprite 二进制文件。
运行 `health_check` 以确认配置（Aseprite 路径，工作区，沙盒状态）。
## 注意事项和限制
- **设计无状态。** 每个工具调用都是一个独立的无界面 Aseprite 进程，因此瞬时状态（GUI 选择，撤销历史记录，“活动”精灵）**不**会在调用之间持续存在。需要持久选择的运算会改为采用显式坐标。未来的 **实时 GUI 模式** 可以在此基础上构建，而无需更改工具 API。
- 使用 `.aseprite`/`.ase` 扩展名以保持图层，帧和标签可编辑。保存到 `.png`/`.gif` 会使图像扁平化。
- `get_pixels` 每调用限制在 4096 像素（例如 64×64）；请分块读取较大区域。
- 抗锯齿（`antialias=True`）仅适用于 RGB 精灵；在索引 / 灰度精灵上会被忽略。图块地图和参考图层需要 **Aseprite 1.3+**。
## 故障排除
- **“找不到 Aseprite 。”** 请将 `ASEPRITE_PATH` 设置为可执行文件的完整路径。
- **无反应 / 保存时权限被拒绝。** 确保工作区路径可写入。相对文件名位于 `ASEPRITE_MCP_WORKSPACE`（默认为 `<repo>/workspace`）。
- **大操作超时：** 提高 `ASEPRITE_MCP_TIMEOUT`（秒）。
- **工具使用 Lua 消息出错。** 消息直接从 Aseprite 传递 - 它通常会命名错误的参量（例如缺少的图层 / 帧）。
- **所有测试均跳过。** 如果没有安装 / 找到 Aseprite，则这是预期的结果；请设置 `ASEPRITE_PATH` 以实际运行它们。
## 开发
```bash
uv run pytest # 集成测试（需要 Aseprite）
uv run aseprite-mcp # 在 stdio 上运行服务器（手动调试）
uv run python scripts/gen_tool_docs.py # 重新生成 docs/TOOLS.md
```
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 了解架构以及如何添加工具，并参见 [CHANGELOG.md](CHANGELOG.md) 了解发行说明。
## 贡献
欢迎贡献！请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，为您的更改添加测试，并在打开 PR 之前重新生成工具参考。
## 许可证
[MIT](LICENSE) © Brendan Malloy.
## 免责声明
这是一个独立的，非官方项目，**不隶属于或获得** Aseprite 或 Igara Studio S.A. 的认可。“Aseprite” 是其各自所有者的商标。您需要自己的 Aseprite 授权副本才能使此服务器正常运行。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器