ha-mcp-dev 7.4.1.dev454__tar.gz → 7.4.1.dev455__tar.gz

{ha_mcp_dev-7.4.1.dev454/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.4.1.dev455}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.4.1.dev454"
+version = "7.4.1.dev455"
 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.4.1.dev454 → ha_mcp_dev-7.4.1.dev455}/src/ha_mcp/tools/device_control.py

@@ -8,6 +8,7 @@ and async operation verification through WebSocket monitoring.
 import asyncio
 import json
 import logging
+import time
 from typing import Any, ClassVar
 
 from fastmcp import Context
@@ -19,7 +20,12 @@ from ..config import get_global_settings
 from ..errors import ErrorCode, create_error_response
 from ..utils.domain_handlers import get_domain_handler
 from ..utils.operation_manager import get_operation_from_memory, store_pending_operation
-from .helpers import exception_to_structured_error, raise_tool_error
+from .helpers import (
+    exception_to_structured_error,
+    raise_tool_error,
+    safe_info,
+    safe_progress,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -394,18 +400,13 @@ class DeviceControlTools:
     async def get_device_operation_status(
         self, operation_id: str, timeout_seconds: int = 10
     ) -> dict[str, Any]:
-        """
-        Check status of device operation with async verification.
-
-        This tool checks the status of operations initiated by control_device_smart.
-        Results come from real-time WebSocket monitoring of Home Assistant state changes.
-
-        Args:
-            operation_id: Operation ID returned by control_device_smart
-            timeout_seconds: Maximum time to wait for completion
+        """Check status of a device operation, waiting up to ``timeout_seconds`` for completion.
 
-        Returns:
-            Operation status with completion details or timeout info
+        Polls the in-memory operation registry (mutated by the WebSocket
+        listener as state changes arrive) every 0.2s while the operation is
+        pending, up to ``timeout_seconds``. Returns the final structured status
+        — completed/failed/timeout/pending — produced by
+        ``control_device_smart``.
         """
         operation = get_operation_from_memory(operation_id)
 
@@ -421,6 +422,30 @@ class DeviceControlTools:
                 context={"operation_id": operation_id},
             ))
 
+        # Wait up to timeout_seconds for the operation to leave the pending state.
+        # The WebSocket listener mutates operation.status as state changes arrive,
+        # so polling memory is sufficient — no need to subscribe again. Uses
+        # time.monotonic() so the deadline can be cleanly patched in tests.
+        if operation.status.value == "pending" and timeout_seconds > 0:
+            deadline = time.monotonic() + timeout_seconds
+            while operation.status.value == "pending":
+                if time.monotonic() >= deadline:
+                    break
+                await asyncio.sleep(0.2)
+                refreshed = get_operation_from_memory(operation_id)
+                if refreshed is None:
+                    raise_tool_error(create_error_response(
+                        ErrorCode.RESOURCE_NOT_FOUND,
+                        "Operation cleaned up during status poll",
+                        suggestions=[
+                            "Operation may have completed and been purged before "
+                            "verification finished",
+                            "Use control_device_smart to start new operation",
+                        ],
+                        context={"operation_id": operation_id},
+                    ))
+                operation = refreshed
+
         # Check operation status
         if operation.status.value == "completed":
             return {
@@ -546,7 +571,6 @@ class DeviceControlTools:
         Args:
             operations: List of device control operations
             parallel: Whether to execute operations in parallel
-            ctx: Optional FastMCP Context for progress reporting
 
         Returns:
             Bulk operation results
@@ -568,17 +592,18 @@ class DeviceControlTools:
                 operations, skipped_operations
             )
 
-            if ctx is not None:
-                await ctx.info(
-                    f"bulk_device_control: {len(valid_operations)} valid op(s), "
-                    f"{len(skipped_operations)} skipped, "
-                    f"mode={'parallel' if parallel else 'sequential'}"
-                )
-                await ctx.report_progress(
-                    progress=0,
-                    total=len(valid_operations),
-                    message="dispatching operations",
-                )
+            await safe_info(
+                ctx,
+                f"bulk_device_control: {len(valid_operations)} valid op(s), "
+                f"{len(skipped_operations)} skipped, "
+                f"mode={'parallel' if parallel else 'sequential'}",
+            )
+            await safe_progress(
+                ctx,
+                progress=0,
+                total=len(valid_operations),
+                message="dispatching operations",
+            )
 
             # Execute only valid operations
             if parallel:
@@ -588,15 +613,15 @@ class DeviceControlTools:
                     valid_operations, results, operation_ids, ctx=ctx
                 )
 
-            if ctx is not None:
-                await ctx.report_progress(
-                    progress=len(valid_operations),
-                    total=len(valid_operations),
-                    message=(
-                        f"dispatched {len(operation_ids)} op(s); "
-                        "use get_bulk_operation_status to verify completion"
-                    ),
-                )
+            await safe_progress(
+                ctx,
+                progress=len(valid_operations),
+                total=len(valid_operations),
+                message=(
+                    f"dispatched {len(operation_ids)} op(s); "
+                    "use get_bulk_operation_status to verify completion"
+                ),
+            )
 
             return self._build_bulk_response(
                 operations, results, operation_ids, skipped_operations, parallel
@@ -682,12 +707,12 @@ class DeviceControlTools:
                     ErrorCode.SERVICE_CALL_FAILED,
                     f"Exception during execution: {e!s}",
                 ))
-            if ctx is not None:
-                await ctx.report_progress(
-                    progress=i + 1,
-                    total=total,
-                    message=f"{entity_id} {action} dispatched",
-                )
+            await safe_progress(
+                ctx,
+                progress=i + 1,
+                total=total,
+                message=f"{entity_id} {action} dispatched",
+            )
 
     def _build_bulk_response(
         self,

{ha_mcp_dev-7.4.1.dev454 → ha_mcp_dev-7.4.1.dev455}/src/ha_mcp/tools/helpers.py

@@ -12,6 +12,7 @@ import sys
 import time
 from typing import Any, Literal, NoReturn, overload
 
+from fastmcp import Context
 from fastmcp.exceptions import ToolError
 
 from ..client.rest_client import (
@@ -371,6 +372,49 @@ def log_tool_usage(func: Any) -> Any:
     return wrapper
 
 
+async def safe_progress(
+    ctx: Context | None,
+    *,
+    progress: float,
+    total: float | None = None,
+    message: str | None = None,
+) -> None:
+    """Report progress via ``ctx.report_progress`` with best-effort error handling.
+
+    A transport hiccup on a progress notification must never convert a
+    successful tool result into a ``ToolError``. Transport errors are logged
+    at debug; ``TypeError``/``AttributeError`` are escalated to ``warning``
+    because they signal a signature/interface mismatch (call-site bug or
+    Context object missing the expected method), not a flaky client.
+    ``ctx is None`` short-circuits without I/O.
+    """
+    if ctx is None:
+        return
+    try:
+        await ctx.report_progress(progress=progress, total=total, message=message)
+    except (TypeError, AttributeError) as e:
+        logger.warning(
+            "ctx.report_progress signature error (%s): %s", type(e).__name__, e
+        )
+    except Exception as e:
+        logger.debug("ctx.report_progress failed (%s): %s", type(e).__name__, e)
+
+
+async def safe_info(ctx: Context | None, message: str) -> None:
+    """Emit an info message via ``ctx.info`` with best-effort error handling.
+
+    Shares the rationale and exception-handling contract of ``safe_progress``.
+    """
+    if ctx is None:
+        return
+    try:
+        await ctx.info(message)
+    except (TypeError, AttributeError) as e:
+        logger.warning("ctx.info signature error (%s): %s", type(e).__name__, e)
+    except Exception as e:
+        logger.debug("ctx.info failed (%s): %s", type(e).__name__, e)
+
+
 def register_tool_methods(mcp: Any, instance: Any) -> None:
     """Register all @tool-decorated methods from a class instance with the MCP server.
 

{ha_mcp_dev-7.4.1.dev454 → ha_mcp_dev-7.4.1.dev455}/src/ha_mcp/tools/smart_search.py

@@ -10,6 +10,7 @@ import time
 from typing import Any
 
 from fastmcp import Context
+from fastmcp.exceptions import ToolError
 
 from ..client.rest_client import HomeAssistantClient
 from ..config import get_global_settings
@@ -20,7 +21,7 @@ from ..utils.fuzzy_search import (
     create_fuzzy_searcher,
     tokenize,
 )
-from .helpers import exception_to_structured_error
+from .helpers import exception_to_structured_error, safe_info, safe_progress
 
 logger = logging.getLogger(__name__)
 
@@ -838,25 +839,25 @@ class SmartSearchTools:
             query_lower = query.lower().strip()
 
             total_phases = len(search_types) + 1  # +1 for initial state fetch
-            if ctx is not None:
-                await ctx.info(
-                    f"deep_search starting: query={query!r} types={search_types}"
-                )
-                await ctx.report_progress(
-                    progress=0,
-                    total=total_phases,
-                    message="fetching entity states",
-                )
+            await safe_info(
+                ctx, f"deep_search starting: query={query!r} types={search_types}"
+            )
+            await safe_progress(
+                ctx,
+                progress=0,
+                total=total_phases,
+                message="fetching entity states",
+            )
 
             # Fetch all entities once at the beginning to avoid repeated calls
             all_entities = await self.client.get_states()
             phase_done = 1
-            if ctx is not None:
-                await ctx.report_progress(
-                    progress=phase_done,
-                    total=total_phases,
-                    message=f"fetched {len(all_entities)} entity states",
-                )
+            await safe_progress(
+                ctx,
+                progress=phase_done,
+                total=total_phases,
+                message=f"fetched {len(all_entities)} entity states",
+            )
 
             # Pre-resolve unique_ids from cached entity states to avoid redundant API calls
             automation_unique_id_map = {}
@@ -1031,12 +1032,12 @@ class SmartSearchTools:
                         )
 
                 phase_done += 1
