ha-mcp-dev 8.3.0.dev2374__tar.gz → 8.3.0.dev2379__tar.gz

{ha_mcp_dev-8.3.0.dev2374/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.3.0.dev2379}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.3.0.dev2374
+Version: 8.3.0.dev2379
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

{ha_mcp_dev-8.3.0.dev2374 → ha_mcp_dev-8.3.0.dev2379}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.3.0.dev2374"
+version = "8.3.0.dev2379"
 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.3.0.dev2374 → ha_mcp_dev-8.3.0.dev2379}/src/ha_mcp/tools/device_control.py

@@ -8,6 +8,7 @@ and async operation verification through WebSocket monitoring.
 import asyncio
 import json
 import logging
+import math
 import time
 from typing import Any, ClassVar
 
@@ -88,7 +89,7 @@ class DeviceControlTools:
         entity_id: str,
         action: str,
         parameters: dict[str, Any] | None = None,
-        timeout_seconds: int = 10,
+        timeout_seconds: float = 10,
         validate_first: bool = True,
     ) -> dict[str, Any]:
         """
@@ -347,7 +348,13 @@ class DeviceControlTools:
     }
 
     _DOMAIN_PARAMS: ClassVar[dict[str, list[str]]] = {
-        "light": ["brightness", "color_temp_kelvin", "rgb_color", "effect"],
+        "light": [
+            "brightness",
+            "brightness_pct",
+            "color_temp_kelvin",
+            "rgb_color",
+            "effect",
+        ],
         "climate": ["temperature", "target_temp_high", "target_temp_low", "hvac_mode"],
         "cover": ["position", "tilt_position"],
         "media_player": ["volume_level", "media_content_id", "media_content_type"],
@@ -462,7 +469,7 @@ class DeviceControlTools:
         return expected if expected else None
 
     async def get_device_operation_status(
-        self, operation_id: str, timeout_seconds: int = 10
+        self, operation_id: str, timeout_seconds: float = 10
     ) -> dict[str, Any]:
         """Check status of a device operation, waiting up to ``timeout_seconds`` for completion.
 
@@ -495,9 +502,10 @@ class DeviceControlTools:
         if operation.status.value == "pending" and timeout_seconds > 0:
             deadline = time.monotonic() + timeout_seconds
             while operation.status.value == "pending":
-                if time.monotonic() >= deadline:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
                     break
-                await asyncio.sleep(0.2)
+                await asyncio.sleep(min(0.2, remaining))
                 refreshed = get_operation_from_memory(operation_id)
                 if refreshed is None:
                     raise_tool_error(
@@ -597,8 +605,52 @@ class DeviceControlTools:
             }
 
     @staticmethod
+    def _normalize_bulk_parameters(
+        value: Any,
+    ) -> tuple[dict[str, Any] | None, ErrorCode | None]:
+        """Normalize optional bulk parameters and identify invalid values."""
+        if isinstance(value, str):
+            try:
+                value = json.loads(value)
+            except json.JSONDecodeError:
+                return None, ErrorCode.VALIDATION_INVALID_JSON
+        if value is not None and not isinstance(value, dict):
+            return None, ErrorCode.VALIDATION_INVALID_PARAMETER
+        return value, None
+
+    @staticmethod
+    def _normalize_bulk_timeout(value: Any) -> tuple[float | None, bool]:
+        """Normalize an optional non-negative finite timeout."""
+        if value is None:
+            return None, True
+        try:
+            timeout = float(value)
+        except (TypeError, ValueError):
+            return None, False
+        return (
+            (timeout, True)
+            if math.isfinite(timeout) and timeout >= 0
+            else (None, False)
+        )
+
+    @staticmethod
+    def _normalized_bulk_operation(
+        operation: dict[str, Any],
+        parameters: dict[str, Any] | None,
+        timeout: float | None,
+    ) -> dict[str, Any]:
+        """Return one normalized valid bulk operation."""
+        normalized = dict(operation)
+        if parameters is not None:
+            normalized["parameters"] = parameters
+        if timeout is not None:
+            normalized["timeout_seconds"] = timeout
+        return normalized
+
+    @classmethod
     def _validate_bulk_operations(
-        operations: list[dict[str, Any]],
+        cls,
+        operations: list[Any],
         skipped_operations: list[dict[str, Any]],
     ) -> list[tuple[int, dict[str, Any], str, str]]:
         valid: list[tuple[int, dict[str, Any], str, str]] = []
