ha-mcp-dev 8.6.0.dev2933__tar.gz → 8.6.0.dev2934__tar.gz

{ha_mcp_dev-8.6.0.dev2933 → ha_mcp_dev-8.6.0.dev2934}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.6.0.dev2933
+Version: 8.6.0.dev2934
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien

{ha_mcp_dev-8.6.0.dev2933 → ha_mcp_dev-8.6.0.dev2934}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.6.0.dev2933"
+version = "8.6.0.dev2934"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.15"

{ha_mcp_dev-8.6.0.dev2933 → ha_mcp_dev-8.6.0.dev2934}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.6.0.dev2933"
+version = "8.6.0.dev2934"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

ha_mcp_dev-8.6.0.dev2934/src/ha_mcp/image_info.py

@@ -0,0 +1,136 @@
+"""Resolve basic facts (format, dimensions) from raw image bytes.
+
+Pure-stdlib header parsing — no image library required. Camera snapshots
+are the target: JPEG (the camera proxy default), PNG, and GIF. The
+resolver always returns a format together with the dimensions, so the
+reported label can never describe different bytes than the size. Every
+parse path is best-effort: undecodable payloads yield no dimensions,
+and callers must degrade gracefully rather than fail the request.
+"""
+
+# Every T.81 start-of-frame (SOF) marker — 0xC0 through 0xCF across the
+# sequential, progressive, lossless and differential coding modes — minus
+# the three non-SOF markers that share the range: DHT (0xC4), JPG (0xC8)
+# and DAC (0xCC). The walker must skip those, not stop at them: a DHT
+# commonly precedes the frame, and misparsing its short header as a frame
+# definition would report garbage dimensions.
+_JPEG_SOF_MARKERS = frozenset(range(0xC0, 0xD0)) - {0xC4, 0xC8, 0xCC}
+
+_PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
+_GIF_SIGNATURES = (b"GIF87a", b"GIF89a")
+
+
+def resolve_image_info(
+    data: bytes, declared_format: str
+) -> tuple[str, tuple[int, int] | None]:
+    """Resolve the payload's actual format and its dimensions.
+
+    The magic bytes decide the format: a recognized container (JPEG, PNG
+    or GIF) wins over *declared_format*, so a mislabeled Content-Type can
+    never make the reported label disagree with the served bytes. When no
+    magic matches, *declared_format* is reported as-is with no
+    dimensions, so the text block can still name the format the header
+    claimed.
+    """
+    if data[:2] == b"\xff\xd8":
+        return "jpeg", _jpeg_dimensions(data)
+    if data[:8] == _PNG_SIGNATURE:
+        return "png", _png_dimensions(data)
+    if data[:6] in _GIF_SIGNATURES:
+        return "gif", _gif_dimensions(data)
+    # No recognized container: keep the declared name, report no size.
+    return declared_format, None
+
+
+def _jpeg_dimensions(data: bytes) -> tuple[int, int] | None:
+    """Walk JPEG segments to the first SOF marker, which carries the size.
+
+    The dispatcher has already verified the two-byte SOI; every further
+    read is bounds-checked by the walk, so a truncated or corrupt header
+    yields ``None`` rather than an exception. Only the header is parsed;
+    the compressed scan data is never decoded. The declared segment
+    length is validated before the dimension fields are read, so a
+    corrupt length can neither reach past the end of the buffer nor
+    report bytes outside the segment as the image size.
+    """
+    sof_pos = _find_sof_position(data)
+    if sof_pos is None:
+        return None
+    # The SOF length field counts itself, so the segment spans
+    # ``2 + length`` bytes from the marker, and the dimension fields sit
+    # at offsets 5..8 — the segment must therefore declare at least 7
+    # bytes.
+    length = (data[sof_pos + 2] << 8) | data[sof_pos + 3]
+    if length < 7:
+        return None
+    if sof_pos + 2 + length > len(data):
+        return None
+    height = (data[sof_pos + 5] << 8) | data[sof_pos + 6]
+    width = (data[sof_pos + 7] << 8) | data[sof_pos + 8]
+    if width == 0 or height == 0:
+        return None
+    return width, height
+
+
+def _skip_fill_bytes(data: bytes, pos: int) -> int:
+    """Advance *pos* past any 0xFF fill bytes after it (T.81 B.1.1.2).
+
+    Encoders may emit any number of 0xFF bytes between markers to align
+    the stream; each is consumed so the next marker read is a real one.
+    Stops at the first non-0xFF byte, or at the buffer end.
+    """
+    size = len(data)
+    while data[pos + 1] == 0xFF and pos + 3 <= size:
+        pos += 1
+    return pos
+
+
+def _find_sof_position(data: bytes) -> int | None:
+    """Advance through the JPEG segments after the SOI to the first SOF marker.
+
+    Returns the offset of the SOF marker, or ``None`` when the header is
+    malformed, truncated, or ends (EOI) without a frame definition.
+    """
+    size = len(data)
+    pos = 2  # first segment after the two-byte SOI
+    while pos + 2 <= size:
+        if data[pos] != 0xFF:
+            return None
+        pos = _skip_fill_bytes(data, pos)
+        marker = data[pos + 1]
+        if marker == 0x01 or 0xD0 <= marker <= 0xD7:  # no payload
+            pos += 2
+            continue
+        if marker == 0xD9 or pos + 4 > size:
+            return None
+        length = (data[pos + 2] << 8) | data[pos + 3]
+        if length < 2:
+            return None
+        if marker in _JPEG_SOF_MARKERS:
+            return pos
+        pos += 2 + length
+    return None
+
+
+def _png_dimensions(data: bytes) -> tuple[int, int] | None:
+    """Read the IHDR chunk, which is always first and carries the size."""
+    if len(data) < 24 or data[:8] != _PNG_SIGNATURE:
+        return None
+    if data[12:16] != b"IHDR":
+        return None
+    width = int.from_bytes(data[16:20], "big")
+    height = int.from_bytes(data[20:24], "big")
+    if width == 0 or height == 0:
+        return None
+    return width, height
+
+
+def _gif_dimensions(data: bytes) -> tuple[int, int] | None:
+    """Read the logical screen width/height from the GIF header."""
+    if len(data) < 10 or data[:6] not in _GIF_SIGNATURES:
+        return None
+    width = int.from_bytes(data[6:8], "little")
+    height = int.from_bytes(data[8:10], "little")
+    if width == 0 or height == 0:
+        return None
+    return width, height

