ha-mcp-dev 7.7.0.dev697__tar.gz → 7.7.0.dev699__tar.gz

{ha_mcp_dev-7.7.0.dev697/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.7.0.dev699}/PKG-INFO

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

{ha_mcp_dev-7.7.0.dev697 → ha_mcp_dev-7.7.0.dev699}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.7.0.dev697"
+version = "7.7.0.dev699"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

{ha_mcp_dev-7.7.0.dev697 → ha_mcp_dev-7.7.0.dev699}/src/ha_mcp/__main__.py

@@ -290,17 +290,28 @@ def _setup_standard_mode() -> None:
     _log_startup_version()
 
 
-def _http_run_kwargs(transport: str, host: str, port: int, path: str) -> dict:
-    """Build common run_async kwargs for HTTP-based transports."""
-    return {
+def _http_run_kwargs(transport: str, host: str, port: int, path: str) -> dict[str, Any]:
+    """Build common run_async kwargs for HTTP-based transports.
+
+    ``stateless_http`` is a Streamable-HTTP concept and is only valid for the
+    ``http``/``streamable-http`` transports. Passing it alongside
+    ``transport="sse"`` makes fastmcp's ``run_async`` raise
+    ``ValueError("SSE transport does not support stateless mode")``. Gating it to
+    non-SSE transports keeps SSE startup working. (Before this fix that raise was
+    also swallowed into a silent exit 0; ``_run_with_shutdown`` now surfaces a
+    self-terminating server task's exception instead.) See #1544.
+    """
+    kwargs: dict[str, Any] = {
         "transport": transport,
         "host": host,
         "port": port,
         "path": path,
         "show_banner": _get_show_banner(),
-        "stateless_http": True,
         "uvicorn_config": {"log_config": _get_timestamped_uvicorn_log_config()},
     }
+    if transport != "sse":
+        kwargs["stateless_http"] = True
+    return kwargs
 
 
 def _create_server() -> "HomeAssistantSmartMCPServer":
@@ -402,6 +413,46 @@ class ToolValidationLogFilter(logging.Filter):
         return True
 
 
+class ProbeAccessLogFilter(logging.Filter):
+    """Drop benign, non-MCP HTTP probe noise from the uvicorn access log.
+
+    * ``GET``/``HEAD`` ``/favicon.ico`` -> ``404``: browsers auto-request a
+      favicon that doesn't exist. Pure noise, always dropped.
+    * ``GET``/``HEAD`` on the MCP path -> ``405``: a non-MCP caller (browser,
+      health check, reverse proxy, or a connector's SSE-style pre-flight) hit a
+      POST-only Streamable HTTP endpoint. The raw access line is dropped and the
+      landing handler logs one annotated "(NORMAL for most non-SSE connections)"
+      line in its place. Dropped only when ``drop_mcp_405`` is set — SSE callers
+      pass False, since there a GET answers 200 and a GET-405 is a genuine fault.
+    """
+
+    def __init__(self, mcp_path: str, *, drop_mcp_405: bool = True) -> None:
+        super().__init__()
+        self._mcp_path = mcp_path.rstrip("/") or "/"
+        self._drop_mcp_405 = drop_mcp_405
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        # uvicorn.access records carry structured args: (client, method, path,
+        # http_version, status_int). Match on those, not the formatted string.
+        args = record.args
+        if not isinstance(args, tuple) or len(args) != 5:
+            return True
+        method, raw_path, status = args[1], args[2], args[4]
+        if method not in ("GET", "HEAD"):
+            return True
+        path = str(raw_path).split("?", 1)[0].rstrip("/") or "/"
+        if status == 404 and path == "/favicon.ico":
+            return False  # browser favicon auto-request — pure noise
+        # By-design probe 405 on the MCP path; the handler logs an annotated line
+        # instead. This trusts that the landing route is the only GET/HEAD responder
+        # on the MCP path (true today). Kept in SSE mode (drop_mcp_405=False), where
+        # a GET answers 200 and a 405 is a real fault.
+        is_dropped_probe = (
+            status == 405 and path == self._mcp_path and self._drop_mcp_405
+        )
+        return not is_dropped_probe
+
+
 def _setup_logging(log_level_str: str, force: bool = False) -> None:
     """Configure root logger with consistent timestamp format."""
     logging.basicConfig(
@@ -532,9 +583,23 @@ async def _run_with_shutdown(server_coro: Coroutine[Any, Any, Any]) -> None:
                 # Expected: we just cancelled server_task above; swallow its
                 # CancelledError so shutdown can proceed to cleanup.
                 pass
+        elif server_task in done:
+            # Server task finished on its own (no shutdown signal). Re-raise any
+            # exception it captured so a hard startup failure surfaces as a
+            # logged sys.exit(1) instead of a silent exit 0 — without this the
+            # exception on the already-done task is never retrieved. See #1544.
+            server_task.result()
 
     except asyncio.CancelledError:
-        logger.info("Server task cancelled")
+        # A shutdown-initiated cancel is a graceful stop. A cancel without a
+        # shutdown signal — including one re-raised by server_task.result()
+        # above — is a hard stop masquerading as success; re-raise it so it
+        # becomes a logged sys.exit(1) rather than a silent exit 0. See #1544.
+        if _shutdown_event is not None and _shutdown_event.is_set():
+            logger.info("Server task cancelled")
+        else:
+            logger.error("Server task cancelled without a shutdown signal")
+            raise
     finally:
         try:
             await asyncio.wait_for(
@@ -543,7 +608,12 @@ async def _run_with_shutdown(server_coro: Coroutine[Any, Any, Any]) -> None:
         except TimeoutError:
             logger.warning("Resource cleanup timed out")
 
-        await _cancel_tasks(server_task, shutdown_task)
+        try:
+            await _cancel_tasks(server_task, shutdown_task)
+        except Exception as e:
+            # Teardown must never mask the exception being propagated from the
+            # try block (Python drops the original if finally raises).
+            logger.warning(f"Task cancellation during shutdown failed: {e}")
 
 
 def _run_entrypoint(coro: Coroutine[Any, Any, Any], label: str) -> None:
@@ -557,7 +627,7 @@ def _run_entrypoint(coro: Coroutine[Any, Any, Any], label: str) -> None:
     except SystemExit:
         raise
     except Exception as e:
-        logger.error(f"{label} error: {e}")
+        logger.error(f"{label} error: {e}", exc_info=True)
         sys.exit(1)
 
     sys.exit(0)
@@ -858,7 +928,12 @@ async def _run_http_with_graceful_shutdown(
 _registered_landing_paths: set[str] = set()
 
 
-def register_browser_landing(mcp_instance: "FastMCP | _DeferredMCP", path: str) -> None:
+def register_browser_landing(
+    mcp_instance: "FastMCP | _DeferredMCP",
+    path: str,
+    *,
+    quiet_probe_log: bool = True,
+) -> None:
     """Register a GET handler that returns 405 with a helpful message.
 
     Browsers and misconfigured clients that send GET instead of POST will see
@@ -869,6 +944,10 @@ def register_browser_landing(mcp_instance: "FastMCP | _DeferredMCP", path: str)
     Args:
         mcp_instance: The FastMCP server to register the route on.
         path: The MCP endpoint path (e.g. "/mcp" or a secret path).
+        quiet_probe_log: When True (default, for Streamable HTTP), drop the
+            by-design GET/HEAD-405 probe line on the MCP path from the uvicorn
+            access log (the handler logs an annotated replacement). Pass False
+            for SSE, where a GET answers 200 and a 405 is a genuine fault.
     """
     if path in _registered_landing_paths:
         logger.warning(
@@ -905,6 +984,12 @@ def register_browser_landing(mcp_instance: "FastMCP | _DeferredMCP", path: str)
     # Custom routes are registered at lowest precedence (after the MCP route).
     @mcp_instance.custom_route(path, methods=["GET"])
     async def _browser_landing(_: Request) -> PlainTextResponse:
+        # Any GET here is a non-MCP caller (browser, health check, proxy, or a
+        # connector's SSE-style pre-flight) hitting this POST-only Streamable HTTP
+        # endpoint, which answers 405 by design. Log one annotated line so the 405
+        # reads as expected; ProbeAccessLogFilter drops the raw uvicorn access line
+        # so there's no cryptic duplicate.
+        logger.info("GET %s -> 405 (NORMAL for most non-SSE connections)", path)
         return PlainTextResponse(
             _landing_message,
             status_code=405,
@@ -913,6 +998,16 @@ def register_browser_landing(mcp_instance: "FastMCP | _DeferredMCP", path: str)
             headers={"Allow": "POST, DELETE"},
         )
 
+    # Tidy uvicorn's access log: always drop browser favicon 404s, and drop the
+    # raw by-design GET/HEAD-405 probe line on the MCP path (the handler above logs
+    # an annotated replacement). The 405 drop is skipped for SSE
+    # (quiet_probe_log=False), where a GET answers 200 and a 405 is a real fault.
+    # Attach to uvicorn.access directly — it has propagate=False, so a root-logger
+    # filter would miss it.
+    logging.getLogger("uvicorn.access").addFilter(
+        ProbeAccessLogFilter(path, drop_mcp_405=quiet_probe_log)
+    )
+
 
 def _log_settings_url(host: str, port: int, path: str) -> None:
     """Log the web settings-UI URL at HTTP startup.
@@ -946,7 +1041,9 @@ def _run_http_server(transport: str, default_port: int = 8086) -> None:
 
     host, port, path = _get_http_runtime(default_port)
     _warn_if_default_path_exposed(host, port, path)
-    register_browser_landing(_get_mcp(), path)
+    # SSE transport answers GET with 200 (the event stream), so a GET->405 there
+    # would be a real fault, not a benign probe — keep its access log intact.
+    register_browser_landing(_get_mcp(), path, quiet_probe_log=transport != "sse")
     register_settings_routes(_get_mcp(), _get_server(), secret_path=path)
     _log_settings_url(host, port, path)
 

{ha_mcp_dev-7.7.0.dev697 → ha_mcp_dev-7.7.0.dev699}/src/ha_mcp/client/rest_client.py

@@ -33,6 +33,12 @@ def _is_ssl_error(exc: BaseException) -> bool:
 
 logger = logging.getLogger(__name__)
 
+# Transient gateway statuses from a reverse proxy / Supervisor ingress — HA Core
+# restarting or briefly overloaded behind it. The upstream couldn't be reached,
+# so the request did not execute and retrying is safe even for writes.
+_RETRYABLE_STATUS = frozenset({502, 503, 504})
+_MAX_REQUEST_ATTEMPTS = 3
+
 
 class HomeAssistantError(Exception):
     """Base exception for Home Assistant API errors."""
@@ -180,7 +186,8 @@ class HomeAssistantClient:
 
         Handles auth, HTTP 4xx/5xx, and transport errors in one place.
         Callers parse the body themselves (JSON via `_request`, text via
-        `get_addon_logs`, etc.).
+        `get_addon_logs`, etc.). Transient gateway errors (502/503/504) are
+        retried with bounded exponential backoff before surfacing.
 
         Raises:
             HomeAssistantAuthError: 401 response.
@@ -188,44 +195,62 @@ class HomeAssistantClient:
                 response_data set from JSON body when possible).
             HomeAssistantConnectionError: Network, timeout, or transport error.
         """
-        try:
-            response = await self.httpx_client.request(method, endpoint, **kwargs)
+        backoff = 0.5
+        for attempt in range(1, _MAX_REQUEST_ATTEMPTS + 1):
+            try:
+                response = await self.httpx_client.request(method, endpoint, **kwargs)
 
-            if response.status_code == 401:
-                raise HomeAssistantAuthError("Invalid authentication token")
+                if response.status_code == 401:
+                    raise HomeAssistantAuthError("Invalid authentication token")
 
-            if response.status_code >= 400:
-                try:
-                    error_data = response.json()
-                except Exception:
-                    error_data = {"message": response.text}
+                if response.status_code >= 400:
+                    try:
+                        error_data = response.json()
+                    except Exception:
+                        error_data = {"message": response.text}
 
-                message = error_data.get("message")
-                if not message or not message.strip():
-                    message = response.reason_phrase or "<empty body>"
+                    message = error_data.get("message")
+                    if not message or not message.strip():
+                        message = response.reason_phrase or "<empty body>"
 
-                raise HomeAssistantAPIError(
-                    f"API error: {response.status_code} - {message}",
-                    status_code=response.status_code,
-                    response_data=error_data,
-                )
+                    if (
+                        response.status_code in _RETRYABLE_STATUS
+                        and attempt < _MAX_REQUEST_ATTEMPTS
+                    ):
+                        logger.warning(
+                            f"Transient {response.status_code} from Home Assistant "
+                            f"(attempt {attempt}/{_MAX_REQUEST_ATTEMPTS}), retrying "
+                            f"in {backoff}s: {message}"
+                        )
+                        await asyncio.sleep(backoff)
+                        backoff *= 2
+                        continue
 
-            return response
+                    raise HomeAssistantAPIError(
+                        f"API error: {response.status_code} - {message}",
+                        status_code=response.status_code,
+                        response_data=error_data,
+                    )
 
-        except httpx.ConnectError as e:
-            if _is_ssl_error(e) and self.verify_ssl:
+                return response
+
+            except httpx.ConnectError as e:
+                if _is_ssl_error(e) and self.verify_ssl:
+                    raise HomeAssistantConnectionError(
+                        f"TLS verification failed for {self.base_url}: {e}. "
+                        "If this is a self-signed certificate or hostname "
+                        "mismatch, set HA_VERIFY_SSL=false to skip verification."
+                    ) from e
                 raise HomeAssistantConnectionError(
-                    f"TLS verification failed for {self.base_url}: {e}. "
-                    "If this is a self-signed certificate or hostname "
-                    "mismatch, set HA_VERIFY_SSL=false to skip verification."
+                    f"Failed to connect to Home Assistant: {e}"
                 ) from e
-            raise HomeAssistantConnectionError(
-                f"Failed to connect to Home Assistant: {e}"
-            ) from e
-        except httpx.TimeoutException as e:
-            raise HomeAssistantConnectionError(f"Request timeout: {e}") from e
-        except httpx.HTTPError as e:
-            raise HomeAssistantConnectionError(f"HTTP error: {e}") from e
+            except httpx.TimeoutException as e:
+                raise HomeAssistantConnectionError(f"Request timeout: {e}") from e
+            except httpx.HTTPError as e:
+                raise HomeAssistantConnectionError(f"HTTP error: {e}") from e
+
+        # Unreachable: the final attempt takes the non-retry branch and raises.
+        raise AssertionError("_raw_request retry loop exhausted without returning")
 
     async def _request(
         self, method: str, endpoint: str, **kwargs: Any

{ha_mcp_dev-7.7.0.dev697 → ha_mcp_dev-7.7.0.dev699}/src/ha_mcp/tools/tools_hacs.py

@@ -674,12 +674,14 @@ def _filter_and_score_repos(
 HACS_REPOSITORY_SIGNAL = "hacs_dispatch_repository"
 
 # Wall-clock budget for ``wait_for_repo_registration``. Generous
-# because the constraint is "HACS finishes registration"; the prior
-# 10 s budget (10 attempts × 1.0 s) was exhausted on the HAOS E2E
-# channel under load, so a 3× headroom backstop avoids re-tripping
-# the same flake. The subscription nudges us, so this is a wall-
-# clock cap rather than the dominant cost.
-HACS_REPO_REGISTRATION_TIMEOUT = 30.0
+# because the constraint is "HACS finishes registration": adding a
+# fresh repo makes HACS clone/index it over the network, which on a
+# slow link (or a loaded HAOS E2E runner) can exceed 30 s — the prior
+# value, which flaked ``test_install_mcp_tools_*`` with "Could not
+# find repository ID after adding". The subscription nudges us the
+# instant registration lands, so the happy path returns in seconds and
+# this larger cap only ever costs wall-clock on a genuinely slow add.
+HACS_REPO_REGISTRATION_TIMEOUT = 60.0
 
 # Budget for the initial ``hacs/subscribe`` ack. Smaller than the
 # overall registration timeout so a slow subscribe doesn't consume

{ha_mcp_dev-7.7.0.dev697 → ha_mcp_dev-7.7.0.dev699/src/ha_mcp_dev.egg-info}/PKG-INFO

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