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

ha_mcp/tools/tools_calendar.py

@@ -0,0 +1,391 @@
+"""
+Calendar event management tools for Home Assistant MCP server.
+
+This module provides tools for managing calendar events in Home Assistant,
+including retrieving events, creating events, and deleting events.
+
+Use ha_search_entities(query='calendar', domain_filter='calendar') to find calendar entities.
+"""
+
+import logging
+from datetime import datetime, timedelta
+from typing import Annotated, Any
+
+from pydantic import Field
+
+from .helpers import log_tool_usage
+
+logger = logging.getLogger(__name__)
+
+
+def register_calendar_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
+    """Register calendar management tools with the MCP server."""
+
+    @mcp.tool(annotations={"idempotentHint": True, "readOnlyHint": True, "tags": ["calendar"], "title": "Get Calendar Events"})
+    @log_tool_usage
+    async def ha_config_get_calendar_events(
+        entity_id: Annotated[
+            str, Field(description="Calendar entity ID (e.g., 'calendar.family')")
+        ],
+        start: Annotated[
+            str | None,
+            Field(
+                description="Start datetime in ISO format (default: now)", default=None
+            ),
+        ] = None,
+        end: Annotated[
+            str | None,
+            Field(
+                description="End datetime in ISO format (default: 7 days from start)",
+                default=None,
+            ),
+        ] = None,
+        max_results: Annotated[
+            int,
+            Field(description="Maximum number of events to return", default=20),
+        ] = 20,
+    ) -> dict[str, Any]:
+        """
+        Retrieve calendar events from a calendar entity.
+
+        Retrieves calendar events within a specified time range.
+
+        **Parameters:**
+        - entity_id: Calendar entity ID (e.g., 'calendar.family')
+        - start: Start datetime in ISO format (default: now)
+        - end: End datetime in ISO format (default: 7 days from start)
+        - max_results: Maximum number of events to return (default: 20)
+
+        **Example Usage:**
+        ```python
+        # Get events for the next week
+        events = ha_config_get_calendar_events("calendar.family")
+
+        # Get events for a specific date range
+        events = ha_config_get_calendar_events(
+            "calendar.work",
+            start="2024-01-01T00:00:00",
+            end="2024-01-31T23:59:59"
+        )
+        ```
+
+        **Note:** To find calendar entities, use ha_search_entities(query='calendar', domain_filter='calendar')
+
+        **Returns:**
+        - List of calendar events with summary, start, end, description, location
+        """
+        try:
+            # Validate entity_id
+            if not entity_id.startswith("calendar."):
+                return {
+                    "success": False,
+                    "error": f"Invalid calendar entity ID: {entity_id}. Must start with 'calendar.'",
+                    "entity_id": entity_id,
+                    "suggestions": [
+                        "Use ha_search_entities(query='calendar', domain_filter='calendar') to find calendar entities",
+                        "Calendar entity IDs start with 'calendar.' prefix",
+                    ],
+                }
+
+            # Set default time range if not provided
+            now = datetime.now()
+            if start is None:
+                start = now.isoformat()
+            if end is None:
+                end_date = now + timedelta(days=7)
+                end = end_date.isoformat()
+
+            # Build the API endpoint for calendar events
+            # Home Assistant uses: GET /api/calendars/{entity_id}?start=...&end=...
+            params = {"start": start, "end": end}
+
+            # Use the REST client to fetch calendar events
+            # The endpoint is /calendars/{entity_id} (note: without /api prefix as client adds it)
+            response = await client._request(
+                "GET", f"/calendars/{entity_id}", params=params
+            )
+
+            # Response is a list of events
+            events = response if isinstance(response, list) else []
+
+            # Limit results
+            limited_events = events[:max_results]
+
+            return {
+                "success": True,
+                "entity_id": entity_id,
+                "events": limited_events,
+                "count": len(limited_events),
+                "total_available": len(events),
+                "time_range": {
+                    "start": start,
+                    "end": end,
+                },
+                "message": f"Retrieved {len(limited_events)} event(s) from {entity_id}",
+            }
+
+        except Exception as error:
+            error_str = str(error)
+            logger.error(f"Failed to get calendar events for {entity_id}: {error}")
+
+            # Provide helpful error messages
+            suggestions = [
+                f"Verify calendar entity '{entity_id}' exists using ha_search_entities(query='calendar', domain_filter='calendar')",
+                "Check start/end datetime format (ISO 8601)",
+                "Ensure calendar integration supports event retrieval",
+            ]
+
+            if "404" in error_str or "not found" in error_str.lower():
+                suggestions.insert(0, f"Calendar entity '{entity_id}' not found")
+
+            return {
+                "success": False,
+                "error": error_str,
+                "entity_id": entity_id,
+                "events": [],
+                "suggestions": suggestions,
+            }
+
+    @mcp.tool(annotations={"destructiveHint": True, "tags": ["calendar"], "title": "Create or Update Calendar Event"})
+    @log_tool_usage
+    async def ha_config_set_calendar_event(
+        entity_id: Annotated[
+            str, Field(description="Calendar entity ID (e.g., 'calendar.family')")
+        ],
+        summary: Annotated[str, Field(description="Event title/summary")],
+        start: Annotated[
+            str, Field(description="Event start datetime in ISO format")
+        ],
+        end: Annotated[str, Field(description="Event end datetime in ISO format")],
+        description: Annotated[
+            str | None,
+            Field(description="Optional event description", default=None),
+        ] = None,
+        location: Annotated[
+            str | None, Field(description="Optional event location", default=None)
+        ] = None,
+    ) -> dict[str, Any]:
+        """
+        Create a new event in a calendar.
+
+        Creates a calendar event using the calendar.create_event service.
+
+        **Parameters:**
+        - entity_id: Calendar entity ID (e.g., 'calendar.family')
+        - summary: Event title/summary
+        - start: Event start datetime in ISO format
+        - end: Event end datetime in ISO format
+        - description: Optional event description
+        - location: Optional event location
+
+        **Example Usage:**
+        ```python
+        # Create a simple event
+        result = ha_config_set_calendar_event(
+            "calendar.family",
+            summary="Doctor appointment",
+            start="2024-01-15T14:00:00",
+            end="2024-01-15T15:00:00"
+        )
+
+        # Create an event with details
+        result = ha_config_set_calendar_event(
+            "calendar.work",
+            summary="Team meeting",
+            start="2024-01-16T10:00:00",
+            end="2024-01-16T11:00:00",
+            description="Weekly sync meeting",
+            location="Conference Room A"
+        )
+        ```
+
+        **Returns:**
+        - Success status and event details
+        """
+        try:
+            # Validate entity_id
+            if not entity_id.startswith("calendar."):
+                return {
+                    "success": False,
+                    "error": f"Invalid calendar entity ID: {entity_id}. Must start with 'calendar.'",
+                    "entity_id": entity_id,
+                    "suggestions": [
+                        "Use ha_search_entities(query='calendar', domain_filter='calendar') to find calendar entities",
+                        "Calendar entity IDs start with 'calendar.' prefix",
+                    ],
+                }
+
+            # Build service data
+            service_data: dict[str, Any] = {
+                "entity_id": entity_id,
+                "summary": summary,
+                "start_date_time": start,
+                "end_date_time": end,
+            }
+
+            if description:
+                service_data["description"] = description
+            if location:
+                service_data["location"] = location
+
+            # Call the calendar.create_event service
+            result = await client.call_service("calendar", "create_event", service_data)
+
+            return {
+                "success": True,
+                "entity_id": entity_id,
+                "event": {
+                    "summary": summary,
+                    "start": start,
+                    "end": end,
+                    "description": description,
+                    "location": location,
+                },
+                "result": result,
+                "message": f"Successfully created event '{summary}' in {entity_id}",
+            }
+
+        except Exception as error:
+            error_str = str(error)
+            logger.error(f"Failed to create calendar event in {entity_id}: {error}")
+
+            suggestions = [
+                f"Verify calendar entity '{entity_id}' exists and supports event creation",
+                "Check datetime format (ISO 8601)",
+                "Ensure end time is after start time",
+                "Some calendar integrations may be read-only",
+            ]
+
+            if "404" in error_str or "not found" in error_str.lower():
+                suggestions.insert(0, f"Calendar entity '{entity_id}' not found")
+            if "not supported" in error_str.lower():
+                suggestions.insert(0, "This calendar does not support event creation")
+
+            return {
+                "success": False,
+                "error": error_str,
+                "entity_id": entity_id,
+                "event": {
+                    "summary": summary,
+                    "start": start,
+                    "end": end,
+                },
+                "suggestions": suggestions,
+            }
+
+    @mcp.tool(annotations={"destructiveHint": True, "idempotentHint": True, "tags": ["calendar"], "title": "Remove Calendar Event"})
+    @log_tool_usage
+    async def ha_config_remove_calendar_event(
+        entity_id: Annotated[
+            str, Field(description="Calendar entity ID (e.g., 'calendar.family')")
+        ],
+        uid: Annotated[str, Field(description="Unique identifier of the event to delete")],
+        recurrence_id: Annotated[
+            str | None,
+            Field(description="Optional recurrence ID for recurring events", default=None),
+        ] = None,
+        recurrence_range: Annotated[
+            str | None,
+            Field(
+                description="Optional recurrence range ('THIS_AND_FUTURE' to delete this and future occurrences)",
+                default=None,
+            ),
+        ] = None,
+    ) -> dict[str, Any]:
+        """
+        Delete an event from a calendar.
+
+        Deletes a calendar event using the calendar.delete_event service.
+
+        **Parameters:**
+        - entity_id: Calendar entity ID (e.g., 'calendar.family')
+        - uid: Unique identifier of the event to delete
+        - recurrence_id: Optional recurrence ID for recurring events
+        - recurrence_range: Optional recurrence range ('THIS_AND_FUTURE' to delete this and future occurrences)
+
+        **Example Usage:**
+        ```python
+        # Delete a single event
+        result = ha_config_remove_calendar_event(
+            "calendar.family",
+            uid="event-12345"
+        )
+
+        # Delete a recurring event instance and future occurrences
+        result = ha_config_remove_calendar_event(
+            "calendar.work",
+            uid="recurring-event-67890",
+            recurrence_id="20240115T100000",
+            recurrence_range="THIS_AND_FUTURE"
+        )
+        ```
+
+        **Note:**
+        To get the event UID, first use ha_config_get_calendar_events() to list events.
+        The UID is returned in each event's data.
+
+        **Returns:**
+        - Success status and deletion confirmation
+        """
+        try:
+            # Validate entity_id
+            if not entity_id.startswith("calendar."):
+                return {
+                    "success": False,
+                    "error": f"Invalid calendar entity ID: {entity_id}. Must start with 'calendar.'",
+                    "entity_id": entity_id,
+                    "suggestions": [
+                        "Use ha_search_entities(query='calendar', domain_filter='calendar') to find calendar entities",
+                        "Calendar entity IDs start with 'calendar.' prefix",
+                    ],
+                }
+
+            # Build service data
+            service_data: dict[str, Any] = {
+                "entity_id": entity_id,
+                "uid": uid,
+            }
+
+            if recurrence_id:
+                service_data["recurrence_id"] = recurrence_id
+            if recurrence_range:
+                service_data["recurrence_range"] = recurrence_range
+
+            # Call the calendar.delete_event service
+            result = await client.call_service("calendar", "delete_event", service_data)
+
+            return {
+                "success": True,
+                "entity_id": entity_id,
+                "uid": uid,
+                "recurrence_id": recurrence_id,
+                "recurrence_range": recurrence_range,
+                "result": result,
+                "message": f"Successfully deleted event '{uid}' from {entity_id}",
+            }
+
+        except Exception as error:
+            error_str = str(error)
+            logger.error(f"Failed to delete calendar event from {entity_id}: {error}")
+
+            suggestions = [
+                f"Verify calendar entity '{entity_id}' exists",
+                f"Verify event with UID '{uid}' exists in the calendar",
+                "Use ha_config_get_calendar_events() to find the correct event UID",
+                "Some calendar integrations may not support event deletion",
+            ]
+
+            if "404" in error_str or "not found" in error_str.lower():
+                suggestions.insert(
+                    0, f"Calendar entity '{entity_id}' or event '{uid}' not found"
+                )
+            if "not supported" in error_str.lower():
+                suggestions.insert(0, "This calendar does not support event deletion")
+
+            return {
+                "success": False,
+                "error": error_str,
+                "entity_id": entity_id,
+                "uid": uid,
+                "suggestions": suggestions,
+            }