-                if ctx is not None:
-                    await ctx.report_progress(
-                        progress=phase_done,
-                        total=total_phases,
-                        message=f"automations searched ({len(results['automations'])} matches)",
-                    )
+                await safe_progress(
+                    ctx,
+                    progress=phase_done,
+                    total=total_phases,
+                    message=f"automations searched ({len(results['automations'])} matches)",
+                )
 
             # ================================================================
             # SCRIPT SEARCH (same 3-tier strategy: REST bulk -> WS bulk -> individual)
@@ -1195,12 +1196,12 @@ class SmartSearchTools:
                         )
 
                 phase_done += 1
-                if ctx is not None:
-                    await ctx.report_progress(
-                        progress=phase_done,
-                        total=total_phases,
-                        message=f"scripts searched ({len(results['scripts'])} matches)",
-                    )
+                await safe_progress(
+                    ctx,
+                    progress=phase_done,
+                    total=total_phases,
+                    message=f"scripts searched ({len(results['scripts'])} matches)",
+                )
 
             # Search helpers with parallel WebSocket calls
             if "helper" in search_types:
@@ -1286,12 +1287,12 @@ class SmartSearchTools:
                         logger.debug(f"Helper list fetch failed: {result}")
 
                 phase_done += 1
-                if ctx is not None:
-                    await ctx.report_progress(
-                        progress=phase_done,
-                        total=total_phases,
-                        message=f"helpers searched ({len(results['helpers'])} matches)",
-                    )
+                await safe_progress(
+                    ctx,
+                    progress=phase_done,
+                    total=total_phases,
+                    message=f"helpers searched ({len(results['helpers'])} matches)",
+                )
 
             # ================================================================
             # DASHBOARD SEARCH
