Aseprite MCP Tools

Instructions

Implementation Reference

• aseprite_mcp/tools/drawing.py:202-237 (handler)

  The MCP tool handler function 'fill_area' which validates inputs, builds a Lua script for Aseprite, and executes it.

  @mcp.tool()
  async def fill_area(filename: str, x: int, y: int, color: str = "#000000", tolerance: int = 0) -> str:
      """Fill an area with color using the paint bucket tool.
  
      Args:
          filename: Name of the Aseprite file to modify
          x: X coordinate to fill from
          y: Y coordinate to fill from
          color: Hex color code (default: "#000000")
          tolerance: Tolerance for color matching (0-255, default: 0)
      """
      try:
          # Validate inputs
          file_path = validate_file_path(filename, must_exist=True)
          color = validate_color(color)
          
          if tolerance < 0 or tolerance > 255:
              raise ValidationError("tolerance", tolerance, "Tolerance must be between 0 and 255")
          
          # Build Lua script
          builder = LuaBuilder()
          builder.add_line('local spr = app.activeSprite')
          builder.if_condition('not spr')
          builder.add_line('error("No active sprite")')
          builder.end_if()
          builder.add_line()
          
          builder.begin_transaction()
          builder.fill_area(x, y, color, tolerance)
          builder.end_transaction()
          builder.save_sprite()
          
          # Execute script
          cmd = get_command()
          success, output = cmd.execute_lua_script(builder.build(), str(file_path))

• aseprite_mcp/core/lua_builder.py:187-198 (helper)

  The 'LuaBuilder' method 'fill_area' that generates the specific Lua script lines for the Aseprite paint bucket tool.

  def fill_area(self, x: int, y: int, color: str, tolerance: int = 0) -> 'LuaBuilder':
      """Fill an area with color (paint bucket)."""
      self.set_color(color)
      
      self.add_line('app.useTool{')
      self.indent()
      self.add_line('tool="paint_bucket",')
      self.add_line(f'points={{{{x={x}, y={y}}}}},')
      self.add_line(f'tolerance={tolerance}')
      self.dedent()
      self.add_line('}')
      return self