ha-mcp-dev 7.13.0.dev2003__tar.gz → 7.13.0.dev2007__tar.gz

{ha_mcp_dev-7.13.0.dev2003/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.13.0.dev2007}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.13.0.dev2003"
+version = "7.13.0.dev2007"
 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
@@ -178,21 +178,12 @@ ignore = [
 "src/ha_mcp/backup_manager.py" = ["C901"]
 "src/ha_mcp/tools/auto_backup.py" = ["C901"]
 "src/ha_mcp/tools/backup.py" = ["C901"]
-"src/ha_mcp/tools/radio/matter.py" = ["C901"]
-"src/ha_mcp/tools/radio/zigbee.py" = ["C901"]
-"src/ha_mcp/tools/radio/zwave.py" = ["C901"]
-"src/ha_mcp/tools/reference_validator.py" = ["C901"]
-"src/ha_mcp/tools/tools_areas.py" = ["C901"]
 "src/ha_mcp/tools/tools_config_automations.py" = ["C901"]
 "src/ha_mcp/tools/tools_config_scenes.py" = ["C901"]
 "src/ha_mcp/tools/tools_config_scripts.py" = ["C901"]
 "src/ha_mcp/tools/tools_dev.py" = ["C901"]
-"src/ha_mcp/tools/tools_history.py" = ["C901"]
 "src/ha_mcp/tools/tools_integrations.py" = ["C901"]
 "src/ha_mcp/tools/tools_system.py" = ["C901"]
-"src/ha_mcp/tools/tools_zones.py" = ["C901"]
-"src/ha_mcp/transforms/categorized_search.py" = ["C901"]
-"src/ha_mcp/visibility/resolver.py" = ["C901"]
 "tests/src/e2e/conftest.py" = ["C901"]
 "tests/src/e2e/error_handling/test_network_errors.py" = ["C901"]
 "tests/src/e2e/policy/test_readonly_mode.py" = ["C901"]

{ha_mcp_dev-7.13.0.dev2003 → ha_mcp_dev-7.13.0.dev2007}/src/ha_mcp/tools/radio/matter.py

@@ -145,6 +145,13 @@ async def handle(client: Any, action: str, args: dict[str, Any]) -> dict[str, An
         # Returns setup_pin_code, setup_manual_code, setup_qr_code.
         return ok("matter", "share_out", commissioning=commissioning)
 
+    return await _handle_matter_more(client, action, args, device_id)
+
+
+async def _handle_matter_more(
+    client: Any, action: str, args: dict[str, Any], device_id: Any
+) -> dict[str, Any]:
+    """Continuation of :func:`handle` for the remaining Matter actions."""
     if action == "interview":
         result = await ws_call(
             client,

{ha_mcp_dev-7.13.0.dev2003 → ha_mcp_dev-7.13.0.dev2007}/src/ha_mcp/tools/radio/zigbee.py

@@ -272,6 +272,13 @@ async def handle(client: Any, action: str, args: dict[str, Any]) -> dict[str, An
             long_running=True,
         )
 
+    return await _handle_zigbee_groups(client, action, args, device_id)
+
+
+async def _handle_zigbee_groups(
+    client: Any, action: str, args: dict[str, Any], device_id: Any
+) -> dict[str, Any]:
+    """Continuation of :func:`handle` for Zigbee group and binding actions."""
     # --- groups ------------------------------------------------------------ #
     if action == "group_add":
         group = await ws_call(
@@ -340,6 +347,14 @@ async def handle(client: Any, action: str, args: dict[str, Any]) -> dict[str, An
         )
         return ok("zigbee", "unbind", result=result)
 
+    return await _handle_zigbee_clusters(client, action, args, device_id)
+
+
+async def _handle_zigbee_clusters(
+    client: Any, action: str, args: dict[str, Any], device_id: Any
+) -> dict[str, Any]:
+    """Continuation of :func:`handle` for Zigbee cluster-write and network actions."""
+    cluster_type = args.get("cluster_type", "in")
     # --- cluster writes (service-only) ------------------------------------- #
     if action == "cluster_write":
         ieee = await _resolve_ieee(client, device_id)

{ha_mcp_dev-7.13.0.dev2003 → ha_mcp_dev-7.13.0.dev2007}/src/ha_mcp/tools/radio/zwave.py

@@ -174,6 +174,13 @@ async def handle(client: Any, action: str, args: dict[str, Any]) -> dict[str, An
         result = await client.call_service("zwave_js", "ping", {"device_id": device_id})
         return ok("zwave", "ping", result=result)
 
+    return await _handle_zwave_inclusion(client, action, args, device_id)
+
+
+async def _handle_zwave_inclusion(
+    client: Any, action: str, args: dict[str, Any], device_id: Any
+) -> dict[str, Any]:
+    """Continuation of :func:`handle` for Z-Wave inclusion/exclusion actions."""
     if action == "add":
         entry_id = await _zwave_entry_id(client)
         if not entry_id:
@@ -289,6 +296,13 @@ async def handle(client: Any, action: str, args: dict[str, Any]) -> dict[str, An
             long_running=True,
         )
 
+    return await _handle_zwave_maintenance(client, action, args, device_id)
+
+
+async def _handle_zwave_maintenance(
+    client: Any, action: str, args: dict[str, Any], device_id: Any
+) -> dict[str, Any]:
+    """Continuation of :func:`handle` for Z-Wave node maintenance actions."""
     if action == "reinterview":
         result = await ws_call(
             client,

{ha_mcp_dev-7.13.0.dev2003 → ha_mcp_dev-7.13.0.dev2007}/src/ha_mcp/tools/reference_validator.py

@@ -69,6 +69,55 @@ class ValidationWarning(TypedDict):
     reason: str
 
 
+def _extract_service_ref(
+    sub_path: str,
+    value: str,
+    refs: list[ExtractedRef],
+    unvalidated_templates: list[int],
+) -> None:
+    """Record a service ref at *sub_path*, counting templates instead."""
+    if _is_template(value):
+        unvalidated_templates[0] += 1
+    else:
+        refs.append({"path": sub_path, "value": value, "kind": "service"})
+
+
+def _extract_entity_refs(
+    sub_path: str,
+    value: Any,
+    refs: list[ExtractedRef],
+    unvalidated_templates: list[int],
+) -> bool:
+    """Record entity ref(s) from a str or list *value*; return True if handled.
+
+    Returns False when *value* is neither a str nor a list so the caller can
+    keep recursing into it (an ``entity_id`` mapped to a nested structure).
+    """
+    if isinstance(value, str):
+        if _is_template(value):
+            unvalidated_templates[0] += 1
+        else:
+            refs.append({"path": sub_path, "value": value, "kind": "entity"})
+        return True
+    if isinstance(value, list):
+        for i, item in enumerate(value):
+            if not isinstance(item, str):
+                continue
+            item_path = f"{sub_path}[{i}]"
+            if _is_template(item):
+                unvalidated_templates[0] += 1
+            else:
+                refs.append(
+                    {
+                        "path": item_path,
+                        "value": item,
+                        "kind": "entity",
+                    }
+                )
+        return True
+    return False
+
+
 def extract_refs(config: Any) -> WalkerResult:
     """Pull every literal service/entity reference out of *config*.
 
@@ -97,43 +146,17 @@ def extract_refs(config: Any) -> WalkerResult:
                 sub_path = f"{path}.{key}" if path else key
 
                 if key in _SERVICE_KEYS and isinstance(value, str):
-                    if _is_template(value):
-                        unvalidated_templates[0] += 1
-                    else:
-                        refs.append(
-                            {"path": sub_path, "value": value, "kind": "service"}
-                        )
+                    _extract_service_ref(sub_path, value, refs, unvalidated_templates)
+                    continue
+
+                if key in _ENTITY_KEYS and _extract_entity_refs(
+                    sub_path, value, refs, unvalidated_templates
+                ):
                     continue
 
-                if key in _ENTITY_KEYS:
-                    if isinstance(value, str):
-                        if _is_template(value):
-                            unvalidated_templates[0] += 1
-                        else:
-                            refs.append(
-                                {"path": sub_path, "value": value, "kind": "entity"}
-                            )
-                        continue
-                    if isinstance(value, list):
-                        for i, item in enumerate(value):
-                            if not isinstance(item, str):
-                                continue
-                            item_path = f"{sub_path}[{i}]"
-                            if _is_template(item):
-                                unvalidated_templates[0] += 1
-                            else:
-                                refs.append(
-                                    {
-                                        "path": item_path,
-                                        "value": item,
-                                        "kind": "entity",
-                                    }
-                                )
-                        continue
-
-                # Neither a service nor an entity key: recurse so deeply
-                # nested action blocks (choose/if/parallel/repeat) still
-                # get walked.
+                # Neither a service nor an entity key (or an entity key whose
+                # value is neither str nor list): recurse so deeply nested
+                # action blocks (choose/if/parallel/repeat) still get walked.
                 _walk(value, sub_path)
 
         elif isinstance(node, list):

{ha_mcp_dev-7.13.0.dev2003 → ha_mcp_dev-7.13.0.dev2007}/src/ha_mcp/tools/tools_areas.py

@@ -34,6 +34,116 @@ from .util_helpers import (
 logger = logging.getLogger(__name__)
 
 
+def _parse_projection_params(
+    fields: str | list[str] | None,
+    area_fields: str | list[str] | None,
+) -> tuple[list[str] | None, list[str] | None]:
+    """Validate the fields/area_fields projection params, raising on a bad shape."""
+    parsed_fields: list[str] | None = None
+    if fields is not None:
+        try:
+            parsed_fields = parse_string_list_param(fields, "fields", allow_csv=True)
+            if parsed_fields is not None and len(parsed_fields) == 0:
+                raise ValueError("fields must contain at least one key")
+        except ValueError as exc:
+            raise_tool_error(create_validation_error(str(exc), parameter="fields"))
+    parsed_area_fields: list[str] | None = None
+    if area_fields is not None:
+        try:
+            parsed_area_fields = parse_string_list_param(
+                area_fields, "area_fields", allow_csv=True
+            )
+            if parsed_area_fields is not None and len(parsed_area_fields) == 0:
+                raise ValueError("area_fields must contain at least one key")
+        except ValueError as exc:
+            raise_tool_error(create_validation_error(str(exc), parameter="area_fields"))
+    return parsed_fields, parsed_area_fields
+
+
+def _partition_areas_by_floor(
+    areas: list[dict[str, Any]], valid_floor_ids: set[Any]
+) -> tuple[
+    dict[str, list[dict[str, Any]]],
+    list[dict[str, Any]],
+    list[dict[str, Any]],
+]:
+    """Partition areas into (floor_map, unassigned_areas, orphaned_areas).
+
+    Partitions areas into three disjoint sets:
+      - nested:    floor_id present AND points to a known floor
+      - orphaned:  floor_id present BUT points to a non-existent floor
+                   (race between the concurrent reads, or manual
+                   .storage inconsistency)
+      - unassigned: no floor_id at all
+    Orphaned is surfaced as a separate key so the LLM can diagnose
+    registry drift without introspecting individual area fields.
+    Use `is None` rather than falsy-check so that a floor_id of ""
+    (valid but unusual) is treated as orphaned if it does not resolve,
+    not as unassigned.
+    """
+    floor_map: dict[str, list[dict[str, Any]]] = {}
+    unassigned_areas: list[dict[str, Any]] = []
+    orphaned_areas: list[dict[str, Any]] = []
+    for area in areas:
+        fid = area.get("floor_id")
+        if fid is None:
+            unassigned_areas.append(area)
+        elif fid in valid_floor_ids:
+            floor_map.setdefault(fid, []).append(area)
+        else:
+            orphaned_areas.append(area)
+    return floor_map, unassigned_areas, orphaned_areas
+
+
+# Sort by level ascending; coerce defensively so a malformed
+# string `level` cannot raise TypeError mid-sort and get
+# flattened by the broad `except Exception` in the caller.
+def _floor_sort_key(floor: dict[str, Any]) -> int:
+    raw = floor.get("level")
+    if raw is None:
+        return 0
+    try:
+        return int(raw)
+    except (TypeError, ValueError):
+        logger.warning(
+            f"Floor {floor.get('floor_id')!r} has non-numeric "
+            f"level {raw!r}; treating as 0 for sort"
+        )
+        return 0
+
+
+def _validate_cross_kind_params(
+    kind: str,
+    level: int | None,
+    floor_id: str | None,
+    picture: str | None,
+) -> None:
+    """Reject params that don't belong to *kind* before building a set message."""
+    # Reject cross-kind params loudly so silent intent loss can't happen
+    # (e.g., kind='floor' with picture='...' previously dropped the picture
+    # without a diagnostic).
+    cross_kind_params: list[str] = []
+    if kind == "area" and level is not None:
+        cross_kind_params.append("level")
+    elif kind == "floor":
+        if floor_id is not None:
+            cross_kind_params.append("floor_id")
+        if picture is not None:
+            cross_kind_params.append("picture")
+    if cross_kind_params:
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.VALIDATION_INVALID_PARAMETER,
+                f"Parameter(s) {cross_kind_params} are not valid for kind={kind!r}",
+                context={"kind": kind, "invalid_parameters": cross_kind_params},
+                suggestions=[
+                    "For kind='area' use: name, id, floor_id, icon, aliases, picture",
+                    "For kind='floor' use: name, id, level, icon, aliases",
+                ],
+            )
+        )
+
+
 class AreaTools:
     """Area and floor management tools for Home Assistant."""
 
@@ -188,28 +298,9 @@ class AreaTools:
         """
         # Validate projection params before any WS round-trips so a bad shape
         # fails fast without burning two registry reads.
-        parsed_fields: list[str] | None = None
-        if fields is not None:
-            try:
-                parsed_fields = parse_string_list_param(
-                    fields, "fields", allow_csv=True
-                )
-                if parsed_fields is not None and len(parsed_fields) == 0:
-                    raise ValueError("fields must contain at least one key")
-            except ValueError as exc:
-                raise_tool_error(create_validation_error(str(exc), parameter="fields"))
-        parsed_area_fields: list[str] | None = None
-        if area_fields is not None:
-            try:
-                parsed_area_fields = parse_string_list_param(
-                    area_fields, "area_fields", allow_csv=True
-                )
-                if parsed_area_fields is not None and len(parsed_area_fields) == 0:
-                    raise ValueError("area_fields must contain at least one key")
-            except ValueError as exc:
-                raise_tool_error(
-                    create_validation_error(str(exc), parameter="area_fields")
-                )
+        parsed_fields, parsed_area_fields = _parse_projection_params(
+            fields, area_fields
+        )
 
         progress: dict[str, Any] = {
             "operation": "list_floors_areas",
@@ -218,31 +309,12 @@ class AreaTools:
         try:
             areas, floors = await self._fetch_area_floor_registries(progress)
 
-            # Partition areas into three disjoint sets:
-            #   - nested:    floor_id present AND points to a known floor
-            #   - orphaned:  floor_id present BUT points to a non-existent floor
-            #                (race between the concurrent reads, or manual
-            #                .storage inconsistency)
-            #   - unassigned: no floor_id at all
-            # Orphaned is surfaced as a separate key so the LLM can diagnose
-            # registry drift without introspecting individual area fields.
-            # Use `is None` rather than falsy-check so that a floor_id of ""
-            # (valid but unusual) is treated as orphaned if it does not resolve,
-            # not as unassigned.
             valid_floor_ids = {
                 f.get("floor_id") for f in floors if f.get("floor_id") is not None
             }
-            floor_map: dict[str, list[dict[str, Any]]] = {}
-            unassigned_areas: list[dict[str, Any]] = []
-            orphaned_areas: list[dict[str, Any]] = []
-            for area in areas:
-                fid = area.get("floor_id")
-                if fid is None:
-                    unassigned_areas.append(area)
-                elif fid in valid_floor_ids:
-                    floor_map.setdefault(fid, []).append(area)
-                else:
-                    orphaned_areas.append(area)
+            floor_map, unassigned_areas, orphaned_areas = _partition_areas_by_floor(
+                areas, valid_floor_ids
+            )
             progress["phase"] = "partitioned"
 
             # Build nested hierarchy, preserving all floor-registry fields for
@@ -257,22 +329,6 @@ class AreaTools:
                 for floor in floors
             ]
 
-            # Sort by level ascending; coerce defensively so a malformed
-            # string `level` cannot raise TypeError mid-sort and get
-            # flattened by the broad `except Exception` below.
-            def _floor_sort_key(floor: dict[str, Any]) -> int:
-                raw = floor.get("level")
-                if raw is None:
-                    return 0
-                try:
-                    return int(raw)
-                except (TypeError, ValueError):
-                    logger.warning(
-                        f"Floor {floor.get('floor_id')!r} has non-numeric "
-                        f"level {raw!r}; treating as 0 for sort"
-                    )
-                    return 0
-
             topology.sort(key=_floor_sort_key)
             progress["phase"] = "sorted"
 
@@ -408,6 +464,82 @@ class AreaTools:
 
         return areas_result["result"], floors_result["result"]
 
+    def _build_area_or_floor_message(
+        self,
+        kind: str,
+        identifier: str | None,
+        name: str | None,
+        floor_id: str | None,
+        level: int | None,
+        icon: str | None,
+        parsed_aliases: list[str] | None,
+        picture: str | None,
+    ) -> tuple[dict[str, Any], str, str, str, str | None]:
+        """Build the WS message plus (result_key, id_key, operation, name) for a set.
+
+        ``name`` is returned because the create branches narrow it from
+        ``str | None`` to ``str`` via ``validate_identifier_not_empty``.
+        """
+        if kind == "area":
+            if identifier:
+                message = self._build_area_update_message(
+                    identifier,
+                    name,
+                    floor_id,
+                    icon,
+                    parsed_aliases,
+                    picture,
+                )
+                operation = "update"
+            else:
+                # Reassignment narrows ``name`` from ``str | None`` to
+                # ``str`` for the build-message call below.
+                name = validate_identifier_not_empty(
+                    name,
+                    "name",
+                    message="name is required when creating a new area",
+                    context={"operation": "create_area"},
+                    suggestions=["Provide a non-empty name for the new area"],
+                )
+                message = self._build_area_create_message(
+                    name,
+                    floor_id,
+                    icon,
+                    parsed_aliases,
+                    picture,
+                )
+                operation = "create"
+            result_key = "area"
+            id_key = "area_id"
+        else:  # kind == "floor"
+            if identifier:
+                message = self._build_floor_update_message(
+                    identifier,
+                    name,
+                    level,
+                    icon,
+                    parsed_aliases,
+                )
+                operation = "update"
+            else:
+                name = validate_identifier_not_empty(
+                    name,
+                    "name",
+                    message="name is required when creating a new floor",
+                    context={"operation": "create_floor"},
+                    suggestions=["Provide a non-empty name for the new floor"],
+                )
+                message = self._build_floor_create_message(
+                    name,
+                    level,
+                    icon,
+                    parsed_aliases,
+                )
+                operation = "create"
+            result_key = "floor"
+            id_key = "floor_id"
+        return message, result_key, id_key, operation, name
+
     # ============================================================
     # COMBINED SET / REMOVE
     # ============================================================
@@ -514,29 +646,7 @@ class AreaTools:
                     )
                 )
 
-            # Reject cross-kind params loudly so silent intent loss can't happen
-            # (e.g., kind='floor' with picture='...' previously dropped the picture
-            # without a diagnostic).
-            cross_kind_params: list[str] = []
-            if kind == "area" and level is not None:
-                cross_kind_params.append("level")
-            elif kind == "floor":
-                if floor_id is not None:
-                    cross_kind_params.append("floor_id")
-                if picture is not None:
-                    cross_kind_params.append("picture")
-            if cross_kind_params:
-                raise_tool_error(
-                    create_error_response(
-                        ErrorCode.VALIDATION_INVALID_PARAMETER,
-                        f"Parameter(s) {cross_kind_params} are not valid for kind={kind!r}",
-                        context={"kind": kind, "invalid_parameters": cross_kind_params},
-                        suggestions=[
-                            "For kind='area' use: name, id, floor_id, icon, aliases, picture",
-                            "For kind='floor' use: name, id, level, icon, aliases",
-                        ],
-                    )
-                )
+            _validate_cross_kind_params(kind, level, floor_id, picture)
 
             # ``None`` stays the documented "create-new" sentinel; explicit
             # empty/whitespace would silently route to the ``if id:`` create
@@ -552,64 +662,18 @@ class AreaTools:
                     context={"kind": kind},
                 )
 
-            if kind == "area":
-                if id:
-                    message = self._build_area_update_message(
-                        id,
-                        name,
-                        floor_id,
-                        icon,
-                        parsed_aliases,
-                        picture,
-                    )
-                    operation = "update"
-                else:
-                    # Reassignment narrows ``name`` from ``str | None`` to
-                    # ``str`` for the build-message call below.
-                    name = validate_identifier_not_empty(
-                        name,
-                        "name",
-                        message="name is required when creating a new area",
-                        context={"operation": "create_area"},
-                        suggestions=["Provide a non-empty name for the new area"],
-                    )
-                    message = self._build_area_create_message(
-                        name,
-                        floor_id,
-                        icon,
-                        parsed_aliases,
-                        picture,
-                    )
-                    operation = "create"
-                result_key = "area"
-                id_key = "area_id"
-            else:  # kind == "floor"
-                if id:
-                    message = self._build_floor_update_message(
-                        id,
-                        name,
-                        level,
-                        icon,
-                        parsed_aliases,
-                    )
-                    operation = "update"
-                else:
-                    name = validate_identifier_not_empty(
-                        name,
-                        "name",
-                        message="name is required when creating a new floor",
-                        context={"operation": "create_floor"},
-                        suggestions=["Provide a non-empty name for the new floor"],
-                    )
-                    message = self._build_floor_create_message(
-                        name,
-                        level,
-                        icon,
-                        parsed_aliases,
-                    )
-                    operation = "create"
-                result_key = "floor"
-                id_key = "floor_id"
+            message, result_key, id_key, operation, name = (
+                self._build_area_or_floor_message(
+                    kind,
+                    id,
+                    name,
+                    floor_id,
+                    level,
+                    icon,
+                    parsed_aliases,
+                    picture,
+                )
+            )
 
             result = await self._client.send_websocket_message(message)