ha-mcp-dev 7.9.0.dev751__tar.gz → 7.9.0.dev753__tar.gz

{ha_mcp_dev-7.9.0.dev751/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.9.0.dev753}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.9.0.dev751
+Version: 7.9.0.dev753
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

{ha_mcp_dev-7.9.0.dev751 → ha_mcp_dev-7.9.0.dev753}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.9.0.dev751"
+version = "7.9.0.dev753"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

{ha_mcp_dev-7.9.0.dev751 → ha_mcp_dev-7.9.0.dev753}/src/ha_mcp/config.py

@@ -155,6 +155,17 @@ class Settings(BaseSettings):
     # files. Disabled by default; only for YAML-only features with no UI/API path.
     enable_yaml_config_editing: bool = Field(False, alias="ENABLE_YAML_CONFIG_EDITING")
 
+    # Two-step confirmation for ha_config_set_yaml (#1720). When on (the
+    # default), the first edit call returns a unified diff preview plus a
+    # confirm token and writes NOTHING; the edit lands only when repeated
+    # with that token. Sub-toggle of enable_yaml_config_editing (nested
+    # beneath it in the UI). Default ON deliberately: the diff preview is
+    # what lets the calling agent catch collateral changes before they
+    # reach disk. Listed in BETA_FEATURE_FIELDS purely for the addon-mode
+    # override path; the master-off cascade forcing it False is moot
+    # because the yaml tool itself is unregistered then.
+    enable_yaml_edit_confirm: bool = Field(True, alias="ENABLE_YAML_EDIT_CONFIRM")
+
     # Per-key gates for ``automation`` / ``script`` / ``scene`` under
     # ``packages/*.yaml``. The custom component accepts these three
     # PACKAGES_ONLY_YAML_KEYS unconditionally; ha-mcp's UI exposes a
