Philips Hue MCP Server

""" Validation utilities for Philips Hue MCP tools. Centralizes all parameter validation logic for consistency and reusability. This module ensures DRY principles by providing reusable validation functions that can be shared across all tool implementations. """ from typing import Any, List from .hue_client import ( BRIGHTNESS_MIN_HUE_API, BRIGHTNESS_MAX_HUE_API, COLOR_TEMP_MIN_MIREDS, COLOR_TEMP_MAX_MIREDS, CIE_XY_MIN, CIE_XY_MAX, ) def _validate_required_string_id(id_value: Any, id_name: str) -> None: """ Validate that an ID parameter is provided, is a string, and is not empty. Args: id_value: The ID value to validate id_name: The name of the ID parameter (for error messages) Raises: ValueError: If id_value is None, empty, whitespace-only, or not a string Example: >>> _validate_required_string_id("abc123", "light_id") # OK >>> _validate_required_string_id("", "light_id") # Raises ValueError >>> _validate_required_string_id(None, "light_id") # Raises ValueError >>> _validate_required_string_id(123, "light_id") # Raises ValueError """ if not id_value or (isinstance(id_value, str) and not id_value.strip()): raise ValueError(f"{id_name} is required and cannot be empty") if not isinstance(id_value, str): raise ValueError(f"{id_name} must be a string, got {type(id_value).__name__}") def validate_light_id(light_id: Any) -> None: """ Validate light ID parameter. Args: light_id: The light ID to validate Raises: ValueError: If light_id is invalid """ _validate_required_string_id(light_id, "light_id") def validate_group_id(group_id: Any) -> None: """ Validate group ID parameter. Args: group_id: The group ID to validate Raises: ValueError: If group_id is invalid """ _validate_required_string_id(group_id, "group_id") def validate_scene_id(scene_id: Any) -> None: """ Validate scene ID parameter. Args: scene_id: The scene ID to validate Raises: ValueError: If scene_id is invalid """ _validate_required_string_id(scene_id, "scene_id") def validate_brightness(brightness: Any) -> None: """ Validate brightness value is within acceptable range. The Hue API accepts brightness values from 0 (minimum) to 254 (maximum). Note that 0 does not turn the light off - use turn_light_off for that. Args: brightness: The brightness value to validate (0-254) Raises: ValueError: If brightness is not a number or out of range Example: >>> validate_brightness(127) # OK >>> validate_brightness(254) # OK >>> validate_brightness(255) # Raises ValueError >>> validate_brightness("100") # Raises ValueError """ if not isinstance(brightness, (int, float)): raise ValueError(f"brightness must be a number, got {type(brightness).__name__}") if brightness < BRIGHTNESS_MIN_HUE_API or brightness > BRIGHTNESS_MAX_HUE_API: raise ValueError( f"brightness must be between {BRIGHTNESS_MIN_HUE_API} " f"and {BRIGHTNESS_MAX_HUE_API}" ) def validate_color_temperature(color_temp: Any) -> None: """ Validate color temperature value is within acceptable range. Color temperature is measured in mireds (micro reciprocal degrees). Lower values (153) are cooler/bluer, higher values (500) are warmer/redder. Args: color_temp: The color temperature value to validate (153-500 mireds) Raises: ValueError: If color_temp is not a number or out of range Example: >>> validate_color_temperature(300) # OK - neutral white >>> validate_color_temperature(153) # OK - cool white >>> validate_color_temperature(500) # OK - warm white >>> validate_color_temperature(100) # Raises ValueError """ if not isinstance(color_temp, (int, float)): raise ValueError(f"color_temp must be a number, got {type(color_temp).__name__}") if color_temp < COLOR_TEMP_MIN_MIREDS or color_temp > COLOR_TEMP_MAX_MIREDS: raise ValueError( f"color_temp must be between {COLOR_TEMP_MIN_MIREDS} " f"and {COLOR_TEMP_MAX_MIREDS} mireds" ) def validate_xy_coordinates(xy: Any) -> None: """ Validate CIE xy color coordinates. The CIE 1931 color space uses x and y coordinates to represent colors. Both coordinates must be between 0.0 and 1.0. Args: xy: The xy coordinates to validate (list of two floats, each 0-1) Raises: ValueError: If xy is not a valid list of two floats between 0 and 1 Example: >>> validate_xy_coordinates([0.3, 0.4]) # OK >>> validate_xy_coordinates([0.0, 1.0]) # OK - edge values >>> validate_xy_coordinates([0.5, 1.5]) # Raises ValueError >>> validate_xy_coordinates([0.3]) # Raises ValueError - needs 2 values """ if not isinstance(xy, list): raise ValueError(f"xy must be a list, got {type(xy).__name__}") if len(xy) != 2: raise ValueError(f"xy must be a list of two values [x, y], got {len(xy)} values") for i, value in enumerate(xy): coordinate_name = "x" if i == 0 else "y" if not isinstance(value, (int, float)): raise ValueError( f"xy[{i}] ({coordinate_name}) must be a number, " f"got {type(value).__name__}" ) if value < CIE_XY_MIN or value > CIE_XY_MAX: raise ValueError( f"xy[{i}] ({coordinate_name}) must be between " f"{CIE_XY_MIN} and {CIE_XY_MAX}" )