ha-mcp-dev 7.14.2.dev2193__tar.gz → 7.14.2.dev2196__tar.gz

{ha_mcp_dev-7.14.2.dev2193/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.14.2.dev2196}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.14.2.dev2193"
+version = "7.14.2.dev2196"
 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-7.14.2.dev2193 → ha_mcp_dev-7.14.2.dev2196}/src/ha_mcp/resources/skills-vendor/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Agent skills for Home Assistant: best practices for automations, helpers, templates, device control, and dashboards",
-    "version": "0.15.0"
+    "version": "0.16.0"
   },
   "plugins": [
     {

{ha_mcp_dev-7.14.2.dev2193 → ha_mcp_dev-7.14.2.dev2196}/src/ha_mcp/resources/skills-vendor/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "home-assistant-skills",
   "description": "Agent skills for Home Assistant: best practices for automations, helpers, templates, device control, and dashboards.",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "repository": "https://github.com/homeassistant-ai/skills",
   "license": "MIT"
 }

{ha_mcp_dev-7.14.2.dev2193 → ha_mcp_dev-7.14.2.dev2196}/src/ha_mcp/resources/skills-vendor/AGENTS.md

@@ -55,3 +55,9 @@ To validate locally:
 ```bash
 uvx skills-ref validate skills/<skill-name>
 ```
+
+## Reviewing Skill PRs
+
+- Judge prose as agent-consumed context, not human docs — the Skill Authoring Principles above are the review bar (e.g. an operator→result lookup table beats narrative bullets, because agents land here holding one case to resolve)
+- Skills make version-pinned claims about HA behavior — verify against source at the release tag: `gh api repos/home-assistant/core/contents/<path>?ref=2026.7.4 --jq .content | base64 -d`
+- Community PRs come from forks: base-repo `?ref=<pr-branch>` 404s; get the fork with `gh pr view <pr> --json headRepository` and fetch files from there

{ha_mcp_dev-7.14.2.dev2193 → ha_mcp_dev-7.14.2.dev2196}/src/ha_mcp/resources/skills-vendor/CLAUDE.md

@@ -55,3 +55,9 @@ To validate locally:
 ```bash
 uvx skills-ref validate skills/<skill-name>
 ```
+
+## Reviewing Skill PRs
+
+- Judge prose as agent-consumed context, not human docs — the Skill Authoring Principles above are the review bar (e.g. an operator→result lookup table beats narrative bullets, because agents land here holding one case to resolve)
+- Skills make version-pinned claims about HA behavior — verify against source at the release tag: `gh api repos/home-assistant/core/contents/<path>?ref=2026.7.4 --jq .content | base64 -d`
+- Community PRs come from forks: base-repo `?ref=<pr-branch>` 404s; get the fork with `gh pr view <pr> --json headRepository` and fetch files from there

{ha_mcp_dev-7.14.2.dev2193 → ha_mcp_dev-7.14.2.dev2196}/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/SKILL.md

@@ -24,7 +24,7 @@ description: >
   - Agent tells user to edit configuration.yaml for UI integrations
   - Agent hardcodes entities in a Blueprint or uses free-text input over a selector
 metadata:
-  version: 15
+  version: 16
 ---
 
 # Home Assistant Best Practices

{ha_mcp_dev-7.14.2.dev2193 → ha_mcp_dev-7.14.2.dev2196}/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/references/automation-patterns.md

@@ -927,6 +927,36 @@ variables:
 
 `trigger_variables:` is a separate top-level key evaluated **before** triggers fire — it supports **limited templates only** (no `states()`/`state_attr()`), mainly for passing a blueprint `!input` into trigger options. Don't put state-based templates there.
 
+### Keys render in order, one at a time
+
+A `variables:` block renders one key at a time, each rendered result feeding the context for the next. A key that reads a name declared **further down the same block** reads it while it is still undefined.
+
+```yaml
+# AVOID — `total` is still undefined when `msg` renders
+variables:
+  msg: "Total: {{ total }}"
+  total: "{{ states('sensor.a') | float(0) + states('sensor.b') | float(0) }}"
+
+# CORRECT — declare before use
+variables:
+  total: "{{ states('sensor.a') | float(0) + states('sensor.b') | float(0) }}"
+  msg: "Total: {{ total }}"
+```
+
+What the forward read costs depends on how the template uses the name (behavior as of 2026.7):
+
+| Use of the undefined name | Result |
+|---|---|
+| `x.attr`, `x['k']`, arithmetic, `<`/`>`/`<=`/`>=`, `\| int`, `\| float` | Raises `UndefinedError`, logs ERROR — **aborts the run** |
+| `{{ x }}`, `{% if x %}`, `{% for i in x %}`, `'p' ~ x` | Empty and falsy, logs WARNING — runs on into the else branch |
+| `x \| length`, `x == y`, `x != y` | `0` / `False` / `True` — **no log and no trace entry** |
+
+For the aborting row, [`continue_on_error:`](#continue-on-error) is no escape — it is an action option, a top-level block is not an action, and on a mid-sequence step it cannot suppress a render error. A default like `| int(0)` does not save it either: the default covers an unconvertible value, not an undefined name. In the silent row, watch `!=`: `{% if later != 'x' %}` on a name that is not defined yet takes the **then** branch, leaving nothing behind to explain why.
+
+Not a problem when the name also exists in an enclosing scope — the reference then resolves outward to that value. The two placements diverge on that collision, though: a top-level `variables:` block **skips** a key already present in the incoming scope, so the incoming value stands and the block's own definition never takes effect for that run, while a mid-sequence `- variables:` step renders and **overwrites** it. Staging a computation across consecutive `variables:` steps is therefore mid-sequence only.
+
+When an automation declares both `trigger_variables:` and `variables:`, the two render as one sequential mapping with `trigger_variables:` first, so a `variables:` key may read a `trigger_variables:` key but not the reverse. That holds for names declared in only one of the two: a name in both merges into a single entry that keeps the `trigger_variables:` position but takes the `variables:` template, so it renders early — before any `trigger_variables:` key declared after it. The separate attach-time render noted above happens before any `variables:` key exists.
+
 ---
 
 ## Capturing Action Responses

{ha_mcp_dev-7.14.2.dev2193 → ha_mcp_dev-7.14.2.dev2196}/src/ha_mcp/tools/best_practice_checker.py

@@ -47,6 +47,10 @@ documented legitimate dynamic-data positions per
 * Top-level ``variables.*``
 * Action ``service_data.*`` (legacy alias for ``data``)
 
+The allowlist covers template *content*. Key *order* inside a ``variables``
+block is separately load-bearing — HA renders one key at a time — so those
+blocks get their own ordering-only pass (:func:`_check_variables_order`).
+
 Anti-patterns sourced from:
   https://github.com/homeassistant-ai/skills
   skill://home-assistant-best-practices
@@ -57,33 +61,12 @@ from __future__ import annotations
 import re
 from typing import Any
 
-_SKILL_URI_PREFIX = "skill://home-assistant-best-practices/references"
-_DEFAULT_SKILL_PREFIX = _SKILL_URI_PREFIX
-_SKILL_NAME = "home-assistant-best-practices"
-
-
-class BestPracticeCheckResult(list[str]):
-    """Warning list with an attached set of referenced skill files.
-
-    Behaves as a plain ``list[str]`` for all call sites — ``len()``,
-    indexing, iteration, equality with ``[...]`` all work unchanged.
-    ``referenced_files`` is added on top so the write tools can resolve
-    and embed the relevant skill bodies into responses.
-
-    Use :func:`_emit` to append warnings; direct ``append``/``extend``
-    skip the ``referenced_files`` mirror. Slicing, ``list()`` coercion,
-    and ``copy.copy``/``copy.deepcopy`` all return plain ``list[str]``
-    without the attribute — no current call site does any of these.
-    """
-
-    __slots__ = ("referenced_files",)
-
-    referenced_files: set[str]
-
-    def __init__(self, items: list[str] | None = None) -> None:
-        super().__init__(items or [])
-        self.referenced_files = set()
-
+from .best_practice_result import (
+    _DEFAULT_SKILL_PREFIX,
+    BestPracticeCheckResult,
+    _emit,
+)
+from .best_practice_variables import _check_variables_order
 
 # ---------------------------------------------------------------------------
 # Regex patterns for template anti-patterns
@@ -241,6 +224,11 @@ def check_automation_config(
     # Mode vs motion pattern
     _check_mode_motion(config, warnings, skill_prefix)
 
+    # Key order inside the top-level variables blocks. Both render one key at a
+    # time, so a forward reference between siblings is silently undefined.
+    for block_key in ("variables", "trigger_variables"):
+        _check_variables_order(config.get(block_key), warnings, skill_prefix, block_key)
+
     _dedupe_inplace(warnings)
     return warnings
 
@@ -260,72 +248,11 @@ def check_script_config(
 
     warnings = BestPracticeCheckResult()
     _check_action_tree(config.get("sequence", []), warnings, skill_prefix)
+    _check_variables_order(config.get("variables"), warnings, skill_prefix, "variables")
     _dedupe_inplace(warnings)
     return warnings
 
 
-# ---------------------------------------------------------------------------
-# Warning emission + skill-reference helpers
-# ---------------------------------------------------------------------------
-
-
-def _emit(
-    warnings: BestPracticeCheckResult,
-    message: str,
-    skill_prefix: str | None,
-    file_ref: str,
-) -> None:
-    """Append a warning with the 2-route ' See ...' suffix and track the file.
-
-    Args:
-        warnings: Accumulator (also holds ``referenced_files``).
-        message: Human-readable warning body — the inline alternative.
-        skill_prefix: When set, embedded as the ``skill://`` URI route.
-            When ``None``, the URI route is omitted but the other two
-            routes still appear.
-        file_ref: File path relative to the ``references/`` directory of
-            the home-assistant-best-practices skill, optionally with a
-            ``#anchor`` suffix
-            (e.g. ``"automation-patterns.md#native-conditions"``). The
-            anchor is preserved end-to-end: in the ``skill://`` URI for
-            display, and in ``referenced_files`` so the auto-embed path
-            ships only the matching markdown section instead of the
-            whole 10-20 KB reference file.
-    """
-    warnings.append(message + _skill_route_suffix(skill_prefix, file_ref))
-    warnings.referenced_files.add(f"references/{file_ref}")
-
-
-def _skill_route_suffix(skill_prefix: str | None, file_ref: str) -> str:
-    """Build the ' See ...' suffix naming the available skill access routes.
-
-    When ``skill_prefix`` is ``None`` the entire suffix is suppressed —
-    skills are off server-wide, so neither route resolves. Otherwise the
-    suffix names both so the LLM has a working path regardless of which
-    mechanism its client supports:
-
-    1. ``skill://`` URI — for clients that auto-fetch resource URIs.
-       Anchor preserved.
-    2. ``ha_get_skill_guide(skill=..., file=...)`` — explicit tool call,
-       works on every MCP client. Anchor stripped (the tool reads the
-       whole file).
-
-    Auto-embed of the matching section still happens in the next
-    write's response, driven by ``referenced_files``; the
-    ``MandatoryBPS`` opt-out param is not named here by design.
-    """
-    if not skill_prefix:
-        # Skills feature is disabled server-wide; none of the routes work.
-        # Matches the historical no-suffix behaviour.
-        return ""
-    bare_file = f"references/{file_ref.split('#', 1)[0]}"
-    routes = [
-        f"{skill_prefix}/{file_ref}",
-        f"call ha_get_skill_guide(skill={_SKILL_NAME!r}, file={bare_file!r})",
-    ]
-    return " See " + " | ".join(routes)
-
-
 # ---------------------------------------------------------------------------
 # Condition template checks
 # ---------------------------------------------------------------------------
@@ -588,16 +515,27 @@ def _check_repeat_actions(
 def _check_control_flow_actions(
     action: dict[str, Any], warnings: BestPracticeCheckResult, skill_prefix: str | None
 ) -> None:
-    """Check choose/if/then/else/repeat/parallel sub-trees in a single action."""
+    """Check choose/if/then/else/repeat/parallel/sequence sub-trees in one action.
+
+    ``sequence`` is both a grouping action of its own
+    (``cv.SCRIPT_ACTION_SEQUENCE``) and the canonical shape of a ``parallel:``
+    branch — HA normalises the shorthand branch list into ``{"sequence": ...}``
+    (``_SCRIPT_PARALLEL_SCHEMA`` / ``_parallel_sequence_action``). Without this
+    arm only the shorthand branch was walked, so the canonical form of both was
+    invisible to every check below this point.
+    """
     if "choose" in action:
         _check_choose_actions(action["choose"], warnings, skill_prefix)
 
     if "if" in action:
         _check_condition_templates(action["if"], warnings, skill_prefix)
 
-    for key in ("then", "else", "default"):
+    # Every one of these is a `SCRIPT_SCHEMA` position, and that schema is
+    # `vol.All(ensure_list, [script_action])` — a lone action mapping is valid
+    # wherever a list is, so both shapes have to be walked.
+    for key in ("then", "else", "default", "sequence"):
         nested = action.get(key)
-        if isinstance(nested, list):
+        if isinstance(nested, list | dict):
             _check_action_tree(nested, warnings, skill_prefix)
 
     if "repeat" in action and isinstance(action["repeat"], dict):
@@ -606,7 +544,7 @@ def _check_control_flow_actions(
     # `parallel:` runs sub-actions concurrently — same shape as `sequence`,
     # different semantics. Recurse so templates inside parallel branches
     # are inspected the same as templates inside choose/repeat sequences.
-    if "parallel" in action and isinstance(action["parallel"], list):
+    if isinstance(action.get("parallel"), list | dict):
         _check_action_tree(action["parallel"], warnings, skill_prefix)
 
 
@@ -646,6 +584,13 @@ def _check_action_tree(
         # service names based on state.
         _check_service_template(action, warnings, skill_prefix)
 
+        # A `variables:` step is a legitimate template position, so it is never
+        # walked for template misuse. Its key *order* is still load-bearing —
+        # scanned separately.
+        _check_variables_order(
+            action.get("variables"), warnings, skill_prefix, "variables"
+        )
+
         # Templates in target sub-fields. Action `data`, `event_data`,
         # `service_data`, notification message/title, and `variables` are
         # legitimate dynamic-data positions per template-guidelines.md and

ha_mcp_dev-7.14.2.dev2196/src/ha_mcp/tools/best_practice_result.py

@@ -0,0 +1,95 @@
+"""Warning accumulator and skill-reference routing for the best-practice checks.
+
+Split out of :mod:`best_practice_checker` so a check module can emit a warning
+without importing the checker back (AGENTS.md - Module Size). Nothing here
+inspects a config; it only carries warnings and builds the ' See ...' suffix.
+"""
+
+_SKILL_URI_PREFIX = "skill://home-assistant-best-practices/references"
+_DEFAULT_SKILL_PREFIX = _SKILL_URI_PREFIX
+_SKILL_NAME = "home-assistant-best-practices"
+
+
+class BestPracticeCheckResult(list[str]):
+    """Warning list with an attached set of referenced skill files.
+
+    Behaves as a plain ``list[str]`` for all call sites — ``len()``,
+    indexing, iteration, equality with ``[...]`` all work unchanged.
+    ``referenced_files`` is added on top so the write tools can resolve
+    and embed the relevant skill bodies into responses.
+
+    Use :func:`_emit` to append warnings; direct ``append``/``extend``
+    skip the ``referenced_files`` mirror. Slicing, ``list()`` coercion,
+    and ``copy.copy``/``copy.deepcopy`` all return plain ``list[str]``
+    without the attribute — no current call site does any of these.
+    """
+
+    __slots__ = ("referenced_files",)
+
+    referenced_files: set[str]
+
+    def __init__(self, items: list[str] | None = None) -> None:
+        super().__init__(items or [])
+        self.referenced_files = set()
+
+
+# ---------------------------------------------------------------------------
+# Warning emission + skill-reference helpers
+# ---------------------------------------------------------------------------
+
+
+def _emit(
+    warnings: BestPracticeCheckResult,
+    message: str,
+    skill_prefix: str | None,
+    file_ref: str,
+) -> None:
+    """Append a warning with the 2-route ' See ...' suffix and track the file.
+
+    Args:
+        warnings: Accumulator (also holds ``referenced_files``).
+        message: Human-readable warning body — the inline alternative.
+        skill_prefix: When set, embedded as the ``skill://`` URI route.
+            When falsy, the whole ``See ...`` suffix is dropped rather than
+            just that route — see :func:`_skill_route_suffix`.
+        file_ref: File path relative to the ``references/`` directory of
+            the home-assistant-best-practices skill, optionally with a
+            ``#anchor`` suffix
+            (e.g. ``"automation-patterns.md#native-conditions"``). The
+            anchor is preserved end-to-end: in the ``skill://`` URI for
+            display, and in ``referenced_files`` so the auto-embed path
+            ships only the matching markdown section instead of the
+            whole 10-20 KB reference file.
+    """
+    warnings.append(message + _skill_route_suffix(skill_prefix, file_ref))
+    warnings.referenced_files.add(f"references/{file_ref}")
+
+
+def _skill_route_suffix(skill_prefix: str | None, file_ref: str) -> str:
+    """Build the ' See ...' suffix naming the available skill access routes.
+
+    When ``skill_prefix`` is ``None`` the entire suffix is suppressed —
+    skills are off server-wide, so neither route resolves. Otherwise the
+    suffix names both so the LLM has a working path regardless of which
+    mechanism its client supports:
+
+    1. ``skill://`` URI — for clients that auto-fetch resource URIs.
+       Anchor preserved.
+    2. ``ha_get_skill_guide(skill=..., file=...)`` — explicit tool call,
+       works on every MCP client. Anchor stripped (the tool reads the
+       whole file).
+
+    Auto-embed of the matching section still happens in the next
+    write's response, driven by ``referenced_files``; the
+    ``MandatoryBPS`` opt-out param is not named here by design.
+    """
+    if not skill_prefix:
+        # Skills feature is disabled server-wide; none of the routes work.
+        # Matches the historical no-suffix behaviour.
+        return ""
+    bare_file = f"references/{file_ref.split('#', 1)[0]}"
+    routes = [
+        f"{skill_prefix}/{file_ref}",
+        f"call ha_get_skill_guide(skill={_SKILL_NAME!r}, file={bare_file!r})",
+    ]
+    return " See " + " | ".join(routes)