ha_mcp/tools/tools_camera.py

@@ -0,0 +1,149 @@
+"""
+Camera tools for Home Assistant MCP server.
+
+This module provides camera-related tools including snapshot retrieval
+that returns images directly to the LLM for visual analysis.
+"""
+
+import logging
+from typing import Any
+
+from fastmcp.utilities.types import Image
+
+from .helpers import log_tool_usage
+
+logger = logging.getLogger(__name__)
+
+
+def register_camera_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
+    """Register Home Assistant camera tools."""
+
+    @mcp.tool(annotations={"idempotentHint": True, "readOnlyHint": True, "tags": ["camera"], "title": "Get Camera Image"})
+    @log_tool_usage
+    async def ha_get_camera_image(
+        entity_id: str,
+        width: int | None = None,
+        height: int | None = None,
+    ) -> Image:
+        """
+        Retrieve a snapshot image from a Home Assistant camera entity.
+
+        This tool fetches the current camera image and returns it directly for visual
+        analysis. Use this when you need to see what a camera is currently viewing.
+
+        **Parameters:**
+        - entity_id: Camera entity ID (e.g., 'camera.front_door', 'camera.living_room')
+        - width: Optional width to resize the image (reduces token usage for large images)
+        - height: Optional height to resize the image
+
+        **Use Cases:**
+        - Security checks: "Is someone at the front door?"
+        - Pet monitoring: "Is my dog still on the couch?"
+        - Delivery verification: "Did my package get delivered?"
+        - Visual confirmation: "Did the garage door actually close?"
+        - Incident investigation: "What triggered the motion sensor?"
+
+        **Example Usage:**
+        ```python
+        # Get current snapshot from front door camera
+        ha_get_camera_image(entity_id="camera.front_door")
+
+        # Get resized image to reduce token usage
+        ha_get_camera_image(entity_id="camera.backyard", width=640, height=480)
+        ```
+
+        **Notes:**
+        - Only cameras exposed to Home Assistant are accessible
+        - The existing HA authentication/authorization applies
+        - Images are returned in their native format (JPEG, PNG, or GIF)
+        - Use width/height parameters for large high-resolution cameras to reduce
+          token usage when full resolution is not needed
+
+        **Related Services:**
+        - camera.snapshot: Save snapshot to file on HA server
+        - camera.turn_on/turn_off: Control camera power
+        - camera.enable_motion_detection: Enable motion detection
+        """
+        # Validate entity_id format
+        if not entity_id or "." not in entity_id:
+            raise ValueError(
+                f"Invalid entity_id format: {entity_id}. "
+                "Expected format: camera.entity_name"
+            )
+
+        # Validate domain is camera
+        domain = entity_id.split(".")[0]
+        if domain != "camera":
+            raise ValueError(
+                f"Entity {entity_id} is not a camera entity. "
+                f"Domain is '{domain}', expected 'camera'."
+            )
+
+        # Build the camera proxy URL with optional size parameters
+        # Home Assistant camera proxy API: /api/camera_proxy/<entity_id>
+        endpoint = f"/camera_proxy/{entity_id}"
+
+        params = {}
+        if width is not None:
+            params["width"] = str(width)
+        if height is not None:
+            params["height"] = str(height)
+
+        try:
+            # Use the client's httpx_client directly for binary image data
+            response = await client.httpx_client.get(endpoint, params=params or None)
+
+            # Handle authentication errors
+            if response.status_code == 401:
+                raise PermissionError("Invalid authentication token for camera access")
+
+            # Handle not found errors
+            if response.status_code == 404:
+                raise ValueError(
+                    f"Camera entity not found: {entity_id}. "
+                    "Use ha_search_entities() to find available cameras."
+                )
+
+            # Handle other HTTP errors
+            if response.status_code >= 400:
+                raise RuntimeError(
+                    f"Failed to retrieve camera image: HTTP {response.status_code}"
+                )
+
+            # Get the image bytes
+            image_data = response.content
+
+            if not image_data:
+                raise RuntimeError(
+                    f"Camera {entity_id} returned empty image data. "
+                    "The camera may be offline or unavailable."
+                )
+
+            # Determine MIME type from response headers or default to JPEG
+            content_type = response.headers.get("content-type", "image/jpeg")
+            if "jpeg" in content_type or "jpg" in content_type:
+                image_format = "jpeg"
+            elif "png" in content_type:
+                image_format = "png"
+            elif "gif" in content_type:
+                image_format = "gif"
+            else:
+                # Default to JPEG as Home Assistant camera proxy typically returns JPEG
+                image_format = "jpeg"
+
+            logger.info(
+                f"Retrieved camera image from {entity_id} "
+                f"({len(image_data)} bytes, format={image_format})"
+            )
+
+            # Return FastMCP Image object which automatically converts to MCP ImageContent
+            return Image(data=image_data, format=image_format)
+
+        except (PermissionError, ValueError, RuntimeError):
+            raise
+        except Exception as e:
+            logger.error(f"Error retrieving camera image from {entity_id}: {e}")
+            raise RuntimeError(
+                f"Failed to retrieve camera image from {entity_id}: {str(e)}. "
+                "Ensure the camera is online and accessible."
+            )