@@ -614,6 +666,33 @@ class DeviceControlTools:
                 skipped_operations.append(err_response)
                 continue
 
+            allowed_keys = {
+                "entity_id",
+                "action",
+                "parameters",
+                "timeout_seconds",
+                "validate_first",
+            }
+            obsolete_keys = sorted(set(op) - allowed_keys)
+            if obsolete_keys:
+                key_list = ", ".join(obsolete_keys)
+                error = (
+                    f"Operation at index {i} contains unsupported key(s): {key_list}"
+                )
+                logger.warning(f"Bulk control: {error}")
+                err_response = create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    error,
+                    suggestions=[
+                        "Use entity_id and action; put action data inside parameters"
+                    ],
+                    context={"index": i, "unsupported_keys": obsolete_keys},
+                )
+                err_response["index"] = i
+                err_response["operation"] = op
+                skipped_operations.append(err_response)
+                continue
+
             entity_id = op.get("entity_id")
             action = op.get("action")
             missing = [f for f in ("entity_id", "action") if not op.get(f)]
@@ -627,13 +706,85 @@ class DeviceControlTools:
                 err_response["index"] = i
                 err_response["operation"] = op
                 skipped_operations.append(err_response)
-            else:
-                valid.append((i, op, str(entity_id), str(action)))
+                continue
+
+            if not isinstance(entity_id, str) or not isinstance(action, str):
+                error = f"Operation at index {i} requires string entity_id and action fields"
+                logger.warning(f"Bulk control: {error}")
+                err_response = create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    error,
+                    context={"index": i},
+                )
+                err_response["index"] = i
+                err_response["operation"] = op
+                skipped_operations.append(err_response)
+                continue
+
+            parameters, parameter_error = cls._normalize_bulk_parameters(
+                op.get("parameters")
+            )
+            if parameter_error is not None:
+                error = (
+                    f"Operation at index {i} has invalid JSON parameters"
+                    if parameter_error == ErrorCode.VALIDATION_INVALID_JSON
+                    else f"Operation at index {i} parameters must be a JSON object"
+                )
+                logger.warning(f"Bulk control: {error}")
+                err_response = create_error_response(
+                    parameter_error,
+                    error,
+                    context={"index": i},
+                )
+                err_response["index"] = i
+                err_response["operation"] = op
+                skipped_operations.append(err_response)
+                continue
+
+            timeout = None
+            timeout_valid = "timeout_seconds" not in op
+            if not timeout_valid:
+                timeout, timeout_valid = cls._normalize_bulk_timeout(
+                    op["timeout_seconds"]
+                )
+                timeout_valid = timeout_valid and timeout is not None
+            if not timeout_valid:
+                error = (
+                    f"Operation at index {i} timeout_seconds must be a "
+                    "non-negative number"
+                )
+                logger.warning(f"Bulk control: {error}")
+                err_response = create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    error,
+                    context={"index": i},
+                )
+                err_response["index"] = i
+                err_response["operation"] = op
+                skipped_operations.append(err_response)
+                continue
+
+            if "validate_first" in op and type(op["validate_first"]) is not bool:
+                error = f"Operation at index {i} validate_first must be a boolean"
+                logger.warning(f"Bulk control: {error}")
+                err_response = create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    error,
+                    context={"index": i},
+                )
+                err_response["index"] = i
+                err_response["operation"] = op
+                skipped_operations.append(err_response)
+                continue
+
+            normalized_op = cls._normalized_bulk_operation(op, parameters, timeout)
+            valid.append((i, normalized_op, entity_id, action))
+
         return valid
 
     async def bulk_device_control(
         self,
-        operations: list[dict[str, Any]],
+        operations: list[Any],
         parallel: bool = True,
         ctx: Context | None = None,
     ) -> dict[str, Any]:
