ha-mcp-dev 7.5.0.dev587__tar.gz → 7.5.0.dev589__tar.gz

{ha_mcp_dev-7.5.0.dev587/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.5.0.dev589}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.5.0.dev587
+Version: 7.5.0.dev589
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -38,7 +38,7 @@ Dynamic: license-file
   <!-- mcp-name: io.github.homeassistant-ai/ha-mcp -->
 
   <p align="center">
-    <img src="https://img.shields.io/badge/tools-88-blue" alt="95+ Tools">
+    <img src="https://img.shields.io/badge/tools-86-blue" alt="95+ Tools">
     <a href="https://github.com/homeassistant-ai/ha-mcp/releases"><img src="https://img.shields.io/github/v/release/homeassistant-ai/ha-mcp" alt="Release"></a>
     <a href="https://github.com/homeassistant-ai/ha-mcp/actions/workflows/e2e-tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/homeassistant-ai/ha-mcp/e2e-tests.yml?branch=master&label=E2E%20Tests" alt="E2E Tests"></a>
     <a href="LICENSE.md"><img src="https://img.shields.io/github/license/homeassistant-ai/ha-mcp.svg" alt="License"></a>
@@ -181,12 +181,12 @@ Spend less time configuring, more time enjoying your smart home.
 <details>
 <!-- TOOLS_TABLE_START -->
 
-<summary><b>Complete Tool List (88 tools)</b></summary>
+<summary><b>Complete Tool List (86 tools)</b></summary>
 
 | Category | Tools |
 |----------|-------|
 | **Add-ons** | `ha_get_addon`, `ha_manage_addon` |
-| **Areas & Floors** | `ha_config_list_areas`, `ha_config_list_floors`, `ha_list_floors_areas`, `ha_remove_area_or_floor`, `ha_set_area_or_floor` |
+| **Areas & Floors** | `ha_list_floors_areas`, `ha_remove_area_or_floor`, `ha_set_area_or_floor` |
 | **Assist** | `ha_manage_pipeline` |
 | **Automations** | `ha_config_get_automation`, `ha_config_remove_automation`, `ha_config_set_automation` |
 | **Blueprints** | `ha_get_blueprint`, `ha_import_blueprint` |
@@ -199,7 +199,7 @@ Spend less time configuring, more time enjoying your smart home.
 | **Files** | `ha_delete_file` *(beta)*, `ha_list_files` *(beta)*, `ha_read_file` *(beta)*, `ha_write_file` *(beta)* |
 | **Groups** | `ha_config_list_groups`, `ha_config_remove_group`, `ha_config_set_group` |
 | **HACS** | `ha_hacs_add_repository`, `ha_hacs_download`, `ha_hacs_repository_info`, `ha_hacs_search` |
-| **Helper Entities** | `ha_config_list_helpers`, `ha_config_set_helper`, `ha_delete_helpers_integrations` |
+| **Helper Entities** | `ha_config_list_helpers`, `ha_config_set_helper`, `ha_remove_helpers_integrations` |
 | **History & Statistics** | `ha_get_automation_traces`, `ha_get_history`, `ha_get_logs` |
 | **Integrations** | `ha_get_integration`, `ha_get_system_health`, `ha_set_integration_enabled` |
 | **Labels & Categories** | `ha_config_get_category`, `ha_config_get_label`, `ha_config_remove_category`, `ha_config_remove_label`, `ha_config_set_category`, `ha_config_set_label` |

{ha_mcp_dev-7.5.0.dev587 → ha_mcp_dev-7.5.0.dev589}/README.md

@@ -8,7 +8,7 @@
   <!-- mcp-name: io.github.homeassistant-ai/ha-mcp -->
 
   <p align="center">
-    <img src="https://img.shields.io/badge/tools-88-blue" alt="95+ Tools">
+    <img src="https://img.shields.io/badge/tools-86-blue" alt="95+ Tools">
     <a href="https://github.com/homeassistant-ai/ha-mcp/releases"><img src="https://img.shields.io/github/v/release/homeassistant-ai/ha-mcp" alt="Release"></a>
     <a href="https://github.com/homeassistant-ai/ha-mcp/actions/workflows/e2e-tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/homeassistant-ai/ha-mcp/e2e-tests.yml?branch=master&label=E2E%20Tests" alt="E2E Tests"></a>
     <a href="LICENSE.md"><img src="https://img.shields.io/github/license/homeassistant-ai/ha-mcp.svg" alt="License"></a>
@@ -151,12 +151,12 @@ Spend less time configuring, more time enjoying your smart home.
 <details>
 <!-- TOOLS_TABLE_START -->
 
