ha-mcp-dev 9.1.0.dev3293__tar.gz → 9.1.0.dev3298__tar.gz

{ha_mcp_dev-9.1.0.dev3293 → ha_mcp_dev-9.1.0.dev3298}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.1.0.dev3293"
+version = "9.1.0.dev3298"
 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.dev3293 → ha_mcp_dev-9.1.0.dev3298}/pyproject.toml.orig

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

@@ -2747,6 +2747,7 @@ async def _fetch_file(client: Any, entity_id: str) -> Any:
     skips it instead of blocking the write or delete. Other read failures
     raise so the capture pipeline logs them at WARNING.
     """
+    from .tools.auto_backup import PathNotAllowedError
     from .tools.tools_filesystem import call_mcp_tools_service
     from .tools.util_helpers import unwrap_service_response
 
@@ -2758,12 +2759,11 @@ async def _fetch_file(client: Any, entity_id: str) -> Any:
         content = result.get("content")
         return content if isinstance(content, str) else None
     error = str(result.get("error", ""))
-    if (
-        "does not exist" in error
-        or "not a file" in error
-        or "Cannot read binary file" in error
-    ):
+    skips = ("does not exist", "not a file", "Cannot read binary file")
+    if any(marker in error for marker in skips):
         return None
+    if error.startswith("Path not allowed"):
+        raise PathNotAllowedError(entity_id, error)
     raise HomeAssistantError(f"read_file failed for {entity_id!r}: {error}")
 
 

{ha_mcp_dev-9.1.0.dev3293 → ha_mcp_dev-9.1.0.dev3298}/src/ha_mcp/settings_ui/locales/en.json

@@ -324,7 +324,7 @@
     "backup.bulk.in_use": "{count} backup(s) are in use. Retry after the active capture or restore finishes.",
     "backup.bulk.unknown": "The deletion result could not be confirmed. Check the backup list before retrying.",
     "filesystem.custom.title": "Custom filesystem paths (advanced)",
-    "filesystem.custom.help": "Extra paths (one per line) that file tools may <strong>read and write</strong>. Config-relative paths, including exact filenames such as <code>sensor.yaml</code>, and paths under <code>/share</code>, <code>/media</code>, <code>/ssl</code>, and <code>/backup</code> are supported. Each entry allows that path and anything below it. Entries are matched literally; wildcards such as <code>*</code> are not supported. You can also manage these paths in Home Assistant under Settings → Devices & Services → HA-MCP Custom Component → HA-MCP File & YAML Tools → Configure; both locations edit the same setting and apply changes immediately.",
+    "filesystem.custom.help": "Extra paths (one per line) that file tools may <strong>read and write</strong>. Config-relative paths, including exact filenames such as <code>sensor.yaml</code>, and paths under <code>/share</code>, <code>/media</code>, and <code>/ssl</code> (read-only on HAOS and Supervised) are supported. Each entry allows that path and anything below it. Entries are matched literally; wildcards such as <code>*</code> are not supported. You can also manage these paths in Home Assistant under Settings → Devices & Services → HA-MCP Custom Component → HA-MCP File & YAML Tools → Configure; both locations edit the same setting and apply changes immediately.",
     "filesystem.custom.blocked": "Always blocked: {paths}, path traversal (<code>..</code>), and absolute paths outside allowed HAOS volumes.",
     "filesystem.custom.enable_first": "Enable beta features and filesystem tools above to edit.",
     "filesystem.custom.unavailable": "Custom paths are currently unavailable.",

{ha_mcp_dev-9.1.0.dev3293 → ha_mcp_dev-9.1.0.dev3298}/src/ha_mcp/settings_ui/settings_js/04_backups.js

@@ -197,8 +197,8 @@ function renderFsCustomPathsSubForm(parentEl, masterOn, fsOn) {
       : '.storage, secrets.yaml';
   info.innerHTML =
     `<div class="feature-name">${escapeHtml(t('filesystem.custom.title', {}, 'Custom filesystem paths (advanced)'))}</div>` +
-    `<div class="feature-help">${tHtml('filesystem.custom.help', {}, 'Extra paths (one per line) that file tools may <strong>read and write</strong>. Config-relative paths, including exact filenames such as <code>sensor.yaml</code>, and paths under <code>/share</code>, <code>/media</code>, <code>/ssl</code>, and <code>/backup</code> are supported. Each entry allows that path and anything below it. You can also manage these paths in Home Assistant under Settings → Devices & Services → HA-MCP Custom Component → HA-MCP File & YAML Tools → Configure; both locations edit the same setting and apply changes immediately.')}</div>` +
-    `<div class="feature-help">${tHtml('filesystem.custom.blocked', {paths: `<code>${escapeHtml(denyList)}</code>`}, 'Always blocked (cannot be added): {paths}, path traversal (<code>..</code>), and any absolute path outside the HAOS sibling volumes.')}</div>`;
+    `<div class="feature-help">${tHtml('filesystem.custom.help', {}, 'Extra paths (one per line) that file tools may <strong>read and write</strong>. Config-relative paths, including exact filenames such as <code>sensor.yaml</code>, and paths under <code>/share</code>, <code>/media</code>, and <code>/ssl</code> (read-only on HAOS and Supervised) are supported. Each entry allows that path and anything below it. Entries are matched literally; wildcards such as <code>*</code> are not supported. You can also manage these paths in Home Assistant under Settings → Devices & Services → HA-MCP Custom Component → HA-MCP File & YAML Tools → Configure; both locations edit the same setting and apply changes immediately.')}</div>` +
+    `<div class="feature-help">${tHtml('filesystem.custom.blocked', {paths: `<code>${escapeHtml(denyList)}</code>`}, 'Always blocked: {paths}, path traversal (<code>..</code>), and absolute paths outside allowed HAOS volumes.')}</div>`;
 
   const control = document.createElement('div');
   control.className = 'feature-control';

{ha_mcp_dev-9.1.0.dev3293 → ha_mcp_dev-9.1.0.dev3298}/src/ha_mcp/tools/auto_backup.py

@@ -42,7 +42,7 @@ from ..backup_manager import (
     get_backup_manager,
 )
 from ..config import get_global_settings
-from ..errors import ErrorCode, create_error_response
+from ..errors import TOOL_ERROR_LOG_LEVEL, ErrorCode, create_error_response
 from .helpers import raise_tool_error
 
 logger = logging.getLogger(__name__)
@@ -55,17 +55,126 @@ logger = logging.getLogger(__name__)
 _DECORATOR_TRANSIENT_ERRORS = _CAPTURE_TRANSIENT_ERRORS
 
 
-def _component_not_installed_cause(err: BaseException) -> ToolError | None:
-    """Return the ``COMPONENT_NOT_INSTALLED`` ToolError behind a capture failure.
+class PathNotAllowedError(ToolError):
+    """The File & YAML Tools component refused the file path itself.
+
+    Raised by the ``file`` capture's read. The write and delete allowlist is a
+    subset of the read gate, so a path the read refuses, the wrapped write or
+    delete would refuse too (#2908). The message names no operation and leaves
+    out the component's read allowlist, which would mislead a write; the
+    component's own text stays in ``context``.
+    """
+
+    def __init__(
+        self,
+        path: str,
+        component_error: str,
+        *,
+        message: str | None = None,
+        suggestions: list[str] | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> None:
+        self.path = path
+        self.component_error = component_error
+        super().__init__(
+            json.dumps(
+                create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    message or f"Path not allowed: {path}",
+                    suggestions=suggestions or _custom_path_suggestions(path),
+                    context={
+                        **(context or {}),
+                        "path": path,
+                        "component_error": component_error,
+                    },
+                ),
+                indent=2,
+                default=str,
+            ),
+            log_level=TOOL_ERROR_LOG_LEVEL,
+        )
+
+
+# The component's volume roots and deny floor, which it doesn't publish to the
+# server on a refusal (custom_components/ha_mcp_tools/const.py: ALLOWED_VOLUME_
+# ROOTS, DENY_PATH_SEGMENTS, DENY_READ_BASENAMES). A unit test pins the copies.
+_VOLUME_ROOTS = ("/share", "/media", "/ssl")
+_DENY_SEGMENTS = frozenset({".storage"})
+_DENY_BASENAMES = frozenset({"secrets.yaml", "approval_pin.json"})
+
+
+def _custom_path_suggestions(path: str) -> list[str]:
+    """Suggest a custom path only where the settings UI can accept one."""
+    parts = path.lower().split("/")
+    if _DENY_SEGMENTS.intersection(parts) or parts[-1] in _DENY_BASENAMES:
+        return ["This path is never available to the file tools"]
+    if path.startswith("/") and not any(
+        path == root or path.startswith(root + "/") for root in _VOLUME_ROOTS
+    ):
+        return [
+            "Custom filesystem paths accept absolute paths only under "
+            f"{', '.join(_VOLUME_ROOTS)}; this one cannot be allowed"
+        ]
+    return [
+        "If it isn't listed already, add it or a folder above it under "
+        "Custom filesystem paths in the ha-mcp settings UI"
+    ]
+
+
+def path_refusal(err: BaseException) -> PathNotAllowedError | None:
+    """The component's path refusal that is, or caused, ``err``; else ``None``."""
+    if isinstance(err, PathNotAllowedError):
+        return err
+    cause = _component_refusal_cause(err)
+    return cause if isinstance(cause, PathNotAllowedError) else None
+
+
+def raise_if_snapshot_path_refused(
+    err: BaseException, action: str, backup_name: str, data: Any = None
+) -> None:
+    """Re-frame a refused live-file read during a diff or restore of a snapshot.
+
+    A snapshot of a path that is no longer allowed (a removed custom path, or
+    any ``/backup`` path after #2875) can't be compared with or written back to
+    its live file. Say that, instead of the write-oriented path refusal. A
+    restore passes its outcome as ``data``, so callers still see that nothing
+    was applied. (On-demand create has no snapshot yet and reports the plain
+    refusal.)
+    """
+    refusal = path_refusal(err)
+    if refusal is None:
+        return
+    raise PathNotAllowedError(
+        refusal.path,
+        refusal.component_error,
+        message=(
+            f"Cannot {action} {backup_name!r}: its live file {refusal.path} is "
+            "no longer readable through the file tools (the path is not allowed)"
+        ),
+        suggestions=[
+            "View the snapshot with ha_manage_backup(scope='edits', "
+            f"action='view', backup_name={backup_name!r}) to recover its content",
+            *_custom_path_suggestions(refusal.path),
+        ],
+        context={
+            "backup_name": backup_name,
+            "action": action,
+            **({"data": data} if data is not None else {}),
+        },
+    ) from None
+
+
+def _component_refusal_cause(err: BaseException) -> ToolError | None:
+    """Return the component's own refusal behind a capture failure.
 
     A mandatory pre-write snapshot reads the current content through the same
-    File & YAML Tools services the wrapped write needs, so on an install
-    without that config entry the capture fails FIRST and the write would be
-    refused as ``BACKUP_CAPTURE_FAILED`` — burying the actionable "add the
-    entry" guidance one level deep (#2292). Walk the cause chain for the
-    original structured error so the caller can surface it unchanged: retrying
-    the backup cannot succeed, and the remediation is the component's, not the
-    backup pipeline's.
+    File & YAML Tools services the wrapped write needs, so when the component
+    refuses the call the capture fails FIRST and the write would be refused as
+    ``BACKUP_CAPTURE_FAILED``, burying the real error one level deep. Two
+    refusals are surfaced unchanged: ``COMPONENT_NOT_INSTALLED`` (no tools
+    entry, #2292) and ``PathNotAllowedError`` (the path is outside the
+    allowlist, #2908). Retrying the backup cannot succeed for either, and the
+    remediation is the component's, not the backup pipeline's.
     """
     seen: set[int] = set()
     # Worklist over BOTH chain links: an explicit ``raise ... from other``
