ha-mcp-dev 6.3.1.dev137__py3-none-any.whl

ha_mcp/tools/tools_zones.py

@@ -0,0 +1,387 @@
+"""
+Configuration management tools for Home Assistant zones.
+
+This module provides tools for listing, creating, updating, and deleting
+Home Assistant zones (location-based areas for presence automation).
+"""
+
+import logging
+from typing import Annotated, Any
+
+from pydantic import Field
+
+from .helpers import log_tool_usage
+
+logger = logging.getLogger(__name__)
+
+
+def register_zone_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
+    """Register Home Assistant zone configuration tools."""
+
+    @mcp.tool(annotations={"idempotentHint": True, "readOnlyHint": True, "tags": ["zone"], "title": "Get Zone"})
+    @log_tool_usage
+    async def ha_get_zone(
+        zone_id: Annotated[
+            str | None,
+            Field(
+                description="Zone ID to get details for (from ha_get_zone() list). "
+                "If omitted, lists all zones.",
+                default=None,
+            ),
+        ] = None,
+    ) -> dict[str, Any]:
+        """
+        Get zone information - list all zones or get details for a specific one.
+
+        Without a zone_id: Lists all Home Assistant zones with their coordinates and radius.
+        With a zone_id: Returns detailed configuration for a specific zone.
+
+        ZONE PROPERTIES:
+        - ID, name, icon
+        - Latitude, longitude, radius
+        - Passive mode setting
+
+        EXAMPLES:
+        - List all zones: ha_get_zone()
+        - Get specific zone: ha_get_zone(zone_id="abc123")
+
+        **NOTE:** This returns storage-based zones (created via UI/API), not YAML-defined zones.
+        The 'home' zone is typically defined in YAML and may not appear in this list.
+        """
+        try:
+            message: dict[str, Any] = {
+                "type": "zone/list",
+            }
+
+            result = await client.send_websocket_message(message)
+
+            if not result.get("success"):
+                return {
+                    "success": False,
+                    "error": f"Failed to get zones: {result.get('error', 'Unknown error')}",
+                }
+
+            zones = result.get("result", [])
+
+            # If no zone_id provided, return list of all zones
+            if zone_id is None:
+                return {
+                    "success": True,
+                    "count": len(zones),
+                    "zones": zones,
+                    "message": f"Found {len(zones)} zone(s)",
+                }
+
+            # Find specific zone by ID
+            zone = next((z for z in zones if z.get("id") == zone_id), None)
+
+            if zone is None:
+                available_ids = [z.get("id") for z in zones[:10]]  # Show first 10
+                return {
+                    "success": False,
+                    "error": f"Zone not found: {zone_id}",
+                    "zone_id": zone_id,
+                    "available_zone_ids": available_ids,
+                    "suggestion": "Use ha_get_zone() without zone_id to see all available zones",
+                }
+
+            return {
+                "success": True,
+                "zone_id": zone_id,
+                "zone": zone,
+            }
+
+        except Exception as e:
+            logger.error(f"Error getting zones: {e}")
+            return {
+                "success": False,
+                "error": f"Failed to get zones: {str(e)}",
+                "suggestions": [
+                    "Check Home Assistant connection",
+                    "Verify WebSocket connection is active",
+                    "Use ha_search_entities(domain_filter='zone') as alternative",
+                ],
+            }
+
+    @mcp.tool(annotations={"destructiveHint": True, "tags": ["zone"], "title": "Create Zone"})
+    @log_tool_usage
+    async def ha_create_zone(
+        name: Annotated[str, Field(description="Display name for the zone")],
+        latitude: Annotated[
+            float,
+            Field(description="Latitude coordinate of the zone center"),
+        ],
+        longitude: Annotated[
+            float,
+            Field(description="Longitude coordinate of the zone center"),
+        ],
+        radius: Annotated[
+            float,
+            Field(
+                description="Radius of the zone in meters (default: 100)",
+                default=100,
+            ),
+        ] = 100,
+        icon: Annotated[
+            str | None,
+            Field(
+                description="Material Design Icon (e.g., 'mdi:briefcase', 'mdi:school')",
+                default=None,
+            ),
+        ] = None,
+        passive: Annotated[
+            bool,
+            Field(
+                description="If True, zone will not trigger automations on enter/exit (default: False)",
+                default=False,
+            ),
+        ] = False,
+    ) -> dict[str, Any]:
+        """
+        Create a new Home Assistant zone for presence detection.
+
+        Zones are location-based areas that can trigger automations when
+        devices enter or exit. Common use cases include:
+        - Home, Work, School locations
+        - Gym, Shopping areas
+        - Family members' locations
+
+        EXAMPLES:
+        - Create office zone: ha_create_zone("Office", 40.7128, -74.0060, radius=150, icon="mdi:briefcase")
+        - Create gym zone: ha_create_zone("Gym", 40.7580, -73.9855, radius=50, icon="mdi:dumbbell")
+        - Create passive zone: ha_create_zone("City Center", 40.7484, -73.9857, radius=500, passive=True)
+
+        Note: The 'home' zone is typically defined in configuration.yaml and cannot be created via this API.
+        """
+        try:
+            # Validate coordinates
+            if not (-90 <= latitude <= 90):
+                return {
+                    "success": False,
+                    "error": f"Invalid latitude: {latitude}. Must be between -90 and 90.",
+                }
+            if not (-180 <= longitude <= 180):
+                return {
+                    "success": False,
+                    "error": f"Invalid longitude: {longitude}. Must be between -180 and 180.",
+                }
+            if radius <= 0:
+                return {
+                    "success": False,
+                    "error": f"Invalid radius: {radius}. Must be greater than 0.",
+                }
+
+            # Build create message
+            message: dict[str, Any] = {
+                "type": "zone/create",
+                "name": name,
+                "latitude": latitude,
+                "longitude": longitude,
+                "radius": radius,
+                "passive": passive,
+            }
+
+            if icon:
+                message["icon"] = icon
+
+            result = await client.send_websocket_message(message)
+
+            if result.get("success"):
+                zone_data = result.get("result", {})
+                return {
+                    "success": True,
+                    "zone_data": zone_data,
+                    "zone_id": zone_data.get("id"),
+                    "message": f"Successfully created zone: {name}",
+                }
+            else:
+                return {
+                    "success": False,
+                    "error": f"Failed to create zone: {result.get('error', 'Unknown error')}",
+                    "name": name,
+                }
+
+        except Exception as e:
+            logger.error(f"Error creating zone: {e}")
+            return {
+                "success": False,
+                "error": f"Zone creation failed: {str(e)}",
+                "name": name,
+                "suggestions": [
+                    "Check Home Assistant connection",
+                    "Verify coordinates are valid",
+                    "Ensure zone name is unique",
+                ],
+            }
+
+    @mcp.tool(annotations={"destructiveHint": True, "tags": ["zone"], "title": "Update Zone"})
+    @log_tool_usage
+    async def ha_update_zone(
+        zone_id: Annotated[
+            str,
+            Field(description="Zone ID to update (from ha_get_zone)"),
+        ],
+        name: Annotated[
+            str | None,
+            Field(description="New display name for the zone", default=None),
+        ] = None,
+        latitude: Annotated[
+            float | None,
+            Field(description="New latitude coordinate", default=None),
+        ] = None,
+        longitude: Annotated[
+            float | None,
+            Field(description="New longitude coordinate", default=None),
+        ] = None,
+        radius: Annotated[
+            float | None,
+            Field(description="New radius in meters", default=None),
+        ] = None,
+        icon: Annotated[
+            str | None,
+            Field(description="New Material Design Icon", default=None),
+        ] = None,
+        passive: Annotated[
+            bool | None,
+            Field(description="New passive mode setting", default=None),
+        ] = None,
+    ) -> dict[str, Any]:
+        """
+        Update an existing Home Assistant zone.
+
+        Only the fields you specify will be updated. Other fields remain unchanged.
+
+        EXAMPLES:
+        - Update zone name: ha_update_zone("abc123", name="New Office")
+        - Update zone radius: ha_update_zone("abc123", radius=200)
+        - Update zone location: ha_update_zone("abc123", latitude=40.7128, longitude=-74.0060)
+        - Update multiple fields: ha_update_zone("abc123", name="Gym", radius=75, icon="mdi:dumbbell")
+
+        **TIP:** Use ha_get_zone() to get the zone_id for the zone you want to update.
+        """
+        try:
+            # Validate that at least one field is being updated
+            update_fields = {
+                "name": name,
+                "latitude": latitude,
+                "longitude": longitude,
+                "radius": radius,
+                "icon": icon,
+                "passive": passive,
+            }
+            fields_to_update = {k: v for k, v in update_fields.items() if v is not None}
+
+            if not fields_to_update:
+                return {
+                    "success": False,
+                    "error": "No fields to update. Provide at least one field to change.",
+                    "zone_id": zone_id,
+                }
+
+            # Validate coordinates if provided
+            if latitude is not None and not (-90 <= latitude <= 90):
+                return {
+                    "success": False,
+                    "error": f"Invalid latitude: {latitude}. Must be between -90 and 90.",
+                }
+            if longitude is not None and not (-180 <= longitude <= 180):
+                return {
+                    "success": False,
+                    "error": f"Invalid longitude: {longitude}. Must be between -180 and 180.",
+                }
+            if radius is not None and radius <= 0:
+                return {
+                    "success": False,
+                    "error": f"Invalid radius: {radius}. Must be greater than 0.",
+                }
+
+            # Build update message
+            message: dict[str, Any] = {
+                "type": "zone/update",
+                "zone_id": zone_id,
+                **fields_to_update,
+            }
+
+            result = await client.send_websocket_message(message)
+
+            if result.get("success"):
+                zone_data = result.get("result", {})
+                return {
+                    "success": True,
+                    "zone_data": zone_data,
+                    "zone_id": zone_id,
+                    "updated_fields": list(fields_to_update.keys()),
+                    "message": f"Successfully updated zone: {zone_id}",
+                }
+            else:
+                return {
+                    "success": False,
+                    "error": f"Failed to update zone: {result.get('error', 'Unknown error')}",
+                    "zone_id": zone_id,
+                }
+
+        except Exception as e:
+            logger.error(f"Error updating zone: {e}")
+            return {
+                "success": False,
+                "error": f"Zone update failed: {str(e)}",
+                "zone_id": zone_id,
+                "suggestions": [
+                    "Check Home Assistant connection",
+                    "Verify zone_id exists using ha_get_zone()",
+                    "Ensure values are valid",
+                ],
+            }
+
+    @mcp.tool(annotations={"destructiveHint": True, "idempotentHint": True, "tags": ["zone"], "title": "Delete Zone"})
+    @log_tool_usage
+    async def ha_delete_zone(
+        zone_id: Annotated[
+            str,
+            Field(description="Zone ID to delete (from ha_get_zone)"),
+        ],
+    ) -> dict[str, Any]:
+        """
+        Delete a Home Assistant zone.
+
+        EXAMPLES:
+        - Delete zone: ha_delete_zone("abc123")
+
+        **WARNING:** Deleting a zone that is used in automations may cause those automations to fail.
+        Use ha_get_zone() to get the zone_id for the zone you want to delete.
+
+        **NOTE:** The 'home' zone cannot be deleted as it is typically defined in configuration.yaml.
+        """
+        try:
+            message: dict[str, Any] = {
+                "type": "zone/delete",
+                "zone_id": zone_id,
+            }
+
+            result = await client.send_websocket_message(message)
+
+            if result.get("success"):
+                return {
+                    "success": True,
+                    "zone_id": zone_id,
+                    "message": f"Successfully deleted zone: {zone_id}",
+                }
+            else:
+                return {
+                    "success": False,
+                    "error": f"Failed to delete zone: {result.get('error', 'Unknown error')}",
+                    "zone_id": zone_id,
+                }
+
+        except Exception as e:
+            logger.error(f"Error deleting zone: {e}")
+            return {
+                "success": False,
+                "error": f"Zone deletion failed: {str(e)}",
+                "zone_id": zone_id,
+                "suggestions": [
+                    "Check Home Assistant connection",
+                    "Verify zone_id exists using ha_get_zone()",
+                    "Ensure zone is not the 'home' zone (YAML-defined)",
+                ],
+            }

