examples

Aseprite MCP Client Examples

This directory contains example clients demonstrating how to use the Aseprite MCP server.

Examples

Basic Client (client/)

The client/ directory contains a complete example MCP client that demonstrates:

• Connecting to the Aseprite MCP server via stdio transport
• Creating a 64x64 RGB sprite
• Adding and deleting layers and frames
• Flattening multiple layers into a single layer
• Drawing animated content (growing circles)
• Drawing polylines and polygons (zigzag, triangle, star)
• Filling areas with colors
• Reading pixels for verification (using get_pixels with pagination)
• Applying dithering patterns for professional gradients
• Analyzing palette harmonies (complementary, triadic, temperature)
• Setting custom limited palettes
• Palette Management: Getting, setting, modifying, adding colors, and sorting palettes
• Applying palette-constrained shading with light direction
• Palette-aware drawing with automatic color snapping
• Detecting and smoothing jagged edges with antialiasing
• Transform Operations: Flipping, rotating, and scaling sprites with algorithm selection
• Drawing operations (demonstrating rectangle and circle tools as alternatives to copy/paste)
• Retrieving sprite metadata
• Exporting to GIF and PNG

Note: Selection tools (select_rectangle, select_ellipse, etc.) are demonstrated in integration tests. Selections are transient and don't persist across tool calls, so copy/paste workflows require combining operations in single Lua scripts.

Palette Quantization Example (quantization/)

The quantization/ directory demonstrates color reduction and palette optimization:

• Creating a high-color gradient with ~16,000 unique colors
• Reducing to 16 colors using three algorithms: median_cut, k-means, and octree
• Optional Floyd-Steinberg dithering for smoother gradients
• Testing different color counts (16, 8, 4 colors)
• Converting sprites to indexed color mode
• Generating side-by-side comparison of all four algorithms
• Exporting quantized sprites as PNG files

Output files:

• sprites/quantization-original.png - Full color gradient
• sprites/quantization-median_cut-16colors.png - Median cut algorithm
• sprites/quantization-median_cut-16colors-dither.png - With Floyd-Steinberg dithering
• sprites/quantization-kmeans-16colors.png - K-means clustering
• sprites/quantization-octree-16colors.png - Octree quantization
• sprites/quantization-median_cut-8colors.png - 8 colors
• sprites/quantization-median_cut-4colors-dither.png - 4 colors with dithering
• sprites/quantization-comparison.png - Side-by-side comparison (Original | Median Cut | K-means | Octree)

Automatic Shading Example (shading/)

The shading/ directory demonstrates geometry-based automatic shading:

• Three shading styles: cell (hard-edged bands), smooth (dithered gradients), soft (subtle blending)
• Eight light directions: top_left, top, top_right, left, right, bottom_left, bottom, bottom_right
• Adjustable intensity (0.0-1.0) for controlling shadow/highlight strength
• Optional hue shifting (shadows→cool, highlights→warm)
• Automatic per-pixel normal calculations for spherical surfaces
• Multiple shape examples: sphere, cube, pill (capsule)
• Comparison sprites showing all light directions and hue shift effects

Output files:

• sprites/shading-cell-sphere.png - Sphere with cell shading
• sprites/shading-cell-cube.png - Cube with cell shading
• sprites/shading-cell-pill.png - Capsule with cell shading
• sprites/shading-smooth-subtle.png - Smooth shading (intensity 0.3)
• sprites/shading-smooth-medium.png - Smooth shading (intensity 0.6)
• sprites/shading-smooth-strong.png - Smooth shading (intensity 0.9)
• sprites/shading-soft-sphere.png - Soft shading
• sprites/shading-directions.png - Comparison of all 8 light directions
• sprites/shading-hueshift-with-hueshift.png - With hue shifting
• sprites/shading-hueshift-no-hueshift.png - Without hue shifting

Running the Examples

Prerequisites

1. Build the Aseprite MCP server:

   cd ../..
   make build

2. Ensure you have Aseprite configured at ~/.config/pixel-mcp/config.json

Run the Examples

# Basic client example
cd examples/client
go run main.go

# Palette quantization example
cd examples/quantization
go run main.go

# Automatic shading example
cd examples/shading
go run main.go

# Or set custom server path for any example
ASEPRITE_MCP_PATH=/path/to/pixel-mcp go run main.go

Basic Client Output

The basic client example creates:

• ../sprites/animated-example.gif - 4-frame animation with growing colored circles on blue background
• ../sprites/frame2-example.png - Single frame export (frame 2, green circle)
• ../sprites/dithered-gradient.png - Demonstration of Bayer 4x4 dithering pattern
• ../sprites/shaded-sphere.png - 64x64 sphere with palette-constrained smooth shading from light to dark
• ../sprites/palette-drawing-comparison.png - Side-by-side comparison: pastel colors (left) vs palette-snapped pure colors (right)
• ../sprites/antialiasing-before.png - Jagged diagonal line (stair-step pattern)
• ../sprites/antialiasing-after.png - Smoothed diagonal with intermediate colors applied
• ../sprites/transform-demo.png - Transform operations: triangle flipped, rotated, and scaled 2x
• ../sprites/animation-spritesheet.png - 4-frame horizontal spritesheet with growing colored circles
• ../sprites/animation-spritesheet.json - JSON metadata for spritesheet
• ../sprites/saved-animation.aseprite - Sprite saved with save_as tool
• ../sprites/imported-spritesheet.png - Result of importing spritesheet as layer
• /tmp/selection-demo.png - Drawing demo showing red squares and blue circle

