ha-mcp-dev 7.8.0.dev702__tar.gz → 7.8.0.dev703__tar.gz

{ha_mcp_dev-7.8.0.dev702/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.8.0.dev703}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.8.0.dev702
+Version: 7.8.0.dev703
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -275,8 +275,8 @@ Some tools require a companion custom component installed in Home Assistant. Sta
 | Tool | Description |
 |------|-------------|
 | `ha_config_set_yaml` *(beta)* | Safely add, replace, or remove top-level YAML keys in `configuration.yaml` and package files (automatic backup, validation, and config check) |
-| `ha_list_files` *(beta)* | List files in allowed directories (www/, themes/, custom_templates/) |
-| `ha_read_file` *(beta)* | Read files from allowed paths (config YAML, logs, www/, themes/, custom_templates/, custom_components/) |
+| `ha_list_files` *(beta)* | List files in allowed directories |
+| `ha_read_file` *(beta)* | Read files from allowed paths (config YAML, logs, and allowed directories) |
 | `ha_write_file` *(beta)* | Write files to allowed directories |
 | `ha_delete_file` *(beta)* | Delete files from allowed directories |
 

{ha_mcp_dev-7.8.0.dev702 → ha_mcp_dev-7.8.0.dev703}/README.md

@@ -245,8 +245,8 @@ Some tools require a companion custom component installed in Home Assistant. Sta
 | Tool | Description |
 |------|-------------|
 | `ha_config_set_yaml` *(beta)* | Safely add, replace, or remove top-level YAML keys in `configuration.yaml` and package files (automatic backup, validation, and config check) |
-| `ha_list_files` *(beta)* | List files in allowed directories (www/, themes/, custom_templates/) |
-| `ha_read_file` *(beta)* | Read files from allowed paths (config YAML, logs, www/, themes/, custom_templates/, custom_components/) |
+| `ha_list_files` *(beta)* | List files in allowed directories |
+| `ha_read_file` *(beta)* | Read files from allowed paths (config YAML, logs, and allowed directories) |
 | `ha_write_file` *(beta)* | Write files to allowed directories |
 | `ha_delete_file` *(beta)* | Delete files from allowed directories |
 