@@ -604,6 +615,7 @@ FEATURE_FLAG_FIELDS: tuple[FeatureFlagField, ...] = (
     # are name-disjoint per _validate_registries()).
     FeatureFlagField("enable_mandatory_bps", "ENABLE_MANDATORY_BPS", bool),
     FeatureFlagField("enable_yaml_config_editing", "ENABLE_YAML_CONFIG_EDITING", bool),
+    FeatureFlagField("enable_yaml_edit_confirm", "ENABLE_YAML_EDIT_CONFIRM", bool),
     # Per-key sub-gates beneath enable_yaml_config_editing. Nested in
     # the UI, dimmed when the parent is off. Also listed in
     # BETA_FEATURE_FIELDS so they follow the same master-gate +
@@ -660,6 +672,7 @@ _FEATURE_FLAG_INT_BOUNDS: dict[str, tuple[int, int]] = {
 # gate, never by the per-field iteration.
 BETA_FEATURE_FIELDS: tuple[str, ...] = (
     "enable_yaml_config_editing",
+    "enable_yaml_edit_confirm",  # Default-ON safety sub-toggle; see field comment.
     # Per-key sub-gates of enable_yaml_config_editing. Included here so
     # they ride the same master gate + addon-mode override path as the
     # other beta flags. Without this, the addon-mode short-circuit in

{ha_mcp_dev-7.9.0.dev751 → ha_mcp_dev-7.9.0.dev753}/src/ha_mcp/server.py

@@ -704,7 +704,9 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
         "ha_config_set_yaml": (
             "Update raw YAML in configuration.yaml or packages/*.yaml "
             "via add / replace / remove on a single top-level key "
-            "(LAST RESORT).\n\n"
+            "(LAST RESORT). By default the first call returns a diff "
+            "preview plus confirm_token; repeat with confirm_token to "
+            "apply.\n\n"
             "Dedicated tools (ha_config_set_automation, "
             "ha_config_set_script, ha_config_set_scene, "
             "ha_config_set_helper) cover almost every use case and "

{ha_mcp_dev-7.9.0.dev751 → ha_mcp_dev-7.9.0.dev753}/src/ha_mcp/settings_ui/settings.js

@@ -1511,17 +1511,21 @@ const FEATURE_META = {
     label: "Enable YAML config editing (beta)",
     help: "Beta feature, disabled by default. Allows AI assistants to add, replace, or remove top-level keys in configuration.yaml and packages/*.yaml. Only whitelisted keys are allowed (e.g., template, sensor, command_line, mqtt, knx); core keys like homeassistant, http, and recorder are blocked. Each edit validates YAML syntax, runs a config check, and creates an automatic backup. Changes to most keys require a full HA restart to take effect. See docs/beta.md for known limitations. Dedicated tools (automations, scripts, scenes, helpers, template sensors) should be preferred when available.",
   },
+  enable_yaml_edit_confirm: {
+    label: "Require confirmation for YAML edits (diff preview)",
+    help: "Sub-toggle of YAML config editing, ON by default (recommended). The first ha_config_set_yaml call returns a unified diff of exactly what would change on disk plus a confirm token and writes nothing; the edit only lands when the call is repeated with that token. Exists so unintended changes outside the requested edit are caught before they reach disk (issue #1720). Turn off only to save one round-trip per edit.",
+  },
   enable_yaml_packages_automation: {
     label: "Allow automation in packages/*.yaml",
-    help: "Sub-toggle of YAML config editing. When on, ha_config_set_yaml accepts yaml_path='automation' inside packages/*.yaml. When off, the wrapper rejects the call client-side AND the custom component rejects it server-side. Storage-mode tools (ha_config_set_automation) cover the UI-managed path and are unaffected. Disabled by default.",
+    help: "Sub-toggle of YAML config editing. When on, ha_config_set_yaml accepts yaml_path='automation' inside packages/*.yaml. When off, the call is rejected both client-side and server-side. The storage-mode tool (ha_config_set_automation) is unaffected. Default OFF; only takes effect when \"Enable YAML config editing\" above is also on.",
   },
   enable_yaml_packages_script: {
     label: "Allow script in packages/*.yaml",
-    help: "Sub-toggle of YAML config editing. When on, ha_config_set_yaml accepts yaml_path='script' inside packages/*.yaml. When off, the wrapper rejects the call client-side AND the custom component rejects it server-side. Storage-mode tools (ha_config_set_script) cover the UI-managed path and are unaffected. Disabled by default.",
+    help: "Sub-toggle of YAML config editing. When on, ha_config_set_yaml accepts yaml_path='script' inside packages/*.yaml. When off, the call is rejected both client-side and server-side. The storage-mode tool (ha_config_set_script) is unaffected. Default OFF; only takes effect when \"Enable YAML config editing\" above is also on.",
   },
   enable_yaml_packages_scene: {
     label: "Allow scene in packages/*.yaml",
-    help: "Sub-toggle of YAML config editing. When on, ha_config_set_yaml accepts yaml_path='scene' inside packages/*.yaml. When off, the wrapper rejects the call client-side AND the custom component rejects it server-side. Storage-mode tools (ha_config_set_scene) cover the UI-managed path and are unaffected. Disabled by default.",
+    help: "Sub-toggle of YAML config editing. When on, ha_config_set_yaml accepts yaml_path='scene' inside packages/*.yaml. When off, the call is rejected both client-side and server-side. The storage-mode tool (ha_config_set_scene) is unaffected. Default OFF; only takes effect when \"Enable YAML config editing\" above is also on.",
   },
   enable_filesystem_tools: {
     label: "Enable filesystem tools (beta)",
@@ -1551,11 +1555,14 @@ const FEATURE_META = {
 // ``config.BETA_FEATURE_FIELDS`` without duplicating the name list here.
 let BETA_SUB_FLAGS = new Set();
 
-// Sub-flags of ``enable_yaml_config_editing``. Rendered nested beneath
-// the parent in renderFeatureFlags so the dependency is visually
-// obvious. They are NOT in BETA_SUB_FLAGS — the parent is the gate,
-// and the master-off → parent-off cascade transitively covers them.
+// Sub-flags of ``enable_yaml_config_editing`` (confirm-flow toggle +
+// per-key packages gates). They ARE in BETA_SUB_FLAGS (it mirrors
+// config.BETA_FEATURE_FIELDS verbatim), but the main render pass skips
+// them via the includes() guard below, and renderYamlPackagesSubRows
+// re-renders them nested beneath their parent — so they never appear
+// as standalone beta-sub rows.
 const YAML_PACKAGES_SUB_FLAGS = [
+  'enable_yaml_edit_confirm',
   'enable_yaml_packages_automation',
   'enable_yaml_packages_script',
   'enable_yaml_packages_scene',

{ha_mcp_dev-7.9.0.dev751 → ha_mcp_dev-7.9.0.dev753}/src/ha_mcp/tools/auto_backup.py

@@ -108,6 +108,7 @@ def with_auto_backup(
     id_fn: Callable[[dict[str, Any]], str] | None = None,
     client: Any = None,
     mandatory: bool = False,
+    skip_fn: Callable[[dict[str, Any]], bool] | None = None,
 ) -> Callable[..., Any]:
     """Decorate a write/destructive tool with pre-write auto-backup capture.
 
@@ -125,6 +126,11 @@ def with_auto_backup(
     Backup capture is best-effort: failure logs a WARNING and the wrapped
     write proceeds regardless.
 
+    ``skip_fn`` (optional) short-circuits the whole decorator — including
+    the ``mandatory`` gate — for calls it identifies as unable to write
+    (e.g. a yaml-edit confirm-flow preview): no snapshot, no refusal, the
+    wrapped tool runs directly.
+
     ``mandatory=True`` makes auto-backup a precondition (file/YAML writes,
     #1579 — those formerly kept their own private backups). It fails the
     write closed in two cases, both with a structured error and without
@@ -150,6 +156,12 @@ def with_auto_backup(
     def decorator(func: Callable[..., Awaitable[Any]]) -> Callable[..., Awaitable[Any]]:
         @functools.wraps(func)
         async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            # A call skip_fn identifies as unable to write (e.g. a yaml-edit
+            # confirm-flow PREVIEW, which returns a diff and writes nothing)
+            # needs no pre-write snapshot — and must not be refused by the
+            # mandatory gate either, since there is nothing to protect.
+            if skip_fn is not None and skip_fn(kwargs):
+                return await func(*args, **kwargs)
             # Settings + target resolution happen OUTSIDE the best-effort
             # ``try`` below: under ``mandatory`` a transient-tuple error from
             # ``get_global_settings`` / ``domain_fn`` / ``id_fn`` must NOT be

{ha_mcp_dev-7.9.0.dev751 → ha_mcp_dev-7.9.0.dev753}/src/ha_mcp/tools/tools_filesystem.py

@@ -67,7 +67,13 @@ CALLER_TOKEN_BOOTSTRAP_SERVICE = "get_caller_token"
 # and a ``yaml_path`` arg on ``read_file``. A <0.10.0 component lacks these
 # services; the gate surfaces an actionable "update" instead of a raw
 # "service not found".
-MIN_COMPONENT_VERSION = "0.10.0"
+# 0.11.0: the confirm-flow + diff work (#1720) adds ``require_confirm`` /
+# ``confirm_token`` args to ``edit_yaml_config`` and ``diff`` / ``written``
+# response fields. The server always sends ``require_confirm`` (from
+# ENABLE_YAML_EDIT_CONFIRM, default on); a <0.11.0 component's strict
+# (PREVENT_EXTRA) schema rejects the unknown arg with a raw voluptuous
+# error — the gate surfaces an actionable "update" prompt instead.
+MIN_COMPONENT_VERSION = "0.11.0"
 
 
 def _version_tuple(version: str) -> tuple[int, ...]:

{ha_mcp_dev-7.9.0.dev751 → ha_mcp_dev-7.9.0.dev753}/src/ha_mcp/tools/tools_yaml_config.py

@@ -63,6 +63,34 @@ _YAML_PACKAGES_FLAG_BY_KEY = {
     "scene": "enable_yaml_packages_scene",
 }
 
+# Keys editable here that ALSO have a storage-mode helper equivalent.
+# Deliberately NOT blocked (git-managed YAML configs are legitimate) —
+# the response instead carries a reactive routing warning, since this
+# exact entry point (utility_meter via raw YAML when the helper tool
+# covered it) is how the #1720 corruption reached a production config.
+_HELPER_EQUIVALENT_KEYS: dict[str, str] = {
+    "template": "template",
+    "utility_meter": "utility_meter",
+    "group": "group",
+}
+
+
+def _is_preview_only_call(kwargs: dict[str, Any]) -> bool:
+    """True when this ha_config_set_yaml call can only return a preview.
+
+    With the confirm flow enabled and no ``confirm_token`` supplied, the
+    component returns a diff preview and writes nothing — so the mandatory
+    pre-write auto-backup would snapshot for an edit that never happens
+    (phantom ``scope="edits"`` entries). A settings failure returns False,
+    failing toward capturing a backup.
+    """
+    if kwargs.get("confirm_token") is not None:
+        return False
+    try:
+        return bool(get_global_settings().enable_yaml_edit_confirm)
+    except Exception:
+        return False
+
 
 def _disabled_packages_keys(settings: Any) -> list[str]:
     """Return the sorted list of PACKAGES_ONLY_YAML_KEYS whose Settings
@@ -146,6 +174,7 @@ class YamlConfigTools:
             f"{kw.get('file') or 'configuration.yaml'}::{kw.get('yaml_path') or ''}"
         ),
         mandatory=True,
+        skip_fn=_is_preview_only_call,
     )
     @log_tool_usage
     async def ha_config_set_yaml(
@@ -204,6 +233,19 @@ class YamlConfigTools:
                 ),
             ),
         ] = "configuration.yaml",
+        confirm_token: Annotated[
+            str | None,
+            Field(
+                default=None,
+                description=(
+                    "Confirmation token from a prior preview response. When "
+                    "the YAML edit confirmation flow is enabled (default), "
+                    "the first call writes nothing and returns a unified "
+                    "diff plus confirm_token; repeat the identical call "
+                    "with that token to apply the edit."
+                ),
+            ),
+        ] = None,
         MandatoryBPS: Annotated[
             bool,
             Field(default=True),
@@ -249,6 +291,16 @@ class YamlConfigTools:
         live. Preserves YAML comments and HA tags (``!include``,
         ``!secret``) on round-trip; ``replace`` swaps the subtree as-is.
 
+        Two-step confirmation (default ON, toggle ENABLE_YAML_EDIT_CONFIRM /
+        Server Settings): the first call returns ``preview: true`` with a
+        unified ``diff`` of exactly what would change on disk and a
+        ``confirm_token`` — nothing is written. Review the diff for
+        changes outside the requested edit, then repeat the identical
+        call adding ``confirm_token`` to apply. Every applied write also
+        returns the final ``diff``. A token mismatch means the file
+        changed since the preview (or the token was wrong); use the
+        freshly returned token.
+
         ``template-guidelines.md`` ships in this response under ``skill_content``
         by default — YAML packages frequently include
         template sensors / command_line entities / mqtt templates, exactly where
@@ -348,9 +400,12 @@ class YamlConfigTools:
                 "action": action,
                 "yaml_path": yaml_path,
                 "disabled_packages_keys": disabled_keys,
+                "require_confirm": settings.enable_yaml_edit_confirm,
             }
             if content is not None:
                 service_data["content"] = content
+            if confirm_token is not None:
+                service_data["confirm_token"] = confirm_token
 
             # Call the custom component service (token injected by helper)
             result = await call_mcp_tools_service(
@@ -375,9 +430,30 @@ class YamlConfigTools:
                         '(e.g. ha_reload_core(target="themes")) or restart '
                         "Home Assistant to apply the change."
                     )
+                # themes/*.yaml guard: there the top_key is a THEME NAME, so
+                # a theme that happens to be called 'template'/'group'/
+                # 'utility_meter' must not draw the helper-routing warning.
+                if (
+                    action in ("add", "replace")
+                    and top_key in _HELPER_EQUIVALENT_KEYS
+                    and not fnmatch.fnmatch(normalized_target, "themes/*.yaml")
+                ):
+                    result.setdefault("warnings", []).append(
+                        f"Best practice: '{top_key}' has a storage-mode "
+                        f"equivalent — ha_config_set_helper(helper_type="
+                        f"'{_HELPER_EQUIVALENT_KEYS[top_key]}') — which avoids "
+                        "raw YAML file rewrites entirely. Prefer it unless "
+                        "this configuration is deliberately YAML-managed "
+                        "(e.g. git-tracked packages)."
+                    )
                 attach_skill_content(
                     result,
-                    MandatoryBPS=MandatoryBPS,
+                    # The confirm leg (token supplied) skips the bulky skill
+                    # payload: possession of a token proves the caller just
+                    # received the preview response that carried it. Preview
+                    # and single-call writes keep it — pre-write guidance is
+                    # the whole point of MandatoryBPS.
+                    MandatoryBPS=MandatoryBPS and confirm_token is None,
                     canonical_files=_YAML_SKILL_FILES,
                     referenced_files=None,
                 )

{ha_mcp_dev-7.9.0.dev751 → ha_mcp_dev-7.9.0.dev753/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.9.0.dev751
+Version: 7.9.0.dev753
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT