Aseprite_MCP: Instructions file for Codex

AGENTS.md

MCP server that lets an AI draw pixel art in Aseprite. Python (FastMCP) exposes a three-tool surface backed by an op registry; each op is implemented in .lua and run inside Aseprite, either as a headless CLI subprocess or over a WebSocket bridge to a live Aseprite window.

Commands

pip install -e ".[dev]"      # runtime deps + pytest
python server.py             # start MCP server over stdio
pytest                       # all tests; fast, no Aseprite needed
pytest -m "not e2e"          # skip tests that need real Aseprite
pytest -m e2e                # real Aseprite; auto-skips if not found
pytest tests/v2/test_apply_tool.py::test_apply_operations_happy_path -v

# on-machine harnesses (tests/live/, NOT collected by pytest - real Aseprite, real exit code)
python tests/live/probe_server_version.py      # is this build behaving as specified?
python tests/live/live_smoke.py --all          # 8 regression scenarios incl. big-canvas timing
python tests/live/ws_probe.py                  # websocket bridge: protocol, simulated ext, fallback

No linter, formatter, or typechecker is configured — do not invent one.

tests/ is local-only: it is gitignored and never published to the repository. In a fresh clone these commands have nothing to run.

ASEPRITE_PATH overrides Aseprite auto-detection (src/aseprite_locate.py: env var → PATH → common install locations, see src/config.py). Set it to run e2e, the tests/live/ harnesses, or the server for real.

Architecture

server.py            create_server(): builds Config/runner/SessionManager, registers the v2
                     three-tool surface + resources + prompts; starts session cleanup thread
src/config.py        env vars -> Config; scripts_dir is fixed at <root>/scripts (not env-configurable);
                     work_dir defaults to <root>/work and is resolved to an absolute path
src/session.py       SessionManager: <work>/sessions/<uuid>/canvas.ase; expiry sweeps the
                     filesystem, not the in-memory registry
src/runner.py        AsepriteRunner (CLI subprocess) and WebSocketRunner (bridge); identical run_script()
src/bridge.py        WebSocket server in a background thread; tab-delimited text protocol
src/v2/registry.py   REGISTRY (OpRegistry): single source of truth — OpSpec = name / category /
                     Pydantic params / lua function / mutating+destructive flags; validate() + catalog()
src/v2/compile.py    ops[] -> one generated Lua program; prints one JSON line after __MCP_JSON__
src/v2/executor.py   Engine: per-session lock, CLI file backup, atomic apply, dry_run, undo/redo
src/v2/result.py     Envelope / OpResult / stable ErrorCode — returned by apply_operations and
                     run_lua; inspect instead returns a fastmcp ToolResult
src/v2/inspect.py    metrics computed from the scale-1 exported PNG (palette, bbox, coverage, ...)
src/v2/tools.py      register_v2_tools(): apply_operations, inspect, run_lua
src/v2/ops/          built-in op definitions: draw_ops.py, session_ops.py (imported by __init__.py)
scripts/mcp_common.lua  shared Lua helpers (sprite I/O, draw primitives, selection masks)
scripts/ops_*.lua    op implementations grouped by category, named _mcp_op_<name>
scripts/inspect.lua  read-only perception export (works on a temp copy; never modifies the document)
scripts/mcp_run_lua.lua / scripts/undo.lua / scripts/redo.lua  run_lua entry + ws-mode native history
extension/main.lua   Aseprite extension; connects as WebSocket client, dofiles scripts, captures print()
tests/v2/            pytest suite (local-only, gitignored; mocked runner, Lua is never executed)
tests/live/          on-machine harnesses (local-only, gitignored), run by hand against real Aseprite