ha-mcp-dev 7.4.1.dev422__tar.gz → 7.4.1.dev424__tar.gz

{ha_mcp_dev-7.4.1.dev422/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.4.1.dev424}/PKG-INFO

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

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

@@ -5,12 +5,27 @@ Home Assistant HTTP client with authentication and error handling.
 import asyncio
 import json
 import logging
+import ssl
 from typing import Any
 
 import httpx
 
 from ..config import get_global_settings
 
+
+def _is_ssl_error(exc: BaseException) -> bool:
+    """True if ``exc`` (or anything in its cause chain) is an SSL error.
+
+    httpx wraps ``ssl.SSLError`` inside ``httpx.ConnectError``; the only
+    reliable check is to walk ``__cause__`` / ``__context__``.
+    """
+    cur: BaseException | None = exc
+    while cur is not None:
+        if isinstance(cur, ssl.SSLError):
+            return True
+        cur = cur.__cause__ or cur.__context__
+    return False
+
 logger = logging.getLogger(__name__)
 
 
@@ -62,6 +77,7 @@ class HomeAssistantClient:
         base_url: str | None = None,
         token: str | None = None,
         timeout: int | None = None,
+        verify_ssl: bool | None = None,
     ):
         """
         Initialize Home Assistant client.
@@ -70,18 +86,31 @@ class HomeAssistantClient:
             base_url: Home Assistant URL (defaults to config)
             token: Long-lived access token (defaults to config)
             timeout: Request timeout in seconds (defaults to config)
+            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.
         """
-        # Only load settings if we need to use fallback values
-        if base_url is None or token is None:
+        if base_url is None or token is None or verify_ssl is None:
             settings = get_global_settings()
             self.base_url = (base_url or settings.homeassistant_url).rstrip("/")
             self.token = token or settings.homeassistant_token
             self.timeout = timeout if timeout is not None else settings.timeout
+            self.verify_ssl = (
+                verify_ssl if verify_ssl is not None else settings.verify_ssl
+            )
         else:
-            # All required parameters provided, use them directly without loading settings
             self.base_url = base_url.rstrip("/")
             self.token = token
             self.timeout = timeout if timeout is not None else 30  # Default timeout
+            self.verify_ssl = verify_ssl
+
+        if not self.verify_ssl:
+            logger.warning(
+                "TLS verification disabled for Home Assistant REST client "
+                "(HA_VERIFY_SSL=false). Connections to %s will accept "
+                "self-signed and mismatched certificates.",
+                self.base_url,
+            )
 
         # Create HTTP client with authentication headers
         self.httpx_client = httpx.AsyncClient(
@@ -91,6 +120,7 @@ class HomeAssistantClient:
                 "Content-Type": "application/json",
             },
             timeout=httpx.Timeout(self.timeout),
+            verify=self.verify_ssl,
         )
 
         logger.info(f"Initialized Home Assistant client for {self.base_url}")
@@ -148,6 +178,12 @@ class HomeAssistantClient:
             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"Failed to connect to Home Assistant: {e}"
             ) from e

{ha_mcp_dev-7.4.1.dev422 → ha_mcp_dev-7.4.1.dev424}/src/ha_mcp/client/websocket_client.py

@@ -11,6 +11,7 @@ import asyncio
 import hashlib
 import json
 import logging
+import ssl
 import time
 from collections import defaultdict
 from collections.abc import Awaitable, Callable
@@ -20,7 +21,11 @@ from urllib.parse import urlparse
 import websockets
 
 from ..config import get_global_settings
-from .rest_client import HomeAssistantCommandError, HomeAssistantConnectionError
+from .rest_client import (
+    HomeAssistantCommandError,
+    HomeAssistantConnectionError,
+    _is_ssl_error,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -158,15 +163,33 @@ class WebSocketConnectionState:
 class HomeAssistantWebSocketClient:
     """WebSocket client for Home Assistant real-time communication."""
 
-    def __init__(self, url: str, token: str):
+    def __init__(self, url: str, token: str, verify_ssl: bool | None = None):
         """Initialize WebSocket client.
 
         Args:
             url: Home Assistant URL (e.g., 'https://homeassistant.local:8123')
             token: Home Assistant long-lived access token
+            verify_ssl: Whether to verify the HA server's TLS certificate
+                for ``wss://`` connections. Defaults to
+                ``settings.verify_ssl``. Pass False to allow self-signed
+                certs or hostname mismatches.
         """
         self.base_url = url.rstrip("/")
         self.token = token
+        if verify_ssl is None:
+            try:
+                verify_ssl = get_global_settings().verify_ssl
+            except Exception as e:
+                # A bad env var elsewhere should not silently flip TLS off:
+                # log which key tripped and fall back to the secure default.
+                logger.warning(
+                    "Could not load settings while resolving verify_ssl "
+                    "(%s); falling back to verify_ssl=True.",
+                    e,
+                )
+                verify_ssl = True
+        self.verify_ssl = verify_ssl
+        self._warned_verify_disabled = False
         self.websocket: websockets.ClientConnection | None = None
         self.background_task: asyncio.Task | None = None
         self._send_lock: asyncio.Lock | None = None
@@ -197,6 +220,25 @@ class HomeAssistantWebSocketClient:
             logger.info(f"Connecting to Home Assistant WebSocket: {self.ws_url}")
             self._state.reset_connection()
 
+            # Only configure an SSLContext for wss://; ws:// (Supervisor
+            # proxy) doesn't use TLS and gets ssl=None.
+            ssl_ctx: ssl.SSLContext | None = None
+            if self.ws_url.startswith("wss://"):
+                ssl_ctx = ssl.create_default_context()
+                if not self.verify_ssl:
+                    if not self._warned_verify_disabled:
+                        # Once per client — pool reconnects/HA restarts
+                        # otherwise flood logs with the same warning.
+                        logger.warning(
+                            "TLS verification disabled for Home Assistant "
+                            "WebSocket (HA_VERIFY_SSL=false). Connecting to "
+                            "%s with hostname/cert checks off.",
+                            self.ws_url,
+                        )
+                        self._warned_verify_disabled = True
+                    ssl_ctx.check_hostname = False
+                    ssl_ctx.verify_mode = ssl.CERT_NONE
+
             # Connect to WebSocket
             # Include Authorization header for Supervisor proxy compatibility
             # (required when connecting via http://supervisor/core/websocket)
@@ -205,6 +247,7 @@ class HomeAssistantWebSocketClient:
                 ping_interval=30,
                 ping_timeout=10,
                 additional_headers={"Authorization": f"Bearer {self.token}"},
+                ssl=ssl_ctx,
                 # Increase max message size to 20MB for large responses
                 # (e.g., HACS repository list can be 2MB+)
                 max_size=20 * 1024 * 1024,
@@ -241,7 +284,16 @@ class HomeAssistantWebSocketClient:
             return True
 
         except Exception as e:
-            logger.error(f"WebSocket connection failed: {e}")
+            if _is_ssl_error(e) and self.verify_ssl:
+                logger.error(
+                    "WebSocket TLS verification failed for %s: %s. "
+                    "If this is a self-signed certificate or hostname "
+                    "mismatch, set HA_VERIFY_SSL=false to skip verification.",
+                    self.ws_url,
+                    e,
+                )
+            else:
+                logger.error(f"WebSocket connection failed: {e}")
             await self.disconnect()
             return False
 

{ha_mcp_dev-7.4.1.dev422 → ha_mcp_dev-7.4.1.dev424}/src/ha_mcp/config.py

@@ -54,6 +54,9 @@ class Settings(BaseSettings):
     timeout: int = Field(30, alias="HA_TIMEOUT")
     max_retries: int = Field(3, alias="HA_MAX_RETRIES")
 
+    # False = skip TLS verification (self-signed / hostname mismatch). Trusted networks only.
+    verify_ssl: bool = Field(True, alias="HA_VERIFY_SSL")
+
     # Tool configuration
     fuzzy_threshold: int = Field(60, alias="FUZZY_THRESHOLD")
     entity_search_limit: int = Field(20, alias="ENTITY_SEARCH_LIMIT")
@@ -231,3 +234,13 @@ def get_global_settings() -> Settings:
     if _settings is None:
         _settings = get_settings()
     return _settings
+
+
+def _reset_global_settings() -> None:
+    """Drop the cached settings singleton.
+
+    Test-only seam so suites that mutate ``HA_*`` env vars can force a
+    re-read without reaching into module-private state.
+    """
+    global _settings
+    _settings = None

{ha_mcp_dev-7.4.1.dev422 → ha_mcp_dev-7.4.1.dev424}/src/ha_mcp/tools/backup.py

@@ -179,7 +179,9 @@ async def create_backup(
 
     try:
         # Connect to WebSocket
-        ws_client, error = await get_connected_ws_client(client.base_url, client.token)
+        ws_client, error = await get_connected_ws_client(
+            client.base_url, client.token, verify_ssl=client.verify_ssl
+        )
         if error:
             raise_tool_error(error or create_error_response(
                 ErrorCode.CONNECTION_FAILED,
@@ -300,7 +302,9 @@ async def restore_backup(
 
     try:
         # Connect to WebSocket
-        ws_client, error = await get_connected_ws_client(client.base_url, client.token)
+        ws_client, error = await get_connected_ws_client(
+            client.base_url, client.token, verify_ssl=client.verify_ssl
+        )
         if error:
             raise_tool_error(error or create_error_response(
                 ErrorCode.CONNECTION_FAILED,

{ha_mcp_dev-7.4.1.dev422 → ha_mcp_dev-7.4.1.dev424}/src/ha_mcp/tools/helpers.py

@@ -78,7 +78,7 @@ def extract_tool_error_message(te: ToolError) -> str:
 
 
 async def get_connected_ws_client(
-    base_url: str, token: str
+    base_url: str, token: str, verify_ssl: bool | None = None
 ) -> tuple[HomeAssistantWebSocketClient | None, dict[str, Any] | None]:
     """
     Create and connect a WebSocket client.
@@ -86,11 +86,15 @@ async def get_connected_ws_client(
     Args:
         base_url: Home Assistant base URL
         token: Authentication token
+        verify_ssl: TLS verification override. Pass ``client.verify_ssl``
+            from the calling REST client so a programmatic
+            ``HomeAssistantClient(verify_ssl=False)`` propagates to the
+            WebSocket too. ``None`` falls back to ``settings.verify_ssl``.
 
     Returns:
         Tuple of (ws_client, error_dict). If connection fails, ws_client is None.
     """
-    ws_client = HomeAssistantWebSocketClient(base_url, token)
+    ws_client = HomeAssistantWebSocketClient(base_url, token, verify_ssl=verify_ssl)
     connected = await ws_client.connect()
     if not connected:
         return None, create_connection_error(

{ha_mcp_dev-7.4.1.dev422 → ha_mcp_dev-7.4.1.dev424}/src/ha_mcp/tools/tools_addons.py

@@ -13,19 +13,19 @@ import logging
 import re
 import time
 from typing import Annotated, Any
-from urllib.parse import unquote
+from urllib.parse import unquote, urlsplit
 
 import httpx
 import websockets
 from fastmcp.exceptions import ToolError
 from pydantic import Field
 
+from .._version import is_running_in_addon
 from ..client.rest_client import HomeAssistantClient
 from ..errors import (
     ErrorCode,
     create_connection_error,
     create_error_response,
-    create_timeout_error,
     create_validation_error,
 )
 from ..utils.python_sandbox import PythonSandboxError, safe_execute_expression
@@ -232,7 +232,9 @@ async def _supervisor_api_call(
     """
     ws_client = None
     try:
-        ws_client, error = await get_connected_ws_client(client.base_url, client.token)
+        ws_client, error = await get_connected_ws_client(
+            client.base_url, client.token, verify_ssl=client.verify_ssl
+        )
         if error or ws_client is None:
             return error or create_connection_error(
                 "Failed to establish WebSocket connection",
@@ -286,6 +288,217 @@ async def _supervisor_api_call(
                 pass
 
 
+def _addon_connection_failure_suggestions(
+    client: HomeAssistantClient, port: int | None
+) -> list[str]:
+    """Suggestions for connect/timeout failures against an add-on.
+
+    Three modes — direct-port hits a container IP, the addon-variant ingress
+    route hits a sibling container's ingress port, the off-host ingress route
+    hits HA Core. Each mode fails for different reasons, so suggest different
+    next steps.
+    """
+    if port:
+        return [
+            "Check that the add-on is running",
+            "Direct-port access requires the MCP host to share Home "
+            "Assistant's container network. On PyPI/uvx installs, drop "
+            "the 'port' parameter to route through Ingress instead.",
+        ]
+    if is_running_in_addon():
+        return [
+            "The target add-on container may not be reachable from this "
+            "MCP add-on. Check that the target add-on is running.",
+            "If the failure persists, the addon Docker network may be "
+            "unhealthy — try restarting the target add-on, then this "
+            "MCP add-on.",
+        ]
+    return [
+        f"Verify Home Assistant is reachable at {client.base_url}",
+        "Check network connectivity from the MCP host to HA Core",
+    ]
+
+
+async def _create_ingress_session(client: HomeAssistantClient) -> str:
+    """Create a Supervisor ingress session and return its token.
+
+    Sessions are minted via the WS `supervisor/api` proxy (which HA Core
+    authenticates on our behalf), so this works the same on HAOS, Supervised,
+    and PyPI/uvx hosts. The returned token is set as the `ingress_session`
+    cookie on requests to HA Core's `/api/hassio_ingress/<addon_token>/...`
+    endpoint, which Supervisor validates before proxying to the add-on
+    container. Sessions are valid for ~15 minutes; we mint a fresh one per
+    call to avoid managing lifetime.
+    """
+    response = await _supervisor_api_call(
+        client, "/ingress/session", method="POST", data={}
+    )
+    if not response.get("success"):
+        raise_tool_error(response)
+
+    session = response.get("result", {}).get("session")
+    if not isinstance(session, str) or not session:
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.SERVICE_CALL_FAILED,
+                "Supervisor returned no ingress session token",
+                details=str(response),
+            )
+        )
+    return session
+
+
+async def _resolve_http_route(
+    client: HomeAssistantClient,
+    addon: dict[str, Any],
+    normalized_path: str,
+    port: int | None,
+) -> tuple[str, dict[str, str]]:
+    """Pick the HTTP route shape based on `port` and install variant.
+
+    Three branches:
+    - `port` set → direct container port (`http://<ip>:<port>/...`), no
+      auth headers. Only reachable when the MCP host shares HA's container
+      network.
+    - Running as the HA add-on (`is_running_in_addon()` true) → direct
+      `<addon_ip>:<addon_ingress_port>` with `X-Ingress-Path` and
+      `X-Hass-Source: core.ingress` headers. This is the path the addon
+      variant always took on master; routing through HA Core's
+      `/api/hassio_ingress/...` proxy regresses here because
+      `client.base_url` is `http://supervisor/core` (a Supervisor proxy
+      mount that demands `Authorization: Bearer $SUPERVISOR_TOKEN`).
+    - Off-host → HA Core ingress proxy at
+      `<base_url>/api/hassio_ingress/<token>/<path>` with `Cookie:
+      ingress_session=<token>`. Mints a fresh session per call.
+    """
+    addon_name = addon.get("name", "")
+    headers: dict[str, str] = {}
+
+    if port:
+        addon_ip = addon.get("ip_address", "")
+        if not addon_ip:
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.INTERNAL_ERROR,
+                    f"Add-on '{addon_name}' is missing ip_address",
+                    context={"slug": addon.get("slug"), "ip_address": addon_ip},
+                )
+            )
+        return f"http://{addon_ip}:{port}/{normalized_path}", headers
+
+    ingress_entry = addon.get("ingress_entry")
+    if not ingress_entry:
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.INTERNAL_ERROR,
+                f"Add-on '{addon_name}' is missing ingress_entry",
+                context={"slug": addon.get("slug")},
+            )
+        )
+
+    if is_running_in_addon():
+        addon_ip = addon.get("ip_address", "")
+        ingress_port = addon.get("ingress_port")
+        if not addon_ip or not ingress_port:
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.INTERNAL_ERROR,
+                    f"Add-on '{addon_name}' is missing network info "
+                    "(ip_address or ingress_port)",
+                    context={
+                        "slug": addon.get("slug"),
+                        "ip_address": addon_ip,
+                        "ingress_port": ingress_port,
+                    },
+                )
+            )
+        # Sibling addon containers share the hassio bridge, so we hit the
+        # ingress port directly. The X-Ingress-Path / X-Hass-Source headers
+        # are what the addon's nginx trusts as authenticated ingress source.
+        headers["X-Ingress-Path"] = ingress_entry
+        headers["X-Hass-Source"] = "core.ingress"
+        return (
+            f"http://{addon_ip}:{ingress_port}/{normalized_path}",
+            headers,
+        )
+
+    session = await _create_ingress_session(client)
+    base = client.base_url.rstrip("/")
+    headers["Cookie"] = f"ingress_session={session}"
+    return f"{base}{ingress_entry}/{normalized_path}", headers
+
+
+async def _resolve_ws_route(
+    client: HomeAssistantClient,
+    addon: dict[str, Any],
+    normalized_path: str,
+    port: int | None,
+) -> tuple[str, dict[str, str]]:
+    """Pick the WebSocket route shape. Mirrors `_resolve_http_route`.
+
+    The addon-variant and direct-port branches always speak `ws://` because
+    they hit the container directly. The off-host branch echoes
+    `client.base_url`'s scheme (so HTTPS-fronted HA gets `wss://`).
+    """
+    addon_name = addon.get("name", "")
+    headers: dict[str, str] = {}
+
+    if port:
+        addon_ip = addon.get("ip_address", "")
+        if not addon_ip:
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.INTERNAL_ERROR,
+                    f"Add-on '{addon_name}' is missing ip_address",
+                    context={"slug": addon.get("slug")},
+                )
+            )
+        return f"ws://{addon_ip}:{port}/{normalized_path}", headers
+
+    ingress_entry = addon.get("ingress_entry")
+    if not ingress_entry:
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.INTERNAL_ERROR,
+                f"Add-on '{addon_name}' is missing ingress_entry",
+                context={"slug": addon.get("slug")},
+            )
+        )
+
+    if is_running_in_addon():
+        addon_ip = addon.get("ip_address", "")
+        ingress_port = addon.get("ingress_port")
+        if not addon_ip or not ingress_port:
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.INTERNAL_ERROR,
+                    f"Add-on '{addon_name}' is missing network info "
+                    "(ip_address or ingress_port)",
+                    context={
+                        "slug": addon.get("slug"),
+                        "ip_address": addon_ip,
+                        "ingress_port": ingress_port,
+                    },
+                )
+            )
+        headers["X-Ingress-Path"] = ingress_entry
+        headers["X-Hass-Source"] = "core.ingress"
+        return (
+            f"ws://{addon_ip}:{ingress_port}/{normalized_path}",
+            headers,
+        )
+
+    session = await _create_ingress_session(client)
+    parsed = urlsplit(client.base_url)
+    ws_scheme = "wss" if parsed.scheme == "https" else "ws"
+    ws_path_prefix = parsed.path.rstrip("/")
+    headers["Cookie"] = f"ingress_session={session}"
+    return (
+        f"{ws_scheme}://{parsed.netloc}{ws_path_prefix}{ingress_entry}/{normalized_path}",
+        headers,
+    )
+
+
 async def get_addon_info(client: HomeAssistantClient, slug: str) -> dict[str, Any]:
     """Get detailed info for a specific add-on.
 
@@ -517,6 +730,11 @@ async def _call_addon_ws(
 ) -> dict[str, Any]:
     """Connect to an add-on's WebSocket API and collect messages.
 
+    Routing mirrors the HTTP variant (see `_resolve_ws_route`): off-host
+    ingress tunnels through HA Core's `/api/hassio_ingress` proxy; the
+    HA-add-on variant hits the container's ingress port directly;
+    direct-port mode (`port` set) connects to the container's mapped port.
+
     Args:
         client: Home Assistant REST client
         slug: Add-on slug (e.g., "5c53de3b_esphome")
@@ -591,38 +809,8 @@ async def _call_addon_ws(
             )
         )
 
-    # 5. Build WebSocket URL
-    addon_ip = addon.get("ip_address", "")
-    if port:
-        if not addon_ip:
-            raise_tool_error(
-                create_error_response(
-                    ErrorCode.INTERNAL_ERROR,
-                    f"Add-on '{addon_name}' is missing ip_address",
-                    context={"slug": slug},
-                )
-            )
-        target_port = port
-    else:
-        ingress_port = addon.get("ingress_port")
-        if not addon_ip or not ingress_port:
-            raise_tool_error(
-                create_error_response(
-                    ErrorCode.INTERNAL_ERROR,
-                    f"Add-on '{addon_name}' is missing network info",
-                    context={"slug": slug},
-                )
-            )
-        target_port = ingress_port
-
-    ws_url = f"ws://{addon_ip}:{target_port}/{normalized}"
-
-    # 6. Build connection headers
-    headers: dict[str, str] = {}
-    if not port:
-        ingress_entry = addon.get("ingress_entry", "")
-        headers["X-Ingress-Path"] = ingress_entry
-        headers["X-Hass-Source"] = "core.ingress"
+    # 5. Resolve route (direct-port / addon-variant / off-host).
+    ws_url, headers = await _resolve_ws_route(client, addon, normalized, port)
 
     # 7. Connect and exchange messages
     collected: list[str] = []
@@ -703,14 +891,25 @@ async def _call_addon_ws(
                 total_size += len(clean)
 
     except websockets.exceptions.InvalidHandshake as e:
+        suggestions = [
+            "Check that the add-on supports WebSocket on this path",
+            f"Use ha_get_addon(slug='{slug}') to inspect available endpoints",
+        ]
+        # 401/403 means auth was rejected, not a path-shape problem.
+        if isinstance(e, websockets.exceptions.InvalidStatus):
+            status = e.response.status_code
+            if status in (401, 403):
+                suggestions = [
+                    "The ingress session may have expired or your HA token "
+                    "may lack the required scope. Verify the token has admin "
+                    "rights and try again.",
+                    f"Status {status} from the WebSocket handshake.",
+                ]
         raise_tool_error(
             create_error_response(
                 ErrorCode.SERVICE_CALL_FAILED,
                 f"WebSocket handshake failed with '{addon_name}': {e!s}",
-                suggestions=[
-                    "Check that the add-on supports WebSocket on this path",
-                    f"Use ha_get_addon(slug='{slug}') to inspect available endpoints",
-                ],
+                suggestions=suggestions,
                 context={"slug": slug, "path": path},
             )
         )
@@ -728,19 +927,28 @@ async def _call_addon_ws(
         )
     except TimeoutError:
         raise_tool_error(
-            create_timeout_error(
-                f"WebSocket connection to '{addon_name}'",
-                timeout,
+            create_error_response(
+                ErrorCode.TIMEOUT_OPERATION,
+                f"Operation 'WebSocket connection to {addon_name!r}' timed out after {timeout}s",
                 details=f"path={path}",
-                context={"slug": slug, "path": path},
+                context={
+                    "slug": slug,
+                    "path": path,
+                    "operation": f"WebSocket connection to '{addon_name}'",
+                    "timeout_seconds": timeout,
+                    "direct_port": bool(port),
+                },
+                suggestions=_addon_connection_failure_suggestions(client, port),
             )
         )
     except OSError as e:
         raise_tool_error(
-            create_connection_error(
+            create_error_response(
+                ErrorCode.CONNECTION_FAILED,
                 f"Failed to connect to add-on '{addon_name}' WebSocket: {e!s}",
-                details="Check that the add-on is running and the port is correct",
-                context={"slug": slug},
+                details=f"url={ws_url}",
+                context={"slug": slug, "direct_port": bool(port)},
+                suggestions=_addon_connection_failure_suggestions(client, port),
             )
         )
 
@@ -852,7 +1060,21 @@ async def _call_addon_api(
     limit: int | None = None,
     python_transform: str | None = None,
 ) -> dict[str, Any]:
-    """Call an add-on's web API through Home Assistant's Ingress proxy.
+    """Call an add-on's web API.
+
+    Routing is picked per install variant (see `_resolve_http_route`):
+
+    - **Ingress (default), off-host**: tunnels through HA Core's
+      `/api/hassio_ingress/<token>/...` proxy with a per-call Supervisor
+      session cookie. The path that makes off-host (PyPI/uvx) installs work.
+    - **Ingress (default), HA add-on**: hits the addon container's
+      ingress port directly with the `core.ingress` source headers. Avoids
+      the Supervisor `/core` proxy hop that would otherwise demand
+      `Authorization: Bearer $SUPERVISOR_TOKEN` on top of the cookie.
+    - **Direct port** (when `port` is set): connects to
+      `http://<addon_ip>:<port>/...` for add-ons that expose mapped ports
+      (e.g. Node-RED on 1880). Only works when the MCP host shares HA's
+      Docker network.
 
     Args:
         client: Home Assistant REST client
@@ -868,9 +1090,6 @@ async def _call_addon_api(
             parsed response body. The variable ``response`` is bound to
             ``dict | list | str`` depending on content-type. Transform runs
             after offset/limit slicing.
-
-    Returns:
-        Dictionary with response data, status code, and content type.
     """
     # 1. Sanitize path to prevent traversal attacks (including URL-encoded)
     normalized = unquote(path).lstrip("/")
@@ -919,52 +1138,10 @@ async def _call_addon_api(
             )
         )
 
-    # 5. Build URL to the add-on container
-    addon_ip = addon.get("ip_address", "")
-
-    if port:
-        # Direct port access: connect to the add-on's mapped network port
-        # (e.g., 1880 for Node-RED, 6052 for ESPHome) instead of the ingress port.
-        # Requires 'leave_front_door_open' or equivalent setting on the add-on.
-        if not addon_ip:
-            raise_tool_error(
-                create_error_response(
-                    ErrorCode.INTERNAL_ERROR,
-                    f"Add-on '{addon_name}' is missing ip_address",
-                    context={"slug": slug, "ip_address": addon_ip},
-                )
-            )
-        target_port = port
-    else:
-        # Default: use the ingress port for direct container communication
-        ingress_port = addon.get("ingress_port")
-        if not addon_ip or not ingress_port:
-            raise_tool_error(
-                create_error_response(
-                    ErrorCode.INTERNAL_ERROR,
-                    f"Add-on '{addon_name}' is missing network info (ip_address or ingress_port)",
-                    context={
-                        "slug": slug,
-                        "ip_address": addon_ip,
-                        "ingress_port": ingress_port,
-                    },
-                )
-            )
-        target_port = ingress_port
-
-    url = f"http://{addon_ip}:{target_port}/{normalized}"
+    # 5. Resolve route (direct-port / addon-variant / off-host).
+    url, headers = await _resolve_http_route(client, addon, normalized, port)
 
-    # 6. Make HTTP request directly to the add-on container
-    # Include Ingress headers so the add-on's web server (e.g., Nginx) recognizes
-    # this as an authenticated Ingress request and bypasses its own auth layer.
-    # When using a direct port, skip Ingress headers (not needed/recognized).
-    ingress_entry = addon.get("ingress_entry", "")
-    headers: dict[str, str] = {}
-    if not port:
-        headers["X-Ingress-Path"] = ingress_entry
-        headers["X-Hass-Source"] = "core.ingress"
-
-    # Set content type based on body type
+    # 6. Set content type based on body type
     if isinstance(body, dict):
         headers["Content-Type"] = "application/json"
         request_content = json.dumps(body).encode()
@@ -984,19 +1161,28 @@ async def _call_addon_api(
             )
     except httpx.TimeoutException:
         raise_tool_error(
-            create_timeout_error(
-                f"add-on API call to '{addon_name}'",
-                timeout,
+            create_error_response(
+                ErrorCode.TIMEOUT_OPERATION,
+                f"Operation 'add-on API call to {addon_name!r}' timed out after {timeout}s",
                 details=f"path={path}, method={method}",
-                context={"slug": slug, "path": path},
+                context={
+                    "slug": slug,
+                    "path": path,
+                    "operation": f"add-on API call to '{addon_name}'",
+                    "timeout_seconds": timeout,
+                    "direct_port": bool(port),
+                },
+                suggestions=_addon_connection_failure_suggestions(client, port),
             )
         )
     except httpx.ConnectError as e:
         raise_tool_error(
-            create_connection_error(
+            create_error_response(
+                ErrorCode.CONNECTION_FAILED,
                 f"Failed to connect to add-on '{addon_name}': {e!s}",
-                details="Check that the add-on is running and Home Assistant Ingress is working",
-                context={"slug": slug},
+                details=f"url={url}",
+                context={"slug": slug, "direct_port": bool(port)},
+                suggestions=_addon_connection_failure_suggestions(client, port),
             )
         )
 
@@ -1101,16 +1287,21 @@ async def _call_addon_api(
 
     if response.status_code >= 400:
         result["error"] = f"Add-on API returned HTTP {response.status_code}"
-        # On 403/401, include addon config so the LLM can spot relevant settings
-        # (e.g., "leave_front_door_open", auth toggles, port mappings)
-        if response.status_code in (401, 403):
-            addon_options = addon.get("options")
-            addon_ports = addon.get("network") or addon.get("ports")
-            addon_host_network = addon.get("host_network")
+        # 401 = auth credential problem (token/scope/session); IP-restriction
+        # hint and addon_config attachment would misdirect.
+        # 403 = forbidden (likely Nginx ACL); addon_config helps the LLM spot
+        # relevant toggles like leave_front_door_open and port mappings.
+        if response.status_code == 401:
+            result["suggestion"] = (
+                "Authentication failed. The ingress session may have expired, "
+                "or your HA token may lack the required scope. Verify the "
+                "token has admin rights and try again."
+            )
+        elif response.status_code == 403:
             result["addon_config"] = {
-                "options": addon_options,
-                "ports": addon_ports,
-                "host_network": addon_host_network,
+                "options": addon.get("options"),
+                "ports": addon.get("network") or addon.get("ports"),
+                "host_network": addon.get("host_network"),
                 "ingress_port": addon.get("ingress_port"),
             }
             result["suggestion"] = (
@@ -1411,7 +1602,11 @@ def register_addon_tools(mcp: Any, client: HomeAssistantClient, **kwargs: Any) -
         are fetched and merged automatically (including one level of nested dicts).
 
         **Proxy mode** (when path is provided):
-        Sends requests directly to the add-on container's own web API via HTTP or WebSocket.
+        Routes HTTP or WebSocket requests through Home Assistant's Ingress
+        proxy by default (works on HAOS, Supervised, and off-host PyPI/uvx
+        installs). Pass `port=...` to bypass Ingress and connect directly to
+        an add-on's container port — that mode requires the MCP host to
+        share Home Assistant's container network (i.e. only the HAOS addon).
         Use ha_get_addon(slug="...") to discover available ports and endpoints.
 
         **Response shaping (proxy mode):**

{ha_mcp_dev-7.4.1.dev422 → ha_mcp_dev-7.4.1.dev424}/src/ha_mcp/tools/tools_history.py

@@ -290,7 +290,9 @@ class HistoryTools:
 
             # Connect to WebSocket (shared by both sources)
             ws_client, error = await get_connected_ws_client(
-                self._client.base_url, self._client.token
+                self._client.base_url,
+                self._client.token,
+                verify_ssl=self._client.verify_ssl,
             )
             if error or ws_client is None:
                 raise_tool_error(error or create_error_response(

{ha_mcp_dev-7.4.1.dev422 → ha_mcp_dev-7.4.1.dev424}/src/ha_mcp/tools/tools_system.py

@@ -415,7 +415,9 @@ class SystemTools:
             for subsequent optional fetches.
         """
         ws_client, error = await get_connected_ws_client(
-            self._client.base_url, self._client.token
+            self._client.base_url,
+            self._client.token,
+            verify_ssl=self._client.verify_ssl,
         )
         if error or ws_client is None:
             raise_tool_error(error or create_error_response(

{ha_mcp_dev-7.4.1.dev422 → ha_mcp_dev-7.4.1.dev424}/src/ha_mcp/tools/tools_traces.py

@@ -167,7 +167,9 @@ class TraceTools:
 
             # Connect to WebSocket
             ws_client, error = await get_connected_ws_client(
-                self._client.base_url, self._client.token
+                self._client.base_url,
+                self._client.token,
+                verify_ssl=self._client.verify_ssl,
             )
             if error or ws_client is None:
                 raise_tool_error(error or create_error_response(

{ha_mcp_dev-7.4.1.dev422 → ha_mcp_dev-7.4.1.dev424/src/ha_mcp_dev.egg-info}/PKG-INFO

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