ha-mcp-dev 9.1.0.dev3339__tar.gz → 9.1.0.dev3344__tar.gz

{ha_mcp_dev-9.1.0.dev3339 → ha_mcp_dev-9.1.0.dev3344}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 9.1.0.dev3339
+Version: 9.1.0.dev3344
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien

{ha_mcp_dev-9.1.0.dev3339 → ha_mcp_dev-9.1.0.dev3344}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.1.0.dev3339"
+version = "9.1.0.dev3344"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.15"

{ha_mcp_dev-9.1.0.dev3339 → ha_mcp_dev-9.1.0.dev3344}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.1.0.dev3339"
+version = "9.1.0.dev3344"
 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-9.1.0.dev3339 → ha_mcp_dev-9.1.0.dev3344}/src/ha_mcp/read_only.py

@@ -31,7 +31,6 @@ whether the call is a read (allowed) or a write (blocked).
 
 from __future__ import annotations
 
-import json
 import logging
 from collections.abc import Awaitable, Callable, Iterator, Sequence
 from contextlib import contextmanager
@@ -49,7 +48,7 @@ from ha_mcp._vendor.fastmcp.tools import Tool
 from .config import get_global_settings
 from .errors import ErrorCode, create_error_response
 from .renamed_tools import current_tool_name
-from .tool_dispatch import CALL_PROXY_META_TOOLS
+from .tool_dispatch import CALL_PROXY_META_TOOLS, coerce_proxy_arguments
 from .tools.helpers import raise_tool_error
 
 if TYPE_CHECKING:
@@ -477,32 +476,6 @@ class ReadOnlyMiddleware(Middleware):
             return "write"
         return "unknown"
 
