ha-mcp-dev 7.6.0.dev662__tar.gz → 7.6.0.dev664__tar.gz

{ha_mcp_dev-7.6.0.dev662/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.6.0.dev664}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.6.0.dev662"
+version = "7.6.0.dev664"
 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.6.0.dev662 → ha_mcp_dev-7.6.0.dev664}/src/ha_mcp/__main__.py

@@ -22,6 +22,7 @@ truststore.inject_into_ssl()
 import asyncio  # noqa: E402
 import copy  # noqa: E402
 import hashlib  # noqa: E402
+import ipaddress  # noqa: E402
 import logging  # noqa: E402
 import os  # noqa: E402
 import signal  # noqa: E402
@@ -755,10 +756,93 @@ def _get_http_runtime(default_port: int = 8086) -> tuple[str, int, str]:
     except ValueError:
         logger.error(f"Invalid MCP_PORT value: {port_str!r}. Must be an integer.")
         sys.exit(1)
-    path = os.getenv("MCP_SECRET_PATH", "/mcp")
+    path = os.getenv("MCP_SECRET_PATH", DEFAULT_MCP_PATH)
     return host, port, path
 
 
+# Default ``MCP_SECRET_PATH`` value, shared by ``_get_http_runtime`` (the
+# read-from-env fallback) and ``_warn_if_default_path_exposed`` (the
+# hardening-nudge predicate). Single source of truth so the two sites
+# can't drift.
+DEFAULT_MCP_PATH = "/mcp"
+
+# Hostname literals (not IP addresses) treated as loopback by
+# ``_is_loopback_host``. IP literals — the whole ``127.0.0.0/8`` block,
+# ``::1``, bracketed forms, zone-suffixed forms, and IPv4-mapped IPv6 — are
+# handled by the ``ipaddress`` parse before this set is consulted.
+_LOOPBACK_HOSTNAMES = frozenset({"localhost", "ip6-localhost", "ip6-loopback"})
+
+
+def _is_loopback_host(host: str) -> bool:
+    """Return True when ``host`` names the local machine only.
+
+    Accepts IPv6 hosts in bracketed (``[::1]``) or zone-suffixed
+    (``::1%eth0``) form, the full ``127.0.0.0/8`` range, IPv4-mapped IPv6
+    loopback (``::ffff:127.0.0.1``, which ``is_loopback`` resolves on its
+    own), and the names in ``_LOOPBACK_HOSTNAMES``. A value that is neither
+    an IP literal nor a known loopback name (a real hostname, or a malformed
+    string) is treated as non-loopback.
+    """
+    try:
+        candidate = host.strip("[]").split("%", 1)[0]
+        return ipaddress.ip_address(candidate).is_loopback
+    except ValueError:
+        # Not an IP literal — fall back to the known loopback hostnames.
+        return host.lower() in _LOOPBACK_HOSTNAMES
+
+
+def _is_running_in_container() -> bool:
+    """Best-effort detection of containerized execution.
+
+    Inside a container the server binds ``0.0.0.0`` regardless of how the
+    operator restricted host-side exposure (``docker run -p 127.0.0.1:...``),
+    so the bind host alone can't tell a loopback-only deployment from a
+    LAN-reachable one — the default-path warning would be a false positive
+    for every container. Container deployments are hardened through the
+    published guidance instead (AGENTS.md -> Docker; the add-on
+    auto-generates a secret path).
+    """
+    # Docker writes /.dockerenv; Podman writes /run/.containerenv.
+    if os.path.exists("/.dockerenv") or os.path.exists("/run/.containerenv"):
+        return True
+    # The Home Assistant add-on runs under the Supervisor.
+    return bool(os.getenv("SUPERVISOR_TOKEN"))
+
+
+def _warn_if_default_path_exposed(host: str, port: int, path: str) -> None:
+    """Warn on a direct run that leaves the default path on a LAN bind.
+
+    Standard-mode HTTP/SSE authenticates by URL-path secrecy (see
+    SECURITY.md → Threat Model). The default ``/mcp`` is not the
+    high-entropy secret that model assumes once the bind leaves loopback.
+
+    Fires only for a direct ``ha-mcp-web`` / ``ha-mcp-sse`` start (uvx, pip,
+    source) that uses the default path on a non-loopback host. Operators
+    silence it the same way they harden — bind ``MCP_HOST=127.0.0.1`` or set
+    a high-entropy ``MCP_SECRET_PATH``. Containers are skipped: an
+    in-container ``0.0.0.0`` bind says nothing about real exposure, which is
+    set by the ``docker -p`` mapping the process can't observe (see
+    ``_is_running_in_container``).
+    """
+    if path != DEFAULT_MCP_PATH:
+        return
+    if _is_running_in_container():
+        return
+    if _is_loopback_host(host):
+        return
+    logger.warning(
+        "ha-mcp listening on %s:%s%s with default MCP_SECRET_PATH. "
+        "Standard-mode HTTP/SSE authenticates by URL-path secrecy and assumes "
+        "a high-entropy MCP_SECRET_PATH for non-loopback binds "
+        "(see SECURITY.md → Threat Model). "
+        "Either bind loopback (MCP_HOST=127.0.0.1) or set MCP_SECRET_PATH "
+        "to a high-entropy value (e.g. /private_<token_urlsafe(16)>).",
+        host,
+        port,
+        path,
+    )
+
+
 async def _run_http_with_graceful_shutdown(
     transport: str,
     host: str,
@@ -861,6 +945,7 @@ def _run_http_server(transport: str, default_port: int = 8086) -> None:
     from ha_mcp.settings_ui import register_settings_routes
 
     host, port, path = _get_http_runtime(default_port)
+    _warn_if_default_path_exposed(host, port, path)
     register_browser_landing(_get_mcp(), path)
     register_settings_routes(_get_mcp(), _get_server(), secret_path=path)
     _log_settings_url(host, port, path)

{ha_mcp_dev-7.6.0.dev662 → ha_mcp_dev-7.6.0.dev664}/src/ha_mcp/tools/tools_utility.py

@@ -1099,6 +1099,39 @@ def register_utility_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         Home Assistant automations, scripts, and configurations. It provides real-time evaluation with
         access to all Home Assistant states, functions, and template variables.
 
+        **When NOT to use this for automation/script logic:**
+        Templates have legitimate uses (notification bodies, dynamic `data.*` values,
+        debugging existing templates), but `condition:` / `trigger:` positions and
+        action service names are better expressed as native HA constructs:
+        native constructs are schema-validated at config load and surface
+        structural errors loudly, whereas equivalent template logic only errors
+        at runtime — and a template that renders a non-truthy value is silently
+        treated as false.
+        Prefer:
+        - `condition: numeric_state` over `{{ states('x') | float > N }}`
+        - `condition: state` over `{{ is_state(...) }}`
+        - `condition: time` / `condition: sun` over `now().hour` / `is_state('sun.sun', ...)`
+        - Native `for:` field on state/numeric_state triggers and state conditions over
+          `{{ now() - X.last_changed > timedelta(...) }}` duration math
+        - `choose` action over templated `service:` / `action:` strings
+        See `ha_get_skill_guide` (best-practices skill) for the full anti-pattern list.
+
+        **When to use (reach for this tool, don't compute it yourself):**
+        Any one-shot question whose answer is DERIVED from current HA state — an
+        average/sum/min/max across sensors, a count of entities matching a
+        condition, a boolean comparison, or a rendered message with live values.
+        One render call beats fetching N states and doing the math yourself, and
+        it is the canonical way to *test* a template before embedding it. This is
+        for one-shot answers and template testing only — NOT for putting templates
+        into automation logic; for `condition:` / `trigger:` positions native
+        constructs win.
+        - "average temperature across the bedroom sensors"
+          -> `{{ ([states('sensor.a'), states('sensor.b')] | map('float', 0) | sum) / 2 }}`
+        - "how many lights are on"
+          -> `{{ states.light | selectattr('state', 'eq', 'on') | list | count }}`
+        NOT for a plain single-entity value ("what's the state of X") — that is
+        `ha_get_state` / `ha_search`; rendering `{{ states('X') }}` there is over-use.
+
         **Parameters:**
         - template: The Jinja2 template string to evaluate
         - timeout: Maximum evaluation time in seconds (default: 3)
@@ -1117,8 +1150,8 @@ def register_utility_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         **Numeric Operations:**
         ```jinja2
         {{ states('sensor.temperature') | float(0) }}   # Convert to float with default
-        {{ states('sensor.humidity') | int }}           # Convert to integer
-        {{ (states('sensor.temp') | float + 5) | round(1) }} # Math operations
+        {{ states('sensor.humidity') | int(0) }}        # Convert to integer with default
+        {{ (states('sensor.temp') | float(0) + 5) | round(1) }} # Math operations
         ```
 
         **Time and Date:**
@@ -1163,20 +1196,6 @@ def register_utility_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         {{ device_id('light.bedroom') }}               # Get device ID for entity
         ```
 
-        **When NOT to use this for automation/script logic:**
-        Templates have legitimate uses (notification bodies, dynamic `data.*` values,
-        debugging existing templates), but `condition:` / `trigger:` positions and
-        action service names are better expressed as native HA constructs — they
-        validate at config load, fail loudly, and avoid silent runtime failures.
-        Prefer:
-        - `condition: numeric_state` over `{{ states('x') | float > N }}`
-        - `condition: state` over `{{ is_state(...) }}`
-        - `condition: time` / `condition: sun` over `now().hour` / `is_state('sun.sun', ...)`
-        - Native `for:` field on state/numeric_state triggers and state conditions over
-          `{{ now() - X.last_changed > timedelta(...) }}` duration math
-        - `choose` action over templated `service:` / `action:` strings
-        See `ha_get_skill_guide` (best-practices skill) for the full anti-pattern list.
-
         **Common Use Cases (legitimate template positions):**
 
         **Dynamic Service Data:**
@@ -1202,7 +1221,7 @@ def register_utility_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
 
         **Test mathematical operations:**
         ```python
-        ha_eval_template("{{ (states('sensor.temperature') | float + 5) | round(1) }}")
+        ha_eval_template("{{ (states('sensor.temperature') | float(0) + 5) | round(1) }}")
         ```
 
         **Test entity counting:**

{ha_mcp_dev-7.6.0.dev662 → ha_mcp_dev-7.6.0.dev664/src/ha_mcp_dev.egg-info}/PKG-INFO

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