ha-mcp-dev 7.5.0.dev564__tar.gz → 7.5.0.dev566__tar.gz

{ha_mcp_dev-7.5.0.dev564/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.5.0.dev566}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.5.0.dev564"
+version = "7.5.0.dev566"
 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.dev564 → ha_mcp_dev-7.5.0.dev566}/src/ha_mcp/client/rest_client.py

@@ -82,6 +82,20 @@ class HomeAssistantCommandError(HomeAssistantError):
     """
 
 
+class HomeAssistantCommandTimeout(HomeAssistantError):
+    """WebSocket ``send_command`` timed out waiting for HA's response.
+
+    Sibling of ``HomeAssistantCommandError`` (not a subclass) so existing
+    ``except HomeAssistantCommandError`` sites — including the match
+    dispatch in ``helpers._classify_exception`` — keep their original
+    semantics. Callers that specifically want to handle our 30s WS
+    round-trip timeout (e.g. short-lived waiter cleanup that should
+    swallow a timeout instead of masking the real wait result) catch
+    this type directly. Replaces a bare ``Exception("Command timeout")``
+    string-match pattern (#1382 Patch76 review).
+    """
+
+
 class HomeAssistantClient:
     """Authenticated HTTP client for Home Assistant API."""
 

{ha_mcp_dev-7.5.0.dev564 → ha_mcp_dev-7.5.0.dev566}/src/ha_mcp/client/websocket_client.py

@@ -23,6 +23,7 @@ import websockets
 from ..config import get_global_settings
 from .rest_client import (
     HomeAssistantCommandError,
+    HomeAssistantCommandTimeout,
     HomeAssistantConnectionError,
     _is_ssl_error,
 )
@@ -58,6 +59,7 @@ class WebSocketConnectionState:
         )
         self._pending_requests[message_id] = future
         return future
+
     def resolve_pending_request(
         self, message_id: int
     ) -> asyncio.Future[dict[str, Any]] | None:
@@ -262,7 +264,9 @@ class HomeAssistantWebSocketClient:
                 message_type="auth_required", timeout=5
             )
             if not auth_msg:
-                raise HomeAssistantConnectionError("Did not receive auth_required message")
+                raise HomeAssistantConnectionError(
+                    "Did not receive auth_required message"
+                )
 
             # Send authentication
             await self._send_auth()
@@ -511,7 +515,7 @@ class HomeAssistantWebSocketClient:
 
         except TimeoutError as e:
             self.cancel_pending_response(message_id)
-            raise Exception("Command timeout") from e
+            raise HomeAssistantCommandTimeout("Command timeout") from e
         except Exception:
             self.cancel_pending_response(message_id)
             raise
@@ -572,9 +576,7 @@ class HomeAssistantWebSocketClient:
             raise HomeAssistantCommandError(f"Command failed: {error_msg}")
 
         try:
-            event_response = await asyncio.wait_for(
-                event_future, timeout=wait_timeout
-            )
+            event_response = await asyncio.wait_for(event_future, timeout=wait_timeout)
         except TimeoutError:
             self.cancel_event_response(message_id)
             raise
@@ -639,13 +641,50 @@ class HomeAssistantWebSocketClient:
 
         error = response.get("error", {})
         error_msg = (
-            error.get("message", str(error))
-            if isinstance(error, dict)
-            else str(error)
-        )
-        raise HomeAssistantCommandError(
-            f"subscribe_events failed: {error_msg}"
+            error.get("message", str(error)) if isinstance(error, dict) else str(error)
         )
+        raise HomeAssistantCommandError(f"subscribe_events failed: {error_msg}")
+
+    async def unsubscribe_events(self, subscription_id: int) -> None:
+        """Release a subscription previously returned by ``subscribe_events``.
+
+        Used by short-lived waiters (``util_helpers.wait_for_*``) that need
+        to drop the subscription as soon as their event arrives so the
+        shared socket doesn't accumulate stale ``state_changed`` listeners.
+
+        Exception policy (narrow, distinct log levels — Gemini #1382):
+
+        - Transport-level loss (``OSError``): subscription is implicitly
+          gone with the connection. Logged at ``debug`` so HA-mid-restart
+          cleanup doesn't spam warnings.
+        - HA-side rejection (``HomeAssistantCommandError``, e.g. "Subscription
+          not found" after a server-side reset): unexpected during normal
+          cleanup. Logged at ``warning`` so a real subscription leak is
+          discoverable.
+        - Everything else: propagates to the caller's ``finally`` so a
+          programming bug (TypeError, AttributeError) fails loudly instead
+          of being buried under a broad ``except``.
+        """
+        if not self._state.is_ready:
+            logger.debug(
+                "unsubscribe_events(%s) skipped: WebSocket not ready",
+                subscription_id,
+            )
+            return
+        try:
+            await self.send_command("unsubscribe_events", subscription=subscription_id)
+        except OSError as e:
+            logger.debug(
+                "unsubscribe_events(%s): transport lost during cleanup: %s",
+                subscription_id,
+                e,
+            )
+        except HomeAssistantCommandError as e:
+            logger.warning(
+                "unsubscribe_events(%s) rejected by HA: %s",
+                subscription_id,
+                e,
+            )
 
     def add_event_handler(
         self,
@@ -721,7 +760,6 @@ class HomeAssistantWebSocketClient:
         return self._state.is_ready
 
 
-
 MAX_POOL_SIZE = 50
 
 
@@ -755,7 +793,8 @@ class WebSocketManager:
     def configure(
         self,
         *,
-        client_factory: Callable[[str, str], HomeAssistantWebSocketClient] | None = None,
+        client_factory: Callable[[str, str], HomeAssistantWebSocketClient]
+        | None = None,
     ) -> None:
         """Configure the manager with injectable dependencies."""
         if client_factory is not None:

{ha_mcp_dev-7.5.0.dev564 → ha_mcp_dev-7.5.0.dev566}/src/ha_mcp/tools/tools_areas.py

@@ -12,7 +12,7 @@ from fastmcp.exceptions import ToolError
 from fastmcp.tools import tool
 from pydantic import Field
 
-from ..errors import ErrorCode, create_error_response
+from ..errors import ErrorCode, create_error_response, create_validation_error
 from .helpers import (
     exception_to_structured_error,
     log_tool_usage,
@@ -20,7 +20,12 @@ from .helpers import (
     register_tool_methods,
     validate_identifier_not_empty,
 )
-from .util_helpers import parse_string_list_param
+from .util_helpers import (
+    parse_string_list_param,
+    project_fields,
+    project_records,
+    result_fields_warning,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -130,15 +135,65 @@ class AreaTools:
     @tool(
         name="ha_config_list_areas",
         tags={"Areas & Floors"},
-        annotations={"idempotentHint": True, "readOnlyHint": True, "title": "List Areas"},
+        annotations={
+            "idempotentHint": True,
+            "readOnlyHint": True,
+            "title": "List Areas",
+        },
     )
     @log_tool_usage
-    async def ha_config_list_areas(self) -> dict[str, Any]:
+    async def ha_config_list_areas(
+        self,
+        fields: Annotated[
+            str | list[str] | None,
+            Field(
+                default=None,
+                description=(
+                    "Return only the specified top-level response keys to reduce "
+                    'response size (e.g. ["areas"]). '
+                    "None = full response (default). "
+                    "Available keys: success, count, areas, message."
+                ),
+            ),
+        ] = None,
+        area_fields: Annotated[
+            str | list[str] | None,
+            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."
+                ),
+            ),
+        ] = None,
+    ) -> dict[str, Any]:
         """
         List all Home Assistant areas (rooms).
 
         Returns area ID, name, icon, floor assignment, aliases, and picture URL.
         """
+        parsed_fields: list[str] | None = None
+        if fields is not None:
+            try:
+                parsed_fields = parse_string_list_param(
+                    fields, "fields", allow_csv=True
+                )
+            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")
+                )
         try:
             message: dict[str, Any] = {
                 "type": "config/area_registry/list",
@@ -148,26 +203,42 @@ class AreaTools:
 
             if result.get("success"):
                 areas = result.get("result", [])
-                return {
+                _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"),
-                ))
+                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",
-            ])
+            exception_to_structured_error(
+                e,
+                context={"operation": "list_areas"},
+                suggestions=[
+                    "Check Home Assistant connection",
+                    "Verify WebSocket connection is active",
+                ],
+            )
 
     # ============================================================
     # FLOOR TOOLS
@@ -176,7 +247,11 @@ class AreaTools:
     @tool(
         name="ha_config_list_floors",
         tags={"Areas & Floors"},
-        annotations={"idempotentHint": True, "readOnlyHint": True, "title": "List Floors"},
+        annotations={
+            "idempotentHint": True,
+            "readOnlyHint": True,
+            "title": "List Floors",
+        },
     )
     @log_tool_usage
     async def ha_config_list_floors(self) -> dict[str, Any]:
@@ -201,24 +276,34 @@ class AreaTools:
                     "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"),
-                ))
+                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",
-            ])
+            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"},
+        annotations={
+            "idempotentHint": True,
+            "readOnlyHint": True,
+            "title": "List Floors and Areas",
+        },
     )
     @log_tool_usage
     async def ha_list_floors_areas(self) -> dict[str, Any]:
@@ -251,20 +336,22 @@ class AreaTools:
             areas_ok = areas_result.get("success") and "result" in areas_result
             floors_ok = floors_result.get("success") and "result" in floors_result
             if not (areas_ok and floors_ok):
-                raise_tool_error(create_error_response(
-                    ErrorCode.SERVICE_CALL_FAILED,
-                    "Failed to retrieve area or floor registry",
-                    context={
-                        "areas_success": areas_result.get("success"),
-                        "floors_success": floors_result.get("success"),
-                        "areas_response_keys": sorted(areas_result.keys()),
-                        "floors_response_keys": sorted(floors_result.keys()),
-                    },
-                    suggestions=[
-                        "Check Home Assistant connection",
-                        "Verify WebSocket connection is active",
-                    ],
-                ))
+                raise_tool_error(
+                    create_error_response(
+                        ErrorCode.SERVICE_CALL_FAILED,
+                        "Failed to retrieve area or floor registry",
+                        context={
+                            "areas_success": areas_result.get("success"),
+                            "floors_success": floors_result.get("success"),
+                            "areas_response_keys": sorted(areas_result.keys()),
+                            "floors_response_keys": sorted(floors_result.keys()),
+                        },
+                        suggestions=[
+                            "Check Home Assistant connection",
+                            "Verify WebSocket connection is active",
+                        ],
+                    )
+                )
 
             areas = areas_result["result"]
             floors = floors_result["result"]
@@ -361,7 +448,10 @@ class AreaTools:
     @tool(
         name="ha_set_area_or_floor",
         tags={"Areas & Floors"},
-        annotations={"destructiveHint": True, "title": "Create or Update Area or Floor"},
+        annotations={
+            "destructiveHint": True,
+            "title": "Create or Update Area or Floor",
+        },
     )
     @log_tool_usage
     async def ha_set_area_or_floor(
@@ -439,10 +529,12 @@ class AreaTools:
             try:
                 parsed_aliases = parse_string_list_param(aliases, "aliases")
             except ValueError as e:
-                raise_tool_error(create_error_response(
-                    ErrorCode.VALIDATION_INVALID_PARAMETER,
-                    f"Invalid aliases parameter: {e}",
-                ))
+                raise_tool_error(
+                    create_error_response(
+                        ErrorCode.VALIDATION_INVALID_PARAMETER,
+                        f"Invalid aliases parameter: {e}",
+                    )
+                )
 
             # Reject cross-kind params loudly so silent intent loss can't happen
             # (e.g., kind='floor' with picture='...' previously dropped the picture
@@ -456,15 +548,17 @@ class AreaTools:
                 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",
-                    ],
-                ))
+                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",
+                        ],
+                    )
+                )
 
             # ``None`` stays the documented "create-new" sentinel; explicit
             # empty/whitespace would silently route to the ``if id:`` create
@@ -483,7 +577,12 @@ class AreaTools:
             if kind == "area":
                 if id:
                     message = self._build_area_update_message(
-                        id, name, floor_id, icon, parsed_aliases, picture,
+                        id,
+                        name,
+                        floor_id,
+                        icon,
+                        parsed_aliases,
+                        picture,
                     )
                     operation = "update"
                 else:
@@ -497,7 +596,11 @@ class AreaTools:
                         suggestions=["Provide a non-empty name for the new area"],
                     )
                     message = self._build_area_create_message(
-                        name, floor_id, icon, parsed_aliases, picture,
+                        name,
+                        floor_id,
+                        icon,
+                        parsed_aliases,
+                        picture,
                     )
                     operation = "create"
                 result_key = "area"
@@ -505,7 +608,11 @@ class AreaTools:
             else:  # kind == "floor"
                 if id:
                     message = self._build_floor_update_message(
-                        id, name, level, icon, parsed_aliases,
+                        id,
+                        name,
+                        level,
+                        icon,
+                        parsed_aliases,
                     )
                     operation = "update"
                 else:
@@ -517,7 +624,10 @@ class AreaTools:
                         suggestions=["Provide a non-empty name for the new floor"],
                     )
                     message = self._build_floor_create_message(
-                        name, level, icon, parsed_aliases,
+                        name,
+                        level,
+                        icon,
+                        parsed_aliases,
                     )
                     operation = "create"
                 result_key = "floor"
@@ -538,17 +648,23 @@ class AreaTools:
                 }
 
             error = result.get("error", {})
-            error_msg = error.get("message", str(error)) if isinstance(error, dict) else str(error)
+            error_msg = (
+                error.get("message", str(error))
+                if isinstance(error, dict)
+                else str(error)
+            )
             ctx: dict[str, Any] = {"operation": operation, "kind": kind}
             if name:
                 ctx["name"] = name
             if id:
                 ctx[id_key] = id
-            raise_tool_error(create_error_response(
-                ErrorCode.SERVICE_CALL_FAILED,
-                f"Failed to {operation} {kind}: {error_msg}",
-                context=ctx,
-            ))
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.SERVICE_CALL_FAILED,
+                    f"Failed to {operation} {kind}: {error_msg}",
+                    context=ctx,
+                )
+            )
 
         except ToolError:
             raise
@@ -570,7 +686,11 @@ class AreaTools:
     @tool(
         name="ha_remove_area_or_floor",
         tags={"Areas & Floors"},
-        annotations={"destructiveHint": True, "idempotentHint": True, "title": "Remove Area or Floor"},
+        annotations={
+            "destructiveHint": True,
+            "idempotentHint": True,
+            "title": "Remove Area or Floor",
+        },
     )
     @log_tool_usage
     async def ha_remove_area_or_floor(
@@ -581,7 +701,9 @@ class AreaTools:
         ],
         id: Annotated[  # noqa: A002
             str,
-            Field(description="Area ID or floor ID to delete (use ha_list_floors_areas to find IDs)"),
+            Field(
+                description="Area ID or floor ID to delete (use ha_list_floors_areas to find IDs)"
+            ),
         ],
     ) -> dict[str, Any]:
         """Remove a Home Assistant area or floor.
@@ -618,12 +740,18 @@ class AreaTools:
                 }
 
             error = result.get("error", {})
-            error_msg = error.get("message", str(error)) if isinstance(error, dict) else str(error)
-            raise_tool_error(create_error_response(
-                ErrorCode.SERVICE_CALL_FAILED,
-                f"Failed to remove {kind}: {error_msg}",
-                context={"kind": kind, id_key: id},
-            ))
+            error_msg = (
+                error.get("message", str(error))
+                if isinstance(error, dict)
+                else str(error)
+            )
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.SERVICE_CALL_FAILED,
+                    f"Failed to remove {kind}: {error_msg}",
+                    context={"kind": kind, id_key: id},
+                )
+            )
 
         except ToolError:
             raise