Aseprite Agent MCP

Append a new frame to the animation. Args: duration_ms: Frame duration in milliseconds (default 100). copy_from: If given (1-based), duplicate the content of that frame; otherwise the new frame is empty. Returns the new frame number and updated frame count.

Add a new (empty) normal layer on top of the stack. Args: name: Layer name. group: Optional name of an existing group layer to nest the new layer in. opacity: 0-255. blend_mode: normal, multiply, screen, overlay, darken, lighten, color_dodge, color_burn, hard_light, soft_light, difference, exclusion, hue, saturation, color, luminosity, addition, subtract, divide. visible: Initial visibility.

Create an animation tag spanning frames [from_frame, to_frame] (1-based). direction: "forward" (default), "reverse", "pingpong", or "pingpong_reverse". color: optional tag colour (shown in the timeline).

Apply a list of edit operations to a sprite in one atomic, single-process batch. If any op fails, the whole batch is rolled back, nothing is saved, and the error names the failing op index. dry_run=true checks the list without launching Aseprite (shape only; a missing layer still fails on a real run). Returns a workflow_manifest.v1 with a per-op operations list. Each operation is {"op": "<name>", "args": {...}}. Ops run in order against the same open sprite, so later ops see earlier ones (add a layer, then draw on it). Coordinates are pixels from the top-left (0,0); frames are 1-based and must exist; layer is a name or 1-based index and defaults to the top layer; durations are milliseconds. '?' marks an optional arg. - add_layer(name:str, opacity?:int, blend_mode?:str, visible?:bool): new layer on top - rename_layer(layer:str, new_name:str): rename a layer - set_layer_visible(layer:str, visible:bool): show or hide a layer - set_layer_opacity(layer:str, opacity:int): layer opacity 0-255 - remove_layer(layer:str): delete a layer (not the last one) - add_frame(duration_ms?:int, copy_from?:int): append a frame (copy_from copies an existing frame) - duplicate_frame(frame:int): insert a copy of a frame after it - set_frame_duration(frame:int, duration_ms:int): frame duration in milliseconds - add_tag(name:str, from:int, to:int, direction?:str, color?:color): animation tag over frames from..to (direction forward|reverse|pingpong) - remove_tag(name:str): delete a tag by name - set_pixel(layer?:str, frame?:int, x:int, y:int, color:color): one pixel - draw_line(layer?:str, frame?:int, x1:int, y1:int, x2:int, y2:int, color:color): 1px line between two points - draw_rectangle(layer?:str, frame?:int, x:int, y:int, width:int, height:int, color:color): rectangle outline - fill_rectangle(layer?:str, frame?:int, x:int, y:int, width:int, height:int, color:color): filled rectangle - draw_ellipse(layer?:str, frame?:int, cx:int, cy:int, rx:int, ry:int, color:color): ellipse outline -…

Atomically apply typed batch operations to a native master, then return the result and a nearest-neighbour PNG of `frame` at `scale` (1-16). Save succeeds before the preview; a preview failure is reported as saved, not rolled back. Each operation is {"op": "<name>", "args": {...}}. Ops run in order against the same open sprite, so later ops see earlier ones (add a layer, then draw on it). Coordinates are pixels from the top-left (0,0); frames are 1-based and must exist; layer is a name or 1-based index and defaults to the top layer; durations are milliseconds. '?' marks an optional arg. - add_layer(name:str, opacity?:int, blend_mode?:str, visible?:bool): new layer on top - rename_layer(layer:str, new_name:str): rename a layer - set_layer_visible(layer:str, visible:bool): show or hide a layer - set_layer_opacity(layer:str, opacity:int): layer opacity 0-255 - remove_layer(layer:str): delete a layer (not the last one) - add_frame(duration_ms?:int, copy_from?:int): append a frame (copy_from copies an existing frame) - duplicate_frame(frame:int): insert a copy of a frame after it - set_frame_duration(frame:int, duration_ms:int): frame duration in milliseconds - add_tag(name:str, from:int, to:int, direction?:str, color?:color): animation tag over frames from..to (direction forward|reverse|pingpong) - remove_tag(name:str): delete a tag by name - set_pixel(layer?:str, frame?:int, x:int, y:int, color:color): one pixel - draw_line(layer?:str, frame?:int, x1:int, y1:int, x2:int, y2:int, color:color): 1px line between two points - draw_rectangle(layer?:str, frame?:int, x:int, y:int, width:int, height:int, color:color): rectangle outline - fill_rectangle(layer?:str, frame?:int, x:int, y:int, width:int, height:int, color:color): filled rectangle - draw_ellipse(layer?:str, frame?:int, cx:int, cy:int, rx:int, ry:int, color:color): ellipse outline - fill_ellipse(layer?:str, frame?:int, cx:int, cy:int, rx:int, ry:int, color:color): filled ellipse - fill_layer(layer?:str, frame?:int…

Validate several character masters and export them as ONE Phaser atlas. Each member is validated against its own contract; if any fails, nothing is written and every failure is returned. Characters are stacked as row blocks in one sheet.png. Atlas frames are "<character>/<tag>_<nn>" and animations are "<character>:<tag>", all under the atlas key `name`. Every frame of every master is reopened and compared pixel-for-pixel with the written sheet before publishing.

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) or a plain 8-column grid (False).

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 prior pipeline.

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 neither, every frame is copied. layer: Destination layer name or 1-based index (default: top layer). new_tag: Optionally tag the copied frames with this name (must not exist yet).

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 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" (up/down).

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). Map a character to "transparent" to erase pixels. layer: Layer name or 1-based index (default: top layer). frame: 1-based frame; it must already exist. clear: Erase the whole cel before drawing (use for full-frame redraws).

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 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.

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.

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

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

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.

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.

List sprite/image files in the workspace directory.

Load a palette from a file (.gpl, .pal, .aseprite, .png, ...) and apply 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.

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. tolerance: Per-channel match tolerance 0-255 (default exact). overwrite: Allow `output` to replace an existing file. Returns per-colour pixel counts; a source colour with zero matches is listed under `unmatched` so a typo is visible.

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

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.

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).

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

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"].

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.