@@ -1386,12 +1387,12 @@ class SmartSearchTools:
                     raise
 
                 phase_done += 1
-                if ctx is not None:
-                    await ctx.report_progress(
-                        progress=phase_done,
-                        total=total_phases,
-                        message=f"dashboards searched ({len(results['dashboards'])} matches)",
-                    )
+                await safe_progress(
+                    ctx,
+                    progress=phase_done,
+                    total=total_phases,
+                    message=f"dashboards searched ({len(results['dashboards'])} matches)",
+                )
 
             # Merge all results with their category, sort by score, and paginate
             tagged_results: list[tuple[str, dict[str, Any]]] = []
@@ -1438,6 +1439,8 @@ class SmartSearchTools:
 
             return response
 
+        except ToolError:
+            raise
         except Exception as e:
             logger.error(f"Error in deep_search: {e}")
             exception_to_structured_error(

{ha_mcp_dev-7.4.1.dev454 → ha_mcp_dev-7.4.1.dev455}/src/ha_mcp/tools/tools_hacs.py

@@ -19,6 +19,8 @@ from .helpers import (
     log_tool_usage,
     raise_tool_error,
     register_tool_methods,
+    safe_info,
+    safe_progress,
 )
 from .util_helpers import add_timezone_metadata, coerce_bool_param, coerce_int_param
 
@@ -183,16 +185,17 @@ class HacsTools:
                 min_value=0,
             )
 
