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

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

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

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

@@ -42,10 +42,23 @@ from .helpers import (
     safe_info,
     safe_progress,
 )
+from .tools_service import BulkControlOperation
 from .util_helpers import _SERVICE_TO_STATE
 
 logger = logging.getLogger(__name__)
 
+# The bulk row contract is declared once, on the advertised transport schema.
+# Reading its keys back here keeps the runtime batch validator from drifting
+# out of sync with what models are told they may send.
+_BULK_OPERATION_KEYS: frozenset[str] = frozenset(BulkControlOperation.__annotations__)
+
+# The row shape models get wrong most often is a service-style row, so this
+# leads every suggestion list a rejected bulk batch produces.
+_BULK_ROW_SHAPE_SUGGESTION = (
+    "Use entity_id and action (e.g. action='off', not service='turn_off'); "
+    "send no domain or service keys and put action data in parameters"
+)
+
 # The ha_mcp_tools/bulk_call_service WS command (Phase 3, D5a): the BATCH write
 # capability. When the component advertises ``bulk_call_service`` the consumer
 # resolves every op's domain/service server-side (D6), sends one register-before-fire
@@ -347,6 +360,10 @@ class DeviceControlTools:
         "set": "set_temperature",
     }
 
+    # Silent allowlist: _add_domain_params copies only these keys into the
+    # service call and drops everything else without an error, and a domain
+    # absent from this table loses every parameter. Extend it when adding
+    # support for a new parameter, or the parameter vanishes at dispatch.
     _DOMAIN_PARAMS: ClassVar[dict[str, list[str]]] = {
         "light": [
             "brightness",
@@ -474,10 +491,10 @@ class DeviceControlTools:
         """Check status of a device operation, waiting up to ``timeout_seconds`` for completion.
 
         Polls the in-memory operation registry (mutated by the WebSocket
-        listener as state changes arrive) every 0.2s while the operation is
-        pending, up to ``timeout_seconds``. Returns the final structured status
-        — completed/failed/timeout/pending — produced by
-        ``control_device_smart``.
+        listener as state changes arrive) while the operation is pending, at
+        0.2s intervals except for a final shorter poll that lands exactly on
+        the deadline. Returns the final structured status —
+        completed/failed/timeout/pending — produced by ``control_device_smart``.
         """
         operation = get_operation_from_memory(operation_id)
 
@@ -607,31 +624,58 @@ class DeviceControlTools:
     @staticmethod
     def _normalize_bulk_parameters(
         value: Any,
-    ) -> tuple[dict[str, Any] | None, ErrorCode | None]:
-        """Normalize optional bulk parameters and identify invalid values."""
+    ) -> tuple[dict[str, Any] | None, ErrorCode | None, str]:
+        """Normalize a present ``parameters`` value and identify invalid ones.
+
+        Returns ``(parameters, error_code, detail)``. ``detail`` carries the
+        decoder's own reason and offset for a JSON failure — without it the
+        caller can only say "invalid JSON", which does not tell the sender
+        where its string went wrong. It is empty for every other outcome.
+        """
         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
+            except json.JSONDecodeError as exc:
+                return (
+                    None,
+                    ErrorCode.VALIDATION_INVALID_JSON,
+                    f"{exc.msg} at position {exc.pos}",
+                )
+            except RecursionError:
+                # json.loads recurses per nesting level; a pathologically
+                # nested string must skip the row, not abort the batch.
+                return (
+                    None,
+                    ErrorCode.VALIDATION_INVALID_JSON,
+                    "JSON nested too deeply",
+                )
+        if not isinstance(value, dict):
+            # A present-but-null value is malformed, same as timeout_seconds
+            # and validate_first; an absent key never reaches this helper.
+            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
+    def _normalize_bulk_timeout(value: Any) -> float | None:
+        """Normalize a non-negative finite timeout, or ``None`` when invalid.
+
+        Bools are rejected before ``float()`` sees them: ``float(True)`` is 1.0,
+        which would silently accept ``timeout_seconds: true`` as a one-second
+        wait. Strings are rejected for the same reason — the advertised schema
+        is ``strict``, so coercing ``"10"`` here would silently accept what the
+        schema tells the model is invalid. ``None`` is invalid here too — the
+        caller only calls this when the key is present, and a present-but-null
+        timeout is a malformed row.
+        """
+        if isinstance(value, (bool, str)) or value is None:
+            return None
         try:
             timeout = float(value)
-        except (TypeError, ValueError):
-            return None, False
-        return (
-            (timeout, True)
-            if math.isfinite(timeout) and timeout >= 0
-            else (None, False)
-        )
+        except (TypeError, ValueError, OverflowError):
+            # OverflowError: an int too large for float must skip the row,
+            # not abort the batch through the generic exception handler.
+            return None
+        return timeout if math.isfinite(timeout) and timeout >= 0 else None
 
     @staticmethod
     def _normalized_bulk_operation(
@@ -647,6 +691,28 @@ class DeviceControlTools:
             normalized["timeout_seconds"] = timeout
         return normalized
 
+    @staticmethod
+    def _skip_bulk_operation(
+        skipped_operations: list[dict[str, Any]],
+        op: Any,
+        code: ErrorCode,
+        error: str,
+        context: dict[str, Any],
+        suggestions: list[str] | None = None,
+    ) -> None:
+        """Log one rejected bulk row and record its structured skip entry.
+
+        ``create_error_response`` lifts every ``context`` key to the top level,
+        so ``index`` needs no separate write; ``operation`` is not a context
+        key and is attached here so callers can see the row they sent.
+        """
+        logger.warning(f"Bulk control: {error}")
+        err_response = create_error_response(
+            code, error, suggestions=suggestions, context=context
+        )
+        err_response["operation"] = op
+        skipped_operations.append(err_response)
+
     @classmethod
     def _validate_bulk_operations(
         cls,
@@ -656,41 +722,28 @@ class DeviceControlTools:
         valid: list[tuple[int, dict[str, Any], str, str]] = []
         for i, op in enumerate(operations):
             if not isinstance(op, dict):
-                error = f"Operation at index {i} is not a dict: {type(op).__name__}"
-                logger.warning(f"Bulk control: {error}")
-                err_response = create_error_response(
-                    ErrorCode.VALIDATION_MISSING_PARAMETER, error, context={"index": i}
+                cls._skip_bulk_operation(
+                    skipped_operations,
+                    op,
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    f"Operation at index {i} is not a dict: {type(op).__name__}",
+                    {"index": i},
                 )
-                err_response["index"] = i
-                err_response["operation"] = op
-                skipped_operations.append(err_response)
                 continue
 
-            allowed_keys = {
-                "entity_id",
-                "action",
-                "parameters",
-                "timeout_seconds",
-                "validate_first",
-            }
-            obsolete_keys = sorted(set(op) - allowed_keys)
+            # str() before sorting: a direct Python caller can pass non-string
+            # keys, and mixed key types make sorted()/join() raise mid-batch.
+            obsolete_keys = sorted(str(key) for key in set(op) - _BULK_OPERATION_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(
+                cls._skip_bulk_operation(
+                    skipped_operations,
+                    op,
                     ErrorCode.VALIDATION_INVALID_PARAMETER,
-                    error,
-                    suggestions=[
-                        "Use entity_id and action; put action data inside parameters"
-                    ],
-                    context={"index": i, "unsupported_keys": obsolete_keys},
+                    f"Operation at index {i} contains unsupported key(s): {key_list}",
+                    {"index": i, "unsupported_keys": obsolete_keys},
+                    suggestions=[_BULK_ROW_SHAPE_SUGGESTION],
                 )
-                err_response["index"] = i
-                err_response["operation"] = op
-                skipped_operations.append(err_response)
                 continue
 
             entity_id = op.get("entity_id")
@@ -698,83 +751,70 @@ class DeviceControlTools:
             missing = [f for f in ("entity_id", "action") if not op.get(f)]
 
             if missing:
-                error = f"Operation at index {i} missing required fields: {', '.join(missing)}"
-                logger.warning(f"Bulk control: {error}")
-                err_response = create_error_response(
-                    ErrorCode.VALIDATION_MISSING_PARAMETER, error, context={"index": i}
+                cls._skip_bulk_operation(
+                    skipped_operations,
+                    op,
+                    ErrorCode.VALIDATION_MISSING_PARAMETER,
+                    f"Operation at index {i} missing required fields: "
+                    f"{', '.join(missing)}",
+                    {"index": i},
                 )
-                err_response["index"] = i
-                err_response["operation"] = op
-                skipped_operations.append(err_response)
                 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(
+                cls._skip_bulk_operation(
+                    skipped_operations,
+                    op,
                     ErrorCode.VALIDATION_INVALID_PARAMETER,
-                    error,
-                    context={"index": i},
+                    f"Operation at index {i} requires string entity_id and "
+                    "action fields",
+                    {"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")
+            parameters, parameter_error, parameter_detail = (
+                cls._normalize_bulk_parameters(op["parameters"])
+                if "parameters" in op
+                else (None, None, "")
             )
             if parameter_error is not None:
-                error = (
-                    f"Operation at index {i} has invalid JSON parameters"
+                parameter_message = (
+                    f"Operation at index {i} has invalid JSON parameters: "
+                    f"{parameter_detail}"
                     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(
+                cls._skip_bulk_operation(
+                    skipped_operations,
+                    op,
                     parameter_error,
-                    error,
-                    context={"index": i},
+                    parameter_message,
+                    {"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
+            timeout: float | None = None
+            if "timeout_seconds" in op:
+                timeout = cls._normalize_bulk_timeout(op["timeout_seconds"])
+                if timeout is None:
+                    cls._skip_bulk_operation(
+                        skipped_operations,
+                        op,
+                        ErrorCode.VALIDATION_INVALID_PARAMETER,
+                        f"Operation at index {i} timeout_seconds must be a "
+                        "non-negative number",
+                        {"index": i},
+                    )
+                    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(
+            if "validate_first" in op and not isinstance(op["validate_first"], bool):
+                cls._skip_bulk_operation(
+                    skipped_operations,
+                    op,
                     ErrorCode.VALIDATION_INVALID_PARAMETER,
-                    error,
-                    context={"index": i},
+                    f"Operation at index {i} validate_first must be a boolean",
+                    {"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)
@@ -824,8 +864,24 @@ class DeviceControlTools:
                 f"mode={'parallel' if parallel else 'sequential'}",
             )
             if not valid_operations:
-                return self._build_bulk_response(
-                    operations, results, operation_ids, skipped_operations, parallel
+                # Nothing dispatched, so nothing to fail soft for: the batch
+                # carve-out from "all tool-level failures raise" exists to
+                # protect successful siblings, and there are none. Raising
+                # before the component probe keeps the no-dispatch guarantee.
+                raise_tool_error(
+                    create_error_response(
+                        ErrorCode.VALIDATION_INVALID_PARAMETER,
+                        f"All {len(operations)} operation(s) failed validation; "
+                        "nothing was dispatched",
+                        suggestions=[
+                            _BULK_ROW_SHAPE_SUGGESTION,
+                            "Each operation requires 'entity_id' and 'action'",
+                            "Check skipped_details for the per-operation reason",
+                            "Example: {'entity_id': 'light.living_room', "
+                            + "'action': 'on'}",
+                        ],
+                        context={"skipped_details": skipped_operations},
+                    )
                 )
 
             # Route through the component's bulk_call_service capability when
@@ -1439,6 +1495,7 @@ class DeviceControlTools:
         if skipped_operations:
             response["skipped_details"] = skipped_operations
             response["suggestions"] = [
+                _BULK_ROW_SHAPE_SUGGESTION,
                 "Some operations were skipped due to validation errors",
                 "Each operation requires 'entity_id' and 'action' fields",
                 "Check skipped_details for specific errors",

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

@@ -40,9 +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"):
-            payload = result.get("result", [])
+            # No default for a missing key: a legitimate empty registry is
+            # "result": [], so an absent result is a malformed envelope and
+            # must degrade loudly, not read as available-and-empty.
+            payload = result.get("result")
             if isinstance(payload, list):
                 registry = payload
+            elif payload is None and "result" not in result:
+                cause = "malformed result payload: result key missing"
             else:
                 cause = (
                     "malformed result payload: expected list, "

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

@@ -473,13 +473,15 @@ 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)
+            # Availability is read back OUT of the parse rather than re-derived
+            # from the raw payload: the parser already decides what counts as
+            # usable floor data, and a second predicate here drifted from it
+            # once. An empty warnings list means the parser accepted the
+            # payload; anything else disables the fuzzy floor/area fallback.
+            floor_warnings: list[str] = []
+            floor_registry = self._parse_floor_registry(results[4], floor_warnings)
+            floor_registry_available = not floor_warnings
+            registry_warnings.extend(floor_warnings)
             degraded_warnings = registry_warnings + visibility_warnings
 
             matched_area_ids, resolution_warnings = self._resolve_area_query(
@@ -657,8 +659,15 @@ class EntitySearchMixin(_SearchBase):
 
         if not floor_registry_available:
             # Without the floor registry, fuzzy area matching could silently
-            # recreate the original floor->partial-area misresolution.
-            return set(), []
+            # recreate the original floor->partial-area misresolution. The
+            # fetch warning names the outage; this one names what the outage
+            # cost the caller, so "no match" is not read as "no such area".
+            return set(), [
+                f"Floor data is unavailable, so '{area_query}' was matched only "
+                "against exact area IDs, names, and aliases; close-spelling "
+                "matching was skipped. Retry, or pass an exact area_id from "
+                "ha_list_floors_areas."
+            ]
 
         fuzzy_floor_ids, floor_score = cls._match_fuzzy_registry_ids(
             floor_registry, "floor_id", query_lower
@@ -768,7 +777,10 @@ class EntitySearchMixin(_SearchBase):
         """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.
+        precedence use identical case-insensitive semantics. Exact must win
+        outright: a query like "bedroom_kids" partial-matches its parent
+        "bedroom" at ratio 100, so falling through to the fuzzy pass would
+        aggregate every sibling area's entities under an exact hit.
         """
         exact_area_ids = cls._match_exact_registry_ids(
             area_registry, "area_id", area_query_lower

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

@@ -321,12 +321,11 @@ 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
+        _merge_partial_reason(
+            response,
+            "; ".join(
+                f"{error['surface']}: {error['error']}" for error in errors_local
+            ),
         )
 
 
@@ -2217,7 +2216,11 @@ class SearchTools:
                 raise outcome
             if isinstance(outcome, Exception):
                 partial = True
-                errors.append({"surface": label, "error": str(outcome)})
+                # ``str(asyncio.TimeoutError())`` is "" — fall back to the type
+                # name so partial_reason never reads "entities: ".
+                errors.append(
+                    {"surface": label, "error": str(outcome) or type(outcome).__name__}
+                )
                 logger.warning("ha_search %s branch failed: %r", label, outcome)
                 continue
             _apply_search_outcome(response, label, outcome)

{ha_mcp_dev-8.3.0.dev2379 → ha_mcp_dev-8.3.0.dev2382}/src/ha_mcp/tools/tools_service.py

@@ -83,7 +83,10 @@ class BulkControlOperation(TypedDict):
             Field(
                 description=(
                     "Optional action parameters, e.g. {'brightness_pct': 30} "
-                    "when action='on'."
+                    "when action='on'. Each domain has a fixed allowlist of "
+                    "supported keys; keys outside it are ignored rather than "
+                    "rejected. Use ha_call_service for parameters this tool "
+                    "does not carry."
                 )
             ),
         ]
@@ -94,6 +97,10 @@ class BulkControlOperation(TypedDict):
             Field(
                 ge=0,
                 allow_inf_nan=False,
+                # ``strict`` for the same reason validate_first carries it:
+                # lax mode coerces ``true`` to 1.0, so a bool would land
+                # downstream as a silent one-second timeout.
+                strict=True,
                 description=(
                     "Optional confirmation timeout. On the component path, all "
                     "operations share the maximum requested wait (default 10s, "
@@ -108,8 +115,10 @@ class BulkControlOperation(TypedDict):
             Field(
                 strict=True,
                 description=(
-                    "Validate that the entity exists before dispatch; default true. "
-                    "The action is always validated."
+                    "Report an ENTITY_NOT_FOUND failure when the target entity "
+                    "does not exist; default true. On the component batch path "
+                    "this is detected from the captured pre-state rather than by "
+                    "preventing dispatch. The action is always validated."
                 ),
             ),
         ]
@@ -1531,7 +1540,8 @@ class ServiceTools:
 
         Caveats: put every target in ``operations`` and call the tool once. Parallel
         execution is the default, and invalid items are reported without aborting
-        valid operations in the same batch.
+        valid operations in the same batch. A batch in which every item fails
+        validation dispatches nothing and fails the call.
         """
         parallel_bool = parallel
 
@@ -1559,14 +1569,24 @@ class ServiceTools:
             )
 
         operations_list: list[Any] = []
-        for operation in parsed_operations:
+        for index, operation in enumerate(parsed_operations):
             try:
                 operations_list.append(
                     _BULK_CONTROL_OPERATION_ADAPTER.validate_python(operation)
                 )
-            except ValidationError:
+            except ValidationError as exc:
                 # Preserve malformed rows for the runtime batch validator, which
                 # reports them in skipped_details instead of rejecting the call.
+                # The schema's reason is richer than the runtime validator's and
+                # is the only place it survives, so log it here.
+                # include_input=False: a malformed row can carry sensitive
+                # values (lock or alarm codes in a mistyped field), and
+                # str(exc) would write them to persistent server logs.
+                logger.warning(
+                    "ha_bulk_control operation %d failed schema validation: %s",
+                    index,
+                    exc.errors(include_url=False, include_input=False),
+                )
                 operations_list.append(operation)
 
         result = await self._device_tools.bulk_device_control(

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

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