ha-mcp-dev 8.5.0.dev2770__tar.gz → 8.5.0.dev2772__tar.gz

{ha_mcp_dev-8.5.0.dev2770/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.5.0.dev2772}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.5.0.dev2770
+Version: 8.5.0.dev2772
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -143,7 +143,7 @@ Prefer to run ha-mcp as a Home Assistant **app (add-on)**? On **Home Assistant O
 
 These run the server outside Home Assistant — useful for **Container** / **Core** installs (which can't run apps) or a separate host. The [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/) generates the exact client-specific config for each.
 
-- **Docker (HTTP server):** run `ghcr.io/homeassistant-ai/ha-mcp` in HTTP mode, pointed at your Home Assistant URL and a long-lived token, and connect your client to its secret URL. See the [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/) for the full command and per-client config.
+- **Docker (HTTP server):** run `ghcr.io/homeassistant-ai/ha-mcp` in HTTP mode, pointed at your Home Assistant URL and a long-lived token (an administrator's is recommended; non-admin tokens work with limitations), and connect your client to its secret URL. See the [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/) for the full command and per-client config.
 - **PyPI / uvx (HTTP server):** run the published `ha-mcp` package with `uvx ha-mcp@latest` (or pip) as a streamable-HTTP server the same way. Details in the [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/).
 - **Local stdio (not recommended):** runs ha-mcp on your own machine over stdio. The one-command installers in the **Demo server** section below use this path; the [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/) covers connecting it to your own Home Assistant.
 - **OIDC authentication:** gate remote access behind an external identity provider (Authentik, Keycloak, Auth0, etc.) instead of a secret URL — all authenticated users share the server's Home Assistant credentials. See [OIDC Mode](docs/oidc.md).

{ha_mcp_dev-8.5.0.dev2770 → ha_mcp_dev-8.5.0.dev2772}/README.md

@@ -82,7 +82,7 @@ Prefer to run ha-mcp as a Home Assistant **app (add-on)**? On **Home Assistant O
 
 These run the server outside Home Assistant — useful for **Container** / **Core** installs (which can't run apps) or a separate host. The [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/) generates the exact client-specific config for each.
 
-- **Docker (HTTP server):** run `ghcr.io/homeassistant-ai/ha-mcp` in HTTP mode, pointed at your Home Assistant URL and a long-lived token, and connect your client to its secret URL. See the [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/) for the full command and per-client config.
+- **Docker (HTTP server):** run `ghcr.io/homeassistant-ai/ha-mcp` in HTTP mode, pointed at your Home Assistant URL and a long-lived token (an administrator's is recommended; non-admin tokens work with limitations), and connect your client to its secret URL. See the [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/) for the full command and per-client config.
 - **PyPI / uvx (HTTP server):** run the published `ha-mcp` package with `uvx ha-mcp@latest` (or pip) as a streamable-HTTP server the same way. Details in the [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/).
 - **Local stdio (not recommended):** runs ha-mcp on your own machine over stdio. The one-command installers in the **Demo server** section below use this path; the [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/) covers connecting it to your own Home Assistant.
 - **OIDC authentication:** gate remote access behind an external identity provider (Authentik, Keycloak, Auth0, etc.) instead of a secret URL — all authenticated users share the server's Home Assistant credentials. See [OIDC Mode](docs/oidc.md).

{ha_mcp_dev-8.5.0.dev2770 → ha_mcp_dev-8.5.0.dev2772}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.5.0.dev2770"
+version = "8.5.0.dev2772"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

{ha_mcp_dev-8.5.0.dev2770 → ha_mcp_dev-8.5.0.dev2772}/src/ha_mcp/__main__.py

@@ -182,7 +182,7 @@ To fix this, you need to provide your Home Assistant connection details:
   1. HOMEASSISTANT_URL - Your Home Assistant instance URL
      Example: http://homeassistant.local:8123
 
-  2. HOMEASSISTANT_TOKEN - A long-lived access token
+  2. HOMEASSISTANT_TOKEN - A long-lived access token (an administrator's is recommended)
      Get one from: Home Assistant -> Profile -> Long-Lived Access Tokens
 
 Configuration options:

{ha_mcp_dev-8.5.0.dev2770 → ha_mcp_dev-8.5.0.dev2772}/src/ha_mcp/auth/consent_form.py

@@ -316,7 +316,8 @@ def create_consent_html(
                     autocomplete="off"
                 >
                 <p class="help-text">
-                    Create a token at: Home Assistant &rarr; Profile &rarr;
+                    Create a token (an administrator's is recommended; non-admin
+                    tokens work with limitations) at: Home Assistant &rarr; Profile &rarr;
                     <a href="https://www.home-assistant.io/docs/authentication/#your-account-profile" target="_blank" rel="noopener">
                         Long-Lived Access Tokens
                     </a>

ha_mcp_dev-8.5.0.dev2772/src/ha_mcp/client/admin_routes.py

@@ -0,0 +1,43 @@
+"""REST routes Home Assistant refuses to non-admin users with a counted 401.
+
+Each answers a non-admin with a raised 401, which ``http.ban`` counts as a
+failed login, so a burst of them IP-bans the ha-mcp host (#2546). Verified
+against home-assistant/core ``api/__init__.py``,
+``config/{view,core,config_entries}.py`` and ``diagnostics/__init__.py``.
+Not listed: routes that check entity permissions instead (e.g.
+``GET /api/states/<id>``), the hassio proxy (its 401 is returned, not raised,
+so it is not counted), and admin-only services, which ``call_service`` sends
+over WebSocket for a non-admin token.
+"""
+
+import re
+
+_ANY_METHOD = frozenset({"GET", "POST", "PUT", "PATCH", "DELETE"})
+
+_ADMIN_ONLY_ROUTES: tuple[tuple[frozenset[str], re.Pattern[str]], ...] = tuple(
+    (frozenset(methods), re.compile(pattern))
+    for methods, pattern in (
+        ({"POST", "DELETE"}, r"states/[^/]+"),
+        ({"POST"}, r"events/[^/]+"),
+        ({"GET"}, r"stream"),
+        ({"POST"}, r"template"),
+        ({"GET"}, r"error_log"),
+        (_ANY_METHOD, r"config/(automation|script|scene)/config/[^/]+"),
+        ({"POST"}, r"config/core/check_config"),
+        ({"GET"}, r"diagnostics/[^/]+/[^/]+(/[^/]+/[^/]+)?"),
+        ({"DELETE"}, r"config/config_entries/entry/[^/]+"),
+        ({"POST"}, r"config/config_entries/entry/[^/]+/reload"),
+        ({"POST"}, r"config/config_entries/(options/|subentries/)?flow"),
+        ({"GET", "POST"}, r"config/config_entries/(options/|subentries/)?flow/[^/]+"),
+    )
+)
+
+
+def is_admin_only_route(method: str, endpoint: str) -> bool:
+    """True when ``endpoint`` (relative to ``/api``) is admin-only for ``method``."""
+    path = endpoint.split("?", 1)[0].strip("/")
+    method = method.upper()
+    return any(
+        method in methods and pattern.fullmatch(path)
+        for methods, pattern in _ADMIN_ONLY_ROUTES
+    )

{ha_mcp_dev-8.5.0.dev2770 → ha_mcp_dev-8.5.0.dev2772}/src/ha_mcp/client/rest_client.py

@@ -17,6 +17,7 @@ import httpx
 from .._vendor.websockets.exceptions import WebSocketException
 from .._version import get_supervisor_base_url, is_running_in_addon
 from ..config import get_global_settings
+from .admin_routes import is_admin_only_route
 from .supervisor_client import make_supervisor_httpx_client
 
 
@@ -70,6 +71,15 @@ MIN_LOG_WINDOW_LINES = 2
 # journald's cursor/timestamp metadata exists only in the journal export
 # format, which the hassio-proxy route cannot request.
 _PROBE_ENTRIES = 8
+NON_ADMIN_TOKEN_WARNING = (
+    "ha-mcp does not officially support non-admin Home Assistant tokens. They "
+    "still work, but admin-only operations fail. Use a long-lived access token "
+    "from an administrator's profile for full access."
+)
+_ADMIN_ONLY_401_MESSAGE = (
+    "Home Assistant returned 401 for an admin-only endpoint: "
+    "the token is invalid or its user is not an administrator"
+)
 
 
 class HomeAssistantError(Exception):
@@ -114,6 +124,15 @@ class HomeAssistantAuthError(HomeAssistantError):
     """
 
 
+class HomeAssistantAdminRequiredError(HomeAssistantAuthError):
+    """An admin-only request refused because the token's user is not an admin.
+
+    A REST request is refused locally, never sent: Home Assistant would answer
+    401 and count it toward its IP ban (#2546). A service call is refused by
+    Home Assistant over WebSocket, where a refusal is not counted.
+    """
+
+
 class HomeAssistantAPIError(HomeAssistantError):
     """API error from Home Assistant."""
 
@@ -334,6 +353,8 @@ class HomeAssistantClient:
         token: str | None = None,
         timeout: int | None = None,
         verify_ssl: bool | None = None,
+        is_admin: bool | None = None,
+        admin_route_refused: bool = False,
     ):
         """
         Initialize Home Assistant client.
@@ -345,6 +366,10 @@ class HomeAssistantClient:
             verify_ssl: Whether to verify the HA server's TLS certificate
                 (defaults to ``settings.verify_ssl``). Pass False to allow
                 self-signed certs or hostname mismatches.
+            is_admin: Whether the token's user is an administrator, when
+                another client for the same token already knows.
+            admin_route_refused: Whether another client for the same token
+                already got a 401 on an admin-only request.
         """
         if base_url is None or token is None or verify_ssl is None:
             settings = get_global_settings()
@@ -386,6 +411,14 @@ class HomeAssistantClient:
         # disable the supervised branch — subsequent calls re-probe.
         self._supervised_detected: bool | None = None
 
+        # Whether the token's user is an admin; ``None`` until Home Assistant
+        # has answered. See ``token_is_admin`` and ``guarded_request``.
+        self._is_admin: bool | None = is_admin
+        # Set by a 401 on an admin-only route or service call, so no further
+        # admin-only request is sent over REST. See ``guarded_request``.
+        self._admin_route_refused = admin_route_refused
+        self._admin_route_lock = asyncio.Lock()
+
         logger.info(f"Initialized Home Assistant client for {self.base_url}")
 
     async def __aenter__(self) -> "HomeAssistantClient":
@@ -432,6 +465,8 @@ class HomeAssistantClient:
         is never replayed.
 
         Raises:
+            HomeAssistantAdminRequiredError: Admin-only route refused without
+                being sent (see ``guarded_request``).
             HomeAssistantAuthError: 401 response.
             HomeAssistantAPIError: Non-2xx response (with status_code and
                 response_data set from JSON body when possible).
@@ -440,10 +475,14 @@ class HomeAssistantClient:
         backoff = 0.5
         for attempt in range(1, _MAX_REQUEST_ATTEMPTS + 1):
             try:
-                response = await self.httpx_client.request(method, endpoint, **kwargs)
+                response = await self.guarded_request(method, endpoint, **kwargs)
 
                 if response.status_code == 401:
-                    raise HomeAssistantAuthError("Invalid authentication token")
+                    raise HomeAssistantAuthError(
+                        _ADMIN_ONLY_401_MESSAGE
+                        if is_admin_only_route(method, endpoint)
+                        else "Invalid authentication token"
+                    )
 
                 if response.status_code >= 400:
                     message, error_data = self._error_message_from_response(response)
@@ -488,6 +527,104 @@ class HomeAssistantClient:
         # Unreachable: the final attempt takes the non-retry branch and raises.
         raise AssertionError("_raw_request retry loop exhausted without returning")
 
+    async def guarded_request(
+        self, method: str, endpoint: str, **kwargs: Any
+    ) -> httpx.Response:
+        """Send a request, unless it is an admin-only route this token can't use.
+
+        Raises ``HomeAssistantAdminRequiredError`` without sending when the
+        token is known to be a non-admin's, or after an admin-only request got
+        401. While Home Assistant has not answered whether the token is an
+        admin's, admin-only requests go out one at a time and the first
+        response settles it: a 401 stops further ones, and a 2xx proves the
+        token is an admin's (a 404 or 405 can come before the admin gate).
+        """
+        if not is_admin_only_route(method, endpoint):
+            return await self.httpx_client.request(method, endpoint, **kwargs)
+        if self._is_admin is True:
+            response = await self.httpx_client.request(method, endpoint, **kwargs)
+            self._note_admin_route_response(response)
+            return response
+        async with self._admin_route_lock:
+            route = f"{method.upper()} /api/{endpoint.lstrip('/')}"
+            if self._admin_route_refused:
+                raise HomeAssistantAdminRequiredError(
+                    f"{route} not sent: an earlier admin-only request got 401 "
+                    "(the token is invalid or its user is not an administrator)"
+                )
+            is_admin = await self.token_is_admin()
+            if is_admin is False:
+                raise HomeAssistantAdminRequiredError(
+                    f"{route} is admin-only in Home Assistant and this token's "
+                    "user is not an administrator"
+                )
+            response = await self.httpx_client.request(method, endpoint, **kwargs)
+            if is_admin is None and 200 <= response.status_code < 300:
+                self._is_admin = True
+            self._note_admin_route_response(response)
+            return response
+
+    def _note_admin_route_response(self, response: httpx.Response) -> None:
+        if response.status_code == 401:
+            self._is_admin = None
+            self._admin_route_refused = True
+
+    @property
+    def admin_route_refused(self) -> bool:
+        """Whether admin-only requests are being refused for this token."""
+        return self._is_admin is False or self._admin_route_refused
+
+    @property
+    def known_is_admin(self) -> bool | None:
+        """The cached answer to ``token_is_admin``, without asking."""
+        return self._is_admin
+
+    async def token_is_admin(self) -> bool | None:
+        """Whether this token's user is a Home Assistant administrator.
+
+        ``None`` when Home Assistant gave no answer; only a definite answer is
+        cached. The first non-admin answer logs ``NON_ADMIN_TOKEN_WARNING``.
+        """
+        if self._is_admin is None:
+            user = await self._current_user()
+            is_admin = user.get("is_admin") if user else None
+            if not isinstance(is_admin, bool):
+                return None
+            self._is_admin = is_admin
+            if not is_admin:
+                logger.warning(
+                    "The Home Assistant token for %s belongs to a non-admin user. %s",
+                    self.base_url,
+                    NON_ADMIN_TOKEN_WARNING,
+                )
+        return self._is_admin
+
+    async def _current_user(self) -> dict[str, Any] | None:
+        """``auth/current_user`` for this token, or ``None`` when it can't be asked.
+
+        Asked over WebSocket because ``auth/current_user`` answers every user;
+        REST has no such route, only admin-only ones whose 401 would count
+        toward ``http.ban``. It uses a connection of its own: the pooled one
+        may be serving the caller's own event handler (a policy result event
+        fired from the bus), which would wait on itself.
+        """
+        from .websocket_client import HomeAssistantWebSocketClient
+
+        ws = HomeAssistantWebSocketClient(
+            self.base_url, self.token, verify_ssl=self.verify_ssl
+        )
+        try:
+            if not await ws.connect():
+                return None
+            reply = await ws.send_command("auth/current_user")
+        except (HomeAssistantError, WebSocketException, OSError) as e:
+            logger.debug(f"auth/current_user probe failed: {e}")
+            return None
+        finally:
+            await ws.disconnect()
+        user = reply.get("result")
+        return user if isinstance(user, dict) else None
+
     async def _request(
         self, method: str, endpoint: str, **kwargs: Any
     ) -> dict[str, Any]:
@@ -582,17 +719,55 @@ class HomeAssistantClient:
 
         payload = data or {}
 
+        if self._admin_route_refused or await self.token_is_admin() is False:
+            return await self._call_service_over_websocket(
+                domain, service, payload, return_response
+            )
+        if self._is_admin is True:
+            return await self._call_service_over_rest(
+                domain, service, payload, return_response
+            )
+        # Admin status unknown: one REST call at a time, so a 401 for an
+        # admin-only service latches before a second is sent.
+        async with self._admin_route_lock:
+            if self._admin_route_refused:
+                return await self._call_service_over_websocket(
+                    domain, service, payload, return_response
+                )
+            return await self._call_service_over_rest(
+                domain, service, payload, return_response
+            )
+
+    async def _call_service_over_rest(
+        self,
+        domain: str,
+        service: str,
+        payload: dict[str, Any],
+        return_response: bool,
+    ) -> list[dict[str, Any]] | dict[str, Any]:
+        """POST the service call; on a 401 latch and retry it over WebSocket.
+
+        A 401 means Home Assistant refused before running the service, so the
+        WebSocket retry cannot apply it twice.
+        """
         # Build query params for return_response
         params = {}
         if return_response:
             params["return_response"] = "true"
 
-        result = await self._request(
-            "POST",
-            f"/services/{domain}/{service}",
-            json=payload,
-            params=params if params else None,
-        )
+        try:
+            result = await self._request(
+                "POST",
+                f"/services/{domain}/{service}",
+                json=payload,
+                params=params if params else None,
+            )
+        except HomeAssistantAuthError:
+            self._is_admin = None
+            self._admin_route_refused = True
+            return await self._call_service_over_websocket(
+                domain, service, payload, return_response
+            )
 
         # When return_response is True, HA returns a dict with service_response key
         if return_response:
@@ -606,6 +781,45 @@ class HomeAssistantClient:
         else:
             return []
 
+    async def _call_service_over_websocket(
+        self,
+        domain: str,
+        service: str,
+        payload: dict[str, Any],
+        return_response: bool,
+    ) -> list[dict[str, Any]] | dict[str, Any]:
+        """Call a service for a non-admin token, in ``call_service``'s return shape.
+
+        Over REST an admin-only service answers a non-admin with a 401 that
+        ``http.ban`` counts; over WebSocket the refusal is only an error
+        (#2546). WebSocket reports no changed states, so that list is empty.
+        """
+        reply = await self.send_websocket_message(
+            {
+                "type": "call_service",
+                "domain": domain,
+                "service": service,
+                "service_data": payload,
+                "return_response": return_response,
+            }
+        )
+        if not reply.get("success"):
+            error = str(reply.get("error", "Service call failed"))
+            if error.removeprefix("Command failed: ") == "Unauthorized":
+                raise HomeAssistantAdminRequiredError(
+                    f"Service {domain}.{service} is admin-only in Home Assistant "
+                    "and this token's user is not an administrator"
+                )
+            raise HomeAssistantAPIError(
+                f"API error: 400 - {error}",
+                status_code=400,
+                response_data={"message": error},
+            )
+        if return_response:
+            result = reply.get("result") or {}
+            return {"changed_states": [], "service_response": result.get("response")}
+        return []
+
     async def get_services(self) -> dict[str, Any]:
         """Get all available services."""
         logger.debug("Fetching available services")

{ha_mcp_dev-8.5.0.dev2770 → ha_mcp_dev-8.5.0.dev2772}/src/ha_mcp/hacs_auto_refresh.py

@@ -278,11 +278,11 @@ async def maybe_refresh_hacs_after_update() -> None:
 async def hacs_refresh_lifespan(_server: Any) -> AsyncIterator[dict[str, Any]]:
     """Schedule the startup nudge for the lifetime of any server run.
 
-    Attached as the FastMCP ``lifespan`` so it runs on EVERY launcher —
-    stdio, the HTTP CLI entry points, and the add-on's ``start.py``, which
-    calls ``mcp.run()`` directly and never passes through ``__main__``'s
-    ``_run_with_shutdown`` (the wiring this replaces; the add-on gap was
-    found live, not by CI, because the e2e suites launch via the CLI
+    Entered by ``server_lifespan``, the FastMCP ``lifespan``, so it runs on
+    EVERY launcher — stdio, the HTTP CLI entry points, and the app's
+    ``start.py``, which calls ``mcp.run()`` directly and never passes through
+    ``__main__``'s ``_run_with_shutdown`` (the wiring this replaces; the app
+    gap was found live, not by CI, because the e2e suites launch via the CLI
     entry points).
     """
     task = asyncio.create_task(maybe_refresh_hacs_after_update())

{ha_mcp_dev-8.5.0.dev2770 → ha_mcp_dev-8.5.0.dev2772}/src/ha_mcp/policy/events.py

@@ -14,6 +14,7 @@ from typing import TYPE_CHECKING, Any
 
 import anyio
 
+from ..client.rest_client import HomeAssistantAdminRequiredError
 from .approval_queue import PendingApproval
 from .model import Rule
 
@@ -184,6 +185,13 @@ async def emit_approval_result(
                 token,
                 EMIT_TIMEOUT_SECONDS,
             )
+    except HomeAssistantAdminRequiredError:
+        logger.warning(
+            "policy events: %s for token=%s not fired: events need an "
+            "administrator's token; the decision itself is unaffected",
+            APPROVAL_RESULT_EVENT,
+            token,
+        )
     except Exception:
         logger.warning(
             "policy events: failed to fire %s for token=%s; the decision "
@@ -227,6 +235,14 @@ async def emit_approval_requested(
                 entry.tool_name,
                 EMIT_TIMEOUT_SECONDS,
             )
+    except HomeAssistantAdminRequiredError:
+        logger.warning(
+            "policy events: %s for tool=%s not fired: events need an "
+            "administrator's token; the pending request is still queued and "
+            "visible in the settings UI",
+            APPROVAL_REQUESTED_EVENT,
+            entry.tool_name,
+        )
     except Exception:
         # Broad by intent: every failure mode here has the same handling —
         # log it and leave the gate working. Narrowing would turn an

{ha_mcp_dev-8.5.0.dev2770 → ha_mcp_dev-8.5.0.dev2772}/src/ha_mcp/server.py

@@ -20,8 +20,8 @@ from ha_mcp._vendor.mcp.types import Icon
 
 from .config import _PACKAGE_VERSION, get_global_settings
 from .errors import ErrorCode, create_error_response
-from .hacs_auto_refresh import hacs_refresh_lifespan
 from .http_transport import HttpTransportFastMCP as FastMCP
+from .server_lifespan import server_lifespan
 from .tools.helpers import raise_tool_error
 from .transforms import DEFAULT_PINNED_TOOLS
 
@@ -144,7 +144,7 @@ class HomeAssistantSmartMCPServer:
             version=server_version,
             icons=SERVER_ICONS,
             instructions=instructions,
-            lifespan=hacs_refresh_lifespan,
+            lifespan=server_lifespan,
         )
 
         # Register all tools and expert prompts
@@ -1441,10 +1441,14 @@ class HomeAssistantSmartMCPServer:
             url: str | None
             token_value: str | None
             verify_ssl: bool | None
+            known_is_admin: bool | None
+            admin_route_refused: bool
             try:
                 url = client.base_url
                 token_value = client.token
                 verify_ssl = client.verify_ssl
+                known_is_admin = client.known_is_admin
+                admin_route_refused = client.admin_route_refused is True
             except Exception:
                 logger.debug(
                     "policy decisions: no credentials for the result event; "
@@ -1457,7 +1461,11 @@ class HomeAssistantSmartMCPServer:
             # ever reclaim. A wrong PIN retried by a chatty automation would
             # otherwise open one per attempt.
             async with HomeAssistantClient(
-                url, token_value, verify_ssl=verify_ssl
+                url,
+                token_value,
+                verify_ssl=verify_ssl,
+                is_admin=known_is_admin,
+                admin_route_refused=admin_route_refused,
             ) as result_client:
                 await emit_approval_result(
                     result_client,

ha_mcp_dev-8.5.0.dev2772/src/ha_mcp/server_lifespan.py

@@ -0,0 +1,52 @@
+"""FastMCP lifespan shared by every launcher: background startup passes."""
+
+import asyncio
+import logging
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager, suppress
+from typing import Any
+
+from ._version import is_embedded
+from .client.rest_client import HomeAssistantClient
+from .config import OAUTH_MODE_TOKEN, get_global_settings
+from .hacs_auto_refresh import hacs_refresh_lifespan
+
+logger = logging.getLogger(__name__)
+
+
+async def warn_if_non_admin_token() -> None:
+    """Ask Home Assistant about the configured token so a non-admin one is logged at startup (#2546)."""
+    try:
+        # The embedded server provisions its own admin token; OAuth mode has
+        # no server-level token to ask about.
+        settings = get_global_settings()
+        if is_embedded() or settings.homeassistant_token == OAUTH_MODE_TOKEN:
+            return
+        async with HomeAssistantClient() as client:
+            if await client.token_is_admin() is None:
+                logger.info(
+                    "Could not ask Home Assistant whether the token is an "
+                    "administrator's; admin-only requests go out one at a time "
+                    "until the first one answers it"
+                )
+    except asyncio.CancelledError:
+        raise
+    except Exception:
+        logger.warning("Startup admin-token check failed", exc_info=True)
+
+
+@asynccontextmanager
+async def server_lifespan(server: Any) -> AsyncIterator[dict[str, Any]]:
+    """Run the HACS startup nudge and the admin-token check for the server's lifetime.
+
+    Attached as the FastMCP ``lifespan`` so it runs on every launcher, including
+    the app's ``start.py``, which calls ``mcp.run()`` directly.
+    """
+    async with hacs_refresh_lifespan(server) as state:
+        task = asyncio.create_task(warn_if_non_admin_token())
+        try:
+            yield state
+        finally:
+            task.cancel()
+            with suppress(asyncio.CancelledError):
+                await task

{ha_mcp_dev-8.5.0.dev2770 → ha_mcp_dev-8.5.0.dev2772}/src/ha_mcp/tools/helpers.py

@@ -16,6 +16,8 @@ from ha_mcp._vendor.fastmcp import Context
 from ha_mcp._vendor.fastmcp.exceptions import ToolError
 
 from ..client.rest_client import (
+    NON_ADMIN_TOKEN_WARNING,
+    HomeAssistantAdminRequiredError,
     HomeAssistantAPIError,
     HomeAssistantAuthError,
     HomeAssistantCommandError,
@@ -322,6 +324,17 @@ def _classify_exception(
             result = create_connection_error(
                 error_msg, timeout="timeout" in error_str, context=context
             )
+        case HomeAssistantAdminRequiredError():
+            result = create_error_response(
+                ErrorCode.AUTH_INSUFFICIENT_PERMISSIONS,
+                error_msg,
+                suggestions=[
+                    "Use a long-lived access token from an administrator's profile",
+                    "Or use the in-process server, which provisions its own admin token",
+                ],
+                context=context,
+            )
+            result["warnings"] = [NON_ADMIN_TOKEN_WARNING]
         case HomeAssistantAuthError():
             result = create_auth_error(
                 error_msg, expired="expired" in error_str, context=context

{ha_mcp_dev-8.5.0.dev2770 → ha_mcp_dev-8.5.0.dev2772}/src/ha_mcp/tools/smart_search/_deep.py

@@ -8,7 +8,7 @@ from typing import Any
 from ha_mcp._vendor.fastmcp import Context
 from ha_mcp._vendor.fastmcp.exceptions import ToolError
 
-from ...client.rest_client import HomeAssistantAPIError
+from ...client.rest_client import NON_ADMIN_TOKEN_WARNING, HomeAssistantAPIError
 from ...errors import get_error_code, get_error_message
 from ..component_api import component_supports, get_component_caps
 from ..config_entry_flow import FLOW_HELPER_TYPES
@@ -1347,6 +1347,15 @@ class DeepSearchMixin(SceneSearchMixin):
             graph_surfaces_skipped=graph_surfaces_skipped,
             graph_unavailable=graph_unavailable,
         )
+        # Keyed on the client, not the failure sample, which names only the
+        # first error.
+        if (
+            automation_failed
+            or script_failed
+            or scene_stats.get("failed")
+            or helper_failed
+        ) and self.client.admin_route_refused is True:
+            response.setdefault("warnings", []).append(NON_ADMIN_TOKEN_WARNING)
         return response
 
     @staticmethod

{ha_mcp_dev-8.5.0.dev2770 → ha_mcp_dev-8.5.0.dev2772}/src/ha_mcp/tools/tools_code.py

@@ -35,6 +35,10 @@ from pydantic import Field
 from ha_mcp._vendor.fastmcp.exceptions import ToolError
 from ha_mcp._vendor.fastmcp.server.context import Context
 
+from ..client.rest_client import (
+    NON_ADMIN_TOKEN_WARNING,
+    HomeAssistantAdminRequiredError,
+)
 from ..config import get_global_settings
 from ..errors import ErrorCode, create_error_response
 from .helpers import log_tool_usage, raise_tool_error
@@ -757,11 +761,13 @@ class _SandboxBridge:
             logger.warning("api_get rejected endpoint %r: %s", endpoint, exc)
             return {"error": str(exc)}
         try:
-            response = await self.client.httpx_client.request("GET", normalized)
+            response = await self.client.guarded_request("GET", normalized)
             try:
                 return response.json()
             except json.JSONDecodeError:
                 return response.text
+        except HomeAssistantAdminRequiredError as exc:
+            return {"error": str(exc), "warnings": [NON_ADMIN_TOKEN_WARNING]}
         except Exception as exc:
             logger.warning("api_get(%r) failed", endpoint, exc_info=True)
             return {"error": str(exc)[:200]}
@@ -804,13 +810,15 @@ class _SandboxBridge:
             post_kwargs: dict[str, Any] = {}
             if data is not None:
                 post_kwargs["json"] = data
-            response = await self.client.httpx_client.request(
+            response = await self.client.guarded_request(
                 "POST", normalized, **post_kwargs
             )
             try:
                 return response.json()
             except json.JSONDecodeError:
                 return response.text
+        except HomeAssistantAdminRequiredError as exc:
+            return {"error": str(exc), "warnings": [NON_ADMIN_TOKEN_WARNING]}
         except Exception as exc:
             logger.warning("api_post(%r) failed", endpoint, exc_info=True)
             return {"error": str(exc)[:200]}