Create a new pixel art document. Palette is a preset name (gameboy, grayscale4, pico8, sweetie16, nes) or a list of hex colors; index 0 is always transparent.

Import a PNG image as a new document from exactly one of png_base64 or path, quantizing to at most max_colors colors. Max 256x256.

Extract a color palette from a PNG supplied as exactly one of png_base64 or path, with median-cut quantization, WITHOUT creating a document. Returns a list of hex colors ready to pass to create_document(palette=[...]) (or add_palette_color), plus a swatch render so the colors are visible. Use this to pull a palette from a reference image; use open_document when you also want its pixels.

Export the document to a real file and return its absolute path. png: one frame with true transparency. gif: all frames animated. aseprite_json: JSON with embedded spritesheet. This is delivery for humans — the response contains no rendered image; use view/view_frames for perception.

Split a regular PNG sprite sheet into separate pixel-mcp documents in row-major order. Provide exactly one of png_base64 or path. Supports sheet margins and spacing between cells; transparent cells are skipped by default.

Pack document frames into a transparent PNG sprite sheet in row-major order and write it to disk. Sprites may have different sizes; cell dimensions default to the largest sprite. This is delivery output and returns no preview image.

Resize the canvas. Existing content is placed according to the anchor; new area is transparent. Clears saved selections.

Undo the last edit(s).

Redo previously undone edit(s).

Full document state: size, palette with usage counts, layers, frames, symmetry, stamps, selections.

List all documents, including ones persisted by other sessions sharing the data dir.

Permanently delete a document from memory and disk. Cannot be undone.

Set the document symmetry mode. While set, drawing and region tools mirror writes across the canvas center automatically.

Set seamless-tiling mode. While set, drawing tools wrap across the tiling edges (a stroke off one side continues on the opposite side) and the tile_seams lint rule activates. 'horizontal' tiles left-right, 'vertical' top-bottom, 'both' for a full repeat. Use view_tiled to check seams.

Set the default target layer for editing tools.

Set the default target frame for editing tools.

Label the current state for later comparison with view_diff.

Change the color (and optionally name) of a palette entry. All pixels using the index update visually.

Append a color to the palette. Fails when the palette is full (64 entries).

Delete a palette entry, remapping its pixels to remap_to. Higher indices shift down by one.

Swap two palette entries and all pixel references to them. The image looks unchanged.

Append a shading ramp built around a base color (dark to light). Shadows hue-shift toward cool, highlights toward warm.

Blend two palette colors and store the result. The indexed-color way to make an in-between shade: t interpolates from color a (0) to color b (1). Appends a new entry by default, or overwrites into_index.

Nudge a palette color in HSL space: darken/lighten via lightness, shift saturation or hue. Saves the model from hand-computing hex. Edits in place (all pixels using it update), or appends a fresh variant with as_new.

Replace every pixel of one palette index with another on a layer (palette untouched). Optionally restricted to a region.

Set individual pixels to palette indices.

Draw a Bresenham line. no_doubles removes L-shaped double pixels for pixel-perfect diagonals.

Draw a rectangle (outline or filled).

Draw an ellipse centered at (cx,cy) with radii rx,ry (outline or filled).

Flood fill from a seed pixel. contiguous=false recolors every pixel that matches the seed color.

Draw a 1px border around all non-transparent pixels of the layer (or region). 'outside' draws into transparent pixels; 'inside' onto the shape's edge.

Bulk-write a region from grid text (one char per pixel, '.'=transparent, then 1-9, a-z, A-Z, '#', '@' for palette indices 1-63; rows top to bottom). The workhorse for blocking in shapes.

Darken or lighten existing pixels. A pixel whose color is part of a ramp steps along that ramp; otherwise it snaps to the nearest palette color in that direction. mode 'ramp' only moves ramp colors, 'nearest' ignores ramps, 'auto' (default) does ramp-then-nearest. Operates on the whole layer unless a region is given.

