ha-mcp-dev 7.7.0.dev692__tar.gz → 7.7.0.dev694__tar.gz

{ha_mcp_dev-7.7.0.dev692/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.7.0.dev694}/PKG-INFO

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

{ha_mcp_dev-7.7.0.dev692 → ha_mcp_dev-7.7.0.dev694}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.7.0.dev692"
+version = "7.7.0.dev694"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

{ha_mcp_dev-7.7.0.dev692 → ha_mcp_dev-7.7.0.dev694}/src/ha_mcp/tools/tools_addons.py

@@ -41,7 +41,7 @@ from .helpers import (
     raise_tool_error,
     validate_identifier_not_empty,
 )
-from .util_helpers import ANSI_ESCAPE_RE
+from .util_helpers import ANSI_ESCAPE_RE, JSON_STRING_COERCION
 
 logger = logging.getLogger(__name__)
 
@@ -2712,6 +2712,7 @@ def register_addon_tools(mcp: Any, client: HomeAssistantClient, **kwargs: Any) -
         ] = None,
         options: Annotated[
             dict[str, Any] | None,
+            JSON_STRING_COERCION,
             Field(
                 description="Config mode: Add-on configuration values (the 'Configuration' tab in the UI).",
                 default=None,
@@ -2719,6 +2720,7 @@ def register_addon_tools(mcp: Any, client: HomeAssistantClient, **kwargs: Any) -
         ] = None,
         network: Annotated[
             dict[str, Any] | None,
+            JSON_STRING_COERCION,
             Field(
                 description="Config mode: Host port mappings (e.g., {'5800/tcp': 8081}).",
                 default=None,
@@ -2747,6 +2749,7 @@ def register_addon_tools(mcp: Any, client: HomeAssistantClient, **kwargs: Any) -
         ] = None,
         array_patch: Annotated[
             dict[str, Any] | None,
+            JSON_STRING_COERCION,
             Field(
                 description=(
                     "Array-patch mode: atomically GET a JSON array endpoint, "
@@ -2760,6 +2763,7 @@ def register_addon_tools(mcp: Any, client: HomeAssistantClient, **kwargs: Any) -
         ] = None,
         request_headers: Annotated[
             dict[str, str] | None,
+            JSON_STRING_COERCION,
             Field(
                 description=(
                     "Proxy/array-patch mode: extra HTTP headers to send to the addon API. "

{ha_mcp_dev-7.7.0.dev692 → ha_mcp_dev-7.7.0.dev694}/src/ha_mcp/tools/tools_areas.py

@@ -23,6 +23,7 @@ from .helpers import (
     validate_identifier_not_empty,
 )
 from .util_helpers import (
+    JSON_STRING_COERCION,
     parse_string_list_param,
     project_fields,
     project_records,
@@ -148,6 +149,7 @@ class AreaTools:
         self,
         fields: Annotated[
             str | list[str] | None,
+            JSON_STRING_COERCION,
             Field(
                 default=None,
                 description=(
@@ -162,6 +164,7 @@ class AreaTools:
         ] = None,
         area_fields: Annotated[
             str | list[str] | None,
+            JSON_STRING_COERCION,
             Field(
                 default=None,
                 description=(
@@ -446,6 +449,7 @@ class AreaTools:
         ] = None,
         aliases: Annotated[
             str | list[str] | None,
+            JSON_STRING_COERCION,
             Field(
                 description="Alternative names for voice assistant recognition (e.g., ['lounge'], empty list to clear)",
                 default=None,

{ha_mcp_dev-7.7.0.dev692 → ha_mcp_dev-7.7.0.dev694}/src/ha_mcp/tools/tools_config_helpers.py

@@ -3500,6 +3500,7 @@ class HelperConfigTools:
         ] = None,
         labels: Annotated[
             str | list[str] | None,
+            JSON_STRING_COERCION,
             Field(description="Labels to categorize the helper", default=None),
         ] = None,
         min_value: Annotated[
@@ -3535,6 +3536,7 @@ class HelperConfigTools:
         ] = None,
         options: Annotated[
             str | list[str] | None,
+            JSON_STRING_COERCION,
             Field(
                 description="List of options for input_select (required for input_select)",
                 default=None,
@@ -3582,6 +3584,7 @@ class HelperConfigTools:
         ] = None,
         monday: Annotated[
             list[dict[str, Any]] | None,
+            JSON_STRING_COERCION,
             Field(
                 description="Schedule time ranges for Monday. List of {'from': 'HH:MM', 'to': 'HH:MM'} dicts. Optional 'data' dict for additional attributes (e.g. {'from': '07:00', 'to': '22:00', 'data': {'mode': 'comfort'}})",
                 default=None,
@@ -3589,6 +3592,7 @@ class HelperConfigTools:
         ] = None,
         tuesday: Annotated[
             list[dict[str, Any]] | None,
+            JSON_STRING_COERCION,
             Field(
                 description="Schedule time ranges for Tuesday. List of {'from': 'HH:MM', 'to': 'HH:MM'} dicts. Optional 'data' dict for additional attributes.",
                 default=None,
@@ -3596,6 +3600,7 @@ class HelperConfigTools:
         ] = None,
         wednesday: Annotated[
             list[dict[str, Any]] | None,
+            JSON_STRING_COERCION,
             Field(
                 description="Schedule time ranges for Wednesday. List of {'from': 'HH:MM', 'to': 'HH:MM'} dicts. Optional 'data' dict for additional attributes.",
                 default=None,
@@ -3603,6 +3608,7 @@ class HelperConfigTools:
         ] = None,
         thursday: Annotated[
             list[dict[str, Any]] | None,
+            JSON_STRING_COERCION,
             Field(
                 description="Schedule time ranges for Thursday. List of {'from': 'HH:MM', 'to': 'HH:MM'} dicts. Optional 'data' dict for additional attributes.",
                 default=None,
@@ -3610,6 +3616,7 @@ class HelperConfigTools:
         ] = None,
         friday: Annotated[
             list[dict[str, Any]] | None,
+            JSON_STRING_COERCION,
             Field(
                 description="Schedule time ranges for Friday. List of {'from': 'HH:MM', 'to': 'HH:MM'} dicts. Optional 'data' dict for additional attributes.",
                 default=None,
@@ -3617,6 +3624,7 @@ class HelperConfigTools:
         ] = None,
         saturday: Annotated[
             list[dict[str, Any]] | None,
+            JSON_STRING_COERCION,
             Field(
                 description="Schedule time ranges for Saturday. List of {'from': 'HH:MM', 'to': 'HH:MM'} dicts. Optional 'data' dict for additional attributes.",
                 default=None,
@@ -3624,6 +3632,7 @@ class HelperConfigTools:
         ] = None,
         sunday: Annotated[
             list[dict[str, Any]] | None,
+            JSON_STRING_COERCION,
             Field(
                 description="Schedule time ranges for Sunday. List of {'from': 'HH:MM', 'to': 'HH:MM'} dicts. Optional 'data' dict for additional attributes.",
                 default=None,
@@ -3654,6 +3663,7 @@ class HelperConfigTools:
         ] = None,
         device_trackers: Annotated[
             list[str] | None,
+            JSON_STRING_COERCION,
             Field(
                 description="List of device_tracker entity IDs for person", default=None
             ),

{ha_mcp_dev-7.7.0.dev692 → ha_mcp_dev-7.7.0.dev694}/src/ha_mcp/tools/tools_energy.py

@@ -43,6 +43,7 @@ from .helpers import (
     register_tool_methods,
     validate_identifier_not_empty,
 )
+from .util_helpers import JSON_STRING_COERCION
 
 logger = logging.getLogger(__name__)
 
@@ -341,6 +342,7 @@ class EnergyTools:
         ],
         config: Annotated[
             dict[str, Any] | None,
+            JSON_STRING_COERCION,
             Field(
                 description=(
                     "Full prefs payload for mode='set'. Must contain the "
@@ -362,9 +364,12 @@ class EnergyTools:
                     "Hash from a previous mode='get' call. REQUIRED for "
                     "mode='set' unless dry_run=True. Two forms: str (full-"
                     "blob lock) or dict (per-key lock, taken from the "
-                    "config_hash_per_key field of mode='get'). See the tool "
-                    "docstring for fail-closed semantics. Ignored by "
-                    "convenience modes."
+                    "config_hash_per_key field of mode='get'). Pass the dict "
+                    "form as a native object, NOT a JSON-encoded string — a "
+                    "stringified dict is treated as a full-blob token and will "
+                    "report RESOURCE_LOCKED; clients that can only send strings "
+                    "should use the str full-blob form. See the tool docstring "
+                    "for fail-closed semantics. Ignored by convenience modes."
                 ),
                 default=None,
             ),
@@ -438,6 +443,7 @@ class EnergyTools:
         ] = False,
         source: Annotated[
             dict[str, Any] | None,
+            JSON_STRING_COERCION,
             Field(
                 description=(
                     "Single energy_sources entry for mode='add_source'. Must "

{ha_mcp_dev-7.7.0.dev692 → ha_mcp_dev-7.7.0.dev694}/src/ha_mcp/tools/tools_entities.py

@@ -559,6 +559,7 @@ def register_entity_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
     async def ha_set_entity(
         entity_id: Annotated[
             str | list[str],
+            JSON_STRING_COERCION,
             Field(
                 description="Entity ID or list of entity IDs to update. Bulk operations (list) only support labels, expose_to, and categories parameters."
             ),
@@ -639,6 +640,7 @@ def register_entity_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         ] = None,
         aliases: Annotated[
             str | list[str] | None,
+            JSON_STRING_COERCION,
             Field(
                 description="List of voice assistant aliases for the entity (replaces existing aliases). Single entity only.",
                 default=None,
@@ -659,6 +661,7 @@ def register_entity_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         ] = None,
         labels: Annotated[
             str | list[str] | None,
+            JSON_STRING_COERCION,
             Field(
                 description="List of label IDs for the entity. Behavior depends on label_operation parameter. Supports bulk operations.",
                 default=None,
@@ -1117,6 +1120,7 @@ def register_entity_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
     async def ha_get_entity(
         entity_id: Annotated[
             str | list[str],
+            JSON_STRING_COERCION,
             Field(
                 description="Entity ID or list of entity IDs to retrieve (e.g., 'sensor.temperature' or ['light.living_room', 'switch.porch'])"
             ),

{ha_mcp_dev-7.7.0.dev692 → ha_mcp_dev-7.7.0.dev694}/src/ha_mcp/tools/tools_groups.py

@@ -26,6 +26,7 @@ from .helpers import (
     validate_identifier_not_empty,
 )
 from .util_helpers import (
+    JSON_STRING_COERCION,
     wait_for_entity_registered,
     wait_for_entity_removed,
 )
@@ -223,6 +224,7 @@ class GroupTools:
         ],
         entities: Annotated[
             list[str] | None,
+            JSON_STRING_COERCION,
             Field(
                 description="List of entity IDs for the group. Required when creating new group. When updating, replaces all entities (mutually exclusive with add_entities/remove_entities).",
                 default=None,
@@ -251,6 +253,7 @@ class GroupTools:
         ] = None,
         add_entities: Annotated[
             list[str] | None,
+            JSON_STRING_COERCION,
             Field(
                 description="Add these entities to an existing group (mutually exclusive with entities)",
                 default=None,
@@ -258,6 +261,7 @@ class GroupTools:
         ] = None,
         remove_entities: Annotated[
             list[str] | None,
+            JSON_STRING_COERCION,
             Field(
                 description="Remove these entities from an existing group (mutually exclusive with entities)",
                 default=None,

{ha_mcp_dev-7.7.0.dev692 → ha_mcp_dev-7.7.0.dev694}/src/ha_mcp/tools/tools_history.py

@@ -30,6 +30,7 @@ from .helpers import (
     safe_progress,
 )
 from .util_helpers import (
+    JSON_STRING_COERCION,
     add_timezone_metadata,
     build_pagination_metadata,
     parse_string_list_param,
@@ -136,6 +137,7 @@ class HistoryTools:
         self,
         entity_ids: Annotated[
             str | list[str],
+            JSON_STRING_COERCION,
             Field(
                 description="Entity ID(s) to query. Can be a single ID, comma-separated string, or JSON array."
             ),
@@ -206,6 +208,7 @@ class HistoryTools:
         ] = "day",
         statistic_types: Annotated[
             str | list[str] | None,
+            JSON_STRING_COERCION,
             Field(
                 description='Statistics types: "mean", "min", "max", "sum", "state", "change". Default: all. Ignored when source="history"',
                 default=None,
@@ -224,6 +227,7 @@ class HistoryTools:
         ] = "desc",
         fields: Annotated[
             str | list[str] | None,
+            JSON_STRING_COERCION,
             Field(
                 default=None,
                 description=(
@@ -425,6 +429,9 @@ def _parse_entity_ids(entity_ids: str | list[str]) -> list[str]:
     """Parse entity_ids parameter into a list of strings."""
     if isinstance(entity_ids, str):
         if entity_ids.startswith("["):
+            # Belt-and-suspenders: JSON_STRING_COERCION on the param already
+            # parses a JSON-array string to a list upstream, so a string reaching
+            # here is normally CSV/single. This branch stays as a fallback.
             parsed_ids = parse_string_list_param(entity_ids, "entity_ids")
             if parsed_ids is None:
                 raise_tool_error(

{ha_mcp_dev-7.7.0.dev692 → ha_mcp_dev-7.7.0.dev694}/src/ha_mcp/tools/tools_integrations.py

@@ -33,6 +33,7 @@ from .tools_config_helpers import (
     _get_entities_for_config_entry,
 )
 from .util_helpers import (
+    JSON_STRING_COERCION,
     build_pagination_metadata,
     fetch_integration_diagnostics,
     get_logger_levels,
@@ -459,6 +460,7 @@ class IntegrationTools:
         ] = None,
         diagnostics_fields: Annotated[
             list[str] | str | None,
+            JSON_STRING_COERCION,
             Field(
                 description=(
                     "Optional list of top-level keys to keep from the diagnostics "

{ha_mcp_dev-7.7.0.dev692 → ha_mcp_dev-7.7.0.dev694}/src/ha_mcp/tools/tools_registry.py

@@ -21,6 +21,7 @@ from .helpers import (
     validate_identifier_not_empty,
 )
 from .util_helpers import (
+    JSON_STRING_COERCION,
     build_pagination_metadata,
     parse_string_list_param,
 )
@@ -627,6 +628,7 @@ def register_registry_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         ] = None,
         labels: Annotated[
             str | list[str] | None,
+            JSON_STRING_COERCION,
             Field(
                 description="Labels to assign to the device (replaces existing labels)",
                 default=None,

{ha_mcp_dev-7.7.0.dev692 → ha_mcp_dev-7.7.0.dev694}/src/ha_mcp/tools/tools_search.py

@@ -18,6 +18,7 @@ from ..transforms.categorized_search import DEFAULT_PINNED_TOOLS
 from ..utils.fuzzy_search import apply_hidden_penalty
 from .helpers import exception_to_structured_error, log_tool_usage, raise_tool_error
 from .util_helpers import (
+    JSON_STRING_COERCION,
     add_timezone_metadata,
     build_pagination_metadata,
     filter_active_repairs,
@@ -581,6 +582,7 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         ] = None,
         search_types: Annotated[
             str | list[str] | None,
+            JSON_STRING_COERCION,
             Field(
                 default=None,
                 description=(
@@ -672,6 +674,7 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         ] = None,
         result_fields: Annotated[
             str | list[str] | None,
+            JSON_STRING_COERCION,
             Field(
                 default=None,
                 description=(
@@ -682,6 +685,7 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         ] = None,
         fields: Annotated[
             str | list[str] | None,
+            JSON_STRING_COERCION,
             Field(
                 default=None,
                 description=(
@@ -1810,6 +1814,7 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         ] = "minimal",
         domains: Annotated[
             str | list[str] | None,
+            JSON_STRING_COERCION,
             Field(
                 default=None,
                 description=(
@@ -1878,6 +1883,7 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         ] = False,
         fields: Annotated[
             str | list[str] | None,
+            JSON_STRING_COERCION,
             Field(
                 default=None,
                 description=(
@@ -2326,6 +2332,7 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
     async def ha_get_state(
         entity_id: Annotated[
             str | list[str],
+            JSON_STRING_COERCION,
             Field(
                 description="Entity ID or list of entity IDs to retrieve state for "
                 "(e.g., 'light.kitchen' or ['light.kitchen', 'sensor.temperature'])"
@@ -2333,6 +2340,7 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         ],
         fields: Annotated[
             str | list[str] | None,
+            JSON_STRING_COERCION,
             Field(
                 default=None,
                 description=(
@@ -2346,6 +2354,7 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         ] = None,
         attribute_keys: Annotated[
             str | list[str] | None,
+            JSON_STRING_COERCION,
             Field(
                 default=None,
                 description=(

{ha_mcp_dev-7.7.0.dev692 → ha_mcp_dev-7.7.0.dev694}/src/ha_mcp/tools/tools_service.py

@@ -315,6 +315,7 @@ class ServiceTools:
         ] = False,
         result_fields: Annotated[
             str | list[str] | None,
+            JSON_STRING_COERCION,
             Field(
                 default=None,
                 description=(
@@ -327,6 +328,7 @@ class ServiceTools:
         ] = None,
         result_attribute_keys: Annotated[
             str | list[str] | None,
+            JSON_STRING_COERCION,
             Field(
                 default=None,
                 description=(
@@ -522,6 +524,7 @@ class ServiceTools:
         self,
         operation_id: Annotated[
             str | list[str],
+            JSON_STRING_COERCION,
             Field(
                 description=(
                     "Single operation ID or list of operation IDs to check. "
@@ -544,23 +547,15 @@ class ServiceTools:
         For current entity states, use ha_get_state instead.
         """
         try:
-            # Handle JSON string coercion (MCP clients may send '["op1","op2"]')
-            resolved_id: str | list[str] = operation_id
-            if isinstance(operation_id, str):
-                try:
-                    parsed = parse_json_param(operation_id, "operation_id")
-                    if isinstance(parsed, list):
-                        resolved_id = [str(item) for item in parsed]
-                except ValueError:
-                    pass  # Plain string — treat as single operation ID
-
-            if isinstance(resolved_id, list):
+            # JSON_STRING_COERCION turns a '["op1","op2"]' string into a list
+            # before the body runs, so operation_id is already the final shape.
+            if isinstance(operation_id, list):
                 result = await self._device_tools.get_bulk_operation_status(
-                    operation_ids=resolved_id
+                    operation_ids=operation_id
                 )
                 return cast(dict[str, Any], result)
             result = await self._device_tools.get_device_operation_status(
-                operation_id=resolved_id, timeout_seconds=timeout_seconds
+                operation_id=operation_id, timeout_seconds=timeout_seconds
             )
             return cast(dict[str, Any], result)
         except ToolError:

{ha_mcp_dev-7.7.0.dev692 → ha_mcp_dev-7.7.0.dev694}/src/ha_mcp/tools/tools_services.py

@@ -20,6 +20,7 @@ from .helpers import (
     register_tool_methods,
 )
 from .util_helpers import (
+    JSON_STRING_COERCION,
     build_pagination_metadata,
     parse_string_list_param,
     project_fields,
@@ -78,6 +79,7 @@ class ServiceDiscoveryTools:
         ] = "summary",
         service_fields: Annotated[
             str | list[str] | None,
+            JSON_STRING_COERCION,
             Field(
                 default=None,
                 description=(
@@ -91,6 +93,7 @@ class ServiceDiscoveryTools:
         ] = None,
         fields: Annotated[
             str | list[str] | None,
+            JSON_STRING_COERCION,
             Field(
                 default=None,
                 description=(

{ha_mcp_dev-7.7.0.dev692 → ha_mcp_dev-7.7.0.dev694}/src/ha_mcp/tools/tools_system.py

@@ -25,6 +25,7 @@ from .helpers import (
     register_tool_methods,
 )
 from .util_helpers import (
+    JSON_STRING_COERCION,
     fetch_integration_diagnostics,
     filter_active_repairs,
     parse_diagnostics_fields,
@@ -323,7 +324,9 @@ class SystemTools:
         include_dismissed_repairs: bool | None = False,
         config_entry_id: str | None = None,
         device_id: str | None = None,
-        diagnostics_fields: list[str] | str | None = None,
+        diagnostics_fields: Annotated[
+            list[str] | str | None, JSON_STRING_COERCION
+        ] = None,
         diagnostics_truncate_at_bytes: Annotated[int, Field(ge=1)] | None = None,
         diagnostics_data_path: str | None = None,
         diagnostics_data_offset: Annotated[int, Field(ge=0)] | None = 0,

{ha_mcp_dev-7.7.0.dev692 → ha_mcp_dev-7.7.0.dev694}/src/ha_mcp/tools/validation_middleware.py

@@ -43,15 +43,33 @@ class ValidationErrorMiddleware(Middleware):
             return await call_next(context)
         except PydanticValidationError as exc:
             errors = exc.errors(include_url=False)
-            parts: list[str] = []
+            # Group by the real argument path. A union param like
+            # `str | list[str]` emits one error per arm with loc (param, "str"),
+            # (param, "list[str]"); without grouping the user saw `param.str` /
+            # `param.list[str]` instead of `param` (#1601). We keep the param
+            # name plus any numeric list indices (so a bad element still reports
+            # `monday.1`) but drop the non-numeric union-arm tags.
+            grouped: dict[str, list[Any]] = {}
             for err in errors:
-                loc = err.get("loc", ())
-                param = ".".join(str(p) for p in loc if p != "__root__")
-                hint = _TYPE_HINTS.get(err["type"], err["msg"])
+                loc = [str(p) for p in err.get("loc", ()) if p != "__root__"]
+                if loc:
+                    key = ".".join([loc[0], *(p for p in loc[1:] if p.isdigit())])
+                else:
+                    key = ""
+                grouped.setdefault(key, []).append(err)
+
+            parts: list[str] = []
+            for param, errs in grouped.items():
+                # Prefer an actionable container hint when any arm produced one
+                # (dict_type/list_type); else fall back to the first raw message.
+                hint = next(
+                    (_TYPE_HINTS[e["type"]] for e in errs if e["type"] in _TYPE_HINTS),
+                    errs[0]["msg"],
+                )
                 parts.append(f"`{param}`: {hint}" if param else hint)
             raise_tool_error(
                 create_validation_error(
                     "; ".join(parts) if parts else "Invalid argument types.",
-                    details=", ".join(err["type"] for err in errors),
+                    details=", ".join(dict.fromkeys(err["type"] for err in errors)),
                 )
             )

{ha_mcp_dev-7.7.0.dev692 → ha_mcp_dev-7.7.0.dev694/src/ha_mcp_dev.egg-info}/PKG-INFO

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