@@ -672,6 +823,10 @@ class DeviceControlTools:
                 f"{len(skipped_operations)} skipped, "
                 f"mode={'parallel' if parallel else 'sequential'}",
             )
+            if not valid_operations:
+                return self._build_bulk_response(
+                    operations, results, operation_ids, skipped_operations, parallel
+                )
 
             # Route through the component's bulk_call_service capability when
             # advertised (D5a): one register-before-fire batch frame confirms every
@@ -904,7 +1059,7 @@ class DeviceControlTools:
 
     async def _bulk_via_component(
         self,
-        operations: list[dict[str, Any]],
+        operations: list[Any],
         valid_operations: list[tuple[int, dict[str, Any], str, str]],
         skipped_operations: list[dict[str, Any]],
         parallel: bool,
@@ -1111,7 +1266,7 @@ class DeviceControlTools:
 
     def _build_ambiguous_bulk_response(
         self,
-        operations: list[dict[str, Any]],
+        operations: list[Any],
         valid_operations: list[tuple[int, dict[str, Any], str, str]],
         rows: list[dict[str, Any]],
         skipped_operations: list[dict[str, Any]],
@@ -1246,7 +1401,7 @@ class DeviceControlTools:
 
     def _build_bulk_response(
         self,
-        operations: list[dict[str, Any]],
+        operations: list[Any],
         results: list[dict[str, Any]],
         operation_ids: list[str],
         skipped_operations: list[dict[str, Any]],
@@ -1293,7 +1448,7 @@ class DeviceControlTools:
         return response
 
     async def get_bulk_operation_status(
-        self, operation_ids: list[str], timeout_seconds: int = 10
+        self, operation_ids: list[str], timeout_seconds: float = 10
     ) -> dict[str, Any]:
         """
         Check status of multiple operations.

{ha_mcp_dev-8.3.0.dev2374 → ha_mcp_dev-8.3.0.dev2379}/src/ha_mcp/tools/smart_search/_base.py

@@ -40,7 +40,14 @@ class _SearchBase:
             logger.debug(f"Could not fetch {label}: {result}")
             cause = str(result) or type(result).__name__
         elif isinstance(result, dict) and result.get("success"):
-            registry = result.get("result", [])
+            payload = result.get("result", [])
+            if isinstance(payload, list):
+                registry = payload
+            else:
+                cause = (
+                    "malformed result payload: expected list, "
+                    f"got {type(payload).__name__}"
+                )
         elif isinstance(result, dict):
             cause = str(result.get("error") or "request failed")
         else:

{ha_mcp_dev-8.3.0.dev2374 → ha_mcp_dev-8.3.0.dev2379}/src/ha_mcp/tools/smart_search/_entities.py

@@ -4,7 +4,7 @@ import asyncio
 import logging
 from typing import Any
 
-from ...utils.fuzzy_search import calculate_partial_ratio
+from ...utils.fuzzy_search import calculate_partial_ratio, calculate_ratio
 from ...visibility.resolver import (
     device_registry_needed_for_visibility,
     load_hidden_set,
@@ -405,9 +405,10 @@ class EntitySearchMixin(_SearchBase):
         """
         Get entities grouped by area/room using the HA registries for accurate area resolution.
 
-        Uses entity registry, device registry, and area registry to determine
-        which area each entity belongs to. Fuzzy matches the query against
-        area names, IDs, and area-registry aliases to find the target area(s).
+        Uses the entity, device, area, and floor registries to determine which
+        area each entity belongs to. Resolution tries an exact area first,
+        then an exact or unambiguous close-spelling floor (expanded to every
+        area on that floor), and finally falls back to fuzzy area matching.
 
         Args:
             area_query: Area/room name (or alias) to search for
@@ -419,6 +420,10 @@ class EntitySearchMixin(_SearchBase):
 
         Returns:
             Dictionary with area-grouped entities
+
+        Raises:
+            ToolError: If mandatory Home Assistant state retrieval fails or an
+                unexpected search error occurs.
         """
         try:
             # Fetch all registries and states in parallel
@@ -433,6 +438,9 @@ class EntitySearchMixin(_SearchBase):
                 self.client.send_websocket_message(
                     {"type": "config/device_registry/list"}
                 ),
+                self.client.send_websocket_message(
+                    {"type": "config/floor_registry/list"}
+                ),
                 return_exceptions=True,
             )
 
@@ -465,11 +473,22 @@ class EntitySearchMixin(_SearchBase):
             area_registry = self._parse_area_registry(results[1], registry_warnings)
             entity_reg_map = self._parse_entity_reg_map(results[2], registry_warnings)
             device_area_map = self._parse_device_area_map(results[3], registry_warnings)
+            floor_result = results[4]
+            floor_registry_available = (
+                isinstance(floor_result, dict)
+                and floor_result.get("success") is True
+                and isinstance(floor_result.get("result"), list)
+            )
+            floor_registry = self._parse_floor_registry(floor_result, registry_warnings)
             degraded_warnings = registry_warnings + visibility_warnings
 
-            area_query_lower = area_query.lower().strip()
-            matched_area_ids = self._match_area_ids(area_registry, area_query_lower)
-
+            matched_area_ids, resolution_warnings = self._resolve_area_query(
+                area_registry,
+                floor_registry,
+                area_query,
+                floor_registry_available=floor_registry_available,
+            )
+            degraded_warnings.extend(resolution_warnings)
             if not matched_area_ids:
                 return merge_visibility_warnings(
                     {
@@ -536,6 +555,18 @@ class EntitySearchMixin(_SearchBase):
                 area_registry[area_id] = area
         return area_registry
 
+    @classmethod
+    def _parse_floor_registry(
+        cls, result: Any, warnings: list[str] | None = None
+    ) -> dict[str, dict[str, Any]]:
+        """Parse the floor registry into ``floor_id -> floor info``."""
+        floor_registry: dict[str, dict[str, Any]] = {}
+        for floor in cls._extract_registry_list(result, "floor registry", warnings):
+            floor_id = floor.get("floor_id", "")
+            if floor_id:
+                floor_registry[floor_id] = floor
+        return floor_registry
+
     @classmethod
     def _parse_entity_reg_map(
         cls, result: Any, warnings: list[str] | None = None
@@ -565,54 +596,203 @@ class EntitySearchMixin(_SearchBase):
         return device_area_map
 
     @staticmethod
+    def _match_exact_registry_ids(
+        registry: dict[str, dict[str, Any]],
+        id_key: str,
+        query_lower: str,
+    ) -> set[str]:
+        """Return exact case-insensitive id, name, or alias matches."""
+        matches: set[str] = set()
+        for registry_id, info in registry.items():
+            item_id = str(info.get(id_key) or registry_id)
+            name = str(info.get("name") or "")
+            aliases = info.get("aliases", []) or []
+            if (
+                query_lower == item_id.lower()
+                or query_lower == name.lower()
+                or any(
+                    query_lower == alias.lower()
+                    for alias in aliases
+                    if isinstance(alias, str)
+                )
+            ):
+                matches.add(registry_id)
+        return matches
+
+    @classmethod
+    def _resolve_area_query(
+        cls,
+        area_registry: dict[str, dict[str, Any]],
+        floor_registry: dict[str, dict[str, Any]],
+        area_query: str,
+        *,
+        floor_registry_available: bool,
+    ) -> tuple[set[str], list[str]]:
+        """Resolve exact area first, then exact/fuzzy floor, then fuzzy area."""
+        query_lower = area_query.lower().strip()
+        exact_area_ids = cls._match_exact_registry_ids(
+            area_registry, "area_id", query_lower
+        )
+        exact_floor_ids = cls._match_exact_registry_ids(
+            floor_registry, "floor_id", query_lower
+        )
+        if exact_area_ids:
+            warnings = []
+            if exact_floor_ids:
+                warnings.append(
+                    f"'{area_query}' matches both an area and a floor; "
+                    "the exact area match was used."
+                )
+            return exact_area_ids, warnings
+
+        if exact_floor_ids:
+            area_ids, warning = cls._expand_floor_ids(
+                area_registry,
+                floor_registry,
+                exact_floor_ids,
+                area_query,
+                fuzzy_match=False,
+            )
+            return area_ids, [warning]
+
+        if not floor_registry_available:
+            # Without the floor registry, fuzzy area matching could silently
+            # recreate the original floor->partial-area misresolution.
+            return set(), []
+
+        fuzzy_floor_ids, floor_score = cls._match_fuzzy_registry_ids(
+            floor_registry, "floor_id", query_lower
+        )
+        _, area_score = cls._match_fuzzy_registry_ids(
+            area_registry, "area_id", query_lower
+        )
+        if len(fuzzy_floor_ids) > 1 and floor_score > area_score:
+            floor_names = sorted(
+                str(
+                    floor_registry[floor_id].get("name")
+                    or floor_registry[floor_id].get("floor_id")
+                    or floor_id
+                )
+                for floor_id in fuzzy_floor_ids
+            )
+            return set(), [
+                f"'{area_query}' ambiguously matches multiple floors: "
+                f"{', '.join(floor_names)}. Use an exact floor name or ID."
+            ]
+        if len(fuzzy_floor_ids) == 1 and floor_score > area_score:
+            area_ids, warning = cls._expand_floor_ids(
+                area_registry,
+                floor_registry,
+                fuzzy_floor_ids,
+                area_query,
+                fuzzy_match=True,
+            )
+            return area_ids, [warning]
+        return cls._match_area_ids(area_registry, query_lower), []
+
+    @staticmethod
+    def _match_fuzzy_registry_ids(
+        registry: dict[str, dict[str, Any]],
+        id_key: str,
+        query_lower: str,
+    ) -> tuple[set[str], int]:
+        """Return best whole-string registry matches and their score.
+
+        Whole-string similarity distinguishes a typo in a floor name from an
+        area name that merely contains the floor name as one component.
+        """
+        best_ids: set[str] = set()
+        best_score = 0
+        for registry_id, info in registry.items():
+            values = [
+                str(info.get(id_key) or registry_id),
+                str(info.get("name") or ""),
+                *(
+                    alias
+                    for alias in (info.get("aliases", []) or [])
+                    if isinstance(alias, str)
+                ),
+            ]
+            score = max(
+                (
+                    calculate_ratio(query_lower, value.lower())
+                    for value in values
+                    if value
+                ),
+                default=0,
+            )
+            if score > best_score:
+                best_ids = {registry_id}
+                best_score = score
+            elif score == best_score:
+                best_ids.add(registry_id)
+        return (best_ids, best_score) if best_score >= 80 else (set(), best_score)
+
+    @staticmethod
+    def _expand_floor_ids(
+        area_registry: dict[str, dict[str, Any]],
+        floor_registry: dict[str, dict[str, Any]],
+        floor_ids: set[str],
+        area_query: str,
+        *,
+        fuzzy_match: bool,
+    ) -> tuple[set[str], str]:
+        """Expand floor IDs to their areas and build the model-facing warning."""
+        area_ids = {
+            area_id
+            for area_id, area in area_registry.items()
+            if area.get("floor_id") in floor_ids
+        }
+        floor_names = [
+            str(
+                floor_registry[floor_id].get("name")
+                or floor_registry[floor_id].get("floor_id")
+                or ""
+            )
+            for floor_id in sorted(floor_ids)
+        ]
+        floor_label = ", ".join(name for name in floor_names if name)
+        floor_suffix = f" ({floor_label})" if floor_label else ""
+        match_suffix = " from a close spelling" if fuzzy_match else ""
+        warning = (
+            f"'{area_query}' is a floor, not an area — expanded to "
+            f"{len(area_ids)} area(s) on the matched floor(s){floor_suffix}"
+            f"{match_suffix}."
+        )
+        return area_ids, warning
+
+    @classmethod
     def _match_area_ids(
-        area_registry: dict[str, dict[str, Any]], area_query_lower: str
+        cls, area_registry: dict[str, dict[str, Any]], area_query_lower: str
     ) -> set[str]:
-        """Resolve the query to area_ids: exact id/name/alias match, else fuzzy.
-
-        Two-pass: pass 1 collects exact id / name / alias matches; if any are
-        found, fuzzy aggregation is skipped entirely. This makes ``area_filter``
-        honor a literal area_id from ``ha_list_floors_areas`` — a query like
-        ``"bedroom_kids"`` would otherwise also fuzzy-match its parent
-        ``"bedroom"`` (partial_ratio=100) and aggregate sibling areas' entities.
-        Aliases (per-area registry, used by HA voice config) mirror the
-        entity-side enrichment in smart_entity_search.
+        """Resolve the query to area IDs: exact id/name/alias, then fuzzy.
+
+        Exact matches delegate to the shared registry matcher so area and floor
+        precedence use identical case-insensitive semantics.
         """
-        exact_area_ids: set[str] = set()
-        fuzzy_area_ids: set[str] = set()
+        exact_area_ids = cls._match_exact_registry_ids(
+            area_registry, "area_id", area_query_lower
+        )
+        if exact_area_ids:
+            return exact_area_ids
 
+        fuzzy_area_ids: set[str] = set()
         for area_id, area_info in area_registry.items():
-            area_name = area_info.get("name", "")
+            area_name = str(area_info.get("name") or "")
             area_aliases = area_info.get("aliases", []) or []
-            # Exact match on area_id, name, or any alias (case-insensitive)
-            if (
-                area_query_lower == area_id.lower()
-                or area_query_lower == area_name.lower()
-                or any(
-                    area_query_lower == a.lower()
-                    for a in area_aliases
-                    if isinstance(a, str)
-                )
-            ):
-                exact_area_ids.add(area_id)
-                continue
-            # Fuzzy match on area name, id, or any alias
             name_score = calculate_partial_ratio(area_query_lower, area_name.lower())
             id_score = calculate_partial_ratio(area_query_lower, area_id.lower())
             alias_score = max(
                 (
-                    calculate_partial_ratio(area_query_lower, a.lower())
-                    for a in area_aliases
-                    if isinstance(a, str)
+                    calculate_partial_ratio(area_query_lower, alias.lower())
+                    for alias in area_aliases
+                    if isinstance(alias, str)
                 ),
                 default=0,
             )
             if max(name_score, id_score, alias_score) >= 80:
                 fuzzy_area_ids.add(area_id)
-
-        # Exact matches win — fuzzy aggregation only runs when no area_query is
-        # itself an area_id / name / alias.
-        return exact_area_ids or fuzzy_area_ids
+        return fuzzy_area_ids
 
     @staticmethod
     def _resolve_entity_areas(

{ha_mcp_dev-8.3.0.dev2374 → ha_mcp_dev-8.3.0.dev2379}/src/ha_mcp/tools/tools_search.py

@@ -321,6 +321,13 @@ def _finalize_partial_state(
     if partial_local:
         response["partial"] = True
         response["errors"].extend(errors_local)
+        local_reason = "; ".join(
+            f"{error['surface']}: {error['error']}" for error in errors_local
+        )
+        existing_reason = response.get("partial_reason")
+        response["partial_reason"] = (
+            f"{existing_reason}; {local_reason}" if existing_reason else local_reason
+        )
 
 
 def _compute_eligibility(
@@ -1691,8 +1698,10 @@ class SearchTools:
             Field(
                 default=None,
                 description=(
-                    "Narrow entity-registry results to an area (id or name). "
-                    "Does not affect configuration search."
+                    "Narrow entity-registry results to an area (id, name, or alias), "
+                    "an exact floor (id, name, or alias), or an unambiguous "
+                    "close-spelling floor match; a floor match expands to all areas "
+                    "on that floor. Does not affect configuration search."
                 ),
             ),
         ] = None,
@@ -2255,7 +2264,10 @@ class SearchTools:
             str | None,
             Field(
                 default=None,
-                description="Limit to entities in a specific area (area ID or name).",
+                description=(
+                    "Limit to an area, or an exact/close floor name to expand "
+                    "to every area on that floor."
+                ),
             ),
         ] = None,
         limit: Annotated[