-<summary><b>Complete Tool List (88 tools)</b></summary>
+<summary><b>Complete Tool List (86 tools)</b></summary>
 
 | Category | Tools |
 |----------|-------|
 | **Add-ons** | `ha_get_addon`, `ha_manage_addon` |
-| **Areas & Floors** | `ha_config_list_areas`, `ha_config_list_floors`, `ha_list_floors_areas`, `ha_remove_area_or_floor`, `ha_set_area_or_floor` |
+| **Areas & Floors** | `ha_list_floors_areas`, `ha_remove_area_or_floor`, `ha_set_area_or_floor` |
 | **Assist** | `ha_manage_pipeline` |
 | **Automations** | `ha_config_get_automation`, `ha_config_remove_automation`, `ha_config_set_automation` |
 | **Blueprints** | `ha_get_blueprint`, `ha_import_blueprint` |
@@ -169,7 +169,7 @@ Spend less time configuring, more time enjoying your smart home.
 | **Files** | `ha_delete_file` *(beta)*, `ha_list_files` *(beta)*, `ha_read_file` *(beta)*, `ha_write_file` *(beta)* |
 | **Groups** | `ha_config_list_groups`, `ha_config_remove_group`, `ha_config_set_group` |
 | **HACS** | `ha_hacs_add_repository`, `ha_hacs_download`, `ha_hacs_repository_info`, `ha_hacs_search` |
-| **Helper Entities** | `ha_config_list_helpers`, `ha_config_set_helper`, `ha_delete_helpers_integrations` |
+| **Helper Entities** | `ha_config_list_helpers`, `ha_config_set_helper`, `ha_remove_helpers_integrations` |
 | **History & Statistics** | `ha_get_automation_traces`, `ha_get_history`, `ha_get_logs` |
 | **Integrations** | `ha_get_integration`, `ha_get_system_health`, `ha_set_integration_enabled` |
 | **Labels & Categories** | `ha_config_get_category`, `ha_config_get_label`, `ha_config_remove_category`, `ha_config_remove_label`, `ha_config_set_category`, `ha_config_set_label` |

{ha_mcp_dev-7.5.0.dev587 → ha_mcp_dev-7.5.0.dev589}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.5.0.dev587"
+version = "7.5.0.dev589"
 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.5.0.dev587 → ha_mcp_dev-7.5.0.dev589}/src/ha_mcp/tools/smart_search.py

@@ -197,14 +197,13 @@ class SmartSearchTools:
             aliases_map: dict[str, list[str]] = {}
             if survivor_ids:
                 try:
-                    entries_resp = await self.client.send_websocket_message({
-                        "type": "config/entity_registry/get_entries",
-                        "entity_ids": survivor_ids,
-                    })
-                    if (
-                        isinstance(entries_resp, dict)
-                        and entries_resp.get("success")
-                    ):
+                    entries_resp = await self.client.send_websocket_message(
+                        {
+                            "type": "config/entity_registry/get_entries",
+                            "entity_ids": survivor_ids,
+                        }
+                    )
+                    if isinstance(entries_resp, dict) and entries_resp.get("success"):
                         for eid, entry in (
                             entries_resp.get("result", {}) or {}
                         ).items():
@@ -232,11 +231,13 @@ class SmartSearchTools:
                 # Shallow copy + private-prefixed keys so downstream
                 # consumers that round-trip these dicts don't ship
                 # internal fields back to clients.
-                enriched.append({
-                    **entity,
-                    "_aliases": aliases_map.get(eid, []),
-                    "_hidden_by": slim.get("hidden_by"),
-                })
+                enriched.append(
+                    {
+                        **entity,
+                        "_aliases": aliases_map.get(eid, []),
+                        "_hidden_by": slim.get("hidden_by"),
+                    }
+                )
 
             entities = enriched
             if domain_filter:
@@ -389,7 +390,7 @@ class SmartSearchTools:
             # Two-pass area resolution. Pass 1 collects exact id / name /
             # alias matches; if any are found, fuzzy aggregation is
             # skipped entirely. This makes ``area_filter`` honor a
-            # literal area_id from ``ha_config_list_areas`` — pre-fix a
+            # literal area_id from ``ha_list_floors_areas`` — pre-fix a
             # query like ``"bedroom_kids"`` would also fuzzy-match its
             # parent ``"bedroom"`` (partial_ratio=100) and aggregate
             # sibling areas' entities. Aliases (per-area registry, used
