[FEATURE] Auto-backup edited entities on every write (automations/scripts/scenes/dashboards/helpers)

[kingpanther13]

What would you like to see?

Automatic per-edit backups for the MCP server's write tools — ha_config_set_automation, ha_config_set_script, ha_config_set_scene, ha_config_set_helper, and dashboard writes. Before each write, dump a full backup of whatever is being modified (the entire automation, the entire dashboard, the entire script, etc. — not a diff, not just the changed keys) to a timestamped file in a dedicated folder on HA (e.g. /config/.ha_mcp_backups/...).

Backup in whatever form it's stored locally — JSON for storage-mode entities, YAML for YAML-mode dashboards/packages, etc. Don't transform.

Today, only the beta YAML editing tool (ha_config_set_yaml) does this — to .ha_mcp_tools_backups/. None of the standard write tools do.

Toggle (ships with the first PR)

A single enable/disable toggle, mirrored in both places like the existing enable_tool_search setting:

• homeassistant-addon/config.yaml + schema (and homeassistant-addon-dev/config.yaml)
• The web settings UI

Not deferred — both surfaces ship with the PR that closes the first half of this issue.

Browse / restore interface (follow-up)

Capturing the data here so it doesn't get lost. File a separate follow-up issue once this one closes.

A user-facing UI for browsing the backup folder, viewing diffs, and one-click restore — likely inside the web settings panel from #960. Rough shape:

• List backups grouped by entity (automation/script/scene/dashboard/helper)
• Per-entry: timestamp, originating tool call, side-by-side diff against current state
• "Restore" button that re-applies the captured backup through the same write tool that produced it
• Retention/cleanup controls (max backups per entity, max age, total size cap)

Out of scope for the first PR but tracked here so the data shape, file layout, and metadata captured during writes don't paint the follow-up into a corner. The first PR should write enough metadata alongside each backup file (entity_id, domain, tool name, timestamp, maybe the agent's natural-language intent if available) to make the follow-up cheap.

Why do you need this?

From discussion #984: users want the same "agent went sideways, undo it" safety net git gives them in code repos. Today the options are:

• ha_backup_create — heavy full HA snapshot, manual, loses entity data between snapshots
• The agent showing diffs in chat — only useful if the user catches it in time
• ha_config_set_yaml's built-in backup — only covers that one beta tool

For the common case (agent edits an automation/script/dashboard, gets it wrong, user notices an hour later), nothing covers it. Per-edit backups give clean side-by-side comparison, bound the blast radius, and remove the current "remember to ask the agent to back up first" pattern.

Additional context

• Discussion YAML-level diffing & rollback #984, especially richardgaywood's clarifying reply (2026-05-15): this is about the payloads flowing through MCP write tools, not user-authored configuration.yaml.
• Existing precedent: ha_config_set_yaml's backup=True parameter + .ha_mcp_tools_backups/ folder. The new system could reuse that path or place a sibling under /config/.
• Toggle precedent: enable_tool_search lives in both addon config and web settings — mirror that.
• Related: [FEATURE] Advanced settings panel in web UI + beta-features opt-in #1164 (advanced settings panel) — the eventual home for the browse/restore UI.
• Out of scope: full snapshot rollback (ha_backup_create/ha_backup_restore already cover that).

richardgaywood offered to author the PR in the original discussion post.

[github-actions]

🔍 Analysis

This is a feature request to implement automatic, per-edit backups for all Model Context Protocol (MCP) write tools in ha-mcp. Currently, only the beta ha_config_set_yaml tool performs backups (saving to .ha_mcp_tools_backups/). The user wants this safety net extended to standard tools like ha_config_set_automation, ha_config_set_script, and dashboard writes.

The requested behavior involves fetching the full current configuration of an entity before any modification and dumping it as a timestamped YAML file into a dedicated folder (e.g., /config/.ha_mcp_backups/) on the Home Assistant instance. A global toggle, ENABLE_AUTO_BACKUP, will be added to the add-on configuration and the web settings UI to control this feature.

This feature is highly desirable as it provides an "undo" mechanism for agent-driven changes that might go wrong, similar to version control for smart home configurations.

🛠️ Suggested Steps

1. Add the Toggle Setting:

   • Update src/ha_mcp/config.py to include enable_auto_backup in the Settings class with an environment variable alias ENABLE_AUTO_BACKUP.
   • Update homeassistant-addon/config.yaml (and the dev version) to include the new option in the schema.
   • Update homeassistant-addon/start.py to map the add-on option to the environment variable.

2. Update the Custom Component:

   • Add a new service create_backup to the ha_mcp_tools custom component (custom_components/ha_mcp_tools/).
   • This service should accept content, filename_hint, and metadata (entity_id, domain, etc.) and save it to /config/.ha_mcp_backups/.