Fill a region with an ordered-dither gradient between two palette colors. The indexed-color way to blend a smooth-looking transition: from_index at one end, to_index at the other. axis horizontal/vertical/radial; pattern bayer (4x4, smoother) or checker (2x2, coarser). Either index may be 0 to fade to/from transparent.

Randomly scatter pixels from a set of palette indices across a region, at the given coverage density (0-1). For grain and noise: stone, dirt, wood texture. Deterministic for a given seed, so the same call reproduces the same grain. weights biases which indices are picked.

Import an external PNG supplied as exactly one of png_base64 or path onto the canvas. Resamples to width x height (default native size), maps to the document palette ('document') or extends the palette with median-cut colors ('extend'), then writes it to a layer at (x,y). With as_stamp it is stored as a named stamp instead (place later with paste_stamp). Unlike open_document (new doc) this drops pixels into the current canvas.

Copy a region into a named stamp for later paste_stamp.

Copy a region into a named stamp and clear it from the layer.

Paste a named stamp with optional flips and rotation. Transparent stamp pixels are skipped by default. Unlike other tools, paste_stamp ignores document symmetry by default: stamps are placed content, and mirroring would silently flip deliberate asymmetry.

Copy a region of pixels from another document into this one, lossless in palette-index space — the assembly tool for multi-agent fan-out: subagents draw parts in their own documents, then a parent composes them. Source colors map to identical destination palette entries where they exist; the rest are appended ('extend', default) or snapped to the perceptually nearest existing entry ('nearest'). Placed content: ignores symmetry by default, like paste_stamp.

Move a region by (dx,dy), clearing its old location.

Mirror a region in place across its own bounding-box axis.

Translate the whole layer by (dx,dy), optionally wrapping around the edges.

Set every pixel in a region to transparent.

Store a named selection that region parameters can reference later.

Add a new transparent layer (becomes the active layer).

Delete a layer and its pixels on every frame.

Rename a layer.

Move a layer to a new position in the stack (0 = bottom).

Show or hide a layer.

Lock or unlock a layer against edits.

Merge a layer into the one below it. Non-transparent top pixels replace bottom pixels; partial layer opacity is discarded.

Render the canvas (or a region) as a PNG. The primary perception tool: call it after every couple of edits.

Read pixels as grid text (max 64x64; use view_window or a region for bigger canvases).

Compare the current state against a checkpoint: before, after, and changed-pixels panels.

Zoomed view of a 16 or 32 px window plus a whole-canvas thumbnail with the window marked. The intended workflow for 64px+ canvases.

Render the canvas repeated reps x reps so tiling seams are visible, with the tile boundaries marked in faint red. The perception tool for seamless textures — a tile only reads as seamless when you see it tiled. Pairs with set_tile_mode and the tile_seams lint rule.

Store a reference PNG supplied as exactly one of png_base64 or path under an id for quantizing or side-by-side viewing.

Downsample a reference to the given size and map it to the document palette ('document') or to a fresh median-cut palette appended to the document ('auto'). Optionally write the result into a layer.

Render a reference image, optionally beside the current canvas at matched display size.

Append a frame (optionally duplicating an existing one). The new frame becomes active.

Delete a frame.

Move a frame to a new position on the timeline.

Set how long a frame displays (ms).

Copy one layer's pixels from one frame to another.

Render frames as a horizontal strip. With onion, each frame shows the previous frame at 40% opacity beneath it. This (plus per-frame view) is the perception tool for animation — use it to verify motion, not preview_gif.

Render the animation as a GIF (on checkerboard background). Human-facing output only: most clients show a GIF as a single still in model context, so it verifies nothing — use view_frames to check motion.

Run pixel-art quality checks and return findings with a render circling them. Rules: orphans, doubles, banding, pillow_shading, unused_colors, near_duplicates, broken_outline, symmetry_drift, stray_alpha, tile_seams. Findings are advisory; nothing is auto-fixed.

Persistently waive lint findings so they stay waived on every future pass (reported only as a count). Scope to a region to waive only there; omit the region to waive the whole rule.

Remove a lint waiver by id, or all waivers for the document when no id is given.