ha_mcp/tools/util_helpers.py

@@ -0,0 +1,199 @@
+"""
+Shared utility functions for MCP tool modules.
+
+This module provides common helper functions used across multiple tool registration modules.
+"""
+
+import json
+from typing import Any
+
+
+def coerce_bool_param(
+    value: bool | str | None,
+    param_name: str = "parameter",
+    default: bool | None = None,
+) -> bool | None:
+    """
+    Coerce a value to a boolean, handling string inputs from AI tools.
+
+    AI assistants using XML-style function calls pass boolean parameters as strings
+    (e.g., "true" instead of true). This function safely converts such inputs.
+
+    Args:
+        value: The value to coerce (bool, str, or None)
+        param_name: Parameter name for error messages
+        default: Default value to return if value is None
+
+    Returns:
+        The coerced boolean value, or default if value is None
+
+    Raises:
+        ValueError: If the value cannot be converted to a boolean
+    """
+    if value is None:
+        return default
+
+    if isinstance(value, bool):
+        return value
+
+    if isinstance(value, str):
+        value = value.strip().lower()
+        if not value:
+            return default
+        if value in ("true", "1", "yes", "on"):
+            return True
+        if value in ("false", "0", "no", "off"):
+            return False
+        raise ValueError(
+            f"{param_name} must be a boolean value, got '{value}'"
+        )
+
+    raise ValueError(
+        f"{param_name} must be bool or string, got {type(value).__name__}"
+    )
+
+
+def coerce_int_param(
+    value: int | str | None,
+    param_name: str = "parameter",
+    default: int | None = None,
+    min_value: int | None = None,
+    max_value: int | None = None,
+) -> int | None:
+    """
+    Coerce a value to an integer, handling string inputs from AI tools.
+
+    AI assistants often pass numeric parameters as strings (e.g., "100" instead of 100).
+    This function safely converts such inputs to integers.
+
+    Args:
+        value: The value to coerce (int, str, or None)
+        param_name: Parameter name for error messages
+        default: Default value to return if value is None
+        min_value: Optional minimum value constraint
+        max_value: Optional maximum value constraint
+
+    Returns:
+        The coerced integer value, or default if value is None
+
+    Raises:
+        ValueError: If the value cannot be converted to an integer
+    """
+    if value is None:
+        return default
+
+    if isinstance(value, int):
+        result = value
+    elif isinstance(value, str):
+        value = value.strip()
+        if not value:
+            return default
+        try:
+            # Handle float strings like "100.0" by converting via float first
+            result = int(float(value))
+        except ValueError:
+            raise ValueError(
+                f"{param_name} must be a valid integer, got '{value}'"
+            ) from None
+    else:
+        raise ValueError(
+            f"{param_name} must be int or string, got {type(value).__name__}"
+        )
+
+    # Apply constraints
+    if min_value is not None and result < min_value:
+        result = min_value
+    if max_value is not None and result > max_value:
+        result = max_value
+
+    return result
+
+
+def parse_json_param(
+    param: str | dict | list | None, param_name: str = "parameter"
+) -> dict | list | None:
+    """
+    Parse flexibly JSON string or return existing dict/list.
+
+    Args:
+        param: JSON string, dict, list, or None
+        param_name: Parameter name for error context
+
+    Returns:
+        Parsed dict/list or original value if already correct type
+
+    Raises:
+        ValueError: If JSON parsing fails
+    """
+    if param is None:
+        return None
+
+    if isinstance(param, (dict, list)):
+        return param
+
+    if isinstance(param, str):
+        try:
+            parsed = json.loads(param)
+            if not isinstance(parsed, (dict, list)):
+                raise ValueError(
+                    f"{param_name} must be a JSON object or array, got {type(parsed).__name__}"
+                )
+            return parsed
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid JSON in {param_name}: {e}")
+
+    raise ValueError(
+        f"{param_name} must be string, dict, list, or None, got {type(param).__name__}"
+    )
+
+
+def parse_string_list_param(
+    param: str | list[str] | None, param_name: str = "parameter"
+) -> list[str] | None:
+    """Parse JSON string array or return existing list of strings."""
+    if param is None:
+        return None
+
+    if isinstance(param, list):
+        if all(isinstance(item, str) for item in param):
+            return param
+        raise ValueError(f"{param_name} must be a list of strings")
+
+    if isinstance(param, str):
+        try:
+            parsed = json.loads(param)
+            if not isinstance(parsed, list):
+                raise ValueError(f"{param_name} must be a JSON array")
+            if not all(isinstance(item, str) for item in parsed):
+                raise ValueError(f"{param_name} must be a JSON array of strings")
+            return parsed
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid JSON in {param_name}: {e}")
+
+    raise ValueError(f"{param_name} must be string, list, or None")
+
+
+async def add_timezone_metadata(client: Any, data: dict[str, Any]) -> dict[str, Any]:
+    """Add timezone metadata to tool responses containing timestamps."""
+    try:
+        config = await client.get_config()
+        ha_timezone = config.get("time_zone", "UTC")
+
+        return {
+            "data": data,
+            "metadata": {
+                "home_assistant_timezone": ha_timezone,
+                "timestamp_format": "ISO 8601 (UTC)",
+                "note": f"All timestamps are in UTC. Home Assistant timezone is {ha_timezone}.",
+            },
+        }
+    except Exception:
+        # Fallback if config fetch fails
+        return {
+            "data": data,
+            "metadata": {
+                "home_assistant_timezone": "Unknown",
+                "timestamp_format": "ISO 8601 (UTC)",
+                "note": "All timestamps are in UTC. Could not fetch Home Assistant timezone.",
+            },
+        }

ha_mcp/utils/__init__.py

@@ -0,0 +1,30 @@
+"""
+Utility modules for Home Assistant MCP server.
+"""
+
+from .fuzzy_search import FuzzyEntitySearcher, create_fuzzy_searcher
+from .operation_manager import (
+    DeviceOperation,
+    OperationManager,
+    OperationStatus,
+    get_operation_manager,
+    get_operation_from_memory,
+    store_pending_operation,
+    update_pending_operations,
+)
+from .usage_logger import UsageLogger, ToolUsageLog, log_tool_call
+
+__all__ = [
+    "FuzzyEntitySearcher",
+    "create_fuzzy_searcher",
+    "DeviceOperation",
+    "OperationManager",
+    "OperationStatus",
+    "get_operation_manager",
+    "get_operation_from_memory",
+    "store_pending_operation",
+    "update_pending_operations",
+    "UsageLogger",
+    "ToolUsageLog",
+    "log_tool_call",
+]