ha_mcp_dev-8.6.0.dev2934/src/ha_mcp/tools/tools_camera.py

@@ -0,0 +1,273 @@
+"""
+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, alongside a
+short text block stating the served snapshot's size and retrieval time.
+"""
+
+import logging
+from datetime import UTC, datetime
+from typing import Annotated, Any
+
+from pydantic import Field
+
+from ha_mcp._vendor.fastmcp.exceptions import ToolError
+from ha_mcp._vendor.fastmcp.tools import tool
+from ha_mcp._vendor.fastmcp.utilities.types import Image
+from ha_mcp.errors import (
+    ErrorCode,
+    create_auth_error,
+    create_entity_not_found_error,
+    create_error_response,
+)
+from ha_mcp.image_info import resolve_image_info
+
+from .helpers import (
+    exception_to_structured_error,
+    log_tool_usage,
+    raise_tool_error,
+    register_tool_methods,
+)
+from .response_helpers import fetch_ha_timezone, resolve_local_timezone
+from .tool_hints import read_only_hints
+
+logger = logging.getLogger(__name__)
+
+
+# Subtypes that denote JPEG under an alternate spelling. Every other
+# image/* subtype is reported verbatim (image/webp -> "webp"); the JPEG
+# default applies only when the header names no image subtype at all.
+_JPEG_ALIASES = {"jpg": "jpeg", "jpe": "jpeg", "jif": "jpeg"}
+
+
+def _detect_image_format(content_type: str) -> str:
+    """Report the declared image format from a Content-Type header.
+
+    Only the media type's subtype is relevant (``image/jpeg`` -> ``jpeg``);
+    parameters such as ``; q=0.9`` are stripped and JPEG's alternate
+    spellings are folded in. Unknown image subtypes pass through verbatim —
+    relabelling ``image/webp`` as JPEG would misidentify the Image block.
+    The JPEG default applies only when the header is missing, empty, or
+    not an ``image/*`` type with a subtype (e.g. ``application/octet-stream``).
+    """
+    media_type = content_type.split(";", 1)[0].strip().lower()
+    primary, _, subtype = media_type.partition("/")
+    if primary != "image" or not subtype:
+        return "jpeg"
+    return _JPEG_ALIASES.get(subtype, subtype)
+
+
+def _snapshot_info_text(
+    image_format: str,
+    image_size: tuple[int, int] | None,
+    retrieved: datetime,
+    timezone_fallback: bool = False,
+) -> str:
+    """Build the text half of the camera image response.
+
+    Reports the size of the image actually served (which may differ from
+    the camera's native resolution when Home Assistant rescaled it) and
+    when the snapshot was retrieved, in Home Assistant local time with
+    UTC offset. When the timezone lookup fell back to UTC, the text says
+    so, so the label cannot be mistaken for a genuine UTC install.
+
+    The block deliberately describes only the bytes that were served —
+    never the entity's name or state. Home Assistant can mark an entity
+    ``llm_exposure: hidden``, asking the LLM to know nothing about that
+    entity; that setting does not un-expose this tool, so entity data in
+    the text would keep reporting on the camera despite the setting.
+    """
+    prefix = f"Camera snapshot ({image_format.upper()}"
+    if image_size is None:
+        detail = f"{prefix})"
+    else:
+        width, height = image_size
+        detail = f"{prefix}, {width}x{height})"
+    note = (
+        " (UTC — could not determine the Home Assistant timezone)"
+        if timezone_fallback
+        else ""
+    )
+    return f"{detail}. Retrieved: {retrieved:%Y-%m-%d %H:%M:%S %:z}{note}"
+
+
+class CameraTools:
+    """Camera snapshot retrieval tools."""
+
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    @staticmethod
+    def _check_response(response: Any, entity_id: str) -> None:
+        """Validate a camera-proxy HTTP response, raising a structured ToolError.
+
+        401 maps to an authentication error, 404 to a missing-entity error,
+        any other 4xx/5xx to a service-call failure, and an empty 2xx body
+        is a service failure too (HA answered but had no image to serve).
+        """
+        if response.status_code == 401:
+            raise_tool_error(
+                create_auth_error(
+                    "Invalid authentication token for camera access",
+                    context={"entity_id": entity_id},
+                )
+            )
+        if response.status_code == 404:
+            raise_tool_error(
+                create_entity_not_found_error(
+                    entity_id,
+                    details="Use ha_search to find available cameras",
+                )
+            )
+        if response.status_code >= 400:
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.SERVICE_CALL_FAILED,
+                    f"Failed to retrieve camera image: HTTP {response.status_code}",
+                    context={"entity_id": entity_id},
+                )
+            )
+        if not response.content:
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.SERVICE_CALL_FAILED,
+                    f"Camera {entity_id} returned empty image data. The camera "
+                    "may be offline or temporarily unavailable.",
+                    context={"entity_id": entity_id},
+                )
+            )
+
+    @tool(
+        name="ha_get_camera_image",
+        tags={"Camera"},
+        annotations=read_only_hints("Get Camera Image", open_world=False),
+    )
+    @log_tool_usage
+    async def ha_get_camera_image(
+        self,
+        entity_id: Annotated[
+            str, Field(description="Camera entity ID (e.g., 'camera.front_door')")
+        ],
+        width: Annotated[
+            int | None,
+            Field(
+                description="Width for the resized image. Home Assistant "
+                "rescales only when both width and height are given and "
+                "the camera serves JPEG."
+            ),
+        ] = None,
+        height: Annotated[
+            int | None,
+            Field(
+                description="Height for the resized image. Home Assistant "
+                "rescales only when both width and height are given and "
+                "the camera serves JPEG."
+            ),
+        ] = None,
+    ) -> tuple[str, Image]:
+        """Get a snapshot image from a Home Assistant camera entity.
+
+        Fetches the current camera image and returns it directly for
+        visual analysis (security checks, delivery verification,
+        confirming a garage door actually closed), in the format Home
+        Assistant serves (JPEG, PNG, or GIF), alongside a short text
+        block stating the served snapshot's size and retrieval time in
+        Home Assistant local time.
+
+        Do not use it to inspect the camera's state or attributes — use
+        ha_search or ha_get_state for those; it returns an image, not
+        state. Use it when you need to see the current scene, and on
+        high-resolution cameras pass width and height to reduce token
+        usage.
+
+        EXAMPLE: ha_get_camera_image(entity_id="camera.backyard", width=640, height=480)
+        """
+        if not entity_id or "." not in entity_id:
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    f"Invalid entity_id format: {entity_id}. "
+                    "Expected format: camera.entity_name",
+                )
+            )
+
+        domain = entity_id.split(".", maxsplit=1)[0]
+        if domain != "camera":
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    f"Entity {entity_id} is not a camera entity. "
+                    f"Domain is '{domain}', expected 'camera'.",
+                    context={"entity_id": entity_id},
+                )
+            )
+
+        # 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:
+            response = await self._client.httpx_client.get(
+                endpoint, params=params or None
+            )
+            self._check_response(response, entity_id)
+            # Sample the clock the moment HA handed us the bytes; the zone
+            # is resolved separately so a slow timezone lookup only delays
+            # the label, never the timestamp.
+            retrieved_at = datetime.now(UTC)
+
+            content_type = response.headers.get("content-type", "image/jpeg")
+            # Cameras can mislabel their payload, so resolve the format
+            # from the bytes: the reported label, size, and Image block
+            # must all describe what was actually served.
+            image_format, image_size = resolve_image_info(
+                response.content, _detect_image_format(content_type)
+            )
+            ha_timezone, fetch_failed = await fetch_ha_timezone(self._client)
+            local_tz, resolved_timezone = resolve_local_timezone(ha_timezone)
+            # A failed fetch, or a zone name tzdata cannot resolve, both
+            # fall back to UTC — the note keeps that distinct from a
+            # genuine UTC install.
+            timezone_fallback = fetch_failed or resolved_timezone != ha_timezone
+
+            logger.info(
+                f"Retrieved camera image from {entity_id} "
+                f"({len(response.content)} bytes, format={image_format})"
+            )
+
+            # Return the info text plus a FastMCP Image object (auto-converted
+            # to MCP TextContent and ImageContent, in this order)
+            return (
+                _snapshot_info_text(
+                    image_format,
+                    image_size,
+                    retrieved_at.astimezone(local_tz),
+                    timezone_fallback,
+                ),
+                Image(data=response.content, format=image_format),
+            )
+
+        except ToolError:
+            raise
+        except Exception as e:
+            logger.error(f"Error retrieving camera image from {entity_id}: {e}")
+            # The default raise_error=True path raises inside the helper and
+            # never returns; the surrounding raise keeps that termination
+            # explicit so no path through this function falls off the end.
+            raise exception_to_structured_error(
+                e,
+                context={"entity_id": entity_id},
+                suggestions=["Ensure the camera is online and accessible"],
+            ) from e
+
+
+def register_camera_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
+    """Register Home Assistant camera tools."""
+    register_tool_methods(mcp, CameraTools(client))

