ha-mcp-dev 8.6.0.dev2871__tar.gz → 8.6.0.dev2876__tar.gz

{ha_mcp_dev-8.6.0.dev2871 → ha_mcp_dev-8.6.0.dev2876}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.6.0.dev2871
+Version: 8.6.0.dev2876
 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.dev2871 → ha_mcp_dev-8.6.0.dev2876}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.6.0.dev2871"
+version = "8.6.0.dev2876"
 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.dev2871 → ha_mcp_dev-8.6.0.dev2876}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.6.0.dev2871"
+version = "8.6.0.dev2876"
 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.dev2876/src/ha_mcp/tools/area_messages.py

@@ -0,0 +1,171 @@
+"""WebSocket message builders and parameter checks for the area/floor setter.
+
+Kept apart from ``tools_areas`` so the tool module stays under the size ratchet;
+these are pure functions over the parameters ``ha_set_area_or_floor`` accepts.
+"""
+
+from typing import Any
+
+from ..errors import ErrorCode, create_error_response
+from .helpers import raise_tool_error
+
+_AREA_PARAMS = (
+    "name, id, floor_id, icon, aliases, picture, labels, "
+    "temperature_entity_id, humidity_entity_id"
+)
+
+
+def validate_cross_kind_params(
+    kind: str,
+    level: int | None,
+    floor_id: str | None,
+    picture: str | None,
+    labels: list[str] | None = None,
+    temperature_entity_id: str | None = None,
+    humidity_entity_id: str | None = None,
+) -> None:
+    """Reject params that don't belong to *kind* before building a set message."""
+    # Reject cross-kind params loudly so silent intent loss can't happen
+    # (e.g., kind='floor' with picture='...' previously dropped the picture
+    # without a diagnostic). Floors have no labels in HA core.
+    cross_kind_params: list[str] = []
+    if kind == "area" and level is not None:
+        cross_kind_params.append("level")
+    elif kind == "floor":
+        if floor_id is not None:
+            cross_kind_params.append("floor_id")
+        if picture is not None:
+            cross_kind_params.append("picture")
+        if labels is not None:
+            cross_kind_params.append("labels")
+        if temperature_entity_id is not None:
+            cross_kind_params.append("temperature_entity_id")
+        if humidity_entity_id is not None:
+            cross_kind_params.append("humidity_entity_id")
+    if cross_kind_params:
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.VALIDATION_INVALID_PARAMETER,
+                f"Parameter(s) {cross_kind_params} are not valid for kind={kind!r}",
+                context={"kind": kind, "invalid_parameters": cross_kind_params},
+                suggestions=[
+                    f"For kind='area' use: {_AREA_PARAMS}",
+                    "For kind='floor' use: name, id, level, icon, aliases",
+                ],
+            )
+        )
+
+
+def build_area_update_message(
+    area_id: str,
+    name: str | None,
+    floor_id: str | None,
+    icon: str | None,
+    parsed_aliases: list[str] | None,
+    picture: str | None,
+    parsed_labels: list[str] | None,
+    temperature_entity_id: str | None = None,
+    humidity_entity_id: str | None = None,
+) -> dict[str, Any]:
+    """Build a WebSocket message for updating an existing area."""
+    message: dict[str, Any] = {
+        "type": "config/area_registry/update",
+        "area_id": area_id,
+    }
+    if name is not None:
+        message["name"] = name
+    if floor_id is not None:
+        message["floor_id"] = floor_id if floor_id else None
+    if icon is not None:
+        message["icon"] = icon if icon else None
+    if parsed_aliases is not None:
+        message["aliases"] = parsed_aliases
+    if picture is not None:
+        message["picture"] = picture if picture else None
+    if parsed_labels is not None:
+        message["labels"] = parsed_labels
+    if temperature_entity_id is not None:
+        message["temperature_entity_id"] = temperature_entity_id or None
+    if humidity_entity_id is not None:
+        message["humidity_entity_id"] = humidity_entity_id or None
+    return message
+
+
+def build_area_create_message(
+    name: str,
+    floor_id: str | None,
+    icon: str | None,
+    parsed_aliases: list[str] | None,
+    picture: str | None,
+    parsed_labels: list[str] | None,
+    temperature_entity_id: str | None = None,
+    humidity_entity_id: str | None = None,
+) -> dict[str, Any]:
+    """Build a WebSocket message for creating a new area."""
+    message: dict[str, Any] = {
+        "type": "config/area_registry/create",
+        "name": name,
+    }
+    if floor_id:
+        message["floor_id"] = floor_id
+    if icon:
+        message["icon"] = icon
+    if parsed_aliases:
+        message["aliases"] = parsed_aliases
+    if picture:
+        message["picture"] = picture
+    if parsed_labels:
+        message["labels"] = parsed_labels
+    if temperature_entity_id:
+        message["temperature_entity_id"] = temperature_entity_id
+    if humidity_entity_id:
+        message["humidity_entity_id"] = humidity_entity_id
+    return message
+
+
+def build_floor_update_message(
+    floor_id: str,
+    name: str | None,
+    level: int | None,
+    icon: str | None,
+    parsed_aliases: list[str] | None,
+) -> dict[str, Any]:
+    """Build a WebSocket message for updating an existing floor."""
+    message: dict[str, Any] = {
+        "type": "config/floor_registry/update",
+        "floor_id": floor_id,
+    }
+    if name is not None:
+        message["name"] = name
+    if level is not None:
+        message["level"] = level
+    if icon is not None:
+        message["icon"] = icon if icon else None
+    if parsed_aliases is not None:
+        message["aliases"] = parsed_aliases
+    return message
+
+
+def build_floor_create_message(
+    name: str,
+    level: int | None,
+    icon: str | None,
+    parsed_aliases: list[str] | None,
+) -> dict[str, Any]:
+    """Build a WebSocket message for creating a new floor."""
+    message: dict[str, Any] = {
+        "type": "config/floor_registry/create",
+        "name": name,
+    }
+    if level is not None:
+        message["level"] = level
+    if icon:
+        message["icon"] = icon
+    if parsed_aliases:
+        message["aliases"] = parsed_aliases
+    return message
+
+
+# ============================================================
+# AREA & FLOOR LISTING
+# ============================================================