{ha_mcp_dev-7.8.0.dev702 → ha_mcp_dev-7.8.0.dev703}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.8.0.dev702"
+version = "7.8.0.dev703"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"
@@ -85,6 +85,8 @@ ignore_missing_imports = true
 [[tool.mypy.overrides]]
 module = [
     "homeassistant.*",
+    "aiohasupervisor",
+    "aiohasupervisor.*",
     "aiohttp",
     "voluptuous",
     "jsonschema",

{ha_mcp_dev-7.8.0.dev702 → ha_mcp_dev-7.8.0.dev703}/src/ha_mcp/read_only.py

@@ -66,8 +66,12 @@ class ReadOnlyExemption(NamedTuple):
 def _backup_write(args: dict[str, Any]) -> str | None:
     scope = args.get("scope")
     action = args.get("action")
+    # Read-only-safe: per-edit backup listing/viewing, and snapshot listing
+    # (issue #1586 — pure ``backup/info`` read, no tarball mutation).
     if scope == "edits" and action in ("list", "view"):
         return None
+    if scope == "snapshot" and action == "list":
+        return None
     return f"scope={scope!r}, action={action!r}"
 
 
@@ -144,7 +148,8 @@ def _custom_tool_write(args: dict[str, Any]) -> str | None:
 READ_ONLY_EXEMPT_TOOLS: dict[str, ReadOnlyExemption] = {
     "ha_manage_backup": ReadOnlyExemption(
         _backup_write,
-        "listing and viewing per-edit backups (scope='edits', action='list' or 'view')",
+        "listing and viewing per-edit backups (scope='edits', action='list' or "
+        "'view') and listing snapshots (scope='snapshot', action='list')",
     ),
     "ha_manage_addon": ReadOnlyExemption(
         _addon_write,

{ha_mcp_dev-7.8.0.dev702 → ha_mcp_dev-7.8.0.dev703}/src/ha_mcp/settings.js

@@ -1030,8 +1030,8 @@ function renderFsCustomPathsSubForm(parentEl, masterOn, fsOn) {
       : '.storage, secrets.yaml';
   info.innerHTML =
     `<div class="feature-name">Custom filesystem directories (advanced)</div>` +
-    `<div class="feature-help">Extra directories (one per line, relative to your config dir) that the file tools may READ and WRITE — e.g. <code>pyscript</code>, <code>python_scripts</code>. Each entry grants both read and write. Applies immediately; no restart needed.</div>` +
-    `<div class="feature-help">Always blocked (cannot be added): <code>${escapeHtml(denyList)}</code>, path traversal (<code>..</code>), and absolute paths.</div>`;
+    `<div class="feature-help">Extra directories (one per line) that the file tools may READ and WRITE — either relative to your config dir (e.g. <code>pyscript</code>, <code>python_scripts</code>) or an absolute HAOS sibling volume <code>/share</code>, <code>/media</code>, <code>/ssl</code>, <code>/backup</code> (or a subdirectory of one). Each entry grants both read and write. Applies immediately; no restart needed.</div>` +
+    `<div class="feature-help">Always blocked (cannot be added): <code>${escapeHtml(denyList)}</code>, path traversal (<code>..</code>), and any absolute path outside the HAOS sibling volumes.</div>`;
 
   const control = document.createElement('div');
   control.className = 'feature-control';

{ha_mcp_dev-7.8.0.dev702 → ha_mcp_dev-7.8.0.dev703}/src/ha_mcp/tools/backup.py

@@ -731,10 +731,126 @@ async def restore_backup(
     return None  # py/mixed-returns: explicit terminal; error handlers above always raise (NoReturn), unreachable
 
 
+def _summarize_backup(entry: dict[str, Any]) -> dict[str, Any]:
+    """Project one HA ``backup/info`` entry to the fields a caller needs to
+    identify and choose a snapshot (issue #1586).
+
+    Size is reported per backup agent; we surface the largest reported size
+    across agents. Every field is ``.get`` so a schema the running HA version
+    doesn't populate yields ``None`` rather than raising.
+    """
+    agents = entry.get("agents") or {}
+    size_bytes: int | None = None
+    if isinstance(agents, dict):
+        sizes: list[int] = []
+        for a in agents.values():
+            if isinstance(a, dict):
+                size = a.get("size")
+                # Accept int or float (some agents report byte counts as float);
+                # bool is an int subclass but never a real size, so exclude it.
+                if isinstance(size, (int, float)) and not isinstance(size, bool):
+                    sizes.append(int(size))
+        if sizes:
+            size_bytes = max(sizes)
+    return {
+        "backup_id": entry.get("backup_id"),
+        "name": entry.get("name"),
+        "date": entry.get("date"),
+        "size_bytes": size_bytes,
+        "protected": entry.get("protected"),
+        "database_included": entry.get("database_included"),
+        "homeassistant_included": entry.get("homeassistant_included"),
+        "homeassistant_version": entry.get("homeassistant_version"),
+        "with_automatic_settings": entry.get("with_automatic_settings"),
+        "agent_ids": list(agents.keys()) if isinstance(agents, dict) else [],
+    }
+
+
+async def list_backups(client: HomeAssistantClient, limit: int = 200) -> dict[str, Any]:
+    """List the full HA snapshot tarballs known to Home Assistant (issue #1586).
+
+    Surfaces the inventory HA already returns from its WebSocket ``backup/info``
+    command — the same data ``restore_backup`` uses internally to verify a
+    ``backup_id`` exists. Before this, the snapshot scope exposed only
+    ``create`` and ``restore``, so a caller had no way to discover backup IDs or
+    confirm a specific backup landed; they had to already know the ID. Newest
+    first. Read-only: no safety backup, no restart.
+    """
+    ws_client = None
+    try:
+        ws_client, error = await get_connected_ws_client(
+            client.base_url, client.token, verify_ssl=client.verify_ssl
+        )
+        if error:
+            raise_tool_error(
+                error
+                or create_error_response(
+                    ErrorCode.CONNECTION_FAILED,
+                    "Failed to connect to Home Assistant WebSocket to list backups",
+                )
+            )
+        ws_client = cast(HomeAssistantWebSocketClient, ws_client)
+
+        info = await ws_client.send_command("backup/info")
+        if not info.get("success"):
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.SERVICE_CALL_FAILED,
+                    info.get("error", "Failed to retrieve backup information"),
+                )
+            )
+
+        result_block = info.get("result") or {}
+        raw_backups = result_block.get("backups") or []
+        summarized = [_summarize_backup(b) for b in raw_backups]
+        # Newest first so "did my backup land?" is answered by the top entry.
+        # Parse via _parse_backup_date (handles `Z`/naive) rather than sorting
+        # the raw strings lexicographically — `'Z'` > `'+'` would misorder a mix
+        # of `...Z` and `...+00:00`. Undated entries sink to the bottom.
+        _date_floor = datetime.min.replace(tzinfo=UTC)
+        summarized.sort(
+            key=lambda b: _parse_backup_date(b.get("date")) or _date_floor,
+            reverse=True,
+        )
+        total = len(summarized)
+        if limit and total > limit:
+            summarized = summarized[:limit]
+        return {
+            "success": True,
+            "count": len(summarized),
+            "total": total,
+            "backups": summarized,
+        }
+
+    except ToolError:
+        raise
+    except Exception as e:
+        logger.error(f"Error listing backups: {e}")
+        exception_to_structured_error(
+            e,
+            context={"tool": "list_backups"},
+            suggestions=["Check Home Assistant connection and the backup integration"],
+        )
+        return None  # unreachable: exception_to_structured_error always raises
+    finally:
+        # Always disconnect WebSocket — narrow to transport errors; a
+        # programming error during cleanup should still surface.
+        if ws_client:
+            try:
+                await ws_client.disconnect()
+            except (TimeoutError, OSError, ConnectionError) as err:
+                logger.debug(
+                    "ws disconnect (cleanup) transport error: %s: %s",
+                    type(err).__name__,
+                    err,
+                )
+
+
 # Valid (scope, action) combinations. Anything outside this set is
 # rejected with a structured VALIDATION_INVALID_PARAMETER error.
 _VALID_COMBOS: set[tuple[str, str]] = {
     ("snapshot", "create"),
+    ("snapshot", "list"),
     ("snapshot", "restore"),
     ("edits", "create"),
     ("edits", "list"),
@@ -799,6 +915,7 @@ def register_backup_tools(
 | scope | action | What it does |
 |---|---|---|
 | `snapshot` | `create` | Create a full HA tarball (config + addons, no DB by default). Heavy, seconds-long. |
+| `snapshot` | `list` | List full HA tarball snapshots (id, name, date, size). Read-only — use to discover a `backup_id` or confirm a backup landed. |
 | `snapshot` | `restore` | Restore a full HA tarball. **Restarts HA.** Last-resort recovery. |
 | `edits` | `create` | On-demand snapshot of one entity (`domain` + `entity_id` required). Use before the user manually edits in the HA UI. Same handler path the decorator takes on writes; bypasses the `enable_auto_backup` toggle. |
 | `edits` | `list` | List per-entity auto-backups (lightweight). Filter by `domain` and/or `entity_id`. |
@@ -817,6 +934,7 @@ def register_backup_tools(
 
 **Examples:**
 - Snapshot before risky op: `ha_manage_backup(scope="snapshot", action="create", name="Before_Big_Change")`
+- List snapshots (to discover a backup_id or confirm one landed): `ha_manage_backup(scope="snapshot", action="list")`
 - Restore full snapshot: `ha_manage_backup(scope="snapshot", action="restore", backup_id="dd7550ed")`
 - On-demand entity snapshot before a manual UI edit: `ha_manage_backup(scope="edits", action="create", domain="helper_input_boolean", entity_id="kitchen_lights_active")`
 - List recent auto-backups for one automation: `ha_manage_backup(scope="edits", action="list", domain="automation", entity_id="kitchen_lights")`
@@ -906,7 +1024,7 @@ def register_backup_tools(
                 default=200,
                 ge=1,
                 le=10_000,
-                description="(edits.list) Maximum number of entries to return.",
+                description="(edits.list / snapshot.list) Maximum number of entries to return.",
             ),
         ] = 200,
     ) -> dict[str, Any]:
@@ -916,6 +1034,8 @@ def register_backup_tools(
         if scope == "snapshot":
             if action == "create":
                 return await create_backup(client, name)
+            if action == "list":
+                return await list_backups(client, limit)
             # action == "restore"
             bid = _require("backup_id", backup_id, scope, action)
             return await restore_backup(client, bid, restore_database)

{ha_mcp_dev-7.8.0.dev702 → ha_mcp_dev-7.8.0.dev703}/src/ha_mcp/tools/tools_filesystem.py

@@ -57,7 +57,11 @@ CALLER_TOKEN_BOOTSTRAP_SERVICE = "get_caller_token"
 # ``themes/*.yaml`` yaml_path scope; a <0.8.0 component reaches the old
 # handler and rejects ``themes/<name>.yaml`` with a misleading "not
 # allowed" message instead of this actionable update prompt.
-MIN_COMPONENT_VERSION = "0.8.0"
+# 0.9.0: the file tools accept absolute HAOS sibling-volume paths (/share,
+# /media, /ssl, /backup — issue #1586). A <0.9.0 component's allowlist
+# normalizer rejects every absolute path, so adding a volume would silently
+# do nothing; the version gate surfaces an actionable "update" prompt instead.
+MIN_COMPONENT_VERSION = "0.9.0"
 
 
 def _version_tuple(version: str) -> tuple[int, ...]:
@@ -333,9 +337,12 @@ class FilesystemTools:
             str,
             Field(
                 description=(
-                    "Relative directory path from config directory. "
-                    "Allowed paths: www/, themes/, custom_templates/, dashboards/. "
-                    "Example: 'www/' or 'themes/my_theme'"
+                    "Directory path. Relative to the config dir for the built-in "
+                    "allowlist (www/, themes/, custom_templates/, dashboards/). "
+                    "Custom directories and HAOS sibling volumes "
+                    "(/share, /media, /ssl, /backup) configured in the ha-mcp "
+                    "settings UI are also allowed (pass the absolute path). "
+                    "Example: 'www/' or '/share/llm'"
                 ),
             ),
         ],
@@ -360,7 +367,9 @@ class FilesystemTools:
         - `themes/` - Theme files
         - `custom_templates/` - Jinja2 template files
         - `dashboards/` - YAML-mode dashboard files
-        - Plus any custom directories configured in the ha-mcp settings UI
+        - Plus any custom directories OR HAOS sibling volumes (`/share`,
+          `/media`, `/ssl`, `/backup`) configured in the ha-mcp settings UI
+          (pass the absolute path for volumes)
 
         **Security:** Only directories in the allowed list can be accessed.
         Path traversal attempts (../) are blocked.
@@ -435,8 +444,10 @@ class FilesystemTools:
             str,
             Field(
                 description=(
-                    "Relative path from config directory. "
-                    "Examples: 'configuration.yaml', 'www/custom.css', 'home-assistant.log'"
+                    "File path. Relative to the config dir for the built-in "
+                    "allowlist; absolute for a configured HAOS sibling volume "
+                    "(/share, /media, /ssl, /backup). Examples: "
+                    "'configuration.yaml', 'www/custom.css', '/share/llm/notes.md'"
                 ),
             ),
         ],
@@ -468,7 +479,9 @@ class FilesystemTools:
         - `home-assistant.log` (tail only)
         - `www/**`, `themes/**`, `custom_templates/**`, `dashboards/**`
         - `custom_components/**/*.py` (read-only)
-        - Plus any custom directories configured in the ha-mcp settings UI
+        - Plus any custom directories OR HAOS sibling volumes (`/share`,
+          `/media`, `/ssl`, `/backup`) configured in the ha-mcp settings UI
+          (pass the absolute path for volumes)
 
         **Security:**
         - Path traversal (../) is blocked
@@ -546,9 +559,11 @@ class FilesystemTools:
             str,
             Field(
                 description=(
-                    "Relative path from config directory. "
-                    "Must be in www/, themes/, custom_templates/, or dashboards/. "
-                    "Example: 'www/custom.css', 'themes/my_theme.yaml'"
+                    "File path. Must be in a writable built-in dir (www/, "
+                    "themes/, custom_templates/, dashboards/), a configured "
+                    "custom directory, or a configured HAOS sibling volume "
+                    "(/share, /media, /ssl, /backup — pass the absolute path). "
+                    "Example: 'www/custom.css', '/share/llm/out.txt'"
                 ),
             ),
         ],
@@ -590,7 +605,9 @@ class FilesystemTools:
         - `themes/` - Theme YAML files
         - `custom_templates/` - Jinja2 template files
         - `dashboards/` - YAML-mode dashboard files
-        - Plus any custom directories configured in the ha-mcp settings UI
+        - Plus any custom directories OR HAOS sibling volumes (`/share`,
+          `/media`, `/ssl`, `/backup`) configured in the ha-mcp settings UI
+          (pass the absolute path for volumes)
 
         **Security:**
         - Only the directories above allow writes
@@ -678,8 +695,10 @@ class FilesystemTools:
             str,
             Field(
                 description=(
-                    "Relative path from config directory. "
-                    "Must be in www/, themes/, custom_templates/, or dashboards/. "
+                    "File path. Must be in a writable built-in dir (www/, "
+                    "themes/, custom_templates/, dashboards/), a configured "
+                    "custom directory, or a configured HAOS sibling volume "
+                    "(/share, /media, /ssl, /backup — pass the absolute path). "
                     "Example: 'www/old-file.css'"
                 ),
             ),
@@ -705,7 +724,9 @@ class FilesystemTools:
         - `themes/` - Theme files
         - `custom_templates/` - Template files
         - `dashboards/` - YAML-mode dashboard files
-        - Plus any custom directories configured in the ha-mcp settings UI
+        - Plus any custom directories OR HAOS sibling volumes (`/share`,
+          `/media`, `/ssl`, `/backup`) configured in the ha-mcp settings UI
+          (pass the absolute path for volumes)
 
         **Security:**
         - Only the directories above allow deletions

{ha_mcp_dev-7.8.0.dev702 → ha_mcp_dev-7.8.0.dev703/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.8.0.dev702
+Version: 7.8.0.dev703
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -275,8 +275,8 @@ Some tools require a companion custom component installed in Home Assistant. Sta
 | Tool | Description |
 |------|-------------|
 | `ha_config_set_yaml` *(beta)* | Safely add, replace, or remove top-level YAML keys in `configuration.yaml` and package files (automatic backup, validation, and config check) |
-| `ha_list_files` *(beta)* | List files in allowed directories (www/, themes/, custom_templates/) |
-| `ha_read_file` *(beta)* | Read files from allowed paths (config YAML, logs, www/, themes/, custom_templates/, custom_components/) |
+| `ha_list_files` *(beta)* | List files in allowed directories |
+| `ha_read_file` *(beta)* | Read files from allowed paths (config YAML, logs, and allowed directories) |
 | `ha_write_file` *(beta)* | Write files to allowed directories |
 | `ha_delete_file` *(beta)* | Delete files from allowed directories |