ha-mcp-dev 8.4.2.dev2533__tar.gz → 8.4.3.dev2539__tar.gz

{ha_mcp_dev-8.4.2.dev2533/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.4.3.dev2539}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.4.2.dev2533
+Version: 8.4.3.dev2539
 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.4.2.dev2533 → ha_mcp_dev-8.4.3.dev2539}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.4.2.dev2533"
+version = "8.4.3.dev2539"
 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.4.2.dev2533 → ha_mcp_dev-8.4.3.dev2539}/src/ha_mcp/backup_manager.py

@@ -40,6 +40,7 @@ from __future__ import annotations
 
 import asyncio
 import difflib
+import hashlib
 import logging
 import os
 import re
@@ -103,15 +104,24 @@ class MandatoryBackupError(Exception):
 _TRACKER_SOFT_CAP = 10_000
 _TRACKER_PRUNE_BATCH = 1_000
 
-# Filename pattern: <domain>.<safe_entity_id>.<YYYYMMDD_HHMMSS>.yaml
+# Filename pattern: <domain>.<safe_entity_id>.<YYYYMMDD_HHMMSS>[_NN].yaml
 # The middle ``.`` separators make the timestamp rsplit reliable even
-# when entity_id contains dots (after sanitization, dots are kept).
+# when entity_id contains dots (after sanitization, dots are kept). ``_NN``
+# is the same-second sequence (see ``_unclaimed_target``): the timestamp is
+# a second and the throttle defaults to 0, so a second capture of one entity
+# inside that second takes the next free suffix rather than replacing the
+# first. ``_`` sorts after ``.``, so a suffixed name stays newest-last.
 _FILENAME_RE = re.compile(
     r"^(?P<domain>[A-Za-z0-9_]+)\."
     r"(?P<entity_id>[A-Za-z0-9._-]+)\."
-    r"(?P<ts>\d{8}_\d{6})\.yaml$"
+    r"(?P<ts>\d{8}_\d{6})(?:_(?P<seq>\d{2}))?\.yaml$"
 )
 
+# Captures of one entity inside one second before the manager gives up on a
+# free name. Two is the realistic case (a save then a delete of the same
+# blueprint); the cap only bounds the ``exists()`` probe.
+_MAX_SAME_SECOND = 100
+
 # Domains whose snapshot ``config`` is raw text (file/YAML content) rather
 # than a structured dict. They carry a ``kind: "text"`` marker in the
 # snapshot payload and diff via a unified text diff instead of JSON-Patch