-            if ctx is not None:
-                await ctx.info(
-                    f"ha_hacs_search starting: query={query!r} "
-                    f"category={category} installed_only={installed_only_bool}"
-                )
-                await ctx.report_progress(
-                    progress=0,
-                    total=3,
-                    message="checking HACS availability",
-                )
+            await safe_info(
+                ctx,
+                f"ha_hacs_search starting: query={query!r} "
+                f"category={category} installed_only={installed_only_bool}",
+            )
+            await safe_progress(
+                ctx,
+                progress=0,
+                total=3,
+                message="checking HACS availability",
+            )
 
             # Check if HACS is available
             await _assert_hacs_available()
@@ -208,12 +211,12 @@ class HacsTools:
                 hacs_category = CATEGORY_MAP.get(category, category)
                 kwargs_cmd["categories"] = [hacs_category]
 
-            if ctx is not None:
-                await ctx.report_progress(
-                    progress=1,
-                    total=3,
-                    message="fetching HACS repository list",
-                )
+            await safe_progress(
+                ctx,
+                progress=1,
+                total=3,
+                message="fetching HACS repository list",
+            )
 
             response = await ws_client.send_command(
                 "hacs/repositories/list", **kwargs_cmd
@@ -231,21 +234,21 @@ class HacsTools:
                 )
 
             all_repositories = response.get("result", [])
-            if ctx is not None:
-                await ctx.report_progress(
-                    progress=2,
-                    total=3,
-                    message=f"filtering {len(all_repositories)} repositories",
-                )
+            await safe_progress(
+                ctx,
+                progress=2,
+                total=3,
+                message=f"filtering {len(all_repositories)} repositories",
+            )
             matches = _filter_and_score_repos(
                 all_repositories, query, installed_only_bool
             )
-            if ctx is not None:
-                await ctx.report_progress(
-                    progress=3,
-                    total=3,
-                    message=f"matched {len(matches)} repositories",
-                )
+            await safe_progress(
+                ctx,
+                progress=3,
+                total=3,
+                message=f"matched {len(matches)} repositories",
+            )
 
             limited_matches = matches[offset_int : offset_int + max_results_int]
             has_more = (offset_int + len(limited_matches)) < len(matches)

{ha_mcp_dev-7.4.1.dev454 → ha_mcp_dev-7.4.1.dev455}/src/ha_mcp/tools/tools_history.py

@@ -26,6 +26,8 @@ from .helpers import (
     log_tool_usage,
     raise_tool_error,
     register_tool_methods,
+    safe_info,
+    safe_progress,
 )
 from .util_helpers import (
     add_timezone_metadata,
@@ -290,17 +292,18 @@ class HistoryTools:
             # Parse time parameters
             start_dt, end_dt = _parse_time_range(start_time, end_time, default_hours)
 
-            if ctx is not None:
-                await ctx.info(
-                    f"ha_get_history starting: source={source} "
-                    f"entities={len(entity_id_list)} "
-                    f"window={start_dt.isoformat()}..{end_dt.isoformat()}"
-                )
-                await ctx.report_progress(
-                    progress=0,
-                    total=3,
-                    message="connecting to Home Assistant WebSocket",
-                )
+            await safe_info(
+                ctx,
+                f"ha_get_history starting: source={source} "
+                f"entities={len(entity_id_list)} "
+                f"window={start_dt.isoformat()}..{end_dt.isoformat()}",
+            )
+            await safe_progress(
+                ctx,
+                progress=0,
+                total=3,
+                message="connecting to Home Assistant WebSocket",
+            )
 
             # Connect to WebSocket (shared by both sources)
             ws_client, error = await get_connected_ws_client(
@@ -314,12 +317,12 @@ class HistoryTools:
                     "Failed to connect to Home Assistant WebSocket",
                 ))
 
-            if ctx is not None:
-                await ctx.report_progress(
-                    progress=1,
-                    total=3,
-                    message=f"querying recorder ({source})",
-                )
+            await safe_progress(
+                ctx,
+                progress=1,
+                total=3,
+                message=f"querying recorder ({source})",
+            )
 
             try:
                 if source == "statistics":