3. Implement Backup Logic in MCP Client:

   • In src/ha_mcp/client/rest_client.py, modify the upsert_* methods (automation, script, scene) to check settings.enable_auto_backup.
   • If enabled and an identifier is provided (indicating an update), fetch the current configuration using the corresponding get_* method.
   • Call the new ha_mcp_tools.create_backup service with the fetched configuration before proceeding with the POST update.
   • Repeat this logic for dashboard writes in src/ha_mcp/tools/tools_config_dashboards.py.

4. Enhance Web Settings UI:

   • Update src/ha_mcp/settings_ui.py to include the enable_auto_backup toggle in the HTML template and handle its state in the API routes.

📊 Technical Analysis (for maintainers)

Root Cause

The current write tools perform direct updates to Home Assistant without preserving the previous state. While ha_config_set_yaml has a built-in backup mechanism in the custom component's edit_yaml_config service, the other tools use native HA APIs or WebSocket messages that do not provide automatic backups.

Affected Code

• src/ha_mcp/config.py: Add enable_auto_backup: bool = Field(False, alias="ENABLE_AUTO_BACKUP")
• src/ha_mcp/client/rest_client.py: Intercept upsert_automation_config, upsert_script_config, and upsert_scene_config.
• src/ha_mcp/tools/tools_config_dashboards.py: Intercept dashboard saves.
• custom_components/ha_mcp_tools/__init__.py: Add SERVICE_CREATE_BACKUP.
• homeassistant-addon/config.yaml: Add enable_auto_backup to options and schema.
• src/ha_mcp/settings_ui.py: Add toggle to _SETTINGS_HTML.

Proposed Fix

Custom Component Service (custom_components/ha_mcp_tools/__init__.py):

# Add to SERVICE_CREATE_BACKUP_SCHEMA
async def handle_create_backup(call: ServiceCall):
    content = call.data["content"]
    domain = call.data["domain"]
    entity_id = call.data["entity_id"]
    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
    backup_dir = config_dir / ".ha_mcp_backups"
    backup_dir.mkdir(parents=True, exist_ok=True)
    filename = f"{domain}.{entity_id}.{timestamp}.yaml"
    (backup_dir / filename).write_text(content)

Client Interception (src/ha_mcp/client/rest_client.py):

async def upsert_automation_config(self, config, identifier=None):
    if self.settings.enable_auto_backup and identifier:
        current = await self.get_automation_config(identifier)
        await self.call_service("ha_mcp_tools", "create_backup", {
            "content": yaml.dump(current),
            "domain": "automation",
            "entity_id": identifier
        })
    # ... existing logic ...

Related Issues/PRs

• YAML-level diffing & rollback #984 - Original discussion regarding entity backups.
• feat: web-based settings UI for per-tool enable/disable/pin #960 - Web settings UI implementation.
• [FEATURE] Advanced settings panel in web UI + beta-features opt-in #1164 - Advanced settings panel (future home for restore UI).

---

🤖 Automated analysis by Issue Bot

[Patch76]

Deep-dive on surface, precedent, and architecture choices at HEAD 499ebf0. The bot got the rough shape right; the layered choices below are where the design questions live.

Write-tool surface — broader than the 5 listed

The issue body names 5 tools. The full set/remove surface at HEAD covers 15+ writes:

Domain	Set / Remove tool	File
Automation	ha_config_set_automation	tools_config_automations.py:368
Script	ha_config_set_script	tools_config_scripts.py:262
Scene	ha_config_set_scene	tools_config_scenes.py:411
Helper	ha_config_set_helper	tools_config_helpers.py:1977
Dashboard	ha_config_set_dashboard / _delete_dashboard / _set_dashboard_resource	tools_config_dashboards.py:838 / :1494 / tools_resources.py:241
Label	ha_config_set_label	tools_labels.py:132
Category	ha_config_set_category	tools_categories.py:164
Group	ha_config_set_group	tools_groups.py:189
Zone	ha_set_zone / ha_remove_zone	tools_zones.py:141 / :309
Area/Floor	ha_set_area_or_floor / ha_remove_area_or_floor	tools_areas.py:362 / :571
Todo	ha_set_todo_item / ha_remove_todo_item	tools_todo.py:207 / :513
Calendar	ha_config_set_calendar_event	tools_calendar.py:163
Integration	ha_set_integration_enabled	tools_integrations.py:796
Entity	ha_set_entity	tools_entities.py:559

v1 scope per the issue body stays at 5; the broader surface is useful context for follow-up generalization (and for retention-policy sizing).

Existing precedent — how ha_config_set_yaml's backup actually works

Located at custom_components/ha_mcp_tools/__init__.py:405-423:

• Side: HA-side service edit_yaml_config, in HA process, direct filesystem access.
• Storage: config_dir / ".ha_mcp_tools_backups" — explicitly NOT under www/ per inline comment citing GHSA-g39v-cvjh-8fpf (www/ is served unauthenticated at /local/, would leak backups).
• Format: <safe_name>.<timestamp>.bak, timestamp %Y%m%d_%H%M%S, safe_name normalizes os.sep → _.
• Content source: in-memory pre-read content (raw_content), not a disk re-read — TOCTOU-safe.
• Gating: per-call do_backup boolean.

Toggle-chain — enable_tool_search is the precedent to mirror

enable_auto_backup would touch the same 5 surfaces:

Surface	File:line
Settings field + env alias	src/ha_mcp/config.py:98
Addon default	homeassistant-addon/config.yaml:34
Addon schema	homeassistant-addon/config.yaml:39
Addon-dev mirror	homeassistant-addon-dev/config.yaml
Addon-dev translation	homeassistant-addon-dev/translations/en.yaml:10

Architecture-layer choices

The bot picked REST-client-layer interception in upsert_* methods. That works cleanly for automation/script/scene (clean get_*/upsert_* pairs at rest_client.py:835/864, :1336/1355, :1458/1477), but does not generalize — helpers, dashboards, labels, categories, groups, zones, areas, todos, calendar events all mutate via tool-layer WebSocket sends, not through rest_client.upsert_*. The bot's layer covers 3 of the 5 listed tools.

Three layer options:

• (A) Client-layer interception (bot's proposal) — clean for automation/script/scene only; helper/dashboard need separate handling, fragmenting the implementation.
• (B) Tool-layer decorator (@with_auto_backup wrapping each @tool) — consistent across all writes; each tool's get-pathway encapsulated; adds one WS round-trip per write.
• (C) HA-side service (sibling create_backup service in ha_mcp_tools custom component, mirroring edit_yaml_config's backup block) — each tool calls ha_mcp_tools.create_backup before its write; centralizes file I/O and reuses the security-vetted storage path; +1 WS round-trip per write.

(C) lines up with the existing precedent (file-writing already lives HA-side) and inherits the GHSA-g39v-cvjh-8fpf security treatment for free. (B) gives tighter per-tool integration. (A) only solves part of the surface.

Concurrency interaction with the known RMW race

ha_config_set_automation / _script have a documented RMW race under asyncio.gather with N>1 (#1276). A pre-write backup-fetch extends the window from RMW to FRMW (fetch → read → modify → write).

Net effect on user-visible failure: under a race, the loser's write is still lost — but its pre-state IS preserved as a backup file. That's arguably an improvement over current behavior (lost write + no backup → no recovery). The feature improves the concurrency failure mode rather than worsening it; worth surfacing here but not treating as a blocker.

Decisions implicit in the issue body, decisions still open

Already specified in the body:

• v1 surface: 5 tools (automation, script, scene, helper, dashboard)
• Browse/restore UI: explicit follow-up
• Toggle behavior: single bool, mirrored in addon config + web UI
• Storage path: "reuse .ha_mcp_tools_backups/ or sibling under /config/" — explicitly open

Still open:

• Layer: (A) client / (B) tool-decorator / (C) HA-service — (C) lines up with edit_yaml_config precedent.
• Retention between v1 and v2: not in v1 scope per the body, but a hard cap by file count or age would prevent unbounded growth before the browse-UI lands.
• Metadata fields: bot suggested entity_id/domain/tool/timestamp/intent — intent capture has no plumbing today, so v1 metadata realistically stays at the first four.

richardgaywood PR-offer status

The PR offer is in discussion #984's body: "I would be happy to try and put a PR together if this is a good idea!" No PRs or issues authored by richardgaywood on the repo in the 5 days since #1288 was filed (gh search prs --author=richardgaywood --repo=homeassistant-ai/ha-mcp returns empty). Either off-tree pre-PR-stage, or waiting on the layer/storage decisions above before opening a draft.

[github-actions]

✅ This issue has been addressed in the dev channel!

A fix for this issue has been merged to master (PR #1403) and is available for testing in the dev channel.

Test the fix before the next stable release (biweekly Wednesday):
📖 Dev Channel Documentation

Quick start

# Run dev version
uvx ha-mcp-dev

# Check version
uvx ha-mcp-dev --version

Docker:

docker pull ghcr.io/homeassistant-ai/ha-mcp:dev
docker run --rm -i \
  -e HOMEASSISTANT_URL=http://your-ha:8123 \
  -e HOMEASSISTANT_TOKEN=your_token \
  ghcr.io/homeassistant-ai/ha-mcp:dev

---

After testing:

• ✅ If it's fixed: Great! Feel free to comment here to confirm
• ❌ If still broken: Open a new issue and reference [FEATURE] Auto-backup edited entities on every write (automations/scripts/scenes/dashboards/helpers) #1288
  • Closed issues can't be reopened by reporters
  • A new issue helps us track the problem properly