Example Output

Aseprite MCP Client Example
===========================

Starting server: ../../bin/pixel-mcp
Connecting to server...
Connected!

Available tools:
  - create_canvas: Create a new Aseprite sprite
  - add_layer: Add a new layer to the sprite
  - delete_layer: Delete a layer from the sprite
  - flatten_layers: Flatten all layers into a single layer
  - add_frame: Add a new frame to the sprite timeline
  - delete_frame: Delete a frame from the sprite
  - get_sprite_info: Get metadata about a sprite
  - get_pixels: Read pixel data from a rectangular region (with pagination)
  - draw_pixels: Draw individual pixels on a layer
  - draw_line: Draw a line on a layer
  - draw_contour: Draw polylines and polygons by connecting points
  - draw_rectangle: Draw a rectangle on a layer
  - draw_circle: Draw a circle on a layer
  - fill_area: Fill an area with a color (paint bucket tool)
  - draw_with_dither: Fill region with dithering patterns for gradients/textures
  - analyze_reference: Extract palette, edges, and composition from reference images
  - downsample_image: Convert high-res images to pixel art dimensions
  - set_palette: Set sprite's color palette
  - get_palette: Retrieve current sprite palette as hex color array
  - set_palette_color: Set specific palette index to a color
  - add_palette_color: Add new color to palette
  - sort_palette: Sort palette by hue, saturation, brightness, or luminance
  - apply_shading: Apply palette-constrained shading with light direction
  - analyze_palette_harmonies: Analyze color relationships and temperature
  - flip_sprite: Flip sprite horizontally or vertically (sprite/layer/cel targets)
  - rotate_sprite: Rotate sprite by 90, 180, or 270 degrees
  - scale_sprite: Scale sprite with algorithm selection (nearest/bilinear/rotsprite)
  - crop_sprite: Crop sprite to rectangular region
  - resize_canvas: Resize canvas with anchor positioning
  - apply_outline: Apply outline effect to layer with thickness
  - export_spritesheet: Export animation frames as spritesheet with layout options
  - import_image: Import external image file as a layer
  - save_as: Save sprite to a new .aseprite file path
  - delete_tag: Delete an animation tag by name
  - select_rectangle: Create rectangular selection with mode (replace/add/subtract/intersect)
  - select_ellipse: Create elliptical selection with mode
  - select_all: Select entire canvas
  - deselect: Clear selection
  - move_selection: Move selection bounds by offset
  - cut_selection: Cut selected pixels to clipboard
  - copy_selection: Copy selected pixels to clipboard
  - paste_clipboard: Paste clipboard content at position
  - export_sprite: Export sprite to image file

Step 1: Creating 64x64 RGB canvas...
  Created: /tmp/pixel-mcp/sprite-123456.aseprite

Step 2: Adding 'Background' layer...
  Layer added

Step 3: Filling background with blue...
  Background filled

Step 4: Adding 3 animation frames...
  Frames added (4 total)

Step 5: Drawing animated circles...
  Frame 1: radius 8, color #FF0000
  Frame 2: radius 11, color #00FF00
  Frame 3: radius 14, color #FFFF00
  Frame 4: radius 17, color #FF00FF

Step 6: Reading pixels from frame 2 to verify drawing...
  Read 100 pixels from center region
  Found 78 green pixels in the region

Step 7: Getting sprite metadata...
  Info: {"width":64,"height":64,"color_mode":"RGB","frame_count":4,"layer_count":2,"layers":["Background","Layer 1"]}

Step 8: Exporting as GIF...
  Exported: ../sprites/animated-example.gif

Step 9: Exporting frame 2 as PNG...
  Exported: ../sprites/frame2-example.png

Step 10: Creating sprite with dithered gradient...
  Created: /tmp/pixel-mcp/sprite-789012.aseprite

Step 11: Applying Bayer 4x4 dithering pattern...
  Dithering applied successfully

Step 12: Exporting dithered gradient...
  Exported: ../sprites/dithered-gradient.png

Step 13: Analyzing palette harmonies from our colors...
  Dominant temperature: warm
  Found 2 complementary pairs

Step 14: Creating sprite with limited palette...
  Created: /tmp/pixel-mcp/sprite-456789.aseprite
  Palette set successfully (8 colors)

Step 15: Drawing shape with palette-constrained shading...
  Shading applied successfully
  Exported: ../sprites/shaded-sphere.png

Step 16: Demonstrating palette-aware drawing...
  Created: /tmp/pixel-mcp/sprite-...
  Palette-aware drawing completed (left: pastel colors, right: snapped to pure colors)
  Exported: ../sprites/palette-drawing-comparison.png