@@ -335,12 +338,12 @@ class HistoryTools:
                         significant_changes_only, limit, offset,
                         _DEFAULT_HISTORY_LIMIT, _MAX_HISTORY_LIMIT,
                     )
-                if ctx is not None:
-                    await ctx.report_progress(
-                        progress=3,
-                        total=3,
-                        message="recorder query complete",
-                    )
+                await safe_progress(
+                    ctx,
+                    progress=3,
+                    total=3,
+                    message="recorder query complete",
+                )
                 return result
             finally:
                 if ws_client:

{ha_mcp_dev-7.4.1.dev454 → ha_mcp_dev-7.4.1.dev455}/src/ha_mcp/tools/tools_traces.py

@@ -22,6 +22,8 @@ from .helpers import (
     log_tool_usage,
     raise_tool_error,
     register_tool_methods,
+    safe_info,
+    safe_progress,
 )
 
 logger = logging.getLogger(__name__)
@@ -167,16 +169,17 @@ class TraceTools:
             # Extract the object_id (part after the domain) as fallback
             object_id = automation_id.split(".", 1)[1]
 
-            if ctx is not None:
-                await ctx.info(
-                    f"ha_get_automation_traces starting: id={automation_id} "
-                    f"run_id={run_id or '<list>'}"
-                )
-                await ctx.report_progress(
-                    progress=0,
-                    total=3,
-                    message="connecting to Home Assistant WebSocket",
-                )
+            await safe_info(
+                ctx,
+                f"ha_get_automation_traces starting: id={automation_id} "
+                f"run_id={run_id or '<list>'}",
+            )
+            await safe_progress(
+                ctx,
+                progress=0,
+                total=3,
+                message="connecting to Home Assistant WebSocket",
+            )
 
             # Connect to WebSocket
             ws_client, error = await get_connected_ws_client(
@@ -198,12 +201,12 @@ class TraceTools:
                     ws_client, automation_id, object_id
                 )
 
-                if ctx is not None:
-                    await ctx.report_progress(
-                        progress=1,
-                        total=3,
-                        message=f"fetching trace {'detail' if run_id else 'list'}",
-                    )
+                await safe_progress(
+                    ctx,
+                    progress=1,
+                    total=3,
+                    message=f"fetching trace {'detail' if run_id else 'list'}",
+                )
 
                 if run_id:
                     # Get specific trace details
@@ -225,10 +228,9 @@ class TraceTools:
                         ))
 
                     trace_data = result.get("result", {})
-                    if ctx is not None:
-                        await ctx.report_progress(
-                            progress=3, total=3, message="formatting trace"
-                        )
+                    await safe_progress(
+                        ctx, progress=3, total=3, message="formatting trace"
+                    )
                     return _format_detailed_trace(
                         automation_id, run_id, trace_data,
                         deduplicate=deduplicate, detailed=detailed,
@@ -253,29 +255,28 @@ class TraceTools:
 
                     # If traces are empty, gather diagnostic information
                     if not traces_data:
-                        if ctx is not None:
-                            await ctx.report_progress(
-                                progress=2,
-                                total=3,
-                                message="no traces; gathering diagnostics",
-                            )
+                        await safe_progress(
+                            ctx,
+                            progress=2,
+                            total=3,
+                            message="no traces; gathering diagnostics",
+                        )
                         diagnostics = await _gather_diagnostics(
                             ws_client, self._client, automation_id, domain
                         )
-                        if ctx is not None:
-                            await ctx.report_progress(
-                                progress=3, total=3, message="diagnostics complete"
-                            )
+                        await safe_progress(
+                            ctx, progress=3, total=3, message="diagnostics complete"
+                        )
                         return _format_trace_list(
                             automation_id, traces_data, limit, diagnostics
                         )
 
-                    if ctx is not None:
-                        await ctx.report_progress(
-                            progress=3,
-                            total=3,
-                            message=f"listed {len(traces_data)} traces",
-                        )
+                    await safe_progress(
+                        ctx,
+                        progress=3,
+                        total=3,
+                        message=f"listed {len(traces_data)} traces",
+                    )
                     return _format_trace_list(automation_id, traces_data, limit)
 
             finally:

{ha_mcp_dev-7.4.1.dev454 → ha_mcp_dev-7.4.1.dev455/src/ha_mcp_dev.egg-info}/PKG-INFO

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