ha_mcp_dev-8.6.0.dev2876/src/ha_mcp/tools/entity_param_parsing.py

@@ -0,0 +1,173 @@
+"""Parameter parsing for ha_set_entity's list/dict arguments."""
+
+import json
+from typing import Any
+
+from ..errors import ErrorCode, create_error_response
+from .coercion import parse_json_param, parse_string_list_param
+from .helpers import raise_tool_error
+from .tools_voice_assistant import KNOWN_ASSISTANTS
+
+
+def _parse_string_list_field(
+    value: str | list[str] | None,
+    field_name: str,
+) -> list[str] | None:
+    """Parse and validate a string-list field (aliases, labels, etc.)."""
+    if value is not None:
+        try:
+            return parse_string_list_param(value, field_name)
+        except ValueError as e:
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    f"Invalid {field_name} parameter: {e}",
+                )
+            )
+    return None
+
+
+def _parse_aliases_param(
+    aliases: str | list[str | None] | None,
+) -> list[str | None] | None:
+    """Parse aliases, keeping ``null`` entries.
+
+    HA stores the entity's own (computed) name as a ``null`` entry in
+    ``aliases`` (issue #2495); it must survive the round trip.
+    """
+    if aliases is None:
+        return None
+    parsed: Any = aliases
+    if isinstance(aliases, str):
+        try:
+            parsed = json.loads(aliases)
+        except (json.JSONDecodeError, RecursionError) as e:
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    f"Invalid aliases parameter: Invalid JSON in aliases: {e}",
+                )
+            )
+    if not isinstance(parsed, list) or not all(
+        item is None or isinstance(item, str) for item in parsed
+    ):
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.VALIDATION_INVALID_PARAMETER,
+                "Invalid aliases parameter: aliases must be a JSON array of "
+                "strings (null entries stand for the entity's own name)",
+            )
+        )
+    return parsed
+
+
+def _parse_categories_param(
+    categories: dict[str, str | None] | None,
+) -> dict[str, str | None] | None:
+    """Parse and validate the categories parameter."""
+    if categories is not None:
+        try:
+            parsed_cats = parse_json_param(categories, "categories")
+        except ValueError as e:
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    f"Invalid categories parameter: {e}",
+                )
+            )
+        if not isinstance(parsed_cats, dict):
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    "categories must be a dict mapping scope to category_id, "
+                    'e.g. {"automation": "my_category_id"}',
+                )
+            )
+        return parsed_cats
+    return None
+
+
+def _parse_options_param(
+    options: dict[str, dict[str, Any]] | None,
+) -> dict[str, dict[str, Any]] | None:
+    """Parse and validate the options parameter."""
+    if options is not None:
+        try:
+            parsed_opts = parse_json_param(options, "options")
+        except ValueError as e:
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    f"Invalid options parameter: {e}",
+                )
+            )
+        if not isinstance(parsed_opts, dict):
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    f"options must be a dict mapping domain to a sub-dict "
+                    f"(got {type(parsed_opts).__name__}), "
+                    'e.g. {"sensor": {"display_precision": 2}}',
+                )
+            )
+        if not parsed_opts:
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    "options cannot be an empty dict — pass at least one "
+                    'domain entry, e.g. {"sensor": {"display_precision": 2}}, '
+                    "or omit the parameter entirely.",
+                )
+            )
+        bad_subs = [
+            f"{k!r}: {type(v).__name__}"
+            for k, v in parsed_opts.items()
+            if not isinstance(v, dict)
+        ]
+        if bad_subs:
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    "options sub-values must be dicts, got non-dict for: "
+                    f"{', '.join(bad_subs)}",
+                )
+            )
+        return parsed_opts
+    return None
+
+
+def _parse_expose_to_param(
+    expose_to: dict[str, bool] | None,
+) -> dict[str, bool] | None:
+    """Parse and validate the expose_to parameter."""
+    if expose_to is not None:
+        try:
+            parsed = parse_json_param(expose_to, "expose_to")
+        except ValueError as e:
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    str(e),
+                )
+            )
+        if not isinstance(parsed, dict):
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    "expose_to must be a dict mapping assistant IDs to booleans, "
+                    'e.g. {"conversation": true, "cloud.alexa": false}',
+                )
+            )
+        # Validate assistant names
+        invalid_assistants = [a for a in parsed if a not in KNOWN_ASSISTANTS]
+        if invalid_assistants:
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    f"Invalid assistant(s) in expose_to: {invalid_assistants}. "
+                    f"Valid: {KNOWN_ASSISTANTS}",
+                )
+            )
+        # Values are already bool (enforced by the dict[str, bool] annotation)
+        return parsed
+    return None

