Aseprite Agent MCP

Validate a native master and export a Phaser bundle directory. Writes sheet.png (one row per contract row), a Phaser hash atlas, animations.json (per-frame timing, repeat and yoyo from the contract), qa.json, contract.json and loader.js. The master and the written PNG are reopened and every RGBA pixel is compared before publishing. Animations are named "<contract name>:<row tag>". An existing directory is only replaced with replace=true, and only if it is a previous bundle; the swap is a rename, so a failed export leaves the old one intact.

Return a labelled contact sheet of every frame, scaled with nearest-neighbour. With by_tag (default) each tag gets its own row, labelled with its name, frame range, playback and the frame numbers; untagged frames share a final row. The background is a checkerboard so transparency is visible, or any colour. Also returns the sprite info (frame timing in seconds, tags). This is a review sheet, not proof that the motion reads well. Args: scale: 1-16 pixel magnification. background: "checker" (default), a colour such as "#202020", or null for transparent. by_tag: One row per tag (True…

Reopen a native master and check every frame against a contract. Checks frame count, cell size, that each row's tag covers exactly its frames in order with the expected playback, binary alpha, palette membership, empty frames, and optional per-row foot/centre drift. Unknown contract fields are rejected. Rows are laid out in contract order starting at frame 1. Passing proves geometry and colours, not art quality: still review with ase_preview_animation.

Clean 1..128 ordered PNG poses with one palette; save master, sheet and JSON. Bounding-box mode uses one shared scale, bottom-centres silhouettes and leaves an outline margin. Anchor mode scales same-size canvases and translates each source [x,y] to (width//2,height-2), refusing clipping. No pose synthesis is implied: inspect the preview for identity, timing and motion coherence. Output is atomically published only after master and PNG pixel verification. Use height=128 and colours=32..48 for detailed sprites. palette_first snaps one shared source palette before sampling; defaults retain the …

Build the asset described by an ``aseprite_mcp.asset_spec.v1`` document. Executes the (validated) plan by dispatching each step to an existing tool: scaffolds the sprite for its `kind`, applies palette / extra layers / animation frames+tags / slices, and runs the requested exports. **Structure only — no pixels are drawn;** the returned manifest's `suggested_next_actions` hand the actual art back to you. Args: overwrite: Passed to the export steps (replace existing export files). The sprite itself is created no-clobber, so building over an existing ``<name>.aseprite`` rais…

Erase the target layer/frame cel to full transparency.

Convert the Background layer back into a normal (transparent-capable) layer.

Convert a normal layer into the sprite's opaque Background layer.

Copy a cel's image (and position) from one frame to another on the same layer.

Append frames from another sprite file, flattened onto one layer of this sprite. Use it to start every character from a shared base body or animation. The source frames are composited (all visible layers) and placed on `layer` of `filename`, keeping each frame's duration. If this sprite has a single empty frame (a fresh file), the first copied frame fills it instead of leaving a blank frame in front. Args: source: The .aseprite file to copy from (same width, height and colour mode). source_tag: Copy this tag's frames. Or give from_frame/to_frame (1-based, inclusive). With nei…

Scaffold a character sprite project: a transparent canvas with a tidy layer stack (body + details), an auto-generated shading palette ramp from `base_color`, and (optionally) an outlined placeholder body to draw over. Returns a ``workflow_manifest.v1`` manifest (sprite summary, created files, palette, and suggested next actions).

Scaffold an icon set: a grid sheet with `count` icon cells, each a placeholder inside a named slice (`icon_0`, `icon_1`, …) for easy atlas export. Returns a ``workflow_manifest.v1`` manifest (kind "icon_set"); the per-icon regions appear as slices under `sprite.slices`.

Scaffold an RPG item sheet: a grid sheet with one named slice per item (default sword/shield/potion/coin/key/gem), each with a placeholder. Returns a ``workflow_manifest.v1`` manifest (kind "rpg_item_sheet"); item regions appear as slices (named after each item) under `sprite.slices`.

Create a new sprite file and save it. Args: filename: Output path. Relative paths go in the workspace. Use a .aseprite/.ase extension to keep layers & frames editable. width, height: Canvas size in pixels (1-65535). color_mode: "rgb" (default), "indexed", or "gray". background: Optional fill colour for the first layer (e.g. "#1d2b53"). Omit for a transparent canvas. overwrite: Replace `filename` if it already exists (default False = no-clobber). Returns the new sprite's structured info.

Create a tilemap layer with an empty grid. Args: name: Layer name. tile_width, tile_height: Tile size in pixels (sets the sprite grid). columns, rows: Grid size in tiles (default: enough to cover the canvas).

Scaffold a tilemap project: a canvas sized columns×rows tiles, a tilemap layer, and a starter tileset (grass/dirt/water/stone by default, or your own [{"name","color"}] list). The grid is filled with the first tile to start. Returns a ``workflow_manifest.v1`` manifest with a tilemap block mapping tile names to their tileset indices.

Crop the canvas to the rectangle (x, y, width, height).

Delete a cel (the layer becomes empty at that frame).

Create a new animation tag by mirroring an existing one (e.g. walk_left from walk_right). Copies every frame of `source_tag` to new frames at the end of the sprite, flips every layer's cel along `axis`, keeps each frame's duration, and tags the new frames `new_tag` with the source tag's playback direction. Other tags keep their exact ranges. Asymmetric details (a sword hand, a logo) flip too, so review the result with ase_preview_animation. Args: source_tag: Existing tag to mirror. new_tag: Name for the new tag; must not exist yet. axis: "horizontal" (left/right) or "vertical" (u…

Desaturate toward grayscale by `amount` percent (0-100).

Stamp a custom brush shape at a list of points. Args: brush: The brush as rows of characters. Any character other than space, '.', or '0' is a filled cell. e.g. a plus brush: ["010", "111", "010"]. points: Positions to stamp at, list of {"x": int, "y": int}. color: Colour to stamp the brush in. anchor: "center" (default) or "topleft" — where each point sits in the brush.

Draw a quadratic Bézier curve from (x0,y0) to (x1,y1) bending toward the control point (control_x, control_y). `steps` controls smoothness.

Draw an ellipse centred at (center_x, center_y) with the given radii. For a circle, use the same value for radius_x and radius_y. filled=False draws a 1px outline. antialias smooths a *filled* ellipse with sub-pixel coverage (RGB sprites only; ignored otherwise).

Composite an inline base64-encoded PNG (or other image) onto a layer at (x, y). Useful for pasting externally generated artwork. `image_base64` may include a `data:image/png;base64,` prefix.

Draw a straight line from (x1,y1) to (x2,y2). Args: pixel_perfect: Remove L-shaped corner pixels for a clean 1px pixel-art line. antialias: Smooth (Xiaolin Wu) line with alpha blending — RGB sprites only; ignored on indexed/gray. Takes precedence over pixel_perfect.

Draw a block of pixel art in one call, like a text-art bitmap. Each string in `rows` is one pixel row; each character is looked up in `key` and painted at (x + column, y + row), with (0,0) the top-left of the canvas. '.' and ' ' are left untouched unless `key` defines them. Any other character missing from `key` is an error, so typos never paint silently. Example: rows=["..oo..", ".oxxo.", "..oo.."], key={"o": "#203040", "x": "#f0c060"}. Args: rows: Up to 256 strings of up to 256 characters each. key: Single character -> colour ("#RRGGBB", "#RRGGBBAA", "r,g,b", "index:N", a name). …

Plot individual pixels. Args: pixels: List of {"x": int, "y": int, "color": "#hex"?}. If a pixel omits "color", the shared `color` argument is used. color: Default colour for pixels that don't specify their own. layer: Target layer name or 1-based index (default: top layer). frame: Target frame, 1-based (default 1).

Draw connected line segments through a list of points. points: list of {"x": int, "y": int}. Set closed=True to connect the last point back to the first (outline a polygon). pixel_perfect removes L-corner pixels across the whole path for a clean pixel-art outline.

Draw a rectangle. filled=False draws a 1px outline, True fills it.

Plot pixels together with their mirror image(s). mode: "horizontal" (mirror across vertical axis_x), "vertical" (across axis_y), or "both" (4-way radial symmetry). Axes default to the canvas centre.

Draw text onto a layer at (x, y) in a single colour. Args: text: The string (supports "\n" for multiple lines). x, y: Top-left position of the text. color: Text colour. scale: Integer pixel-scaling of the rendered glyphs (default 1). font_path: Optional path to a .ttf/.otf font. If omitted, a built-in bitmap font is used (best for tiny pixel text). font_size: Point size when a TrueType font_path is given. spacing: Extra pixels between lines. threshold: 0-255 cutoff; pixels brighter than this are drawn (lower = heavier text). Keeps glyphs crisp (…

Duplicate an existing frame (1-based); the copy is inserted after it.

Duplicate a layer (including its cels) as a new layer on top.

Export each frame to its own image file. output_pattern must contain "{frame}" (and optionally "{tag}", "{layer}"), e.g. "frames/walk_{frame}.png". Aseprite substitutes the values.

Export a sprite into a game-ready bundle directory: a flattened PNG, an animated GIF, a packed sprite sheet (+ JSON data), a GIF per animation tag, and a `manifest.json` describing everything. Args: overwrite: Replace existing bundle files (default False = no-clobber). Every planned output is checked up front, so the bundle fails before writing any file if a target already exists. Returns a ``workflow_manifest.v1`` manifest (the same object is also written to disk as manifest.json inside the bundle).

Export the full animation as an animated GIF (honours frame durations & tags). overwrite: Replace `output` if it already exists (default False = no-clobber).

Export a sprite as a Godot 4 ``SpriteFrames`` resource (.tres) + a packed sheet. Produces three files: a packed PNG sprite sheet, its JSON frame/tag metadata, and a ``SpriteFrames`` .tres that references the sheet via ``AtlasTexture`` regions — one Godot animation per Aseprite tag (or a single ``default`` animation if untagged), with per-frame timing taken from Aseprite frame durations. v1 emits ``SpriteFrames`` only (no pivot/origin/hitbox/9-slice). Aseprite tag direction isn't represented (Godot animations only loop or not); ``default_loop`` is applied to all. Args: output: Destinatio…

Export a single layer of one frame as a PNG (others excluded).

Export each layer to its own image file. output_pattern must contain "{layer}" (e.g. "layers/{layer}.png"); add "{frame}" too for animations. include_hidden also exports hidden layers.

Export a frame with neighbouring frames ghosted behind it (onion skin). Args: frame: The in-focus frame (drawn fully opaque), 1-based. previous, next: How many earlier/later frames to ghost. ghost_opacity: Max opacity (0-255) of the nearest ghost; further frames fade. scale: Integer upscaling factor for the output PNG. overwrite: Replace an existing output file. Editable .ase/.aseprite masters are never replaced.

Export one frame as a flattened PNG. Args: output: Destination .png path. frame: Frame to export, 1-based (default 1). scale: Integer upscaling factor (default 1). overwrite: Replace `output` if it already exists (default False = no-clobber).

Export every slice as engine-agnostic JSON (``aseprite_mcp.slice_metadata.v1``). Each slice becomes ``{name, type, id, bounds, pivot, nine_slice, color, data, raw_data}``. **Type detection:** a slice's user-data JSON ``type`` wins; otherwise the name convention ``<type>:<id>`` (recognized types: hitbox, hurtbox, collision, interact, pivot, origin, attach, spawn, nine_slice — anything else becomes ``"custom"``, never an error). ``id`` comes from the data ``id`` or the name's ``:<id>`` suffix. ``nine_slice`` (Aseprite's 9-patch center) and ``pivot`` are emitted whenever the slice has them. Slic…

Export frames into a single sprite-sheet image. Args: output: Destination sheet image (.png). sheet_type: one of horizontal, vertical, rows, columns, packed. scale: Integer upscaling factor. data_output: Optional .json path to also write frame/tag/slice metadata (JSON-array format) describing each frame's rectangle in the sheet. padding: Pixels of padding around/between frames. layer: Only include this layer. ignore_layer: Exclude this layer (e.g. a "reference" layer). split_layers: Lay out each layer as separate cels in the sheet. split_tags: Treat…

Export only the frames of a named animation tag as an animated GIF. overwrite: Replace `output` if it already exists (default False = no-clobber).

Export each animation tag's frames to their own files. output_pattern must contain "{tag}" (and usually "{frame}"), e.g. "anim/{tag}_{frame}.png".

Extract the unique colours used in a sprite (or another image). Args: from_image: Optional image/sprite to scan instead of `filename`. set_as_palette: Apply the extracted colours as `filename`'s palette. include_alpha: Treat differing alpha as distinct colours (default off). max_colors: Error out if more unique colours than this are found. Returns the list of "#RRGGBBAA" colours found.

Flood fill (paint bucket): replace the contiguous region of matching colour starting at (x,y) on the target layer with `color`.

Fill a region with a 2-colour checkerboard of `size`-pixel squares.

Fill a region with a gradient. Args: colors: 2+ colour stops, e.g. ["#000000", "#ff004d", "#ffec27"], spread evenly. For dither=True, provide exactly 2 colours. gradient_type: "linear" or "radial". angle: Direction in degrees for linear gradients (0 = left->right). dither: Ordered (Bayer 4x4) dithering between 2 colours instead of smooth interpolation — great for limited palettes / retro looks. x, y, width, height: Region (defaults to the whole canvas).

Fill the entire target layer/frame cel with a solid colour.

Fill an existing tile's artwork with a solid colour.

Fill the entire tilemap grid with a single tile index.

Flatten all layers into a single layer (in place).

Flip the entire sprite. direction: "horizontal" or "vertical".

Generate a shading ramp from a base colour (dark -> light). Produces `steps` colours by varying lightness across `light_range`, optionally rotating hue by `hue_shift` total degrees across the ramp (classic pixel-art hue shifting: cool shadows / warm highlights) and scaling saturation by `saturation_shift` percent across the ramp. Args: filename: If set with apply, write the ramp into that sprite's palette. apply: "none" (just return), "append" (add to palette), or "replace". Returns the ramp as a list of "#RRGGBB" colours (darkest first).

Inspect a cel: whether it exists, its position, bounds, and opacity.

Return the sprite's palette as a list of "#RRGGBBAA" colours.

Read the composited (all visible layers) pixel colours of a region. Returns rows of "#RRGGBBAA" hex strings. The region is capped at 64x64 (4096 pixels) per call to keep responses small — read in tiles for bigger areas.

Return structured info about a sprite: size, colour mode, frames (with durations), the full layer tree (names, opacity, blend mode, visibility), animation tags, and palette size.

Read the tilemap as a 2D grid of tile indices, plus tile size and count.

Check whether the Aseprite GUI can be launched (executable resolvable).

Run a self-test of the server and its Aseprite integration. Returns whether Aseprite was found, its version, the resolved workspace, the number of registered tools, and whether a real create-sprite + export-PNG round-trip succeeds. `ok` is True only if the full round-trip works.

Clean one PNG into a binary-alpha pixel grid, palette and editable master. background is an explicit #RRGGBB border-connected colour key, not semantic segmentation. outline adds a 1px eight-neighbour border, clipped at the cell edge, and may add one palette colour. N colours excludes transparency. New output directory only. Returns a nearest-neighbour preview for review. width/height support 1..256px grids. palette_first snaps the source to one shared palette before sampling, useful with majority on generated shading.

Create an editable .aseprite sprite from a flat image (.png/.bmp/.jpg/...). Args: input_image: Source raster image. output: Destination .aseprite path. overwrite: Replace an existing file at output. Defaults to False so masters are not clobbered.

Import a sequence of images as per-frame references for rotoscoping. Each image is placed on its own frame in a single dimmed, locked layer (frames are created as needed). Draw your animation on a layer above, then exclude this layer at export with ignore_layer="<layer_name>".

Invert the RGB colours of a layer's pixels (alpha preserved).

List all slices in the sprite with their bounds, center, and pivot.

List sprite/image files in the workspace directory.

Load a palette from a file (.gpl, .pal, .aseprite, .png, ...) and apply it.

Turn a single-frame sprite into a 4-frame idle "bob" loop. Duplicates frame 1 to 4 frames, nudges `layer` down by `bob_pixels` on frames 2 and 4 for a subtle bob, sets uniform durations, and adds a looping tag. Returns a ``workflow_manifest.v1`` manifest (sprite summary + animation block).

Scaffold an 8-direction walk-cycle template on an existing sprite: enough frames for `frames_per_direction` per direction, with one animation tag per direction (N, NE, E, SE, S, SW, W, NW by default). Frames are placeholders to draw over. Returns a ``workflow_manifest.v1`` manifest (kind "walk_template") with an animation block listing the directions/tags.

Merge a layer down into the layer directly beneath it.

Mirror one half of a layer onto the other (build symmetric artwork). Args: direction: "horizontal" (reflect left<->right) or "vertical" (top<->bottom). source_side: which half is copied: "first" (left/top) or "second" (right/bottom). axis: mirror line position (x for horizontal, y for vertical); default = centre.

Reorder a layer to a new 1-based stack index (1 = bottom-most). Note: moves within the layer's current parent group.

Open a sprite in the Aseprite GUI window (non-blocking) for live viewing. The window stays open and runs independently of this server. Keep editing the file with the other tools — Aseprite detects the on-disk change and prompts to reload (or reloads automatically, depending on your Aseprite preferences), so you can watch edits land without re-opening. Returns the launched process id. To stop watching, just close the Aseprite window yourself.

Draw individual pixels into a tile's artwork (tile-local coordinates). pixels: list of {"x", "y", "color"?}; falls back to the shared `color`.

Return the ordered build steps for an asset spec **without launching Aseprite**. The pure dry-run: each step is ``{tool, args, purpose}`` naming the existing tool that `build_asset_from_spec` would call. Returns a ``workflow_manifest.v1`` (kind ``asset_spec``) with the steps under `plan` and `dry_run=true`. If the spec is invalid, returns the validation report instead.

Replace colours across every layer, frame and palette entry of a sprite. Use it to turn one character template into another (new shirt, hair, skin). Each source colour is matched per channel within `tolerance` and replaced by its target; every pixel is mapped once from its original value, so swaps such as A->B and B->A work. With `output`, the recoloured sprite is saved as a new file and the original is left untouched. Args: mapping: Source colour -> target colour, e.g. {"#3060c0": "#c03030"}. output: Optional new .aseprite path. Without it the sprite is edited in place. toleranc…

Delete a frame (1-based). The sprite must have more than one frame.

Delete a layer (or group, including its children) by name or 1-based index.

Delete a slice by name.

Delete an animation tag by name.

Rename a layer.

Render a single frame to a PNG and return it as an image you can view. Use this to *see* your work. frame is 1-based; scale enlarges small sprites (default 8x) so individual pixels are visible.

Replace every pixel matching `from_color` (within `tolerance` per channel) with `to_color`, on the chosen layer + frame.

Resize the canvas WITHOUT scaling the artwork (adds or trims space). anchor controls where existing content sits in the new canvas: "top_left" (default) or "center".

Resize the palette to `size` entries (new entries are black).

Rotate the entire sprite by 90, 180, or 270 degrees (clockwise).

Save a copy of a sprite under a new path (optionally flattened). The original file is left untouched. Useful for exporting an editable .aseprite to another .aseprite, or snapshotting a version. overwrite: Replace `new_filename` if it already exists (default False = no-clobber).

Scale the whole sprite (artwork included). Provide either `factor` (e.g. 2.0 to double) OR explicit `width`/`height`. method: "nearest" (crisp pixels, default) or "bilinear" (smooth).

Set every frame's duration in milliseconds (uniform animation speed).

Set a cel's opacity (0-255).

Move a cel's image to position (x, y) within the canvas.

Convert a sprite between colour modes ("rgb", "indexed", "gray"). When converting to "indexed", dithering can be "none", "ordered", or "old" to control how RGB colours are mapped to the palette.

Set a single frame's duration in milliseconds (1-based frame).

Update one or more layer properties. Only the arguments you pass are changed.

Replace the entire palette with the given list of colours. colors: list of colour strings, e.g. ["#000000", "#ffffff", "255,0,0"].

Set a single palette entry by index (0-based). Grows the palette if needed.

Update an existing slice's bounds, name, colour, or data.

Update an existing tag. Only the arguments you pass are changed. Note: changing from_frame/to_frame recreates the tag in place to update its range reliably across Aseprite versions.

Place a tile (by tileset index, 0 = empty) at grid cell (column, row).

Place many tiles at once. tiles: list of {"column", "row", "index"}.

Set which palette index is treated as transparent (indexed sprites only).

Sort the palette by "hue", "luminance" (default), "saturation", or "value". For indexed sprites the pixel indices are remapped so the image looks identical.

Composite another image/sprite file onto a layer at (x, y). Args: source: Path to a .aseprite/.png/.bmp/... to stamp in. x, y: Top-left placement on the target canvas. source_frame: Which frame of the source to use (1-based). opacity: 0-255. blend_mode: Blend mode for compositing (normal, multiply, …).

Tile an image/sprite across a region to fill it with a repeating pattern. Args: source: Image/sprite to tile. x, y, width, height: Region to fill (defaults to the whole canvas). spacing_x, spacing_y: Gap between tiles. opacity, blend_mode: Compositing of each tile.

Auto-crop the canvas to the bounding box of all non-transparent content (across every frame).

Validate an ``aseprite_mcp.asset_spec.v1`` document (does the *spec* make sense?). Checks the schema, kind, canvas, per-kind fields, palette, layers, animations (`frame_count`, not `frames`), slices, and export formats. Returns a ``workflow_manifest.v1`` (kind ``asset_spec``) with a `validation` block `{passed, checks, errors, warnings}`. This does **not** check a finished sprite against the spec — that's a separate future tool.

Check whether a sprite is game-ready against the criteria you specify. Runs a series of checks — does the file open, do dimensions match (exactly or as a tile multiple), is the colour mode allowed, are frame counts / required animation tags present, is the background transparent, is the palette within budget, do expected export files exist, and is sprite-sheet metadata readable — plus soft warnings for oversized canvases, missing tags, and default/blank layer names. All criteria are optional; only the ones you pass are enforced. Returns a ``workflow_manifest.v1`` manifest (kind "validation")…