@@ -519,9 +520,7 @@ class SmartSearchTools:
                                 ),
                                 "state": state_info.get("state", "unknown"),
                                 "_hidden_by": (
-                                    "hidden"
-                                    if entity_id in hidden_entity_ids
-                                    else None
+                                    "hidden" if entity_id in hidden_entity_ids else None
                                 ),
                             }
                         )
@@ -538,9 +537,7 @@ class SmartSearchTools:
                             "domain": entity_id.split(".")[0],
                             "state": state_info.get("state", "unknown"),
                             "_hidden_by": (
-                                "hidden"
-                                if entity_id in hidden_entity_ids
-                                else None
+                                "hidden" if entity_id in hidden_entity_ids else None
                             ),
                         }
                         for entity_id in area_entities

{ha_mcp_dev-7.5.0.dev587 → ha_mcp_dev-7.5.0.dev589}/src/ha_mcp/tools/tools_areas.py

@@ -5,6 +5,7 @@ This module provides tools for listing, creating, updating, and deleting
 Home Assistant areas and floors - essential organizational features for smart homes.
 """
 
+import asyncio
 import logging
 from typing import Annotated, Any, Literal
 
@@ -130,20 +131,20 @@ class AreaTools:
         return message
 
     # ============================================================
-    # AREA TOOLS
+    # AREA & FLOOR LISTING
     # ============================================================
 
     @tool(
-        name="ha_config_list_areas",
+        name="ha_list_floors_areas",
         tags={"Areas & Floors"},
         annotations={
             "idempotentHint": True,
             "readOnlyHint": True,
-            "title": "List Areas",
+            "title": "List Floors and Areas",
         },
     )
     @log_tool_usage
-    async def ha_config_list_areas(
+    async def ha_list_floors_areas(
         self,
         fields: Annotated[
             str | list[str] | None,
@@ -151,9 +152,11 @@ class AreaTools:
                 default=None,
                 description=(
                     "Return only the specified top-level response keys to reduce "
-                    'response size (e.g. ["areas"]). '
+                    'response size (e.g. ["floors"]). '
                     "None = full response (default). "
-                    "Available keys: success, count, areas, message."
+                    "Available keys: success, floor_count, area_count, "
+                    "unassigned_count, orphaned_count, floors, unassigned_areas, "
+                    "orphaned_areas, message."
                 ),
             ),
         ] = None,
@@ -162,25 +165,32 @@ class AreaTools:
             Field(
                 default=None,
                 description=(
-                    "Project each area record to only the specified keys. "
-                    'E.g. ["area_id", "name"] returns slim area records. '
-                    "None = full records (default). Unknown keys yield empty records. "
-                    "Available keys: area_id, name, icon, floor_id, aliases, picture, labels."
+                    "Project each area record (in floors[].areas, unassigned_areas, "
+                    'and orphaned_areas) to only the specified keys. E.g. ["area_id", '
+                    '"name"] returns slim area records. None = full records (default). '
+                    "Unknown keys yield empty records. Available keys: area_id, name, "
+                    "icon, floor_id, aliases, picture, labels."
                 ),
             ),
         ] = None,
     ) -> dict[str, Any]:
         """
-        List all Home Assistant areas (rooms).
+        List floors sorted by level ascending, each with their assigned areas nested, plus areas without a floor.
+
+        Use for location-based reasoning where floor-to-area relationships matter, such as "which rooms are on the ground floor" or operations scoped to a level. Optionally project the response with fields= (top-level keys) or area_fields= (per-area-record keys, applied uniformly across nested, unassigned, and orphaned buckets).
 
