ha-mcp-dev 8.6.0.dev2859__tar.gz → 8.6.0.dev2862__tar.gz

{ha_mcp_dev-8.6.0.dev2859 → ha_mcp_dev-8.6.0.dev2862}/PKG-INFO

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

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

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.6.0.dev2859"
+version = "8.6.0.dev2862"
 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.dev2859 → ha_mcp_dev-8.6.0.dev2862}/src/ha_mcp/client/rest_client.py

@@ -112,7 +112,7 @@ class HomeAssistantAuthError(HomeAssistantError):
     """Authentication error with Home Assistant.
 
     Sibling of ``HomeAssistantAPIError`` (not a subclass). The codebase has
-    18 ``except HomeAssistantAPIError`` sites (util_helpers polling,
+    18 ``except HomeAssistantAPIError`` sites (ws_waiters polling,
     tools_integrations registry lookups, etc.) that deliberately rely on
     auth errors NOT matching so they can propagate to a paired
     ``except (HomeAssistantConnectionError, HomeAssistantAuthError): raise``
@@ -1638,7 +1638,7 @@ class HomeAssistantClient:
     # is fine when the WS happy path is the primary route. #1389's
     # cadence-measurement instrumentation also retired with the loop;
     # the WS waiter logs `time.monotonic()` elapsed via its own debug
-    # line at ``util_helpers._ws_wait_for_condition``.
+    # line at ``ws_waiters._ws_wait_for_condition``.
     _POLL_BUDGET_S: float = 6.0
 
     async def _poll_for_automation_entity(self, unique_id: str) -> str | None:
@@ -1650,10 +1650,10 @@ class HomeAssistantClient:
         polling of ``get_states()`` when the WebSocket is unavailable.
         See #1152 / #1395 for context.
         """
-        # Local import: ``util_helpers`` imports from ``rest_client`` for
+        # Local import: ``ws_waiters`` imports from ``rest_client`` for
         # the typed-error classes, so a module-level import here would be
         # circular. Mirrors the same pattern in ``_get_waiter_ws_client``.