Step 17: Demonstrating antialiasing suggestions...
  Created: /tmp/pixel-mcp/sprite-...
  Found 4 jagged edge positions
    - Suggestion 1: pos=(24,11) direction=diagonal_nw
    - Suggestion 2: pos=(25,12) direction=diagonal_nw
    - Suggestion 3: pos=(26,13) direction=diagonal_nw
  Antialiasing applied: jagged diagonal smoothed
  Exported before: ../sprites/antialiasing-before.png
  Exported after: ../sprites/antialiasing-after.png

Step 17: Demonstrating layer and frame deletion...
  Created: /tmp/pixel-mcp/sprite-...
  Added 2 extra layers (3 total)
  Added 2 extra frames (3 total)
  Deleted Layer 2 (2 layers remaining)
  Deleted frame 2 (2 frames remaining)
  Final state: {"width":32,"height":32,"color_mode":"RGB","frame_count":2,"layer_count":2,"layers":["Layer 1","Layer 3"]}
  Flattening remaining 2 layers into 1...
  Layers flattened successfully
  After flattening: {"width":32,"height":32,"color_mode":"RGB","frame_count":2,"layer_count":1,"layers":["Layer 1"]}

Step 18: Demonstrating polylines and polygons...
  Drawing zigzag polyline on frame 1...
  Drawing triangle on frame 2...
  Drawing star on frame 3 with palette snapping...
  ✓ Drew polylines and polygons successfully

Step 19: Demonstrating palette management tools...
  Creating indexed color sprite for palette demo...
  Setting custom 8-color palette...
  ✓ Custom palette set successfully
  Retrieving palette with get_palette...
  ✓ Retrieved palette with 8 colors: [#000000 #FFFFFF #FF0000 #00FF00 #0000FF #FFFF00 #FF00FF #00FFFF]
  Changing color at index 2 to orange (#FF8000)...
  ✓ Palette color updated successfully
  Adding new color (brown #8B4513) to palette...
  ✓ Added color at index 8
  Sorting palette by hue (ascending)...
  ✓ Palette sorted by hue
  Retrieving sorted palette...
  ✓ Sorted palette has 9 colors: [#000000 #FFFFFF #FF0000 #FF8000 #FFFF00 #00FF00 #00FFFF #0000FF #FF00FF]

Step 20: Demonstrating transform operations (flip, rotate, scale)...
  Creating 64x64 sprite with asymmetric triangle...
  Triangle drawn (pointing right)
  Flipping sprite horizontally...
  ✓ Triangle now points left
  Rotating sprite 90 degrees clockwise...
  ✓ Sprite rotated successfully
  Scaling sprite 2x with nearest neighbor algorithm...
  ✓ Sprite scaled from 64x64 to 128x128
  Exported: ../sprites/transform-demo.png

Step 21: Demonstrating selection and clipboard operations...
  Creating sprite for selection demo...
  Drawing red square (20x20 at 20,20)...
  Copying red square to position (60, 60) using draw_rectangle...
  Drawing blue circle (radius 15 at 30,80)...
  Exporting selection demo to: /tmp/selection-demo.png
  ✓ Drawing operations completed successfully
  ✓ Result saved to: /tmp/selection-demo.png
  Note: Selection tools work within single Lua scripts but don't persist across tool calls

Step 22: Demonstrating advanced export tools (spritesheet, import, save_as, delete_tag)...
  Creating 16x16 animated sprite with 4 frames...
  Creating animation tags...
  Exporting as horizontal spritesheet with JSON metadata...
  ✓ Exported spritesheet: ../sprites/animation-spritesheet.png (4 frames)
  ✓ JSON metadata: ../sprites/animation-spritesheet.json
  Deleting temporary tag 'temp_tag'...
  ✓ Tag deleted successfully
  Saving sprite to new location...
  ✓ Sprite saved to: ../sprites/saved-animation.aseprite
  Creating new sprite to import spritesheet...
  Importing spritesheet as a layer...
  ✓ Spritesheet imported as layer
  ✓ Exported imported result: ../sprites/imported-spritesheet.png

Example completed successfully!

Building Your Own Client

To create your own MCP client for Aseprite:

1. Import the MCP SDK:

   import "github.com/modelcontextprotocol/go-sdk/mcp"

2. Start the server as a subprocess:

   cmd := exec.Command("/path/to/pixel-mcp")
   clientTransport, serverTransport := mcp.NewStdioServerTransport(cmd)

3. Create and connect the client:

   client := mcp.NewClient(&mcp.Implementation{
       Name:    "my-client",
       Version: "1.0.0",
   })
   client.Connect(ctx, clientTransport)
   serverTransport.Start()

4. Call tools:

   args, _ := json.Marshal(map[string]interface{}{
       "width": 64,
       "height": 64,
       "color_mode": "rgb",
   })
   resp, _ := client.CallTool(ctx, &mcp.CallToolRequest{
       Name: "create_canvas",
       Arguments: args,
   })

See client/main.go for a complete working example.