-    @staticmethod
-    def _coerce_arguments(arguments: Any) -> dict[str, Any] | None:
-        """Normalise a proxy envelope's ``arguments`` to a dict or None.
-
-        The categorized proxies tolerate ``arguments`` arriving as a JSON
-        string (small models sometimes serialize it) and json.loads it
-        AFTER this middleware runs (categorized_search.py ~313-352). So:
-        a dict is used as-is; an absent value (``None``) becomes ``{}``
-        (a legitimate no-argument call, not malformed); a string is
-        parsed and only a JSON *object* yields a dict. Anything else — an
-        unparseable string, a non-dict JSON value (list/scalar/null), or
-        a non-str/non-dict type — returns None, meaning "malformed
-        envelope".
-        """
-        if isinstance(arguments, dict):
-            return arguments
-        if arguments is None:
-            return {}
-        if isinstance(arguments, str):
-            try:
-                parsed = json.loads(arguments)
-            except (json.JSONDecodeError, ValueError):
-                return None
-            return parsed if isinstance(parsed, dict) else None
-        return None
-
     @classmethod
     def _unwrap_proxy_call(
         cls,
@@ -518,7 +491,7 @@ class ReadOnlyMiddleware(Middleware):
         lets the middleware decide on the inner call first. Mirrors the
         proxy's own double-wrap unwrapping.
 
-        ``arguments`` is coerced at every level (see _coerce_arguments)
+        ``arguments`` is coerced at every level (see coerce_proxy_arguments)
         because the proxy accepts it as a JSON string. Returns None when
         there is no usable envelope — including when ``arguments`` is a
         MALFORMED string (json.loads fails, or the JSON is not an object).
@@ -528,7 +501,7 @@ class ReadOnlyMiddleware(Middleware):
         (categorized_search.py ~313-352), so no write can occur.
         """
         name = args.get("name")
-        arguments = cls._coerce_arguments(args.get("arguments"))
+        arguments = coerce_proxy_arguments(args.get("arguments"))
         while (
             isinstance(name, str)
             and name in CALL_PROXY_META_TOOLS
@@ -536,7 +509,7 @@ class ReadOnlyMiddleware(Middleware):
             and isinstance(arguments.get("name"), str)
         ):
             name = arguments.get("name")
-            arguments = cls._coerce_arguments(arguments.get("arguments"))
+            arguments = coerce_proxy_arguments(arguments.get("arguments"))
         if not isinstance(name, str):
             return None
         if arguments is None:

{ha_mcp_dev-9.1.0.dev3339 → ha_mcp_dev-9.1.0.dev3344}/src/ha_mcp/settings_ui/locales/en.json

@@ -519,7 +519,7 @@
     "advanced.sidecar_pin_port.label": "Settings UI sidecar port",
     "advanced.sidecar_pin_port.help": "0 picks a free port on first start and keeps it for later restarts; a port in the range pins a preferred port (falls back to a free one if taken).",
     "advanced.enable_dev_mode.label": "Developer mode",
-    "advanced.enable_dev_mode.help": "⚠ Registers hidden tools that can change settings and replace the running server. Development and testing only.",
+    "advanced.enable_dev_mode.help": "⚠ Registers hidden tools that can change settings and replace the running server. It also may bypass some entity visibility or other limitations. Development and testing only.",
     "advanced.dev_tools_security_policy_access.label": "Dev tools security policy access",
     "advanced.dev_tools_security_policy_access.help": "⚠ While developer mode is on, lets the developer tools rewrite tool security policies, add or remove per-tool approval gates, and approve or deny pending approvals on your behalf — an AI agent can accept its own gated calls. Policy testing only. Takes effect without a restart.",
     "addon.secret_path.name": "Secret path override",

{ha_mcp_dev-9.1.0.dev3339 → ha_mcp_dev-9.1.0.dev3344}/src/ha_mcp/stdio_settings_sidecar.py

@@ -62,7 +62,7 @@ import socket
 import subprocess
 import sys
 import threading
-from collections.abc import Awaitable, Callable, Iterator
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterator
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
@@ -183,12 +183,7 @@ def _save_sidecar_state(port: int, secret_path: str) -> None:
 
 
 def read_sidecar_url() -> str | None:
-    """Return the current sidecar URL, or None if no sidecar is running.
-
-    Reads ``~/.ha-mcp/ui.url`` if present. Consumed by
-    ``ha_get_overview`` to surface the URL to the LLM (and through it,
-    the user) on every overview call.
-    """
+    """Return the URL recorded in ``ui.url``, or None when absent/unreadable."""
     try:
         return _url_file().read_text().strip() or None
     except FileNotFoundError:
@@ -198,6 +193,14 @@ def read_sidecar_url() -> str | None:
         return None
 
 
+def live_sidecar_url() -> str | None:
+    """Return the URL ``ha_get_overview`` may surface: UI enabled, recorded pid alive."""
+    pid = _read_recorded_pid()
+    if _is_disabled() or pid is None or not _pid_alive(pid):
+        return None
+    return read_sidecar_url()
+
+
 def _is_disabled() -> bool:
     """Check whether the sidecar should be skipped."""
     val = os.environ.get("HA_MCP_DISABLE_SETTINGS_UI", "").strip().lower()
@@ -817,10 +820,10 @@ def _bind_listener(preferred: int, source: str) -> socket.socket:
 def maybe_spawn(prepare: Callable[[], None] | None = None) -> None:
     """Retire any previous sidecar and spawn a fresh one.
 
-    Called once from stdio ``main()`` after argument validation. No-op
-    when the sidecar is disabled (env var or sentinel), when a
-    concurrent parent already holds the spawn lock, or when subprocess
-    spawn raises (best effort; the MCP server continues regardless).
+    Called once from stdio ``main()`` after argument validation. When the
+    sidecar is disabled (env var or sentinel) it only retires a running one
+    (#2954). No-op when a concurrent parent already holds the spawn lock or
+    when subprocess spawn raises (best effort; the MCP server continues).
 
     A previously spawned sidecar is never reused (issue #2131): it
     serves the code and environment of the parent that spawned it, which
@@ -838,6 +841,9 @@ def maybe_spawn(prepare: Callable[[], None] | None = None) -> None:
             "Settings UI sidecar disabled (env var or %s sentinel); skipping spawn.",
             _disabled_sentinel().name,
         )
+        with _spawn_lock() as acquired:
+            if acquired:
+                _shutdown_existing_sidecar()
         return
 
     # Serialize concurrent spawn attempts. Two parent stdio processes
@@ -953,10 +959,10 @@ def _do_spawn() -> None:
         if log_handle is not None:
             log_handle.close()
         return
+    # Reap the child on exit: a zombie still passes os.kill(pid, 0) (#2954).
+    threading.Thread(target=proc.wait, name="sidecar-reaper", daemon=True).start()
 
-    # The child writes its own pid/url file once it's bound — but log the
-    # spawn here so users grepping the parent stderr see something
-    # immediately, even before the child reports back.
+    # Log now so parent stderr shows the spawn before the child publishes.
     logger.info(
         "Spawned settings UI sidecar pid=%d (log: %s). URL written to %s once ready.",
         proc.pid,
@@ -1131,13 +1137,6 @@ def _write_pid_url(url: str) -> None:
                 pid_path.unlink()
 
 
-# Note: a custom ``_install_shutdown_handlers`` lived here previously.
-# Removed because uvicorn's ``Server.run()`` already installs SIGTERM /
-# SIGINT handlers that set ``should_exit = True`` — the same behavior
-# the custom handler provided. The /shutdown HTTP endpoint reaches the
-# same stop callable via ``app.state.shutdown_state`` and is unaffected.
-
-
 def _build_shutdown_handler(
     shutdown_lock: threading.Lock,
     shutdown_state: dict[str, Callable[[], None] | None],
@@ -1348,12 +1347,18 @@ def _build_app(
         )
     )
 
+    # uvicorn re-raises a captured SIGTERM after shutdown, killing the process
+    # before run_main's finally; app shutdown is the last code a signal reaches.
+    @contextlib.asynccontextmanager
+    async def _lifespan(_app: Any) -> AsyncIterator[None]:
+        yield
+        _cleanup_owned_serving_files()
+
     app = Starlette(
         routes=routes,
         middleware=[Middleware(SecurityMiddleware)],
+        lifespan=_lifespan,
     )
-    # Stash the shutdown_state on the app so run_main() can install the
-    # uvicorn stop callable into it once the server is built.
     app.state.shutdown_state = shutdown_state
     app.state.shutdown_lock = shutdown_lock
     return app
@@ -1438,10 +1443,8 @@ def run_main() -> int:
     def _stop() -> None:
         server.should_exit = True
 
-    # Wire the stop callable into app state so the /shutdown HTTP
-    # endpoint can reach it. OS signals (SIGTERM / SIGINT) are handled
-    # by uvicorn's own ``Server.run()`` installation — see the note
-    # earlier in this module for why we don't install our own.
+    # Wire the stop callable into app state so the /shutdown HTTP endpoint
+    # can reach it; uvicorn's ``Server.run()`` handles SIGTERM / SIGINT.
     with app.state.shutdown_lock:
         app.state.shutdown_state["stop"] = _stop
 
@@ -1465,12 +1468,8 @@ def run_main() -> int:
         # exists to close.
         server.run(sockets=[listener])
     finally:
-        # Best-effort cleanup of serving files on graceful exit — but only
-        # the ones this process still owns. The retire wait in
-        # _shutdown_existing_sidecar is bounded, so a slow exit can outlive
-        # its replacement's file writes; a blind unlink here would delete
-        # the NEW sidecar's discovery files. (ui.state is deliberately
-        # never cleaned: it carries the stable URL to the next spawn.)
+        # Covers exits that never reach app shutdown. ui.state is kept on
+        # purpose: it carries the stable URL to the next spawn.
         _cleanup_owned_serving_files()
 
     return 0

{ha_mcp_dev-9.1.0.dev3339 → ha_mcp_dev-9.1.0.dev3344}/src/ha_mcp/tool_dispatch.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import json
 from typing import Any
 
 # Call proxies dispatch the envelope's ``name`` back through middleware. Policy
@@ -37,3 +38,25 @@ def is_approval_management_call(name: str, args: dict[str, Any]) -> bool:
         name == _APPROVAL_MANAGEMENT_TOOL
         and args.get("action") in _APPROVAL_MANAGEMENT_ACTIONS
     )
+
+
+def coerce_proxy_arguments(arguments: Any) -> dict[str, Any] | None:
+    """Normalise a call-proxy envelope's ``arguments`` to a dict or None.
+
+    The categorized proxies tolerate ``arguments`` arriving as a JSON string
+    (small models sometimes serialize it) and json.loads it after middleware
+    runs. A dict is used as-is; an absent value (``None``) becomes ``{}`` (a
+    legitimate no-argument call); a string is parsed and only a JSON *object*
+    yields a dict. Anything else returns None, meaning "malformed envelope".
+    """
+    if isinstance(arguments, dict):
+        return arguments
+    if arguments is None:
+        return {}
+    if isinstance(arguments, str):
+        try:
+            parsed = json.loads(arguments)
+        except (json.JSONDecodeError, ValueError, RecursionError):
+            return None
+        return parsed if isinstance(parsed, dict) else None
+    return None

{ha_mcp_dev-9.1.0.dev3339 → ha_mcp_dev-9.1.0.dev3344}/src/ha_mcp/tools/tools_search.py

@@ -647,17 +647,17 @@ class SearchTools(ComponentSearchMixin, OverviewMixin, StateMixin):
                 ),
             }
 