-        from ..tools.util_helpers import wait_for_automation_entity_by_unique_id
+        from ..tools.ws_waiters import wait_for_automation_entity_by_unique_id
 
         try:
             entity_id = await wait_for_automation_entity_by_unique_id(

{ha_mcp_dev-8.6.0.dev2859 → ha_mcp_dev-8.6.0.dev2862}/src/ha_mcp/client/websocket_client.py

@@ -686,7 +686,7 @@ class HomeAssistantWebSocketClient:
                     # dispatch loop keeps a single buggy handler from
                     # killing the WS, but the bug itself becomes
                     # invisible — handlers wired to ``asyncio.Event``
-                    # nudges (see ``util_helpers._ws_wait_for_condition``)
+                    # nudges (see ``ws_waiters._ws_wait_for_condition``)
                     # silently stop nudging and the calling waiter times
                     # out reporting "not found." #1395 silent-failure
                     # audit.
@@ -1020,7 +1020,7 @@ class HomeAssistantWebSocketClient:
     async def unsubscribe_events(self, subscription_id: int) -> None:
         """Release a subscription previously returned by ``subscribe_events``.
 
-        Used by short-lived waiters (``util_helpers.wait_for_*``) that need
+        Used by short-lived waiters (``ws_waiters.wait_for_*``) that need
         to drop the subscription as soon as their event arrives so the
         shared socket doesn't accumulate stale ``state_changed`` listeners.
 

{ha_mcp_dev-8.6.0.dev2859 → ha_mcp_dev-8.6.0.dev2862}/src/ha_mcp/policy/evaluator.py

@@ -6,7 +6,7 @@ from collections.abc import Iterable, Iterator
 from enum import StrEnum
 from typing import Any
 
-from ..tools.util_helpers import loads_if_json_container_str
+from ..tools.coercion import loads_if_json_container_str
 from .model import Policy, Predicate, Rule
 
 logger = logging.getLogger(__name__)
@@ -21,7 +21,7 @@ def normalize_stringified_containers(value: Any) -> Any:
     """Recursively parse JSON-encoded object/array strings into real containers.
 
     Some MCP client stacks (Claude Desktop stdio among them — see
-    ``tools/util_helpers.py``'s ``JSON_STRING_COERCION``) pass model-emitted
+    ``tools/coercion.py``'s ``JSON_STRING_COERCION``) pass model-emitted
     stringified objects through unrepaired, e.g. sending
     ``{"selector": "{\\"domain\\": \\"light\\"}"}`` instead of a nested
     object. Pydantic's ``JSON_STRING_COERCION`` ``BeforeValidator`` repairs

{ha_mcp_dev-8.6.0.dev2859 → ha_mcp_dev-8.6.0.dev2862}/src/ha_mcp/settings_ui/_tools_meta.py

@@ -107,7 +107,7 @@ MANDATORY_TOOLS: set[str] = {
 # exclusively through ha_get_skill_guide, so disabling the tool in strict
 # mode would permanently lock out every gated write. Regular
 # (non-strict) mandatory BPS does NOT need the tool: it attaches skill
-# content server-side straight from the skills-vendor (util_helpers.
+# content server-side straight from the skills-vendor (config_write_helpers.
 # build_skill_content), so users who consume the skills through a local
 # install (``npx skills add homeassistant-ai/skills``) may disable the
 # tool whenever strict mode is off. Enforced in three places: here at

{ha_mcp_dev-8.6.0.dev2859 → ha_mcp_dev-8.6.0.dev2862}/src/ha_mcp/strict_bps.py

@@ -164,7 +164,7 @@ def strict_bps_effective() -> bool:
 
     * A ``ValidationError`` from the settings load — a corrupt settings env
       must not brick every gated write. Mirrors the narrow degrade in
-      ``build_skill_content`` (util_helpers.py).
+      ``build_skill_content`` (config_write_helpers.py).
     * No best-practices skill the guide can serve (skills-vendor
       submodule absent, skill folder missing or symlinked, or SKILL.md
       frontmatter unparseable). The key is then unobtainable, so the gate

{ha_mcp_dev-8.6.0.dev2859 → ha_mcp_dev-8.6.0.dev2862}/src/ha_mcp/tools/best_practice_checker.py

@@ -15,7 +15,7 @@ LLM-discoverable way to pull the relevant skill content:
 The write tools also auto-embed the matching section into the next
 response via ``referenced_files`` and accept a ``MandatoryBPS`` opt-out
 parameter. Neither is advertised in the warning suffix by design —
-see ``util_helpers._SKILL_CONTENT_OPTOUT_HINT`` for the param contract.
+see ``config_write_helpers._SKILL_CONTENT_OPTOUT_HINT`` for the param contract.
 
 The ``skill_prefix`` kwarg lets callers pass any URL prefix (e.g., a
 GitHub mirror) when ``skill://`` isn't reachable, or ``None`` to omit

ha_mcp_dev-8.6.0.dev2862/src/ha_mcp/tools/coercion.py

@@ -0,0 +1,148 @@
+"""Coercion and parsing of MCP tool parameters.
+
+Turns JSON-encoded strings, CSV strings and scalar values into the list and
+container shapes the tool functions expect. Also holds the ANSI escape pattern
+used to clean container and log text.
+"""
+
+import json
+import re
+from typing import Any
+
+from pydantic import BeforeValidator
+
+# Strips ANSI terminal escape codes from container/log output.
+ANSI_ESCAPE_RE = re.compile(r"\x1b\[[0-9;]*[a-zA-Z]")
+
+
+def parse_json_param(
+    param: str | dict | list | None, param_name: str = "parameter"
+) -> dict | list | None:
+    """
+    Parse flexibly JSON string or return existing dict/list.
+
+    Args:
+        param: JSON string, dict, list, or None
+        param_name: Parameter name for error context
+
+    Returns:
+        Parsed dict/list or original value if already correct type
+
+    Raises:
+        ValueError: If JSON parsing fails
+    """
+    if param is None:
+        return None
+
+    if isinstance(param, (dict, list)):
+        return param
+
+    if isinstance(param, str):
+        try:
+            parsed = json.loads(param)
+            if not isinstance(parsed, (dict, list)):
+                raise ValueError(
+                    f"{param_name} must be a JSON object or array, got {type(parsed).__name__}"
+                )
+            return parsed
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid JSON in {param_name}: {e}") from e
+
+    raise ValueError(
+        f"{param_name} must be string, dict, list, or None, got {type(param).__name__}"
+    )
+
+
+def loads_if_json_container_str(value: Any) -> Any:
+    """Parse a JSON-encoded object/array string into its container value.
+
+    A string that starts like an object or array but contains malformed JSON
+    raises with the decoder location so ValidationErrorMiddleware can return
+    an actionable error. Jinja templates and other strings pass through
+    unchanged, leaving Pydantic to select the expected parameter type.
+
+    Public (not module-private): also reused by ``policy/evaluator.py`` to
+    normalize stringified args before policy evaluation, outside the
+    Pydantic-validator role ``JSON_STRING_COERCION`` below wraps it in.
+    """
+    if isinstance(value, str):
+        try:
+            parsed = json.loads(value)
+        except json.JSONDecodeError as exc:
+            is_container_like = re.match(r"\s*[\[{]", value) is not None
+            is_standalone_jinja = re.match(r"\s*{[{%#]", value) is not None
+            if is_container_like and not is_standalone_jinja:
+                raise ValueError(
+                    f"Invalid JSON at line {exc.lineno} column {exc.colno}: {exc.msg}"
+                ) from exc
+            return value
+        except RecursionError:
+            # RecursionError (deeply-nested input) must not escape: Pydantic
+            # only converts ValueError/AssertionError into ValidationError.
+            return value
+        if isinstance(parsed, (dict, list)):
+            return parsed
+    return value
+
+
+# Annotated metadata for MCP-exposed dict/list params (issue #1581): coerces a
+# JSON-encoded string to its parsed container before validation, without
+# re-advertising string in the tool schema (the #1485/#1487/#1492 fix). Some
+# MCP client stacks (Claude Desktop stdio among them) pass model-emitted
+# stringified objects through unrepaired, so the strict schema boundary alone
+# rejects previously-valid traffic.
+JSON_STRING_COERCION = BeforeValidator(loads_if_json_container_str)
+
+
+def _parse_json_to_str_list(s: str, param_name: str) -> list[str]:
+    """Parse a JSON string as a list of strings, raising ValueError on failure."""
+    try:
+        parsed = json.loads(s)
+        if not isinstance(parsed, list):
+            raise ValueError(f"{param_name} must be a JSON array")
+        if not all(isinstance(item, str) for item in parsed):
+            raise ValueError(f"{param_name} must be a JSON array of strings")
+        return parsed
+    except (json.JSONDecodeError, RecursionError) as e:
+        # RecursionError: nested past the interpreter's limit is still
+        # "not valid JSON" to the caller, which expects ValueError here.
+        raise ValueError(f"Invalid JSON in {param_name}: {e}") from e
+
+
+def parse_string_list_param(
+    param: str | list[str] | None,
+    param_name: str = "parameter",
+    allow_csv: bool = False,
+) -> list[str] | None:
+    """Parse JSON string array or return existing list of strings.
+
+    Args:
+        param: Value to parse.
+        param_name: Name for error messages.
+        allow_csv: When True, plain strings are split on commas
+            (e.g. ``"light,sensor"`` → ``["light", "sensor"]``).
+            When False (default), non-JSON strings raise ValueError.
+    """
+    if param is None:
+        return None
+
+    if isinstance(param, list):
+        if all(isinstance(item, str) for item in param):
+            return param
+        raise ValueError(f"{param_name} must be a list of strings")
+
+    if isinstance(param, str):
+        if param.strip().startswith("["):
+            return _parse_json_to_str_list(param, param_name)
+        if allow_csv:
+            return [item.strip() for item in param.split(",") if item.strip()]
+        return _parse_json_to_str_list(param, param_name)
+
+    raise ValueError(f"{param_name} must be string, list, or None")
+
+
+def coerce_to_list(value: Any) -> list[Any]:
+    """Return value as a list: list → as-is, dict/other → [value], None/falsy → []."""
+    if isinstance(value, list):
+        return value
+    return [value] if value else []

{ha_mcp_dev-8.6.0.dev2859 → ha_mcp_dev-8.6.0.dev2862}/src/ha_mcp/tools/config_helpers/create.py

@@ -6,8 +6,9 @@ from typing import Any
 
 from ...errors import ErrorCode, create_error_response
 from ...utils.registry_update_lock import registry_update_lock
+from ..config_write_helpers import apply_entity_category
 from ..helpers import raise_tool_error
-from ..util_helpers import apply_entity_category, wait_for_entity_registered
+from ..ws_waiters import wait_for_entity_registered
 from .registry import _ws_error_msg
 from .schemas import (
     _attach_helper_skill,

{ha_mcp_dev-8.6.0.dev2859 → ha_mcp_dev-8.6.0.dev2862}/src/ha_mcp/tools/config_helpers/flow.py

@@ -6,6 +6,7 @@ from typing import Any
 
 from ...errors import ErrorCode, create_error_response
 from ...redaction import redact_flow_schema, redaction_enabled
+from ..coercion import parse_json_param, parse_string_list_param
 from ..config_entry_flow import (
     create_flow_helper,
     get_user_step_field_names,
@@ -14,7 +15,6 @@ from ..config_entry_flow import (
 )
 from ..config_entry_flow_walker import fetch_helper_flow_info
 from ..helpers import raise_tool_error, validate_identifier_not_empty
-from ..util_helpers import parse_json_param, parse_string_list_param
 from .registry import (
     _apply_registry_updates_to_entity,
     _get_entities_for_config_entry,

{ha_mcp_dev-8.6.0.dev2859 → ha_mcp_dev-8.6.0.dev2862}/src/ha_mcp/tools/config_helpers/listing.py

@@ -6,7 +6,7 @@ from typing import Any, NoReturn
 from ...errors import ErrorCode, create_error_response
 from ..config_entry_flow import FLOW_HELPER_TYPES
 from ..helpers import raise_tool_error
-from ..util_helpers import build_pagination_metadata
+from ..response_helpers import build_pagination_metadata
 
 logger = logging.getLogger(__name__)
 

{ha_mcp_dev-8.6.0.dev2859 → ha_mcp_dev-8.6.0.dev2862}/src/ha_mcp/tools/config_helpers/registry.py

@@ -9,8 +9,8 @@ from ...errors import ErrorCode, create_auth_error, create_error_response
 from ...utils.registry_update_lock import registry_update_lock
 from ..component_registry_lookup import fetch_entities_for_config_entry_via_component
 from ..config_entry_flow import FLOW_HELPER_TYPES
+from ..config_write_helpers import apply_entity_category
 from ..helpers import exception_to_structured_error, raise_tool_error
-from ..util_helpers import apply_entity_category
 from .schemas import SIMPLE_HELPER_TYPES, _simple_helper_error_context
 
 logger = logging.getLogger(__name__)

{ha_mcp_dev-8.6.0.dev2859 → ha_mcp_dev-8.6.0.dev2862}/src/ha_mcp/tools/config_helpers/schemas.py

@@ -2,7 +2,7 @@
 
 from typing import Any, TypedDict
 
-from ..util_helpers import attach_skill_content
+from ..config_write_helpers import attach_skill_content
 
 __all__ = [
     "SIMPLE_HELPER_SCHEMAS",

{ha_mcp_dev-8.6.0.dev2859 → ha_mcp_dev-8.6.0.dev2862}/src/ha_mcp/tools/config_helpers/update.py

@@ -5,8 +5,9 @@ from typing import Any
 
 from ...errors import ErrorCode, create_error_response
 from ...utils.registry_update_lock import registry_update_lock
+from ..config_write_helpers import apply_entity_category
 from ..helpers import raise_tool_error
-from ..util_helpers import apply_entity_category, wait_for_entity_registered
+from ..ws_waiters import wait_for_entity_registered
 from .create import _format_schedule_days
 from .registry import _ws_error_msg
 from .schemas import (