@@ -79,6 +188,8 @@ def _component_not_installed_cause(err: BaseException) -> ToolError | None:
         if id(cause) in seen:
             continue
         seen.add(id(cause))
+        if isinstance(cause, PathNotAllowedError):
+            return cause
         if isinstance(cause, ToolError):
             try:
                 payload = json.loads(str(cause))
@@ -389,19 +500,18 @@ async def _capture_pre_write_snapshot(
             # wrapped write never runs, so nothing has been changed.
             # The ToolError this raises propagates rather than being
             # swallowed by the best-effort handler below.
-            component_error = _component_not_installed_cause(err)
+            component_error = _component_refusal_cause(err)
             if component_error is not None:
-                # The capture failed because the File & YAML Tools entry is
-                # not set up — the same reason the wrapped write itself would
-                # refuse. Surface that actionable error (add the entry), not a
-                # backup complaint (#2292). The write is still blocked. ``from
-                # None`` because this IS the underlying error being unwrapped;
-                # chaining it back onto the wrapper it came out of would only
-                # print the chain twice (and B904 wants the intent explicit).
-                # ``from None`` also drops the wrapper's own text from the
-                # traceback, so record it here or the only account of WHICH
-                # mandatory capture was re-pointed at the component error is
-                # gone.
+                # The capture failed because the component refused the call —
+                # the same reason the wrapped write itself would refuse. Surface
+                # that actionable error, not a backup complaint (#2292, #2908).
+                # The write is still blocked. ``from None`` because this IS the
+                # underlying error being unwrapped; chaining it back onto the
+                # wrapper it came out of would only print the chain twice (and
+                # B904 wants the intent explicit). ``from None`` also drops the
+                # wrapper's own text from the traceback, so record it here or
+                # the only account of WHICH mandatory capture was re-pointed at
+                # the component error is gone.
                 logger.warning(
                     "Auto-backup: mandatory capture for '%s' failed (%s) — "
                     "surfacing the underlying component error instead; the "

{ha_mcp_dev-9.1.0.dev3293 → ha_mcp_dev-9.1.0.dev3298}/src/ha_mcp/tools/backup.py

@@ -39,6 +39,7 @@ from ..backup_todo import TodoListNotLoaded
 from ..client.rest_client import HomeAssistantClient
 from ..config import get_global_settings
 from ..errors import ErrorCode, create_error_response
+from .auto_backup import raise_if_snapshot_path_refused
 from .backup_access import (
     gate_backup_combo as _gate_combo,
 )
@@ -552,7 +553,8 @@ async def _edits_diff(
                 context={"backup_name": bname},
             )
         )
-    except ToolError:
+    except ToolError as err:
+        raise_if_snapshot_path_refused(err, "diff", bname)
         raise
     except Exception as err:  # noqa: BLE001
         # Fetching the live config for diff goes through the
@@ -649,26 +651,28 @@ async def _edits_restore(
         # failed — the overwrite was blocked, nothing changed. Same
         # fail-closed contract + error code as the @with_auto_backup write
         # path (#1579), so callers see one consistent failure mode.
+        not_applied = {
+            "restored_from": bname,
+            "safety_backup": None,
+            "apply_status": "not_applied",
+            "verification_status": "not_run",
+        }
+        # Its live file's path is no longer allowed: retrying can't help.
+        raise_if_snapshot_path_refused(err, "restore", bname, not_applied)
         logger.warning("Restore of %s blocked: %s", bname, err.safe_cause)
         raise_tool_error(
             create_error_response(
                 ErrorCode.BACKUP_CAPTURE_FAILED,
                 "Restore blocked: the pre-restore safety snapshot could not be "
                 f"captured ({err.safe_cause}). Nothing was changed.",
-                context={
-                    "backup_name": bname,
-                    "data": {
-                        "restored_from": bname,
-                        "safety_backup": None,
-                        "apply_status": "not_applied",
-                        "verification_status": "not_run",
-                    },
-                },
+                context={"backup_name": bname, "data": not_applied},
                 suggestions=err.suggestions
                 or ["Retry once the underlying issue is resolved"],
             )
         )
-    except ToolError:
+    except ToolError as err:
+        outcome = getattr(err, "restore_outcome", None)
+        raise_if_snapshot_path_refused(err, "restore", bname, outcome)
         raise
     except Exception as err:  # noqa: BLE001
         # ``handler.restore`` is domain-specific and can surface HA-side

{ha_mcp_dev-9.1.0.dev3293 → ha_mcp_dev-9.1.0.dev3298}/src/ha_mcp/tools/backup_on_demand.py

@@ -4,6 +4,7 @@ from pathlib import Path
 
 from ..backup_manager import BackupManager, MandatoryBackupError, _is_flow_helper_domain
 from ..errors import ErrorCode, create_error_response
+from .auto_backup import path_refusal
 from .helper_flows import require_helper_type
 from .helpers import raise_tool_error
 
@@ -27,6 +28,8 @@ async def capture_on_demand(mgr: BackupManager, domain: str, entity_id: str) ->
             mandatory=True,
         )
     except MandatoryBackupError as err:
+        if (refusal := path_refusal(err)) is not None:
+            raise refusal from None  # the path itself is refused; not retryable
         cause = err.__cause__
         raise_tool_error(
             create_error_response(

{ha_mcp_dev-9.1.0.dev3293 → ha_mcp_dev-9.1.0.dev3298}/src/ha_mcp/tools/tools_filesystem.py

@@ -580,7 +580,7 @@ class FilesystemTools:
         - `packages/`, plus the folder bound by `homeassistant: packages:` when
           it has another name
         - Plus any custom directories OR HAOS sibling volumes (`/share`,
-          `/media`, `/ssl`, `/backup`) configured in the ha-mcp settings UI
+          `/media`, `/ssl`) configured in the ha-mcp settings UI
         Path traversal (../) is blocked.
 
         EXAMPLE: ha_list_files(path="www/", pattern="*.css")
@@ -696,7 +696,7 @@ class FilesystemTools:
         - `www/**`, `themes/**`, `custom_templates/**`, `dashboards/**`, `blueprints/**`
         - `custom_components/**/*.py` (read-only)
         - Plus any custom directories OR HAOS sibling volumes (`/share`,
-          `/media`, `/ssl`, `/backup`) configured in the ha-mcp settings UI
+          `/media`, `/ssl`) configured in the ha-mcp settings UI
         Path traversal (../) is blocked.
 
         EXAMPLE: ha_read_file(path="packages/alert2.yaml", yaml_path="alert2")
@@ -797,8 +797,8 @@ class FilesystemTools:
         - `themes/` - Theme YAML files
         - `custom_templates/` - Jinja2 template files
         - `dashboards/` - YAML-mode dashboard files
-        - Plus any custom directories OR HAOS sibling volumes (`/share`,
-          `/media`, `/ssl`, `/backup`) configured in the ha-mcp settings UI
+        - Plus custom directories OR HAOS sibling volumes (`/share`, `/media`, `/ssl`)
+          from the ha-mcp settings UI; `/ssl` is read-only on HAOS and Supervised
         Configuration files (configuration.yaml, etc.) cannot be written; path
         traversal (../) is blocked.
 
@@ -887,9 +887,9 @@ class FilesystemTools:
         recent auto-backup snapshot; a binary file has no snapshot and its
         deletion is permanent. Allowed directories:
         `www/`, `themes/`, `custom_templates/`, `dashboards/`, plus any custom
-        directories OR HAOS sibling volumes (`/share`, `/media`, `/ssl`,
-        `/backup`) configured in the ha-mcp settings UI. Configuration files
-        cannot be deleted; path traversal (../) is blocked.
+        directories OR HAOS sibling volumes (`/share`, `/media`, `/ssl`) configured
+        in the ha-mcp settings UI; `/ssl` is read-only on HAOS and Supervised.
+        Configuration files cannot be deleted; path traversal (../) is blocked.
 
         EXAMPLE: ha_delete_file(path="www/deprecated-style.css", confirm=True)
         """