-        Returns area ID, name, icon, floor assignment, aliases, and picture URL.
+        Floors with level=None sort alongside level 0 (ground floor). Areas without a floor assignment appear in unassigned_areas; areas whose floor_id points to a non-existent floor appear in orphaned_areas — a topology snapshot may diverge from individual list calls if the registries change between reads.
         """
+        # 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
@@ -195,141 +205,39 @@ class AreaTools:
                 raise_tool_error(
                     create_validation_error(str(exc), parameter="area_fields")
                 )
-        try:
-            message: dict[str, Any] = {
-                "type": "config/area_registry/list",
-            }
-
-            result = await self._client.send_websocket_message(message)
-
-            if result.get("success"):
-                areas = result.get("result", [])
-                _orig_areas = areas
-                if parsed_area_fields is not None:
-                    areas = project_records(areas, parsed_area_fields)
-                response: dict[str, Any] = {
-                    "success": True,
-                    "count": len(areas),
-                    "areas": areas,
-                    "message": f"Found {len(areas)} area(s)",
-                }
-                if parsed_area_fields is not None:
-                    _warn = result_fields_warning(
-                        _orig_areas, areas, parsed_area_fields, param_name="area_fields"
-                    )
-                    if _warn:
-                        response.setdefault("warnings", []).append(_warn)
-                return project_fields(response, parsed_fields)
-            else:
-                raise_tool_error(
-                    create_error_response(
-                        ErrorCode.SERVICE_CALL_FAILED,
-                        result.get("error", "Failed to list areas"),
-                    )
-                )
-
-        except ToolError:
-            raise
-        except Exception as e:
-            logger.error(f"Error listing areas: {e}")
-            exception_to_structured_error(
-                e,
-                context={"operation": "list_areas"},
-                suggestions=[
-                    "Check Home Assistant connection",
-                    "Verify WebSocket connection is active",
-                ],
-            )
-
-    # ============================================================
-    # FLOOR TOOLS
-    # ============================================================
-
-    @tool(
-        name="ha_config_list_floors",
-        tags={"Areas & Floors"},
-        annotations={
-            "idempotentHint": True,
-            "readOnlyHint": True,
-            "title": "List Floors",
-        },
-    )
-    @log_tool_usage
-    async def ha_config_list_floors(self) -> dict[str, Any]:
-        """
-        List all Home Assistant floors.
-
-        Returns floor ID, name, icon, level (0=ground, 1=first, -1=basement), and aliases.
-        """
-        try:
-            message: dict[str, Any] = {
-                "type": "config/floor_registry/list",
-            }
-
-            result = await self._client.send_websocket_message(message)
-
-            if result.get("success"):
-                floors = result.get("result", [])
-                return {
-                    "success": True,
-                    "count": len(floors),
-                    "floors": floors,
-                    "message": f"Found {len(floors)} floor(s)",
-                }
-            else:
-                raise_tool_error(
-                    create_error_response(
-                        ErrorCode.SERVICE_CALL_FAILED,
-                        result.get("error", "Failed to list floors"),
-                    )
-                )
 
-        except ToolError:
-            raise
-        except Exception as e:
-            logger.error(f"Error listing floors: {e}")
-            exception_to_structured_error(
-                e,
-                context={"operation": "list_floors"},
-                suggestions=[
-                    "Check Home Assistant connection",
-                    "Verify WebSocket connection is active",
-                ],
-            )
-
-    @tool(
-        name="ha_list_floors_areas",
-        tags={"Areas & Floors"},
-        annotations={
-            "idempotentHint": True,
-            "readOnlyHint": True,
-            "title": "List Floors and Areas",
-        },
-    )
-    @log_tool_usage
-    async def ha_list_floors_areas(self) -> dict[str, Any]:
-        """
-        List floors sorted by level ascending, each with their assigned areas nested, plus areas without a floor.
-
-        Do not use for flat listings — ha_config_list_areas and ha_config_list_floors cover those.
-
-        Use for location-based reasoning where floor-to-area relationships matter, such as "which rooms are on the ground floor" or operations scoped to a level.
-
-        Floors with level=None sort alongside level 0 (ground floor). Areas without a floor assignment appear in unassigned_areas; areas whose floor_id points to a non-existent floor appear in orphaned_areas — a topology snapshot may diverge from individual list calls if the registries change between reads.
-        """
         progress: dict[str, Any] = {
             "operation": "list_floors_areas",
             "phase": "start",
         }
         try:
-            areas_result = await self._client.send_websocket_message(
-                {"type": "config/area_registry/list"}
-            )
-            progress["phase"] = "areas_fetched"
-            floors_result = await self._client.send_websocket_message(
-                {"type": "config/floor_registry/list"}
+            # Fetch both registries concurrently. Sequential awaits add a
+            # round-trip per call on the WS transport; gather halves the
+            # tool-side latency. Use return_exceptions=True so a failure on
+            # one side doesn't cancel the other — the post-fetch guard
+            # below reports both registries' state in the error context for
+            # diagnosis. Indexed access + explicit annotations rather than
+            # tuple-unpack — gather returns list[Any] which mypy can't
+            # statically narrow to a 2-tuple.
+            results = await asyncio.gather(
+                self._client.send_websocket_message(
+                    {"type": "config/area_registry/list"}
+                ),
+                self._client.send_websocket_message(
+                    {"type": "config/floor_registry/list"}
+                ),
+                return_exceptions=True,
             )
-            progress["phase"] = "floors_fetched"
+            progress["phase"] = "registries_fetched"
+
+            # Re-raise transport-level exceptions from either fetch so the
+            # outer except handler classifies them via exception_to_structured_error.
+            if isinstance(results[0], BaseException):
+                raise results[0]
+            if isinstance(results[1], BaseException):
+                raise results[1]
+            areas_result: dict[str, Any] = results[0]
+            floors_result: dict[str, Any] = results[1]
 
             # A response with success=True but no "result" key is malformed —
             # treat it as a service call failure rather than silently returning
@@ -360,7 +268,7 @@ class AreaTools:
             # 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 two sequential reads, or manual
+            #                (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
@@ -410,22 +318,50 @@ class AreaTools:
             topology.sort(key=_floor_sort_key)
             progress["phase"] = "sorted"
 
-            return {
+            # Apply per-area projection across all 3 buckets uniformly.
+            # Snapshot pre-projection areas for the typo-guard warning.
+            _orig_all_areas = list(areas)
+            if parsed_area_fields is not None:
+                for floor in topology:
+                    floor["areas"] = project_records(floor["areas"], parsed_area_fields)
+                unassigned_areas = project_records(unassigned_areas, parsed_area_fields)
+                orphaned_areas = project_records(orphaned_areas, parsed_area_fields)
+
+            response: dict[str, Any] = {
                 "success": True,
                 "floor_count": len(topology),
-                "area_count": len(areas),
+                "area_count": len(_orig_all_areas),
                 "unassigned_count": len(unassigned_areas),
                 "orphaned_count": len(orphaned_areas),
                 "floors": topology,
                 "unassigned_areas": unassigned_areas,
                 "orphaned_areas": orphaned_areas,
                 "message": (
-                    f"Found {len(topology)} floor(s), {len(areas)} area(s), "
+                    f"Found {len(topology)} floor(s), {len(_orig_all_areas)} area(s), "
                     f"{len(unassigned_areas)} unassigned, "
                     f"{len(orphaned_areas)} orphaned"
                 ),
             }
 
+            # Typo-guard: combine projected areas across buckets to detect the
+            # all-empty-records situation that signals an unknown area_fields key.
+            if parsed_area_fields is not None:
+                _projected_all = (
+                    [a for f in topology for a in f["areas"]]
+                    + unassigned_areas
+                    + orphaned_areas
+                )
+                _warn = result_fields_warning(
+                    _orig_all_areas,
+                    _projected_all,
+                    parsed_area_fields,
+                    param_name="area_fields",
+                )
+                if _warn:
+                    response.setdefault("warnings", []).append(_warn)
+
+            return project_fields(response, parsed_fields)
+
         except ToolError:
             raise
         except Exception as e:

{ha_mcp_dev-7.5.0.dev587 → ha_mcp_dev-7.5.0.dev589}/src/ha_mcp/tools/tools_config_helpers.py

@@ -1154,7 +1154,7 @@ async def _validate_registry_ids(
                     f"area_id={area_id!r} does not exist in the area registry.",
                     context={"area_id": area_id},
                     suggestions=[
-                        "Use ha_config_list_areas() to list valid area IDs.",
+                        "Use ha_list_floors_areas() to list valid area IDs.",
                         'Pass area_id="" to clear the area assignment.',
                         f"Available area_ids: {sorted(valid_area_ids)}",
                     ],

{ha_mcp_dev-7.5.0.dev587 → ha_mcp_dev-7.5.0.dev589}/src/ha_mcp/tools/tools_groups.py

@@ -277,12 +277,12 @@ class GroupTools:
         **When NOT to use:** for typical "combine these entities into one controllable group"
         requests, prefer `ha_config_set_helper(helper_type="group", ...)`. Config-entry-backed
         groups are registered in the entity registry, so `ha_set_entity` can assign them to
-        areas and they are deletable via `ha_delete_helpers_integrations`.
+        areas and they are deletable via `ha_remove_helpers_integrations`.
 
         **When to use:** compatibility with existing groups already configured via group.set
         or YAML, or the rare case where entity-registry membership is explicitly unwanted.
         Groups created here are only removable via `ha_config_remove_group` —
-        `ha_delete_helpers_integrations` will not find them.
+        `ha_remove_helpers_integrations` will not find them.
 
         **For NEW groups:** Provide object_id and entities (required).
         **For EXISTING groups:** Provide object_id and any fields to update.
@@ -414,7 +414,7 @@ class GroupTools:
         Remove a service-based Home Assistant entity group via the group.remove service.
 
         **When NOT to use:** for groups created through `ha_config_set_helper(helper_type="group", ...)`,
-        use `ha_delete_helpers_integrations`. Those config-entry-backed groups are not reachable via the
+        use `ha_remove_helpers_integrations`. Those config-entry-backed groups are not reachable via the
         group.remove service.
 
         **When to use:** removing groups created with `ha_config_set_group` or defined in YAML