ha_mcp_dev-8.6.0.dev2876/src/ha_mcp/tools/entity_update_fields.py

@@ -0,0 +1,171 @@
+"""Builders for the config/entity_registry/update message of ha_set_entity."""
+
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from packaging.version import InvalidVersion, Version
+
+from ..errors import ErrorCode, create_error_response
+from .helpers import clearable_value, raise_tool_error
+
+# Home Assistant release that reads an empty entity-name override as "use the
+# device name" (home-assistant/core#181576). Older Cores store "" but render
+# the default name, so the switch would silently do the opposite there.
+USE_DEVICE_NAME_MIN_CORE = (2026, 10)
+
+
+def reject_name_with_use_device_name(
+    name: str | None, use_device_name: bool | None
+) -> None:
+    """Both write the same registry field with different meanings."""
+    if name is not None and use_device_name is not None:
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.VALIDATION_INVALID_PARAMETER,
+                "name and use_device_name cannot be combined: use_device_name "
+                "replaces the name override with the device name",
+                suggestions=[
+                    "Pass use_device_name=True alone to follow the device name",
+                    "Pass name alone to set a custom name ('' reverts to the default)",
+                ],
+            )
+        )
+
+
+def uses_device_name(entry: dict[str, Any]) -> bool:
+    """An empty name override follows the device name; without a device there is nothing to follow."""
+    return entry.get("name") == "" and bool(entry.get("device_id"))
+
+
+def reject_use_device_name_without_device(
+    entity_id: str, entry: dict[str, Any]
+) -> None:
+    """A device-less entity has no device name; Core would render an empty name."""
+    if entry.get("device_id"):
+        return
+    raise_tool_error(
+        create_error_response(
+            ErrorCode.VALIDATION_INVALID_PARAMETER,
+            f"{entity_id} has no device, so there is no device name to follow",
+            context={"entity_id": entity_id},
+            suggestions=["Pass name='<text>' to give the entity a custom name"],
+        )
+    )
+
+
+async def ensure_use_device_name_allowed(
+    use_device_name: bool | None,
+    client: Any,
+    entity_id: str,
+    fetch_entity: Callable[[str], Awaitable[dict[str, Any]]],
+) -> None:
+    """use_device_name=True needs a 2026.10 Core and an entity with a device."""
+    if not use_device_name:
+        return
+    await ensure_use_device_name_supported(client)
+    try:
+        current = await fetch_entity(entity_id)
+    except ValueError as e:
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.SERVICE_CALL_FAILED,
+                f"Entity not found: {e}",
+                context={"entity_id": entity_id},
+                suggestions=["Use ha_search() to find valid entity IDs"],
+            )
+        )
+    reject_use_device_name_without_device(entity_id, current)
+
+
+async def ensure_use_device_name_supported(client: Any) -> None:
+    """Refuse use_device_name=True on a Core older than 2026.10."""
+    config = await client.get_config()
+    raw = str(config.get("version", ""))
+    try:
+        release = Version(raw).release[:2]
+    except InvalidVersion:
+        release = ()
+    if tuple(release) >= USE_DEVICE_NAME_MIN_CORE:
+        return
+    raise_tool_error(
+        create_error_response(
+            ErrorCode.VALIDATION_INVALID_PARAMETER,
+            f"use_device_name needs Home Assistant 2026.10 or newer; this Core "
+            f"reports {raw or 'an unknown version'} and would show the default "
+            f"name instead",
+            context={"ha_version": raw},
+            suggestions=[
+                "Upgrade Home Assistant to 2026.10 or newer",
+                "Pass name='<device name>' to set the device's name as a fixed custom name",
+            ],
+        )
+    )
+
+
+def build_name_visibility_fields(
+    message: dict[str, Any],
+    updates_made: list[str],
+    area_id: str | None,
+    name: str | None,
+    icon: str | None,
+    device_class: str | None,
+    use_device_name: bool | None = None,
+) -> None:
+    """Add basic positioning/appearance fields to the update message."""
+    if area_id is not None:
+        area_id = clearable_value(area_id, "area_id")
+        message["area_id"] = area_id
+        updates_made.append(f"area_id='{area_id}'" if area_id else "area cleared")
+    if name is not None:
+        name = clearable_value(name, "name")
+        message["name"] = name
+        updates_made.append(f"name='{name}'" if name else "name cleared")
+    if use_device_name is not None:
+        message["name"] = "" if use_device_name else None
+        updates_made.append(
+            "name follows device" if use_device_name else "name cleared"
+        )
+    if icon is not None:
+        icon = clearable_value(icon, "icon")
+        message["icon"] = icon
+        updates_made.append(f"icon='{icon}'" if icon else "icon cleared")
+    if device_class is not None:
+        device_class = clearable_value(device_class, "device_class")
+        message["device_class"] = device_class
+        updates_made.append(
+            f"device_class='{device_class}'" if device_class else "device_class cleared"
+        )
+
+
+def build_state_tag_fields(
+    message: dict[str, Any],
+    updates_made: list[str],
+    enabled: bool | None,
+    hidden: bool | None,
+    parsed_aliases: list[str | None] | None,
+    parsed_categories: dict[str, str | None] | None,
+    final_labels: list[str] | None,
+    label_operation: str,
+    parsed_labels: list[str] | None,
+) -> None:
+    """Add enabled/hidden/alias/category/label fields to the update message."""
+    if enabled is not None:
+        message["disabled_by"] = None if enabled else "user"
+        updates_made.append("enabled" if enabled else "disabled")
+    if hidden is not None:
+        message["hidden_by"] = "user" if hidden else None
+        updates_made.append("hidden" if hidden else "visible")
+    if parsed_aliases is not None:
+        message["aliases"] = parsed_aliases
+        updates_made.append(f"aliases={parsed_aliases}")
+    if parsed_categories is not None:
+        message["categories"] = parsed_categories
+        updates_made.append(f"categories={parsed_categories}")
+    if final_labels is not None:
+        message["labels"] = final_labels
+        if label_operation == "set":
+            updates_made.append(f"labels={final_labels}")
+        elif label_operation == "add":
+            updates_made.append(f"labels added: {parsed_labels} -> {final_labels}")
+        else:  # remove
+            updates_made.append(f"labels removed: {parsed_labels} -> {final_labels}")