@@ -121,7 +131,19 @@ _FILENAME_RE = re.compile(
 # (read_file), but restored via edit_yaml_config(action="replace_file") because
 # write_file rejects config files. It backs the pre-restore safety snapshot and
 # the legacy-store restore (#1579).
-_TEXT_DOMAINS = frozenset({"file", "yaml", "yaml_file"})
+#
+# ``blueprint_automation`` / ``blueprint_script`` snapshot the blueprint's raw
+# YAML text (#2329): core stores blueprints as files, and ``blueprint/save``
+# takes the same YAML string back, so the round trip is text on both ends.
+_TEXT_DOMAINS = frozenset(
+    {
+        "file",
+        "yaml",
+        "yaml_file",
+        "blueprint_automation",
+        "blueprint_script",
+    }
+)
 
 # Pre-#1579 backups (``.ha_mcp_tools_backups/*.bak``) are surfaced through the
 # same scope="edits" actions under a synthetic name ``legacy:<filename>``. The
@@ -163,17 +185,74 @@ class DomainHandler:
 # ----------------------------- backup manager -------------------------------
 
 
+def _entity_id_aliases(entity_id: str) -> list[str]:
+    """Every filename stem a snapshot of ``entity_id`` may carry.
+
+    Sanitised ids gained a digest suffix, so snapshots written before that
+    sit under the bare sanitised name. Rotation and entity filtering match
+    both, otherwise those older files would never be counted again: they
+    would never be pruned, and would drop out of an entity-filtered listing.
+    """
+    current = _safe_entity_id(entity_id)
+    legacy = _SAFE_ID_RE.sub("_", entity_id).lstrip(".") or "_"
+    return [current] if legacy == current else [current, legacy]
+
+
 def _safe_entity_id(entity_id: str) -> str:
     """Sanitize an entity id for use in a filename.
 
     Replaces any character outside ``[A-Za-z0-9._-]`` with ``_``. Path
     separators get caught by this (the regex excludes both ``/`` and ``\\``).
     Strips leading dots to prevent dotfile collisions.
+
+    Sanitizing is lossy, so ids that needed it get a short digest of the
+    ORIGINAL appended. Blueprint domains (#2329) key on paths, where
+    ``user/motion.yaml`` and ``user_motion.yaml`` both clean to
+    ``user_motion.yaml`` -- without the digest they share one snapshot
+    namespace, so captures in the same second overwrite each other and
+    rotation counts both histories as one, able to delete the only restore
+    point for a blueprint that was never written. Entity ids are already
+    within the safe set, so their filenames are unchanged and existing
+    snapshots stay discoverable.
     """
     if not entity_id:
         return "_"
     cleaned = _SAFE_ID_RE.sub("_", entity_id).lstrip(".")
-    return cleaned or "_"
+    if not cleaned:
+        return "_"
+    if cleaned == entity_id:
+        return cleaned
+    digest = hashlib.sha256(entity_id.encode("utf-8")).hexdigest()[:8]
+    return f"{cleaned}-{digest}"
+
+
+def _snapshot_order(path: Path) -> tuple[str, str, str]:
+    """Sort key placing snapshots in capture order, oldest first.
+
+    Filenames cannot be compared directly: an id the sanitiser rewrote has
+    two stems, and the digest stem sorts before the bare one on every name
+    (``-`` < ``.``) regardless of timestamp, so by name every new capture
+    would age below every pre-digest file. The parsed timestamp and the
+    same-second sequence order them; the name only breaks exact ties.
+    """
+    m = _FILENAME_RE.match(path.name)
+    if m is None:
+        return ("", "", path.name)
+    return (m.group("ts"), m.group("seq") or "", path.name)
+
+
+def _id_matches(payload_id: str | None, wanted: str) -> bool:
+    """Whether a snapshot whose payload names ``payload_id`` is ``wanted``.
+
+    Two spellings select an entity: the id itself, and the digest stem
+    ``_safe_entity_id`` derives from it — the stem a listing used to show and
+    a filename still carries. Both name exactly one entity. The bare
+    pre-digest stem is deliberately not accepted: it is the current stem of a
+    differently-named entity, which is the ambiguity this check exists for.
+    """
+    if payload_id is None:
+        return False
+    return payload_id == wanted or _safe_entity_id(payload_id) == wanted
 
 
 def _now_ts() -> str:
@@ -517,9 +596,7 @@ class BackupManager:
         self, domain: str, entity_id: str, config: Any, tool_name: str | None
     ) -> Path:
         safe = _safe_entity_id(entity_id)
