Loxone MCP Server

Instructions

Implementation Reference

• src/loxone_mcp/simple_server.py:182-315 (handler)

  The handler for loxone_get_device_state, which connects to the Loxone Miniserver and retrieves state information via a DeviceManager.

  async def loxone_get_device_state(
      uuid: str,
      host: str | None = None,
      username: str | None = None,
      password: str | None = None,
      port: int = 80,
      client_id: str = "default",
  ) -> dict[str, Any]:
      """
      Get comprehensive state information for a specific Loxone device.
  
      Returns detailed device state including all available parameters, capabilities,
      metadata, and device-type specific state structures. This enhanced version
      provides complete state information with parameter descriptions, units, and
      validation rules.
  
      Args:
          uuid: The UUID of the device
          host: Loxone Miniserver host/IP address (uses LOXONE_HOST env var if not provided)
          username: Loxone username (uses LOXONE_USERNAME env var if not provided)
          password: Loxone password (uses LOXONE_PASSWORD env var if not provided)
          port: Loxone port (uses LOXONE_PORT env var or default: 80)
          client_id: Unique identifier for the client (default: "default")
  
      Returns:
          Comprehensive device state response including:
          - Basic device information (uuid, name, type, room, category)
          - Enhanced state structure with device-type specific parameters
          - Device capabilities and supported operations
          - State parameter metadata (descriptions, units, ranges)
          - State validation rules and default values
          - Cache status and update tracking information
      """
  
      if not uuid or not isinstance(uuid, str):
          return {
              "success": False,
              "error": "UUID parameter is required and must be a string",
              "error_code": "INVALID_PARAMETER",
          }
  
      try:
          # Import here to avoid import issues when running as script
          import sys
          from pathlib import Path
  
          # Add the parent directory to path for imports
          parent_dir = Path(__file__).parent
          if str(parent_dir) not in sys.path:
              sys.path.insert(0, str(parent_dir))
  
          from .config import LoxoneConfig
          from .loxone_client import LoxoneClient
          from .device_manager import DeviceManager
  
          # Use environment variables as primary source, parameters as override
          try:
              if not all([host, username, password]):
                  # Load from environment
                  env_config = LoxoneConfig.from_env()
                  host = host or env_config.host
                  username = username or env_config.username
                  password = password or env_config.password
                  port = port if port != 80 else env_config.port
          except ValueError as e:
              return {
                  "success": False,
                  "error": f"Configuration error: {e}",
                  "error_code": "MISSING_PARAMETERS",
              }
  
          logger.info(f"Getting device state for {uuid} on {host}:{port}")
  
          # Create configuration
          config = LoxoneConfig(host=host, username=username, password=password, port=port)
  
          # Create and connect client
          client = LoxoneClient(config)
  
          logger.info(f"Connecting to Loxone Miniserver at {host}:{port}...")
          connected = await client.connect()
  
          if not connected:
              return {
                  "success": False,
                  "error": f"Failed to connect to Loxone Miniserver at {host}:{port}",
                  "error_code": "CONNECTION_FAILED",
              }
  
          try:
              # Get structure data
              structure = await client.get_structure()
  
              # Create device manager and load structure
              device_manager = DeviceManager()
              device_manager.load_devices(structure)
  
              # Get specific device
              device = device_manager.get_device(uuid.strip())
              if not device:
                  return {
                      "success": False,
                      "error": f"Device not found with UUID: {uuid}",
                      "error_code": "DEVICE_NOT_FOUND",
                  }
  
              # Use enhanced device state information
              enhanced_state = device_manager.get_enhanced_device_state(uuid.strip())
  
              # Check if enhanced state retrieval was successful
              if not enhanced_state.get("success", True):
                  # Fall back to basic state if enhanced state fails
                  logger.warning(
                      f"Enhanced state retrieval failed for {uuid}, falling back to basic state"
                  )
                  device_state = {
                      "uuid": device.uuid,
                      "name": device.name,
                      "type": device.type,
                      "room": device.room,
                      "category": device.category,
                      "state": device.states.copy() if device.states else {},
                      "details": device.details.copy() if device.details else {},
                      "capabilities": device.capabilities.copy() if device.capabilities else {},
                      "metadata": device.metadata.copy() if device.metadata else {},
                  }
              else:
                  # Use enhanced state information
                  device_state = enhanced_state
  
              logger.info(
                  f"Successfully retrieved enhanced state for device '{device.name}' ({device.type})"
              )
              logger.debug(f"Enhanced state includes: {list(device_state.get('state', {}).keys())}")