ha_mcp_dev-8.6.0.dev2933/src/ha_mcp/tools/tools_camera.py

@@ -1,144 +0,0 @@
-"""
-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 Annotated, Any
-
-from pydantic import Field
-
-from ha_mcp._vendor.fastmcp.tools import tool
-from ha_mcp._vendor.fastmcp.utilities.types import Image
-
-from .helpers import log_tool_usage, register_tool_methods
-from .tool_hints import read_only_hints
-
-logger = logging.getLogger(__name__)
-
-
-_CONTENT_TYPE_MAP = {
-    "jpeg": "jpeg",
-    "jpg": "jpeg",
-    "png": "png",
-    "gif": "gif",
-}
-
-
-def _detect_image_format(content_type: str) -> str:
-    """Detect image format from Content-Type header, defaulting to JPEG."""
-    for key, fmt in _CONTENT_TYPE_MAP.items():
-        if key in content_type:
-            return fmt
-    return "jpeg"
-
-
-class CameraTools:
-    """Camera snapshot retrieval tools."""
-
-    def __init__(self, client: Any) -> None:
-        self._client = client
-
-    @staticmethod
-    def _check_response(response: Any, entity_id: str) -> None:
-        """Validate camera proxy HTTP response status and content, raising on errors."""
-        if response.status_code == 401:
-            raise PermissionError("Invalid authentication token for camera access")
-        if response.status_code == 404:
-            raise ValueError(
-                f"Camera entity not found: {entity_id}. "
-                "Use ha_search() to find available cameras."
-            )
-        if response.status_code >= 400:
-            raise RuntimeError(
-                f"Failed to retrieve camera image: HTTP {response.status_code}"
-            )
-        if not response.content:
-            raise RuntimeError(
-                f"Camera {entity_id} returned empty image data. "
-                "The camera may be offline or unavailable."
-            )
-
-    @tool(
-        name="ha_get_camera_image",
-        tags={"Camera"},
-        annotations=read_only_hints("Get Camera Image", open_world=False),
-    )
-    @log_tool_usage
-    async def ha_get_camera_image(
-        self,
-        entity_id: Annotated[
-            str, Field(description="Camera entity ID (e.g., 'camera.front_door')")
-        ],
-        width: Annotated[
-            int | None, Field(description="Width to resize the image to")
-        ] = None,
-        height: Annotated[
-            int | None, Field(description="Height to resize the image to")
-        ] = None,
-    ) -> Image:
-        """Get a snapshot image from a Home Assistant camera entity.
-
-        Fetches the current camera image and returns it directly for visual
-        analysis (security checks, delivery verification, confirming a garage
-        door actually closed). Only cameras exposed to Home Assistant are
-        accessible; images come back in their native format (JPEG, PNG, or GIF).
-        Use width/height on high-resolution cameras to reduce token usage.
-
-        EXAMPLE: ha_get_camera_image(entity_id="camera.backyard", width=640, height=480)
-        """
-        if not entity_id or "." not in entity_id:
-            raise ValueError(
-                f"Invalid entity_id format: {entity_id}. "
-                "Expected format: camera.entity_name"
-            )
-
-        domain = entity_id.split(".", maxsplit=1)[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:
-            response = await self._client.httpx_client.get(
-                endpoint, params=params or None
-            )
-            self._check_response(response, entity_id)
-
-            content_type = response.headers.get("content-type", "image/jpeg")
-            image_format = _detect_image_format(content_type)
-
-            logger.info(
-                f"Retrieved camera image from {entity_id} "
-                f"({len(response.content)} bytes, format={image_format})"
-            )
-
-            # Return FastMCP Image object which automatically converts to MCP ImageContent
-            return Image(data=response.content, 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."
-            ) from e
-
-
-def register_camera_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
-    """Register Home Assistant camera tools."""
-    register_tool_methods(mcp, CameraTools(client))