-        ts = _now_ts()
-        filename = f"{domain}.{safe}.{ts}.yaml"
-        target = self._dir / filename
+        target = self._unclaimed_target(domain, safe, _now_ts())
         payload: dict[str, Any] = {
             "schema_version": SCHEMA_VERSION,
             "domain": domain,
@@ -538,10 +615,76 @@ class BackupManager:
         logger.info("Auto-backup: wrote %s", target.name)
         return target
 
+    def _unclaimed_target(self, domain: str, safe: str, ts: str) -> Path:
+        """First filename for ``ts`` that no snapshot of this entity holds yet.
+
+        The bare name is taken when it is free; each later capture inside the
+        same second appends ``_01``, ``_02``, ... so the atomic replace in
+        ``_write_snapshot`` can never discard an earlier pre-write state.
+        ``maybe_snapshot`` serialises captures per key, so the ``exists()``
+        probe is not racing another capture of the same entity.
+        """
+        target = self._dir / f"{domain}.{safe}.{ts}.yaml"
+        for seq in range(1, _MAX_SAME_SECOND):
+            if not target.exists():
+                return target
+            target = self._dir / f"{domain}.{safe}.{ts}_{seq:02d}.yaml"
+        if not target.exists():
+            return target
+        raise OSError(
+            f"{_MAX_SAME_SECOND} snapshots of {domain}:{safe} inside one second"
+        )
+
+    def _payload_entity_id(self, path: Path) -> str | None:
+        """The id the snapshot at ``path`` was taken for, from its payload.
+
+        Filename stems are ambiguous in both directions: the legacy stem for
+        ``user/motion.yaml`` is ``user_motion.yaml``, which is also the
+        CURRENT stem of a differently-named blueprint. The payload keeps the
+        original id, so rotation and the entity filter behind ``list_snapshots``
+        / ``delete_bulk`` ask it rather than trusting the name. A file that
+        cannot be read answers ``None`` and is treated as not ours: skipping it
+        wastes a rotation slot or hides it from one entity's listing, deleting
+        it could destroy another entity's only restore point.
+
+        Only the header is read. ``_write_snapshot`` emits ``entity_id`` before
+        ``config`` (which is the whole automation, dashboard or file), so the
+        read stops at the ``config:`` line and never parses the body: every
+        listing row opens its file, and an unfiltered listing of hundreds of
+        whole-file snapshots has to stay a header read per row.
+        """
+        try:
+            with path.open(encoding="utf-8") as handle:
+                header: list[str] = []
+                for line in handle:
+                    if line.startswith("config:"):
+                        break
+                    header.append(line)
+                loaded = yaml.safe_load("".join(header))
+        except (OSError, yaml.YAMLError) as err:
+            logger.warning(
+                "Auto-backup: cannot identify %s, leaving it in place: %s",
+                path.name,
+                err,
+            )
+            return None
+        if not isinstance(loaded, dict):
+            return None
+        found = loaded.get("entity_id")
+        return found if isinstance(found, str) else None
+
+    def _snapshot_is_for(self, path: Path, entity_id: str) -> bool:
+        """Whether ``path`` holds a snapshot of ``entity_id`` (see ``_id_matches``)."""
+        return _id_matches(self._payload_entity_id(path), entity_id)
+
     def _rotate(self, domain: str, entity_id: str) -> None:
-        safe = _safe_entity_id(entity_id)
-        pattern = f"{domain}.{safe}.*.yaml"
-        files = sorted(self._dir.glob(pattern))
+        candidates: set[Path] = set()
+        for safe in _entity_id_aliases(entity_id):
+            candidates.update(self._dir.glob(f"{domain}.{safe}.*.yaml"))
+        files = sorted(
+            (p for p in candidates if self._snapshot_is_for(p, entity_id)),
+            key=_snapshot_order,
+        )
         excess = len(files) - self.retain_per_entity
         for old in files[: max(0, excess)]:
             try:
@@ -566,30 +709,64 @@ class BackupManager:
         # would otherwise never match a filter passed in original form.
         # Sanitize the filter once up front so the per-file comparison is
         # symmetric: filter and ``meta["entity_id"]`` both come from the
-        # same sanitization function.
-        safe_filter = _safe_entity_id(entity_id) if entity_id else None
+        # same sanitization function. The stem only narrows the candidates:
+        # sanitising is lossy in both directions (``user/motion.yaml``'s
+        # pre-digest stem IS ``user_motion.yaml``'s current stem), so each
+        # stem match is confirmed against the id the payload stores before it
+        # counts as this entity's — ``delete_bulk`` unlinks whatever is
+        # returned here, and the caller named one entity.
+        safe_filter = set(_entity_id_aliases(entity_id)) if entity_id else None
         out: list[dict[str, Any]] = []
-        # Reverse-sorted glob — newest filenames sort last lexicographically,
-        # so reverse=True yields newest-first.
-        for path in sorted(self._dir.glob("*.yaml"), reverse=True):
-            meta = self._parse_filename(path.name)
-            if meta is None:
-                continue
-            if domain and meta["domain"] != domain:
-                continue
-            if safe_filter and meta["entity_id"] != safe_filter:
-                continue
-            try:
-                stat = path.stat()
-            except OSError:
+        # Newest first by capture time — see ``_snapshot_order`` for why the
+        # filename itself is not the key.
+        for path in sorted(self._dir.glob("*.yaml"), key=_snapshot_order, reverse=True):
+            row = self._listing_row(
+                path, domain=domain, safe_filter=safe_filter, entity_id=entity_id
+            )
+            if row is None:
                 continue
-            meta["size"] = stat.st_size
-            meta["mtime"] = stat.st_mtime
-            out.append(meta)
+            out.append(row)
             if limit and len(out) >= limit:
                 break
         return out
 
+    def _listing_row(
+        self,
+        path: Path,
+        *,
+        domain: str | None,
+        safe_filter: set[str] | None,
+        entity_id: str | None,
+    ) -> dict[str, Any] | None:
+        """One ``list_snapshots`` entry for ``path``, or ``None`` if filtered out."""
+        meta = self._parse_filename(path.name)
+        if meta is None:
+            return None
+        if domain and meta["domain"] != domain:
+            return None
+        if safe_filter and meta["entity_id"] not in safe_filter:
+            return None
+        # Every row reports the id its payload names, not its stem: a filter
+        # needs the stored id to settle the stem ambiguity anyway, and a stem
+        # shown to the caller — digest or pre-digest — is a value the filter
+        # would refuse or misroute, where the stored id is what the settings
+        # UI and ha_manage_backup can send straight back and get that entity's
+        # whole history. The read is header-only (``_payload_entity_id``); a
+        # file that cannot identify itself keeps its stem in an unfiltered
+        # listing and is left out of a filtered one.
+        payload_id = self._payload_entity_id(path)
+        if entity_id and not _id_matches(payload_id, entity_id):
+            return None
+        if payload_id is not None:
+            meta["entity_id"] = payload_id
+        try:
+            stat = path.stat()
+        except OSError:
+            return None
+        meta["size"] = stat.st_size
+        meta["mtime"] = stat.st_mtime
+        return meta
+
     def _parse_filename(self, name: str) -> dict[str, Any] | None:
         m = _FILENAME_RE.match(name)
         if m is None:
@@ -2272,6 +2449,62 @@ async def _read_legacy_backup(client: Any, filename: str) -> dict[str, Any]:
     return unwrap_service_response(result)
 
 
+# Blueprints (#2329) — ``ha_manage_blueprints`` can unlink a blueprint file that
+# core will not rebuild (``action="delete"``) or overwrite one
+# (``action="save"``), so the pre-write snapshot is the only way back.
+# ``entity_id`` is the blueprint path inside ``blueprints/<domain>/`` (e.g.
+# ``user/motion.yaml``) and the snapshot ``config`` is the raw YAML text,
+# restored through ``blueprint/save``.
+
+
+async def _fetch_blueprint(client: Any, path: str, domain: str) -> Any:
+    """Fetch a blueprint's YAML for snapshotting, best copy first.
+
+    Delegates to the shared tier ladder in ``tools.blueprint_sources`` — the
+    same one ``ha_manage_blueprints(action="get")`` walks — but only its
+    installed-file tiers: the embedded read, the component's ``blueprint_get``
+    text, and the tools entry's ``read_file``. The ``source_url`` re-fetch
+    ``get`` may fall back to is deliberately NOT a snapshot source: it is what
+    the author publishes now, so a restore from it could silently write
+    different YAML than the delete or overwrite destroyed.
+
+    ``None`` means there is nothing to snapshot (no installed-file tier could
+    serve it); the decorator logs that skip and the write proceeds
+    un-backed-up, which is the best-effort contract.
+    """
+    from .tools.blueprint_sources import resolve_blueprint_source
+
+    found = await resolve_blueprint_source(client, domain, path, source_url=None)
+    return found.text
+
+
+async def _restore_blueprint(client: Any, path: str, config: Any, domain: str) -> Any:
+    """Re-install a captured blueprint via ``blueprint/save``."""
+    response = await client.send_websocket_message(
+        {
+            "type": "blueprint/save",
+            "domain": domain,
+            "path": path,
+            "yaml": str(config),
+            "allow_override": True,
+        }
+    )
+    if not isinstance(response, dict) or not response.get("success"):
+        error = response.get("error") if isinstance(response, dict) else response
+        raise HomeAssistantError(f"blueprint/save restore failed for {path!r}: {error}")
+    return response.get("result") or {}
+
+
+def _make_blueprint_handler(domain: str) -> DomainHandler:
+    async def fetch(client: Any, entity_id: str) -> Any:
+        return await _fetch_blueprint(client, entity_id, domain)
+
+    async def restore(client: Any, entity_id: str, config: Any) -> Any:
+        return await _restore_blueprint(client, entity_id, config, domain)
+
+    return DomainHandler(domain=f"blueprint_{domain}", fetch=fetch, restore=restore)
+
+
 def _make_helper_handler(helper_type: str) -> DomainHandler:
     async def fetch(client: Any, entity_id: str) -> Any:
         return await _fetch_helper(client, entity_id, helper_type)
@@ -2325,5 +2558,9 @@ def register_default_handlers(mgr: BackupManager, _client: Any) -> None:
     # edit_yaml_config(replace_file) since write_file rejects config files.
     # Backs the legacy-restore write path and its pre-restore safety snapshot.
     mgr.register(DomainHandler("yaml_file", _fetch_file, _restore_yaml_file))
+    # Blueprint files (#2329): the pre-write snapshot for
+    # ha_manage_blueprints(action="delete" / "save").
+    for blueprint_domain in ("automation", "script"):
+        mgr.register(_make_blueprint_handler(blueprint_domain))
     for helper_type in _KNOWN_HELPER_TYPES:
         mgr.register(_make_helper_handler(helper_type))

{ha_mcp_dev-8.4.2.dev2533 → ha_mcp_dev-8.4.3.dev2539}/src/ha_mcp/config.py

@@ -1548,7 +1548,10 @@ _EMBEDDED_CONNECTION: dict[str, str | bool] = {}
 
 
 def set_embedded_connection(
-    url: str, token: str, verify_ssl: bool | None = None
+    url: str,
+    token: str,
+    verify_ssl: bool | None = None,
+    config_dir: str | None = None,
 ) -> None:
     """Register the in-process HA connection for embedded mode.
 
@@ -1572,6 +1575,14 @@ def set_embedded_connection(
     for 127.0.0.1, so verification on the loopback connection can only fail.
     ``None`` (the default, and what pre-#1890 components pass implicitly)
     leaves ``Settings.verify_ssl`` alone.
+
+    ``config_dir`` is Home Assistant's own configuration directory (#2329).
+    Embedded mode is its only writer and it is read back through
+    :func:`get_embedded_config_dir` alone — deliberately NOT a ``Settings``
+    field, so no env var or override file can point it anywhere. It lets an
+    in-process server read a blueprint's on-disk YAML directly instead of
+    routing the read through the component, and grants nothing an external
+    server could not already reach.
     """
     _EMBEDDED_CONNECTION["url"] = url
     _EMBEDDED_CONNECTION["token"] = token
@@ -1579,10 +1590,25 @@ def set_embedded_connection(
         _EMBEDDED_CONNECTION.pop("verify_ssl", None)
     else:
         _EMBEDDED_CONNECTION["verify_ssl"] = verify_ssl
+    if config_dir is None:
+        _EMBEDDED_CONNECTION.pop("config_dir", None)
+    else:
+        _EMBEDDED_CONNECTION["config_dir"] = config_dir
     if _settings is not None:
         _apply_embedded_connection(_settings)
 
 
+def get_embedded_config_dir() -> str | None:
+    """Home Assistant's configuration directory, when running embedded.
+
+    ``None`` outside embedded mode, and on an embedded install whose component
+    predates the ``config_dir`` keyword. Consumers must treat it as an optional
+    capability and fall back to their component / service path.
+    """
+    config_dir = _EMBEDDED_CONNECTION.get("config_dir")
+    return config_dir if isinstance(config_dir, str) and config_dir else None
+
+
 def _reset_embedded_connection() -> None:
     """Drop the registered embedded connection (test seam).
 

{ha_mcp_dev-8.4.2.dev2533 → ha_mcp_dev-8.4.3.dev2539}/src/ha_mcp/read_only.py

@@ -153,6 +153,21 @@ def _updates_write(args: dict[str, Any]) -> str | None:
     return f"action={action!r}"
 
 
+def _blueprint_write(args: dict[str, Any]) -> str | None:
+    # Reads (allowed): listing installed blueprints and reading one's
+    # metadata/inputs/body. ``substitute`` joins them because it is a pure
+    # render — core builds the standalone config in memory and sends it back,
+    # touching neither the blueprint store nor any automation/script; writing
+    # the rendered config anywhere still needs ha_config_set_automation /
+    # ha_config_set_script, which read-only mode blocks. ``import`` (writes a
+    # blueprint file), ``save`` (overwrites one with caller-supplied YAML) and
+    # ``delete`` stay blocked, and a missing/unknown action fails closed.
+    action = args.get("action")
+    if action in ("list", "get", "substitute"):
+        return None
+    return f"action={action!r}"
+
+
 def _theme_write(args: dict[str, Any]) -> str | None:
     # Reads (allowed): listing installed themes and inspecting the screenshot
     # engine account's saved per-user theme. The latter has no pure-read
@@ -259,6 +274,14 @@ READ_ONLY_EXEMPT_TOOLS: dict[str, ReadOnlyExemption] = {
         _security_policy_write,
         "reading the policy document (action='get')",
     ),
+    # Blueprint listing and reading exist only here — ha_get_blueprint was
+    # merged into this tool (issue #2329), so hiding it would remove the read
+    # surface entirely.
+    "ha_manage_blueprints": ReadOnlyExemption(
+        _blueprint_write,
+        "listing and reading blueprints (action='list' or 'get') and "
+        "rendering a standalone config (action='substitute')",
+    ),
 }
 
 

ha_mcp_dev-8.4.3.dev2539/src/ha_mcp/renamed_tools.py

@@ -0,0 +1,103 @@
+"""Tools whose names moved, and the stored state that has to follow them.
+
+Home Assistant 2026.2 renamed add-ons to apps, and this server's two add-on
+tools moved with it. Issue #2329 then folded the two blueprint tools into one
+``ha_manage_blueprints``. Neither is a breaking change for callers — clients
+resolve by name at runtime, and ``RenamedToolAliasMiddleware`` keeps the old
+name callable for one that has not re-listed yet.
+
+What does not repair itself is state a user already stored under the old name:
+a tool they disabled or pinned in the settings UI, a ``DISABLED_TOOLS`` entry,
+a policy rule naming the tool. Those keys are read through the mapping here,
+so the setting survives the rename instead of falling back to the default —
+which for a disabled write tool means silently re-enabling it.
+
+A consolidation adds two wrinkles a plain rename does not have. Two retired
+names can now carry different stored states for one current tool, so the
+readers pick the more restrictive one (``rename_retired_keys``'s ``prefer``).
+And a call on a retired name carries the old signature, which the merged tool
+cannot dispatch without the ``action`` it never had —
+``adapt_retired_arguments`` fills that in.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import Any
+
+# Retired tool name -> the name that serves it today.
+RENAMED_TOOLS: dict[str, str] = {
+    "ha_get_addon": "ha_get_app",
+    "ha_manage_addon": "ha_manage_app",
+    # #2329: consolidated, not renamed — both retired tools answer to one
+    # action-dispatched tool. A call on either old name needs an ``action``
+    # (see ``adapt_retired_arguments``), and stored state for the two can
+    # disagree (see ``rename_retired_keys``).
+    "ha_get_blueprint": "ha_manage_blueprints",
+    "ha_import_blueprint": "ha_manage_blueprints",
+}
+
+
+def current_tool_name(name: str) -> str:
+    """The name a tool answers to today, given any name it has had."""
+    return RENAMED_TOOLS.get(name, name)
+
+
+def rename_retired_keys[T](
+    states: Mapping[str, T], *, prefer: Callable[[T, T], T] | None = None
+) -> dict[str, T]:
+    """Re-key a per-tool mapping onto the current tool names.
+
+    A value already stored under the current name wins: it was set against
+    the tool as it is now, while the retired key is inherited.
+
+    When two retired names were folded into one current tool and both carry
+    a value, ``prefer(a, b)`` picks the one to keep; readers pass the more
+    restrictive choice for their value type (a disabled tool must not come
+    back enabled because its sibling was merely pinned). Without ``prefer``
+    the later key in iteration order wins, which is only acceptable for
+    mappings that cannot collide.
+    """
+    renamed: dict[str, T] = {}
+    for name, value in states.items():
+        if name not in RENAMED_TOOLS:
+            continue
+        current = current_tool_name(name)
+        if current in renamed and prefer is not None:
+            renamed[current] = prefer(renamed[current], value)
+        else:
+            renamed[current] = value
+    kept = {name: value for name, value in states.items() if name not in RENAMED_TOOLS}
+    return {**renamed, **kept}
+
+
+def _adapt_get_blueprint(arguments: dict[str, Any]) -> dict[str, Any]:
+    # ``ha_get_blueprint`` listed without a path and read one with it.
+    return {"action": "get" if arguments.get("path") else "list", **arguments}
+
+
+def _adapt_import_blueprint(arguments: dict[str, Any]) -> dict[str, Any]:
+    return {"action": "import", **arguments}
+
+
+# Retired name -> how its call arguments map onto the current tool's. Only a
+# consolidation needs one; a plain rename forwards the arguments unchanged.
+_RETIRED_ARGUMENT_ADAPTERS: dict[str, Callable[[dict[str, Any]], dict[str, Any]]] = {
+    "ha_get_blueprint": _adapt_get_blueprint,
+    "ha_import_blueprint": _adapt_import_blueprint,
+}
+
+
+def adapt_retired_arguments(
+    name: str, arguments: Mapping[str, Any] | None
+) -> dict[str, Any] | None:
+    """Rewrite a retired tool's call arguments for the tool that serves it now.
+
+    ``name`` is the name the caller used. Names without an adapter — current
+    names and plain renames — return the arguments untouched (``None`` stays
+    ``None``). An explicit ``action`` in the arguments is respected.
+    """
+    adapter = _RETIRED_ARGUMENT_ADAPTERS.get(name)
+    if adapter is None:
+        return dict(arguments) if arguments is not None else None
+    return adapter(dict(arguments or {}))

{ha_mcp_dev-8.4.2.dev2533 → ha_mcp_dev-8.4.3.dev2539}/src/ha_mcp/server.py

@@ -637,10 +637,12 @@ class HomeAssistantSmartMCPServer:
         ),
         "ha_config_set_automation": (
             "create update modify edit automation triggers conditions actions "
-            "new automation write save"
+            "new automation write save take control blueprint detach "
+            "unlink standalone convert"
         ),
         "ha_config_set_script": (
-            "create update modify edit script sequence actions new script write save"
+            "create update modify edit script sequence actions new script write "
+            "save take control blueprint detach unlink standalone convert"
         ),
         "ha_config_set_yaml": (
             "edit yaml configuration.yaml packages template sensor "
@@ -668,6 +670,14 @@ class HomeAssistantSmartMCPServer:
             "grid solar battery gas water consumption "
             "number_energy_price entity_energy_price stat_energy_from"
         ),
+        # Old tool names from before the #2329 consolidation, plus the verbs
+        # the merged tool gained. An agent that still knows ha_get_blueprint /
+        # ha_import_blueprint routes to the replacement instead of failing
+        # tool lookup.
+        "ha_manage_blueprints": (
+            "blueprint blueprints import delete remove unused substitute "
+            "take-control list ha_get_blueprint ha_import_blueprint"
+        ),
         # Old tool names from before #1134 consolidation. BM25 retrieval
         # on agents that still know the previous catalog ("call
         # ha_list_resources", "use ha_get_skill_home_assistant_best_practices")
@@ -702,11 +712,13 @@ class HomeAssistantSmartMCPServer:
         ),
         "ha_config_set_automation": (
             "Create or update a Home Assistant automation.\n\n"
-            "Supports two modes: full `config` replacement, or surgical "
+            "Supports three modes: full `config` replacement, surgical "
             "`python_transform` on an existing automation (requires "
             "`identifier` and `config_hash` from "
-            "ha_config_get_automation). Omit `identifier` to create a "
-            "new automation.\n\n"
+            "ha_config_get_automation), or `take_control_of_blueprint` "
+            "to convert a blueprint-backed automation into an editable "
+            "standalone one (the UI's Take control action). Omit "
+            "`identifier` to create a new automation.\n\n"
             "For schema details, examples, and native-vs-template "
             "guidance, see ha_get_skill_guide or your locally "
             "installed skills."
@@ -721,10 +733,12 @@ class HomeAssistantSmartMCPServer:
         ),
         "ha_config_set_script": (
             "Create or update a Home Assistant script.\n\n"
-            "Supports two modes: full `config` replacement, or surgical "
+            "Supports three modes: full `config` replacement, surgical "
             "`python_transform` on an existing script (requires "
-            "`config_hash` from ha_config_get_script). `script_id` names "
-            "the script in both modes.\n\n"
+            "`config_hash` from ha_config_get_script), or "
+            "`take_control_of_blueprint` to convert a blueprint-backed "
+            "script into an editable standalone one. `script_id` names "
+            "the script in every mode.\n\n"
             "For schema details and examples, see "
             "ha_get_skill_guide or your locally installed skills."
         ),