ha-mcp-dev 8.3.0.dev2385__tar.gz → 8.3.0.dev2387__tar.gz

{ha_mcp_dev-8.3.0.dev2385/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.3.0.dev2387}/PKG-INFO

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

{ha_mcp_dev-8.3.0.dev2385 → ha_mcp_dev-8.3.0.dev2387}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.3.0.dev2385"
+version = "8.3.0.dev2387"
 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.3.0.dev2385 → ha_mcp_dev-8.3.0.dev2387}/src/ha_mcp/tools/tools_addons.py

@@ -11,6 +11,7 @@ import asyncio
 import json
 import logging
 import re
+import ssl
 import time
 from typing import Annotated, Any, ClassVar, Literal, NoReturn
 from urllib.parse import unquote, urlsplit
@@ -23,7 +24,11 @@ from ha_mcp._vendor import websockets
 from ha_mcp._vendor.websockets.asyncio.client import ClientConnection
 
 from .._version import is_running_in_addon
-from ..client.rest_client import HomeAssistantClient, HomeAssistantCommandError
+from ..client.rest_client import (
+    HomeAssistantClient,
+    HomeAssistantCommandError,
+    _is_ssl_error,
+)
 from ..errors import (
     ErrorCode,
     create_error_response,
@@ -892,6 +897,111 @@ async def _collect_ws_messages_loop(
         total_size += len(clean)
 
 
+def _tls_setup_error(e: Exception, slug: str) -> NoReturn:
+    """Report a CA-store/TLS-context build failure distinctly from network errors."""
+    raise_tool_error(
+        create_error_response(
+            ErrorCode.CONNECTION_FAILED,
+            f"Could not build a TLS context for the app (add-on) request: {e!s}",
+            context={"slug": slug},
+            suggestions=[
+                "The MCP host's CA store failed to load. Check SSL_CERT_FILE "
+                "and SSL_CERT_DIR, or the system certificate bundle.",
+            ],
+        )
+    )
+
+
+def _build_ws_ssl_context(
+    ws_url: str, verify_ssl: bool, slug: str
+) -> ssl.SSLContext | None:
+    """Build the proxy's client TLS context, honoring the HA verify setting."""
+    if not ws_url.startswith("wss://"):
+        return None
+    try:
+        ssl_context = ssl.create_default_context()
+    except OSError as e:
+        _tls_setup_error(e, slug)
+    if not verify_ssl:
+        logger.warning(
+            "TLS verification disabled for add-on WebSocket proxy "
+            "(HA_VERIFY_SSL=false). Connecting to %s with hostname/cert "
+            "checks off.",
+            ws_url,
+        )
+        ssl_context.check_hostname = False
+        ssl_context.verify_mode = ssl.CERT_NONE
+    return ssl_context
+
+
+def _tls_verification_failure_suggestions() -> list[str]:
+    """Name the TLS remedy instead of pointing the caller at the network."""
+    return [
+        "Home Assistant's certificate did not validate. If it is self-signed "
+        "or issued for a different hostname than the configured HA URL, set "
+        "HA_VERIFY_SSL=false to skip verification, or reach HA at the "
+        "hostname the certificate was issued for.",
+    ]
+
+
+def _build_addon_http_client(
+    client: HomeAssistantClient, timeout: int, slug: str
+) -> httpx.AsyncClient:
+    """Build the proxy's HTTP client, honoring the HA verify setting.
+
+    httpx builds its TLS context at construction; doing it before the request
+    try reports a CA-store failure as such rather than letting it escape
+    unstructured.
+    """
+    try:
+        return httpx.AsyncClient(
+            timeout=httpx.Timeout(timeout),
+            verify=client.verify_ssl,
+        )
+    except OSError as e:
+        _tls_setup_error(e, slug)
+        return None  # py/mixed-returns: unreachable, _tls_setup_error raises
+
+
+def _raise_connect_failure(
+    client: HomeAssistantClient,
+    e: Exception,
+    *,
+    label: str,
+    url: str,
+    slug: str,
+    port: int | None,
+) -> NoReturn:
+    """Raise the structured connect-phase error, classifying TLS failures.
+
+    A certificate-verification failure with verification enabled gets the TLS
+    remedy; everything else keeps the route-appropriate network guidance.
+    """
+    if _is_ssl_error(e) and client.verify_ssl:
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.CONNECTION_FAILED,
+                f"TLS verification failed connecting to {label}: {e!s}",
+                details=f"url={url}",
+                context={
+                    "slug": slug,
+                    "direct_port": bool(port),
+                    "verify_ssl": True,
+                },
+                suggestions=_tls_verification_failure_suggestions(),
+            )
+        )
+    raise_tool_error(
+        create_error_response(
+            ErrorCode.CONNECTION_FAILED,
+            f"Failed to connect to {label}: {e!s}",
+            details=f"url={url}",
+            context={"slug": slug, "direct_port": bool(port)},
+            suggestions=_addon_connection_failure_suggestions(client, port),
+        )
+    )
+
+
 async def _run_ws_session(
     ws_url: str,
     headers: dict[str, str],
@@ -900,6 +1010,7 @@ async def _run_ws_session(
     timeout: int,
     wait_for_close: bool,
     caller_capped: bool,
+    ssl_context: ssl.SSLContext | None,
 ) -> tuple[list[str], int, str, float]:
     """Connect to a WebSocket URL, optionally send body, collect messages.
 
@@ -916,6 +1027,7 @@ async def _run_ws_session(
         max_size=5 * 1024 * 1024,  # 5MB max per message
         open_timeout=10,
         close_timeout=5,
+        ssl=ssl_context,
     ) as ws:
         if body is not None:
             await ws.send(json.dumps(body) if isinstance(body, dict) else str(body))
@@ -1024,6 +1136,58 @@ def _build_ws_result(
     return result
 
 
+def _front_door_state(addon: dict[str, Any]) -> bool | None:
+    """Return the app's ``leave_front_door_open`` state, or None when unexposed.
+
+    Supervisor's ``options`` dict omits an option the user never saved even
+    when the app's schema exposes it, and the app treats that absence as
+    disabled — so the schema, not key presence, decides whether the option
+    applies (stock installs ship the key in the schema only).
+    """
+    options = addon.get("options")
+    if isinstance(options, dict) and "leave_front_door_open" in options:
+        return bool(options["leave_front_door_open"])
+    schema = addon.get("schema")
+    if isinstance(schema, list) and any(
+        isinstance(item, dict) and item.get("name") == "leave_front_door_open"
+        for item in schema
+    ):
+        return False
+    return None
+
+
+def _ws_auth_error_suggestions(
+    addon: dict[str, Any], slug: str, port: int | None, status: int
+) -> list[str]:
+    """Return route-appropriate guidance for a rejected WS handshake."""
+    if port:
+        # Prefer the caller-resolved slug; fall back to the addon dict, then a
+        # placeholder, so the suggestion never renders slug=''.
+        slug_val = slug or addon.get("slug") or "<slug>"
+        if _front_door_state(addon) is False:
+            primary = _direct_port_auth_suggestion(slug_val)
+        else:
+            primary = _direct_port_rejection_suggestion()
+    elif is_running_in_addon():
+        # The addon-variant route authenticates with Supervisor ingress
+        # headers, not an ingress session or HA token — do not send the
+        # caller to inspect credentials this request never carried.
+        primary = (
+            "The app (add-on) rejected the ingress-port handshake. This route "
+            "authenticates with Supervisor ingress headers; check that the "
+            "target app is running and its ingress is healthy."
+        )
+    else:
+        primary = (
+            "The ingress session may have expired or your HA token may lack the "
+            "required scope. Verify the token has admin rights and try again."
+        )
+    return [
+        primary,
+        f"Status {status} from the WebSocket handshake.",
+    ]
+
+
 async def _call_addon_ws(
     client: HomeAssistantClient,
     slug: str,
@@ -1115,6 +1279,9 @@ async def _call_addon_ws(
         requested = max(0, message_offset) + max(0, message_limit)
         collection_cap = min(_MAX_WS_MESSAGES, requested)
 
+    # Built before the try so a CA-store failure is reported as such rather
+    # than as the add-on being unreachable.
+    ssl_context = _build_ws_ssl_context(ws_url, client.verify_ssl, slug)
     try:
         collected, total_size, close_reason, elapsed = await _run_ws_session(
             ws_url,
@@ -1124,6 +1291,7 @@ async def _call_addon_ws(
             timeout,
             wait_for_close,
             caller_capped=message_limit is not None,
+            ssl_context=ssl_context,
         )
     except websockets.exceptions.InvalidHandshake as e:
         suggestions = [
@@ -1134,12 +1302,7 @@ async def _call_addon_ws(
         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.",
-                ]
+                suggestions = _ws_auth_error_suggestions(addon, slug, port, status)
         raise_tool_error(
             create_error_response(
                 ErrorCode.SERVICE_CALL_FAILED,
@@ -1177,14 +1340,13 @@ async def _call_addon_ws(
             )
         )
     except OSError as e:
-        raise_tool_error(
-            create_error_response(
-                ErrorCode.CONNECTION_FAILED,
-                f"Failed to connect to add-on '{addon_name}' WebSocket: {e!s}",
-                details=f"url={ws_url}",
-                context={"slug": slug, "direct_port": bool(port)},
-                suggestions=_addon_connection_failure_suggestions(client, port),
-            )
+        _raise_connect_failure(
+            client,
+            e,
+            label=f"app (add-on) '{addon_name}' WebSocket",
+            url=ws_url,
+            slug=slug,
+            port=port,
         )
 
     return _build_ws_result(
@@ -1553,57 +1715,106 @@ def _build_http_result(
     return result
 
 
+def _addon_config_for_http_hint(addon: dict[str, Any]) -> dict[str, Any]:
+    """Return the app settings that can explain direct-access failures."""
+    return {
+        "options": addon.get("options"),
+        "ports": addon.get("network") or addon.get("ports") or None,
+        "host_network": addon.get("host_network"),
+        "ingress_port": addon.get("ingress_port"),
+    }
+
+
+def _direct_port_auth_suggestion(slug: str) -> str:
+    """Explain the configurable direct-access auth trade-off, Ingress first."""
+    return (
+        "The app (add-on) rejected this direct-port request. Prefer Ingress: retry "
+        f"without the 'port' parameter (ha_manage_app(slug='{slug}', "
+        "path='...')). The app's 'leave_front_door_open' option controls "
+        "direct-access authentication; only if the user explicitly accepts "
+        "the security trade-off, use "
+        f"ha_manage_app(slug='{slug}', "
+        "options={'leave_front_door_open': True}), then "
+        f"ha_manage_app(slug='{slug}', action='restart'), and retry. Enabling "
+        "it removes authentication from the app's direct-access surface for "
+        "hosts that can reach the mapped port."
+    )
+
+
+def _direct_port_rejection_suggestion() -> str:
+    """Explain a direct-port rejection the front-door option cannot fix.
+
+    Fires when the app exposes no ``leave_front_door_open`` option, or when it
+    is already enabled — either way the remedy lives in the app's own auth
+    configuration, not in that option.
+    """
+    return (
+        "The app (add-on) rejected this direct-port request. Check the app's own "
+        "authentication and access-control settings, IP allowlist, and logs."
+    )
+
+
 def _add_http_error_hints(
     result: dict[str, Any],
     response: httpx.Response,
     addon: dict[str, Any],
     slug: str,
+    direct_port: bool,
 ) -> None:
     """Mutate result to add an error key for 4xx/5xx responses, with tailored suggestions for 401 and 403."""
     if response.status_code >= 400:
         result["error"] = f"Add-on API returned HTTP {response.status_code}"
+        # Prefer the caller-resolved slug (authoritative); fall back to the
+        # addon dict, then a placeholder only if neither is populated.
+        slug_val = slug or addon.get("slug") or "<slug>"
         if response.status_code == 401:
-            # 401 is a credential/session problem — addon_config is not attached
-            # because the network layout is irrelevant; the caller needs to fix
-            # their token or re-establish the ingress session, not reconfigure ports.
-            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:
-            # 403 is typically an Nginx IP ACL blocking direct access — a
-            # network configuration problem. Attach addon_config so the LLM
-            # can see the port mapping and suggest the correct port override.
-            ports_dict = addon.get("network") or addon.get("ports") or {}
-            unmapped = sorted(k for k, v in ports_dict.items() if v is None)
-            result["addon_config"] = {
-                "options": addon.get("options"),
-                "ports": ports_dict or None,
-                "host_network": addon.get("host_network"),
-                "ingress_port": addon.get("ingress_port"),
-            }
-            # Prefer the caller-resolved slug (authoritative); fall back to the
-            # addon dict, then a placeholder only if neither is populated.
-            slug_val = slug or addon.get("slug") or "<slug>"
-            example_proto = unmapped[0] if unmapped else ""
-            example_port = example_proto.split("/", 1)[0] if example_proto else ""
-            if unmapped and example_port.isdigit():
-                addon_label = addon.get("name") or slug_val
-                result["suggestion"] = (
-                    f"Map {example_proto} to a host port in the HA UI "
-                    f"('{addon_label}' → Configuration → Network), restart the "
-                    f"add-on, then retry with ha_manage_app(slug='{slug_val}', "
-                    f"path='...', port={example_port})."
-                )
+            if direct_port:
+                result["addon_config"] = _addon_config_for_http_hint(addon)
+                if _front_door_state(addon) is False:
+                    result["suggestion"] = _direct_port_auth_suggestion(slug_val)
+                else:
+                    result["suggestion"] = _direct_port_rejection_suggestion()
             else:
+                # An ingress 401 is a credential/session problem. Keep network
+                # configuration out of that result so the caller fixes the HA
+                # token or ingress session instead of weakening app authentication.
                 result["suggestion"] = (
-                    "This add-on is blocking direct connections (likely Nginx IP restriction). "
-                    "Try using the 'port' parameter to connect to the add-on's direct access port "
-                    "(see addon_config.ports above) with 'leave_front_door_open' enabled. "
-                    "Example: ha_manage_app(slug='...', path='...', port=<direct_port>). "
-                    "The user may need to change add-on settings in the HA UI and restart the add-on."
+                    "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:
+            # A direct-port 403 is app-level access control; an ingress 403 is
+            # typically an Nginx IP ACL blocking direct access — a network
+            # configuration problem. Attach addon_config either way so the LLM
+            # can see the port mapping.
+            result["addon_config"] = _addon_config_for_http_hint(addon)
+            if direct_port:
+                if _front_door_state(addon) is False:
+                    result["suggestion"] = _direct_port_auth_suggestion(slug_val)
+                else:
+                    result["suggestion"] = _direct_port_rejection_suggestion()
+            else:
+                ports_dict = addon.get("network") or addon.get("ports") or {}
+                unmapped = sorted(k for k, v in ports_dict.items() if v is None)
+                example_proto = unmapped[0] if unmapped else ""
+                example_port = example_proto.split("/", 1)[0] if example_proto else ""
+                if unmapped and example_port.isdigit():
+                    addon_label = addon.get("name") or slug_val
+                    result["suggestion"] = (
+                        f"Map {example_proto} to a host port in the HA UI "
+                        f"('{addon_label}' → Configuration → Network), restart the "
+                        f"add-on, then retry with ha_manage_app(slug='{slug_val}', "
+                        f"path='...', port={example_port})."
+                    )
+                else:
+                    result["suggestion"] = (
+                        "This add-on is blocking direct connections (likely Nginx IP restriction). "
+                        "Try using the 'port' parameter to connect to the add-on's direct access port "
+                        "(see addon_config.ports above) with 'leave_front_door_open' enabled. "
+                        "Example: ha_manage_app(slug='...', path='...', port=<direct_port>). "
+                        "The user may need to change add-on settings in the HA UI and restart the add-on."
+                    )
 
 
 async def _call_addon_api(
@@ -1713,8 +1924,9 @@ async def _call_addon_api(
     else:
         request_content = None
 
+    addon_http_client = _build_addon_http_client(client, timeout, slug)
     try:
-        async with httpx.AsyncClient(timeout=httpx.Timeout(timeout)) as http_client:
+        async with addon_http_client as http_client:
             response = await http_client.request(
                 method=method.upper(),
                 url=url,
@@ -1738,14 +1950,13 @@ async def _call_addon_api(
             )
         )
     except httpx.ConnectError as e:
-        raise_tool_error(
-            create_error_response(
-                ErrorCode.CONNECTION_FAILED,
-                f"Failed to connect to add-on '{addon_name}': {e!s}",
-                details=f"url={url}",
-                context={"slug": slug, "direct_port": bool(port)},
-                suggestions=_addon_connection_failure_suggestions(client, port),
-            )
+        _raise_connect_failure(
+            client,
+            e,
+            label=f"app (add-on) '{addon_name}'",
+            url=url,
+            slug=slug,
+            port=port,
         )
 
     # 6. Parse response body
@@ -1786,7 +1997,7 @@ async def _call_addon_api(
         transformed,
         truncated,
     )
-    _add_http_error_hints(result, response, addon, slug)
+    _add_http_error_hints(result, response, addon, slug, direct_port=bool(port))
     return result
 
 
@@ -2884,7 +3095,10 @@ def register_addon_tools(mcp: Any, client: HomeAssistantClient, **kwargs: Any) -
             int | None,
             Field(
                 description="Proxy mode only. Connect to this port instead of the Ingress port. "
-                "Use ha_get_app(slug='...') to find available ports.",
+                "Use ha_get_app(slug='...') to find available ports. Some apps, including "
+                "Node-RED, reject direct access unless their leave_front_door_open option is "
+                "enabled and the app is restarted; related errors include an actionable, "
+                "security-qualified ha_manage_app options command.",
                 default=None,
             ),
         ] = None,
@@ -3086,7 +3300,12 @@ def register_addon_tools(mcp: Any, client: HomeAssistantClient, **kwargs: Any) -
         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).
+        share Home Assistant's container network (in practice: the HAOS app
+        (add-on) deployment). Apps such as Node-RED may reject direct requests
+        unless `leave_front_door_open` is enabled in their options and the app
+        is restarted. Authentication errors name the exact
+        `ha_manage_app(options=...)` remedy and its security tradeoff; prefer
+        Ingress when it works.
 
         **ESPHome Device Builder dashboard (current rewrite):** config and log
         access is a WebSocket JSON-command API, NOT REST. The legacy endpoints
@@ -3148,7 +3367,7 @@ def register_addon_tools(mcp: Any, client: HomeAssistantClient, **kwargs: Any) -
         - Change host port: ha_manage_app(slug="...", network={"5800/tcp": 8082})
         - Set boot mode: ha_manage_app(slug="...", boot="manual")
         - Call HTTP API: ha_manage_app(slug="...", path="/api/events")
-        - Direct port: ha_manage_app(slug="...", path="/flows", port=1880)
+        - Direct port: ha_manage_app(slug="...", path="/flows", port=1880) — if the app rejects it, the error names the 'leave_front_door_open' remedy and its security trade-off; prefer Ingress.
         - ESPHome list devices (HTTP): ha_manage_app(slug="<prefix>_esphome", path="/devices")
         - ESPHome read a device's YAML (WS one-shot): ha_manage_app(slug="<prefix>_esphome", path="/ws", websocket=True, wait_for_close=False, message_limit=2, body={"command": "devices/get_config", "message_id": "1", "args": {"configuration": "device.yaml"}})
         - ESPHome live logs (WS, bounded): ha_manage_app(slug="<prefix>_esphome", path="/ws", websocket=True, wait_for_close=False, message_limit=60, body={"command": "devices/logs", "message_id": "1", "args": {"configuration": "device.yaml", "port": "OTA"}})

{ha_mcp_dev-8.3.0.dev2385 → ha_mcp_dev-8.3.0.dev2387/src/ha_mcp_dev.egg-info}/PKG-INFO

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