-        # Surface the stdio settings UI sidecar URL when a URL file is present.
+        # Surface the stdio settings UI sidecar URL while a sidecar serves it.
         # Added *after* ``project_fields`` so it survives every ``fields=`` projection
         # (issue #863).
-        from ..stdio_settings_sidecar import read_sidecar_url
+        from ..stdio_settings_sidecar import live_sidecar_url
 
         projected = project_fields(
             result,
             parsed_fields,
             available_fields=_OVERVIEW_AVAILABLE_FIELDS,
         )
-        sidecar_url = read_sidecar_url()
+        sidecar_url = live_sidecar_url()
         if sidecar_url:
             projected["settings_url"] = sidecar_url
         else:

{ha_mcp_dev-9.1.0.dev3339 → ha_mcp_dev-9.1.0.dev3344}/src/ha_mcp/visibility/enforcement.py

@@ -5,7 +5,8 @@ The visibility filter (``visibility/``) normally only declutters ``ha_search`` /
 ``"enforce": true`` in ``entity_visibility.json``), the
 :class:`VisibilityInboundEnforcement` / :class:`VisibilityOutboundEnforcement`
 middleware pair makes the hidden set unreadable across tool reads, except for
-the deliberately unrestricted-by-default ``ha_report_issue`` diagnostic
+the never-gated server tools (``ha_get_skill_guide``, ``ha_search_tools``,
+``ha_dev_*``) and the unrestricted-by-default ``ha_report_issue`` diagnostic
 escape hatch — "refuse on contact":
 
 - **Direct reads are concealed.** A call whose arguments name a hidden entity_id
@@ -67,7 +68,7 @@ from ha_mcp._vendor.fastmcp.server.middleware.middleware import (
 
 from ..errors import ErrorCode, create_entity_not_found_error, create_error_response
 from ..renamed_tools import current_tool_name
-from ..tool_dispatch import CALL_PROXY_META_TOOLS
+from ..tool_dispatch import CALL_PROXY_META_TOOLS, coerce_proxy_arguments
 from ..tools.helpers import raise_tool_error
 from . import resolver
 from .identifier_aliases import (
@@ -107,6 +108,10 @@ _CUSTOM_TOOL = "ha_manage_custom_tool"
 
 # Diagnostic tool deliberately outside the visibility barrier unless opted in.
 _REPORT_ISSUE_TOOL = "ha_report_issue"
+# Always outside the barrier: bundled docs and tool schemas whose examples can
+# name a hidden id (#2949), and the ha_dev_* developer override by design.
+_UNGATED_TOOLS = frozenset({"ha_get_skill_guide", "ha_search_tools"})
+_UNGATED_PREFIX = "ha_dev_"
 # State reads have a shape-bounded scrub exception before the outbound scan.
 _STATE_TOOL = "ha_get_state"
 
@@ -511,21 +516,6 @@ def _unscannable_reason(name: str, args: dict[str, Any]) -> str | None:
     return None
 
 
-def _coerce_arguments(arguments: Any) -> dict[str, Any] | None:
-    """Normalise a proxy envelope's ``arguments`` to a dict or None (mirrors read_only)."""
-    if isinstance(arguments, dict):
-        return arguments
-    if arguments is None:
-        return {}
-    if isinstance(arguments, str):
-        try:
-            parsed = json.loads(arguments)
-        except (json.JSONDecodeError, ValueError):
-            return None
-        return parsed if isinstance(parsed, dict) else None
-    return None
-
-
 def _unwrap_proxy_call(args: dict[str, Any]) -> tuple[str, dict[str, Any]] | None:
     """Extract the innermost proxy target and arguments, or None if unusable.
 
@@ -540,7 +530,7 @@ def _unwrap_proxy_call(args: dict[str, Any]) -> tuple[str, dict[str, Any]] | Non
     if not isinstance(raw_name, str):
         return None
     name = current_tool_name(raw_name)
-    arguments = _coerce_arguments(args.get("arguments"))
+    arguments = coerce_proxy_arguments(args.get("arguments"))
     while (
         name in CALL_PROXY_META_TOOLS
         and isinstance(arguments, dict)
@@ -548,7 +538,7 @@ def _unwrap_proxy_call(args: dict[str, Any]) -> tuple[str, dict[str, Any]] | Non
     ):
         raw_name = arguments["name"]
         name = current_tool_name(raw_name)
-        arguments = _coerce_arguments(arguments.get("arguments"))
+        arguments = coerce_proxy_arguments(arguments.get("arguments"))
     if arguments is None:
         return None
     return name, arguments
@@ -599,13 +589,10 @@ class _VisibilityEnforcementBase(Middleware):
             resolver.load_visibility_config, resolver.get_data_dir()
         )
 
-    async def _active_config(
-        self,
-        tool_name: str,
-        *,
-        emit_report_issue_diagnostic: bool = False,
+    async def _load_config_or_last_good(
+        self, tool_name: str
     ) -> VisibilityConfig | None:
-        """Return the config when enforce is active, ``None`` when passthrough.
+        """Load the config, falling back to the last good load (``None`` if none).
 
         The active-mode gate must not crash the call with an opaque trace on an
         unloadable config (a hand-edit typo would break EVERY tool call), nor
@@ -613,7 +600,7 @@ class _VisibilityEnforcementBase(Middleware):
         enforce was on). Policy: fall back to the last config this process
         loaded successfully — for the common non-enforce install that preserves
         availability, and for an enforce install it preserves the boundary.
-        With no good load ever, fail CLOSED like PolicyMiddleware does.
+        With no good load ever, the caller fails CLOSED like PolicyMiddleware.
 
         Each half diagnoses a distinct config-load failure. A context-local
         marker suppresses only the second traceback when both halves fail during
@@ -643,6 +630,18 @@ class _VisibilityEnforcementBase(Middleware):
                 )
                 if warning_emitted is not None:
                     _config_load_warning_emitted.set(True)
+        return config
+
+    async def _active_config(
+        self,
+        tool_name: str,
+        *,
+        emit_report_issue_diagnostic: bool = False,
+    ) -> VisibilityConfig | None:
+        """Return the config when enforce is active, ``None`` when passthrough."""
+        if tool_name in _UNGATED_TOOLS or tool_name.startswith(_UNGATED_PREFIX):
+            return None
+        config = await self._load_config_or_last_good(tool_name)
         # ``ha_report_issue`` is an unconditional diagnostic escape hatch while
         # the toggle is off, not only a registry-failure fallback. A missing or
         # corrupt first config load follows that safe default; a last-known-good