Aseprite-MCP CLAUDE.md

CLAUDE.md — Aseprite MCP

Coding rules for this repo. aseprite-mcp-build-flow.md is the build plan (what/when). This file is the law (how). When the two disagree, this file wins.

Stack

• Python 3.11+, MCP Python SDK 2.x, Pillow, numpy, pydantic ≥2.12.
• No new dependency without a reason that a few lines of stdlib can't cover.
• Entrypoint: aseprite_mcp.server:main, stdio transport.

aseprite-mcp-build-flow.md was written against SDK 1.x and its server code is stale. Its architecture, pixel-art craft rules, and pitfall table still hold. Its imports, error handling, and auto-preview return shape do not. See "SDK 2.x" below.

SDK 2.x — the API actually is this

from mcp.server import MCPServer                        # NOT mcp.server.fastmcp.FastMCP
from mcp.server.mcpserver import Resolve, Context
from mcp.server.mcpserver import Image as MCPImage      # PIL owns the bare name `Image`

• FastMCP is gone. No alias, no deprecation shim. Anything importing mcp.server.fastmcp is v1 code.
• HTTP client is httpx2, not httpx. Don't add httpx.
• All Pydantic field names are snake_case in Python (input_schema, is_error); the wire stays camelCase.
• Transport args (host, port, …) go to run(), not the constructor.
• MCP types silently drop unknown fields. Custom data goes in _meta or it vanishes.

Layout

Follow aseprite-mcp-build-flow.md §2. Don't invent new top-level packages. New tool → a module in src/aseprite_mcp/tools/ exposing register(mcp), pulling the Bridge / Session aliases from deps.py (rule 28).

Build order

M0 → M1 → M2 → M3 → M4, then reassess. Do not start a milestone before the previous one's "done when" is actually true. The Phase 0 spike gates everything: no MCP tool code lands before the bridge round-trips 200 commands.

---

Hard rules — do not violate

These are the failure modes this project is known to hit. Each one cost someone a day.

Bridge

1. Atomic queue writes. Write <id>.tmp, then rename() to <id>.cmd. Never write .cmd directly.
2. Serialize every command behind one lock. Aseprite is single-threaded; concurrent commands corrupt sprite state.
3. Poll for process death inside the wait loop. A crash must raise in ms, not hang for the full timeout.
4. Both backends implement AsepriteBridge (base.py). Server code never branches on which backend is live.
5. Batch backend has no state. Every batch command is open → mutate → save. app.sprite is nil there.