ha-mcp-dev 8.2.0.dev2364__tar.gz → 8.2.0.dev2367__tar.gz

{ha_mcp_dev-8.2.0.dev2364/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.2.0.dev2367}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.2.0.dev2364"
+version = "8.2.0.dev2367"
 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.2.0.dev2364 → ha_mcp_dev-8.2.0.dev2367}/src/ha_mcp/policy/middleware.py

@@ -20,21 +20,23 @@ from .model import Policy, Rule
 
 logger = logging.getLogger(__name__)
 
-# Toolsearch proxy meta-tools — always pass through. Gating the proxy
-# directly would be wrong: rule predicates target the REAL tool's args
-# (e.g. args.domain), but the proxy receives wrapped {"name": "...",
-# "arguments": {...}} envelopes. The proxy re-dispatches via
-# ctx.fastmcp.call_tool(name, arguments), which re-enters the middleware
-# chain with the real tool name and args, so the inner call gets gated
-# correctly there.
-PROXY_META_TOOLS = frozenset(
+# Dispatching call proxies are a strict subset of the ungated tool-search
+# meta-tools. Only these three execute their envelope's ``name``; search merely
+# returns catalog metadata and must not be unwrapped by other middleware.
+# Gating a call proxy directly would be wrong: rule predicates target the real
+# tool's args (for example args.domain), while the proxy receives a wrapped
+# {"name": "...", "arguments": {...}} envelope. Its dispatch re-enters the
+# middleware chain with the real name and args, so the inner call is gated there.
+CALL_PROXY_META_TOOLS = frozenset(
     {
         "ha_call_read_tool",
         "ha_call_write_tool",
         "ha_call_delete_tool",
-        "ha_search_tools",
     }
 )
+# Policy itself also leaves catalog search ungated; unlike the call proxies it
+# never dispatches a tool named in client-supplied arguments.
+PROXY_META_TOOLS = CALL_PROXY_META_TOOLS | {"ha_search_tools"}
 
 # ha_dev_manage_server actions that MANAGE the approval queue itself.
 # Gating these deadlocks by construction: with a wildcard (or

{ha_mcp_dev-8.2.0.dev2364 → ha_mcp_dev-8.2.0.dev2367}/src/ha_mcp/read_only.py

@@ -39,7 +39,7 @@ from fastmcp.tools import Tool
 
 from .config import get_global_settings
 from .errors import ErrorCode, create_error_response
-from .policy.middleware import PROXY_META_TOOLS
+from .policy.middleware import CALL_PROXY_META_TOOLS
 from .renamed_tools import current_tool_name
 from .tools.helpers import raise_tool_error
 
@@ -428,7 +428,7 @@ class ReadOnlyMiddleware(Middleware):
         arguments = cls._coerce_arguments(args.get("arguments"))
         while (
             isinstance(name, str)
-            and name in PROXY_META_TOOLS
+            and name in CALL_PROXY_META_TOOLS
             and isinstance(arguments, dict)
             and isinstance(arguments.get("name"), str)
         ):
@@ -460,12 +460,14 @@ class ReadOnlyMiddleware(Middleware):
         args = context.message.arguments or {}
 
         # Call proxies: decide on the INNER call (see _unwrap_proxy_call).
-        # ha_search_tools and envelope-less proxy calls pass through —
-        # searching is a read, and the proxy raises its own validation
-        # error for a missing inner name. When the inner call is allowed,
-        # the proxy dispatch re-enters this middleware with the real tool
-        # name anyway (harmless re-check, same verdict).
-        if name in PROXY_META_TOOLS:
+        # Envelope-less proxy calls pass through because the proxy raises its own
+        # validation error for a missing inner name. When the inner call is
+        # allowed, proxy dispatch re-enters this middleware with the real tool name
+        # anyway (harmless re-check, same verdict). ``ha_search_tools`` is not a
+        # dispatch proxy; it reaches generic classification below as an unknown
+        # synthetic tool, which passes through to the search transform (or the
+        # stale-tool hint path when search is disabled).
+        if name in CALL_PROXY_META_TOOLS:
             unwrapped = self._unwrap_proxy_call(args)
             if unwrapped is None:
                 return await call_next(context)

{ha_mcp_dev-8.2.0.dev2364 → ha_mcp_dev-8.2.0.dev2367}/src/ha_mcp/settings_ui/__init__.py

@@ -312,21 +312,25 @@ def _build_visibility_handlers(*, data_dir: Path) -> dict[str, Any]:
             new_config = VisibilityConfig.model_validate(await request.json())
         except (ValidationError, ValueError) as e:
             return JSONResponse({"error": str(e)}, status_code=400)
-        # Optimistic concurrency: reject if the on-disk version moved between
-        # this caller's GET and PUT.
-        current = load_visibility_config(data_dir)
-        if new_config.version != current.version:
-            return JSONResponse(
-                {
-                    "error": (
-                        "Visibility config version mismatch. Reload before saving."
-                    ),
-                    "current_version": current.version,
-                    "current_config": current.model_dump(mode="json"),
-                },
-                status_code=409,
-            )
-        save_visibility_config(data_dir, new_config)
+        # The guard makes the version check a real cross-process
+        # compare-and-swap: the stdio settings sidecar and main MCP process can
+        # both write this file.
+        from ..utils.config_write_lock import config_write_guard
+
+        async with config_write_guard():
+            current = load_visibility_config(data_dir)
+            if new_config.version != current.version:
+                return JSONResponse(
+                    {
+                        "error": (
+                            "Visibility config version mismatch. Reload before saving."
+                        ),
+                        "current_version": current.version,
+                        "current_config": current.model_dump(mode="json"),
+                    },
+                    status_code=409,
+                )
+            save_visibility_config(data_dir, new_config)
         return JSONResponse({"saved": True, "version": new_config.version + 1})
 
     return {

{ha_mcp_dev-8.2.0.dev2364 → ha_mcp_dev-8.2.0.dev2367}/src/ha_mcp/settings_ui/locales/en.json

@@ -96,8 +96,10 @@
     "visibility.boundary": "Without enforce mode (below), this is noise reduction, not access control: a hidden entity is still returned by a direct read of its entity_id and still appears in automation, dashboard, and template content. Do not rely on the filter alone as a security boundary.",
     "visibility.enabled": "Enable entity visibility filter",
     "visibility.enforce.title": "Enforce mode",
-    "visibility.enforce.help": "Extends the filter from decluttering search and overview to every tool read. A direct read of a hidden entity returns “not found”, and a content read (dashboard, template, automation, trace, log, or file) that would surface a hidden entity is refused. Best-effort concealment against incidental exposure, not a hardened security boundary.",
-    "visibility.enforce.only_enforced": "Make hidden entities unreadable across all tools (not just search)",
+    "visibility.enforce.help": "Extends the filter from decluttering search and overview to every tool read except ha_report_issue by default. A direct read of a hidden entity returns “not found”, and a content read that would surface one is refused. The report-tool exception is controlled below. Best-effort concealment against incidental exposure, not a hardened security boundary.",
+    "visibility.enforce.only_enforced": "Make hidden entities unreadable across tool reads (except issue reports by default)",
+    "visibility.enforce.report_issue_help": "While this is off, ha_report_issue and all of its diagnostic output—including logs—stay outside enforce mode on every call, even when visibility data is healthy or unavailable. Turn it on to scan and refuse that tool like other reads.",
+    "visibility.enforce.restrict_report_issue": "Apply enforce mode to ha_report_issue",
     "visibility.categories.title": "Hide by category",
     "visibility.categories.help": "Home Assistant tags auto-generated entities as diagnostic or config.",
     "visibility.categories.legend": "Entity categories to hide",

{ha_mcp_dev-8.2.0.dev2364 → ha_mcp_dev-8.2.0.dev2367}/src/ha_mcp/settings_ui/settings.html

@@ -485,8 +485,10 @@
 
   <section class="a11y-section">
     <h2 class="a11y-section-title" data-i18n="visibility.enforce.title">Enforce mode</h2>
-    <p class="a11y-section-help" data-i18n="visibility.enforce.help">Extends the filter from decluttering search and overview to every tool read. A direct read of a hidden entity returns &ldquo;not found&rdquo;, and a content read (dashboard, template, automation, trace, log, or file) that would surface a hidden entity is refused. Best-effort concealment against incidental exposure, not a hardened security boundary.</p>
-    <label class="a11y-option"><input type="checkbox" id="visibility-enforce"> <span data-i18n="visibility.enforce.only_enforced">Make hidden entities unreadable across all tools (not just search)</span></label>
+    <p class="a11y-section-help" data-i18n="visibility.enforce.help">Extends the filter from decluttering search and overview to every tool read except ha_report_issue by default. A direct read of a hidden entity returns &ldquo;not found&rdquo;, and a content read that would surface one is refused. The report-tool exception is controlled below. Best-effort concealment against incidental exposure, not a hardened security boundary.</p>
+    <label class="a11y-option"><input type="checkbox" id="visibility-enforce"> <span data-i18n="visibility.enforce.only_enforced">Make hidden entities unreadable across tool reads (except issue reports by default)</span></label>
+    <p class="a11y-section-help" data-i18n="visibility.enforce.report_issue_help">While this is off, ha_report_issue and all of its diagnostic output&mdash;including logs&mdash;stay outside enforce mode on every call, even when visibility data is healthy or unavailable. Turn it on to scan and refuse that tool like other reads.</p>
+    <label class="a11y-option"><input type="checkbox" id="visibility-restrict-report-issue"> <span data-i18n="visibility.enforce.restrict_report_issue">Apply enforce mode to ha_report_issue</span></label>
   </section>
 
   <section class="a11y-section">

{ha_mcp_dev-8.2.0.dev2364 → ha_mcp_dev-8.2.0.dev2367}/src/ha_mcp/settings_ui/settings.js

@@ -4488,6 +4488,7 @@ async function visibilityLoadConfig() {
   const cats = c.exclude_categories || [];
   document.getElementById('visibility-enabled').checked = !!c.enabled;
   document.getElementById('visibility-enforce').checked = !!c.enforce;
+  document.getElementById('visibility-restrict-report-issue').checked = !!c.restrict_report_issue;
   document.getElementById('visibility-cat-diagnostic').checked = cats.includes('diagnostic');
   document.getElementById('visibility-cat-config').checked = cats.includes('config');
   document.getElementById('visibility-exclude-hidden').checked = !!c.exclude_hidden;
@@ -4509,6 +4510,7 @@ async function visibilitySaveConfig() {
     version: visibilityVersion,
     enabled: document.getElementById('visibility-enabled').checked,
     enforce: document.getElementById('visibility-enforce').checked,
+    restrict_report_issue: document.getElementById('visibility-restrict-report-issue').checked,
     exclude_categories: cats,
     exclude_hidden: document.getElementById('visibility-exclude-hidden').checked,
     deny_entity_ids: _visibilityParseList(document.getElementById('visibility-deny').value, '\n'),

{ha_mcp_dev-8.2.0.dev2364 → ha_mcp_dev-8.2.0.dev2367}/src/ha_mcp/stdio_settings_sidecar.py

@@ -277,7 +277,15 @@ def _no_proxy_opener() -> Any:
     """
     import urllib.request
 
-    return urllib.request.build_opener(urllib.request.ProxyHandler({}))
+    class _NoRedirectHandler(urllib.request.HTTPRedirectHandler):
+        """Keep the loopback-only shutdown request on its original target."""
+
+        def redirect_request(self, *_args: Any, **_kwargs: Any) -> None:
+            return None
+
+    return urllib.request.build_opener(
+        urllib.request.ProxyHandler({}), _NoRedirectHandler()
+    )
 
 
 # Shape run_main() writes into ui.url. Doubles as the legacy-migration
@@ -287,6 +295,15 @@ _SIDECAR_URL_RE = re.compile(
 )
 
 
+def _is_trusted_sidecar_url(url: str) -> bool:
+    """Return whether a URL matches the loopback sidecar producer contract."""
+    match = _SIDECAR_URL_RE.fullmatch(url.strip())
+    if match is None:
+        return False
+    port = int(match.group(1))
+    return 1024 <= port <= 65535
+
+
 def _seed_state_from_url(url: str) -> None:
     """Migrate a pre-``ui.state`` install's stable URL into the state file.
 
@@ -335,6 +352,13 @@ def _post_shutdown(url: str) -> tuple[bool, bool | None]:
     """
     import urllib.error
 
+    if not _is_trusted_sidecar_url(url):
+        logger.warning(
+            "Recorded sidecar URL is invalid; refusing the shutdown request and "
+            "replacing state files only."
+        )
+        return False, None
+
     try:
         import urllib.request
 
@@ -384,6 +408,185 @@ def _post_shutdown(url: str) -> tuple[bool, bool | None]:
     return False, None
 
 
+def _read_external_retirement_url(config_dir: Path) -> str | None:
+    """Read the sidecar URL used by an external-process cleanup."""
+    url_path = config_dir / "ui.url"
+    try:
+        url = url_path.read_text(encoding="utf-8").strip()
+    except FileNotFoundError:
+        logger.debug("Sidecar URL file %s not found; nothing to retire.", url_path)
+        return None
+    except PermissionError:
+        logger.warning(
+            "Cannot read sidecar URL file %s; a detached listener may still be "
+            "running for config dir %s.",
+            url_path,
+            config_dir,
+            exc_info=True,
+        )
+        return None
+    except OSError:
+        logger.warning(
+            "Failed to read sidecar URL file %s; a detached listener may still be "
+            "running for config dir %s.",
+            url_path,
+            config_dir,
+            exc_info=True,
+        )
+        return None
+    if not url:
+        logger.warning(
+            "Sidecar URL file %s is empty; a detached listener may still be running "
+            "for config dir %s.",
+            url_path,
+            config_dir,
+        )
+        return None
+    return url
+
+
+def _read_external_retirement_pid(config_dir: Path) -> int | None:
+    """Read the recorded PID so an acknowledged retirement can await exit."""
+    pid_path = config_dir / "ui.pid"
+    try:
+        return int(pid_path.read_text(encoding="utf-8").strip())
+    except FileNotFoundError:
+        logger.debug("Sidecar PID file %s not found; exit cannot be polled.", pid_path)
+    except PermissionError:
+        logger.warning(
+            "Cannot read sidecar PID file %s; exit cannot be polled for config dir %s.",
+            pid_path,
+            config_dir,
+            exc_info=True,
+        )
+    except OSError:
+        logger.warning(
+            "Failed to read sidecar PID file %s; exit cannot be polled for config "
+            "dir %s.",
+            pid_path,
+            config_dir,
+            exc_info=True,
+        )
+    except ValueError:
+        logger.warning(
+            "Sidecar PID file %s is invalid; exit cannot be polled for config dir %s.",
+            pid_path,
+            config_dir,
+        )
+    return None
+
+
+def _external_retirement_sentinel_preexisting(sentinel_path: Path) -> bool:
+    """Snapshot whether the user already disabled the settings sidecar."""
+    try:
+        return sentinel_path.exists()
+    except OSError:
+        logger.warning(
+            "Cannot inspect sidecar disable sentinel %s; preserving it.",
+            sentinel_path,
+            exc_info=True,
+        )
+        return True
+
+
+def _clear_external_retirement_sentinel(
+    sentinel_path: Path,
+    *,
+    url: str,
+    sentinel_preexisting: bool,
+    sentinel_created: bool | None,
+) -> None:
+    """Clear only a legacy disable sentinel attributable to this retirement."""
+    should_clear = (
+        sentinel_created if sentinel_created is not None else not sentinel_preexisting
+    )
+    if not should_clear:
+        return
+    try:
+        sentinel_path.unlink()
+    except FileNotFoundError:
+        logger.debug(
+            "Sidecar disable sentinel %s was already absent after retiring %s.",
+            sentinel_path,
+            url,
+        )
+    except OSError:
+        logger.warning(
+            "Retired sidecar at %s but could not remove its disable sentinel %s.",
+            url,
+            sentinel_path,
+            exc_info=True,
+        )
+
+
+def _wait_for_external_retired_pid(
+    pid: int | None,
+    *,
+    url: str,
+    config_dir: Path,
+) -> None:
+    """Wait a bounded interval for an acknowledged detached sidecar to exit."""
+    if pid is None:
+        return
+    import time
+
+    deadline = time.monotonic() + _OLD_SIDECAR_EXIT_WAIT
+    while _pid_alive(pid):
+        if time.monotonic() >= deadline:
+            logger.warning(
+                "Retired sidecar pid %s at %s is still alive after %.0fs for "
+                "config dir %s.",
+                pid,
+                url,
+                _OLD_SIDECAR_EXIT_WAIT,
+                config_dir,
+            )
+            return
+        time.sleep(_OLD_SIDECAR_EXIT_POLL)
+
+
+def retire_sidecar(config_dir: Path) -> bool:
+    """Best-effort retirement for an externally managed stdio test process.
+
+    This public helper intentionally crosses the process boundary: callers that
+    spawn a real ``ha-mcp`` stdio server otherwise have no handle to its detached
+    settings listener. It uses discovery files in ``config_dir``, reports each
+    failure mode, and returns whether the sidecar acknowledged shutdown.
+
+    The replacement path in ``_shutdown_existing_sidecar`` deliberately remains
+    separate because it seeds global sidecar state and immediately spawns a successor.
+    """
+    url = _read_external_retirement_url(config_dir)
+    if url is None:
+        return False
+    # Capture both before the POST: an acknowledged sidecar may remove its PID,
+    # and the sentinel snapshot distinguishes a legacy endpoint's write from a
+    # user's preexisting disable choice.
+    pid = _read_external_retirement_pid(config_dir)
+    sentinel_path = config_dir / "settings_ui_disabled"
+    sentinel_preexisting = _external_retirement_sentinel_preexisting(sentinel_path)
+
+    acked, sentinel_created = _post_shutdown(url)
+    if not acked:
+        logger.warning(
+            "Sidecar at %s did not acknowledge retirement for config dir %s; "
+            "the detached listener may still be running.",
+            url,
+            config_dir,
+        )
+        return False
+
+    _clear_external_retirement_sentinel(
+        sentinel_path,
+        url=url,
+        sentinel_preexisting=sentinel_preexisting,
+        sentinel_created=sentinel_created,
+    )
+    logger.info("Retired settings UI sidecar at %s for config dir %s", url, config_dir)
+    _wait_for_external_retired_pid(pid, url=url, config_dir=config_dir)
+    return True
+
+
 def _log_shutdown_timeout(exc: BaseException) -> None:
     logger.warning(
         "Old sidecar did not answer /shutdown within %.1fs (%s); "
@@ -420,6 +623,9 @@ def _shutdown_existing_sidecar() -> None:
     replacement, so nothing hands out the old URL anymore (if the
     replacement loses the port to that lingering process, it serves on
     an ephemeral fallback instead).
+
+    External test-process cleanup uses ``retire_sidecar``; the sequences stay
+    separate because only this path seeds state and immediately replaces the listener.
     """
     url = read_sidecar_url()
     if url is None:
@@ -1163,6 +1369,60 @@ def _build_app(
             handlers["save_theme_prefs"],
             methods=["POST"],
         ),
+        # Advanced settings. The stdio-only sidecar-port control is rendered
+        # from this handler, so these routes are required in sidecar mode.
+        Route(
+            f"{secret_prefix}/api/settings/advanced",
+            handlers["get_advanced_settings"],
+            methods=["GET"],
+        ),
+        Route(
+            f"{secret_prefix}/api/settings/advanced",
+            handlers["save_advanced_settings"],
+            methods=["POST"],
+        ),
+        # Auto-backup endpoints (#1288). The Backups tab is available in the
+        # shared settings page and must use the same handlers in stdio mode.
+        Route(
+            f"{secret_prefix}/api/settings/backups",
+            handlers["list_backups"],
+            methods=["GET"],
+        ),
+        Route(
+            f"{secret_prefix}/api/settings/backups",
+            handlers["delete_backups_bulk"],
+            methods=["DELETE"],
+        ),
+        Route(
+            f"{secret_prefix}/api/settings/backups/{{name}}",
+            handlers["view_backup"],
+            methods=["GET"],
+        ),
+        Route(
+            f"{secret_prefix}/api/settings/backups/{{name}}/diff",
+            handlers["diff_backup"],
+            methods=["GET"],
+        ),
+        Route(
+            f"{secret_prefix}/api/settings/backups/{{name}}/restore",
+            handlers["restore_backup"],
+            methods=["POST"],
+        ),
+        Route(
+            f"{secret_prefix}/api/settings/backups/{{name}}",
+            handlers["delete_backup"],
+            methods=["DELETE"],
+        ),
+        Route(
+            f"{secret_prefix}/api/settings/backup-config",
+            handlers["get_backup_config"],
+            methods=["GET"],
+        ),
+        Route(
+            f"{secret_prefix}/api/settings/backup-config",
+            handlers["save_backup_config"],
+            methods=["POST"],
+        ),
         # Custom filesystem directories (issue #1567). The sub-form is rendered
         # in the features panel, so the stdio sidecar must serve these too — its
         # route list is hand-maintained and does NOT derive from
@@ -1217,6 +1477,19 @@ def _build_app(
             handlers["policy_get_value_source"],
             methods=["GET"],
         ),
+        # Entity visibility filter endpoints. The sidecar owns a hand-maintained
+        # route table (it cannot reuse FastMCP custom-route registration), so
+        # keep this pair in lockstep with settings_ui.register_settings_routes.
+        Route(
+            f"{secret_prefix}/api/visibility/config",
+            handlers["visibility_get_config"],
+            methods=["GET"],
+        ),
+        Route(
+            f"{secret_prefix}/api/visibility/config",
+            handlers["visibility_put_config"],
+            methods=["PUT"],
+        ),
     ]
 
     # /shutdown — POST endpoint that drops the disable sentinel and