ha-mcp-dev 7.7.0.dev691__tar.gz → 7.7.0.dev693__tar.gz

{ha_mcp_dev-7.7.0.dev691/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.7.0.dev693}/PKG-INFO

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

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

@@ -204,11 +204,25 @@ class CalendarTools:
         location: Annotated[
             str | None, Field(description="Optional event location", default=None)
         ] = None,
+        rrule: Annotated[
+            str | None,
+            Field(
+                description=(
+                    "Optional RFC 5545 recurrence rule, without 'RRULE:' prefix "
+                    "(e.g., 'FREQ=WEEKLY;BYDAY=MO' or 'FREQ=MONTHLY;BYDAY=3SA'). "
+                    "Creates a recurring event series."
+                ),
+                default=None,
+            ),
+        ] = None,
     ) -> dict[str, Any]:
         """
         Create a new event in a calendar.
 
-        Creates a calendar event using the calendar.create_event service.
+        Creates a one-off event via the calendar.create_event service, or a
+        recurring series via the WebSocket ``calendar/event/create`` command
+        when ``rrule`` is provided (the REST service schema does not accept
+        recurrence rules).
 
         **Parameters:**
         - entity_id: Calendar entity ID (e.g., 'calendar.family')
@@ -217,6 +231,7 @@ class CalendarTools:
         - end: Event end datetime in ISO format
         - description: Optional event description
         - location: Optional event location
+        - rrule: Optional RFC 5545 recurrence rule (creates a recurring series)
 
         **Example Usage:**
         ```python
@@ -228,17 +243,21 @@ class CalendarTools:
             end="2024-01-15T15:00:00"
         )
 
-        # Create an event with details
+        # Create a recurring event (every Monday, 10 occurrences)
         result = ha_config_set_calendar_event(
             "calendar.work",
             summary="Team meeting",
-            start="2024-01-16T10:00:00",
-            end="2024-01-16T11:00:00",
-            description="Weekly sync meeting",
-            location="Conference Room A"
+            start="2024-01-15T10:00:00",
+            end="2024-01-15T11:00:00",
+            rrule="FREQ=WEEKLY;BYDAY=MO;COUNT=10"
         )
         ```
 
+        **Note:**
+        Not every calendar integration supports event creation; recurring
+        events additionally require the integration to support recurrence
+        (the built-in Local Calendar does).
+
         **Returns:**
         - Success status and event details
         """
@@ -257,23 +276,71 @@ class CalendarTools:
                     )
                 )
 
-            # Build service data
-            service_data: dict[str, Any] = {
-                "entity_id": entity_id,
-                "summary": summary,
-                "start_date_time": start,
-                "end_date_time": end,
-            }
-
-            if description:
-                service_data["description"] = description
-            if location:
-                service_data["location"] = location
+            if rrule:
+                # The ``calendar.create_event`` service schema has no rrule
+                # field — recurrence is only accepted by the WebSocket
+                # command ``calendar/event/create`` (see HA Core
+                # ``homeassistant/components/calendar/__init__.py``), the
+                # same split that forces the delete tool below onto the
+                # WebSocket API.
+                event: dict[str, Any] = {
+                    "summary": summary,
+                    "dtstart": start,
+                    "dtend": end,
+                    "rrule": rrule,
+                }
+                if description:
+                    event["description"] = description
+                if location:
+                    event["location"] = location
+
+                ws_client, conn_error = await get_connected_ws_client(
+                    self._client.base_url,
+                    self._client.token,
+                    verify_ssl=self._client.verify_ssl,
+                )
+                if conn_error or ws_client is None:
+                    raise_tool_error(
+                        conn_error
+                        or create_error_response(
+                            ErrorCode.CONNECTION_FAILED,
+                            "Failed to connect to Home Assistant WebSocket",
+                            context={"entity_id": entity_id},
+                        )
+                    )
 
-            # Call the calendar.create_event service
-            result = await self._client.call_service(
-                "calendar", "create_event", service_data
-            )
+                try:
+                    result = await ws_client.send_command(
+                        "calendar/event/create", entity_id=entity_id, event=event
+                    )
+                finally:
+                    # Guard disconnect: a transport-teardown error here would
+                    # otherwise replace the original send_command exception.
+                    try:
+                        await ws_client.disconnect()
+                    except Exception as disconnect_error:
+                        logger.debug(
+                            f"WebSocket disconnect after create_event for "
+                            f"{entity_id}: {disconnect_error}"
+                        )
+            else:
+                # Build service data
+                service_data: dict[str, Any] = {
+                    "entity_id": entity_id,
+                    "summary": summary,
+                    "start_date_time": start,
+                    "end_date_time": end,
+                }
+
+                if description:
+                    service_data["description"] = description
+                if location:
+                    service_data["location"] = location
+
+                # Call the calendar.create_event service
+                result = await self._client.call_service(
+                    "calendar", "create_event", service_data
+                )
 
             return {
                 "success": True,
@@ -284,6 +351,7 @@ class CalendarTools:
                     "end": end,
                     "description": description,
                     "location": location,
+                    "rrule": rrule,
                 },
                 "result": result,
                 "message": f"Successfully created event '{summary}' in {entity_id}",
@@ -300,6 +368,13 @@ class CalendarTools:
                 "Ensure end time is after start time",
                 "Some calendar integrations may be read-only",
             ]
+            if rrule:
+                suggestions.insert(
+                    0,
+                    "Check RRULE syntax (RFC 5545, without the 'RRULE:' prefix, "
+                    "e.g. 'FREQ=WEEKLY;BYDAY=MO') and that this calendar "
+                    "integration supports recurring events",
+                )
 
             error_str = str(error)
             if "404" in error_str or "not found" in error_str.lower():

{ha_mcp_dev-7.7.0.dev691 → ha_mcp_dev-7.7.0.dev693}/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.dev691 → ha_mcp_dev-7.7.0.dev693}/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.dev691 → ha_mcp_dev-7.7.0.dev693}/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.dev691 → ha_mcp_dev-7.7.0.dev693}/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.dev691 → ha_mcp_dev-7.7.0.dev693}/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.dev691 → ha_mcp_dev-7.7.0.dev693}/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.dev691 → ha_mcp_dev-7.7.0.dev693}/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.dev691 → ha_mcp_dev-7.7.0.dev693}/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.dev691 → ha_mcp_dev-7.7.0.dev693}/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.dev691 → ha_mcp_dev-7.7.0.dev693}/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=(