ha-mcp-dev 9.0.0.dev3202__tar.gz → 9.0.0.dev3203__tar.gz

{ha_mcp_dev-9.0.0.dev3202 → ha_mcp_dev-9.0.0.dev3203}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 9.0.0.dev3202
+Version: 9.0.0.dev3203
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien

{ha_mcp_dev-9.0.0.dev3202 → ha_mcp_dev-9.0.0.dev3203}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.0.0.dev3202"
+version = "9.0.0.dev3203"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.15"

{ha_mcp_dev-9.0.0.dev3202 → ha_mcp_dev-9.0.0.dev3203}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.0.0.dev3202"
+version = "9.0.0.dev3203"
 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-9.0.0.dev3202 → ha_mcp_dev-9.0.0.dev3203}/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/SKILL.md

@@ -23,7 +23,7 @@ description: >
   - Existing state changed with no recovery path
   - Jinja copy-pasted between templates
 metadata:
-  version: "51"
+  version: "53"
 ---
 
 # Home Assistant Best Practices
@@ -148,14 +148,14 @@ Read each file whose row matches the task before you answer:
 |------|--------------|
 | [safe-refactoring](references/safe-refactoring.md) | Renaming entities or their display names, replacing helpers, restructuring automations, or any modification to existing config |
 | [triggers-and-conditions](references/triggers-and-conditions.md) | Writing an automation's triggers or conditions: purpose-specific and native triggers/conditions, `for:` durations, trigger IDs |
-| [automation-actions](references/automation-actions.md) | Writing the actions of an automation or script, or choosing its mode: waits, variables, capturing action responses, `continue_on_error`, admin-only actions (`Unauthorized`) in scripts, stopping a sequence, repeat, if/then vs choose, parallel; documenting/annotating steps; disabling automations |
+| [automation-actions](references/automation-actions.md) | Writing the actions of an automation or script, or choosing its mode: waits, variables, capturing action responses, `continue_on_error`, admin-only actions (`Unauthorized`) in scripts, stopping a sequence, repeat, if/then vs choose, parallel; documenting/annotating steps; disabling automations; [measuring elapsed time via `last_triggered`](references/automation-actions.md#measuring-elapsed-time-across-automations); [Mobile App `notify` action vs entity](references/automation-actions.md#notify-entity-vs-action-namespace) — `action not found` when an entity id is used as an action; [trace retention](references/automation-actions.md#trace-retention) — a frequent trigger pushes the run to debug out of the 5 stored traces |
 | [helper-selection](references/helper-selection.md) | Deciding whether to use a built-in helper vs template sensor — aggregation, rate of change, thresholds, time-in-state, counting/timing, scheduling, grouping, probabilistic inference, smoothing, climate, domain conversion, decision matrix |
 | [template-guidelines](references/template-guidelines.md) | Confirming templates ARE appropriate for a use case; sharing Jinja logic between templates with `custom_templates` macros |
 | [yaml-only-integrations](references/yaml-only-integrations.md) | Creating or editing YAML-only integrations that have no config flow (e.g. `command_line`, platform-based `mqtt`, `rest`) |
 | [device-control](references/device-control.md) | Writing actions, button/remote automations, or using target: |
 | [scenes](references/scenes.md) | Authoring or activating scenes; snapshot/restore patterns, including putting devices back the way they were after a temporary change; snapshot-vs-script distinction |
 | [dashboard-guide](references/dashboard-guide.md) | Designing or modifying Lovelace dashboards — layout, view types, strategies, sections, cards, badges, CSS styling, HACS |
-| [dashboard-cards](references/dashboard-cards.md) | Looking up built-in card types (core, energy, legacy) or where to read a card's fields |
+| [dashboard-cards](references/dashboard-cards.md) | Looking up built-in card types (core, energy, legacy) or where to read a card's fields; [entities-card attribute rows](references/dashboard-cards.md#entities-card-attribute-rows-need-type-attribute) — a row with `attribute:` but no `type: attribute` shows the entity state, not the attribute |
 | [domain-docs](references/domain-docs.md) | Looking up integration/domain documentation, or the dedicated doc page for a specific trigger, condition, or action |
 | [examples.yaml](references/examples.yaml) | Need compound examples combining multiple best practices |
 | [appdaemon](references/appdaemon.md) | AppDaemon apps: when to use vs. native HA, app structure, actions, scheduling, error handling, safe refactoring impact |

{ha_mcp_dev-9.0.0.dev3202 → ha_mcp_dev-9.0.0.dev3203}/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/references/automation-actions.md

@@ -14,6 +14,9 @@ This document covers the `actions:` block of automations and scripts, plus `mode
 9. [Parallel Actions](#parallel-actions)
 10. [Documenting Automations & Scripts](#documenting-automations--scripts)
 11. [Disabling Automations](#disabling-automations)
+12. [Measuring Elapsed Time Across Automations](#measuring-elapsed-time-across-automations)
+13. [Notify: Entity vs Action Namespace](#notify-entity-vs-action-namespace)
+14. [Trace Retention](#trace-retention)
 
 ---
 
@@ -76,7 +79,7 @@ Both waits set `wait.completed` and `wait.remaining`:
 - if:
     - "{{ not wait.completed }}"
   then:
-    - action: notify.mobile_app
+    - action: notify.mobile_app_phone
       data:
         message: "Door still open after 5 minutes!"
 ```
@@ -112,7 +115,7 @@ automation:
         entity_id: binary_sensor.doorbell
         to: "on"
     actions:
-      - action: notify.mobile_app
+      - action: notify.mobile_app_phone
         data:
           message: "Someone at the door!"
 ```
@@ -173,7 +176,7 @@ automation:
         for:
           minutes: 30
     actions:
-      - action: notify.mobile_app
+      - action: notify.mobile_app_phone
         data:
           message: "{{ trigger.to_state.name }} has been open for 30 minutes"
 ```
@@ -201,7 +204,7 @@ actions:
     target:
       entity_id: light.patio
     continue_on_error: true  # Automation proceeds even if this fails
-  - action: notify.mobile_app
+  - action: notify.mobile_app_phone
     data:
       message: "Light action attempted"
 ```
@@ -302,7 +305,7 @@ When an automation declares both `trigger_variables:` and `variables:`, the two
   data:
     type: daily
   response_variable: forecast
-- action: notify.mobile_app
+- action: notify.mobile_app_phone
   data:
     message: "High today: {{ forecast['weather.home'].forecast[0].temperature }}°"
 ```
@@ -329,7 +332,7 @@ Four repeat variants are available:
         entity_id: binary_sensor.door
         state: "on"
     sequence:
-      - action: notify.mobile_app
+      - action: notify.mobile_app_phone
         data:
           message: "Door still open"
       - delay:
@@ -536,3 +539,90 @@ actions:
   - action: notify.notify
     enabled: false
 ```
+
+---
+
+## Measuring Elapsed Time Across Automations
+
+`this.attributes.last_triggered` is captured at trigger time, before the run stamps `last_triggered` —
+so it holds the **previous** run and is the right source for a cooldown condition. A live read
+(`state_attr(this.entity_id, 'last_triggered')`) still sees the previous run while the automation-level
+`variables:` and `conditions:` evaluate (they run before the action script), but "now" inside the
+actions, where the script has stamped `last_triggered` as it started: there it measures the elapsed time
+since *this* run started, not the interval since the previous run.
+
+`trigger.from_state.last_changed` is the timestamp of the entity's most recent state entry, so it is
+correct for a normal intended transition; it does not measure a logical interval across a restart or a
+momentary `unavailable`/`unknown` blip, both of which re-stamp it (see
+[triggers-and-conditions #for-duration-resets-on-restart-and-on-unavailable](triggers-and-conditions.md#for-duration-resets-on-restart-and-on-unavailable)).
+
+For a duration across automations — how long since a *different* automation ran — read that
+automation's `last_triggered`, or stamp a persistent `input_datetime` when the condition begins (the
+restart-proof idiom that same section documents):
+
+```yaml
+# RIGHT — duration since the companion automation last ran, not this one
+- action: notify.mobile_app_phone
+  data:
+    message: >
+      {{ state_attr('automation.fridge_door_opened', 'last_triggered') is not none
+         and ((now() - state_attr('automation.fridge_door_opened', 'last_triggered')).total_seconds() | int) ~ ' s ago'
+         or 'never triggered' }}
+```
+
+---
+
+## Notify: Entity vs Action Namespace
+
+Mobile App exposes each device twice, under two different `notify.*` names, and the two do not track
+each other:
+
+- **Entity** `notify.<device_name>` — the default entity id is the slugified device name (e.g.
+  `notify.iphone`), renameable, and callable only via the `notify.send_message` **action** (named
+  **service** before 2024.8) with `target:`.
+- **Per-device action** `notify.mobile_app_<device_name>` — registered dynamically from the *slugified*
+  device name (e.g. `notify.mobile_app_iphone`), callable directly.
+
+The entity id and the action name are different strings even at the defaults, so `notify.iphone` is not
+an action: `action: notify.iphone` fails with "action not found" regardless of any rename. Renaming the
+entity moves its id further, but the rule does not depend on it.
+
+```yaml
+# WRONG — notify.iphone is the entity, not an action
+- action: notify.iphone
+  data:
+    message: "door open"
+
+# RIGHT — the slugified device-named action
+- action: notify.mobile_app_iphone
+  data:
+    message: "door open"
+
+# RIGHT — the entity, via notify.send_message
+- action: notify.send_message
+  target:
+    entity_id: notify.iphone
+  data:
+    message: "door open"
+```
+
+---
+
+## Trace Retention
+
+Home Assistant keeps the last 5 traces of each automation; a YAML automation without an `id` keeps
+none. Every run uses one, including a run that stops at a condition or takes no `choose` branch, so a
+frequent trigger pushes out the run you need to debug: a `time_pattern` with `minutes: "/5"` replaces
+all five within 25 minutes.
+
+If the poll only backs up a state change that a trigger could miss, replace it with change-driven
+triggers (`homeassistant` `start`, a state trigger with only `to:`). Raise the limit only if the
+poll has to stay on a schedule:
+
+```yaml
+trace:
+  stored_traces: 20
+```
+
+"Did not trigger" traces (a trigger noticed a change but did not start the automation) are kept
+separately and never replace the traces of real runs.

{ha_mcp_dev-9.0.0.dev3202 → ha_mcp_dev-9.0.0.dev3203}/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/references/dashboard-cards.md

@@ -49,3 +49,24 @@ Pick the first row that matches what you have. If your tools are behind a tool s
 | Embed external page | `iframe` |
 | Rich text / instructions | `markdown` |
 | Camera or image with overlays | `picture-elements` |
+
+## Entities Card: Attribute Rows Need `type: attribute`
+
+In an `entities` card, a row carrying `attribute:` must also carry `type: attribute`. Without the
+`type`, the card renders the entity's state and silently ignores the `attribute` key — no error, the
+attribute simply never shows.
+
+```yaml
+# WRONG — `attribute` is ignored, the row shows the state
+type: entities
+entities:
+  - entity: climate.thermostat
+    attribute: current_temperature
+
+# RIGHT — `type: attribute` makes the row render the attribute
+type: entities
+entities:
+  - entity: climate.thermostat
+    type: attribute
+    attribute: current_temperature
+```

{ha_mcp_dev-9.0.0.dev3202 → ha_mcp_dev-9.0.0.dev3203}/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/references/helper-selection.md

@@ -697,7 +697,7 @@ restore: true            # default true
 actions:
   - delay:
       minutes: 5
-  - action: notify.mobile_app
+  - action: notify.mobile_app_phone
     data:
       message: "Timer done!"
 ```

{ha_mcp_dev-9.0.0.dev3202 → ha_mcp_dev-9.0.0.dev3203}/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/references/template-guidelines.md

@@ -52,7 +52,7 @@ Messages that include runtime information:
 
 ```yaml
 actions:
-  - action: notify.mobile_app
+  - action: notify.mobile_app_phone
     data:
       message: >
         {{ trigger.to_state.name }} has been {{ trigger.to_state.state }}
@@ -79,7 +79,7 @@ Using `trigger.` variables in automations:
 
 ```yaml
 actions:
-  - action: notify.mobile_app
+  - action: notify.mobile_app_phone
     data:
       message: >
         {{ trigger.to_state.name }} changed from
@@ -404,7 +404,7 @@ For readability in complex templates:
 
 ```yaml
 actions:
-  - action: notify.mobile_app
+  - action: notify.mobile_app_phone
     data:
       message: >
         {% if is_state('binary_sensor.door', 'on') %}
@@ -422,7 +422,7 @@ automation:
       - trigger: state
         entity_id: light.bedroom
     actions:
-      - action: notify.mobile_app
+      - action: notify.mobile_app_phone
         data:
           message: >
             Light changed from {{ trigger.from_state.state }}
@@ -697,7 +697,7 @@ The `.jinja` file requires filesystem access to the config directory — there i
 | Create `config/custom_templates/` | HA does not create it; a missing directory is not an error, it just yields no macros |
 | Add a `*.jinja` file | Subdirectories are scanned too; only the `.jinja` extension is loaded |
 | Import by path relative to `custom_templates/` | `battery.jinja`, or `sensors/battery.jinja` for a file in a subdirectory |
-| Call `homeassistant.reload_custom_templates` | Admin action, no restart. Required after every edit — HA holds the sources in memory. `homeassistant.reload_all` includes it |
+| Call `homeassistant.reload_custom_templates` | Admin action, no restart. Required after every edit — it swaps in the new sources but re-renders nothing; each consumer shows the change at its next render (template entity) or execution (automation/script). `homeassistant.reload_all` includes it |
 
 
 ```jinja
@@ -724,6 +724,17 @@ template:
 
 The import goes inside every template that uses the macro — imports are per-template, not global.
 
+### Reloading Custom Templates Macros
+
+- `homeassistant.reload_custom_templates` re-reads the `*.jinja` files **and** invalidates cached
+  imports — it replaces the loader's sources and bumps its reload counter.
+- `template.reload` does **not** reload `custom_templates` — it reloads the `template:` YAML entities
+  only.
+- Reload swaps the sources but re-renders nothing — any consumer (a template entity, an automation, or
+  a script) shows the new macro at its next render or execution. For a template entity, check its
+  `last_reported`, not `last_changed`: the latter moves only when the state value changes, so a
+  same-value re-render looks like a failed reload.
+
 ### Imports Do Not Carry the Caller's Context
 
 The costliest mistake. An imported macro sees the template environment's globals, but none of the calling template's variables — a missing one renders empty and logs `Template variable warning: ... is undefined`, while attribute access on it (`trigger.entity_id`) fails the render outright.
@@ -777,7 +788,7 @@ For a real return value, give the macro a `returns` argument and convert it with
 | Symptom | Cause |
 |---------|-------|
 | `TemplateNotFound` | File is not under `config/custom_templates/`, does not end in `.jinja`, or `reload_custom_templates` has not run since it was added |
-| Edits have no effect | Sources are cached in memory — call `homeassistant.reload_custom_templates` |
+| Edits have no effect | Call `homeassistant.reload_custom_templates`; the consumer shows the change at its next render/execution |
 | Empty output where a caller variable should be, or `'trigger' is undefined` in the log | Context does not cross an import — pass it as a macro argument |
 
 ---

{ha_mcp_dev-9.0.0.dev3202 → ha_mcp_dev-9.0.0.dev3203}/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/references/triggers-and-conditions.md

@@ -260,7 +260,7 @@ conditions:
 **Prefer these over the generic triggers below when one matches the intent:**
 
 - **Targets, not entity lists.** Target an area/floor/label ("motion in the living room") and the automation follows area membership as sensors are added, swapped, or removed — no entity list to maintain. This also replaces most remaining legitimate uses of device triggers.
-- **No `unavailable`/`unknown` traps.** Each block handles unavailable states and event-entity re-fire quirks internally.
+- **`unavailable`/`unknown` handled internally.** Each block handles unavailable states and event-entity re-fire quirks internally: a purpose-specific trigger on an entity's state skips a change that starts from `unavailable` (from `unknown` too, except on stateless entities such as buttons and events), which also means an edge through them is missed (see [`from:` misses a change that passes through `unavailable`](#from-misses-a-change-that-passes-through-unavailable)).
 - **Cross-entity-type.** "Door opened" fires whether the door is a contact sensor or a motorized cover.
 - **Integration-extensible.** Integrations register their own (e.g. `zwave_js.*`), so the catalog grows over time.
 
@@ -344,6 +344,58 @@ triggers:
     to: "on"
 ```
 
+### Recovery state trigger fires between `unavailable` and `unknown`
+
+A recovery trigger — `from: [unavailable, unknown]` with no `to:` — fires on **every** transition
+away from those two states, including `unavailable` → `unknown` and back, so it reports a false
+recovery while the entity is still down. Add `not_to: [unavailable, unknown]` to fire only on a
+return to a real state:
+
+```yaml
+# WRONG — fires on unavailable → unknown and back, before the entity actually recovers
+triggers:
+  - trigger: state
+    entity_id: sensor.link_quality
+    from: [unavailable, unknown]
+
+# RIGHT — fires only when the entity reaches a real state
+triggers:
+  - trigger: state
+    entity_id: sensor.link_quality
+    from: [unavailable, unknown]
+    not_to: [unavailable, unknown]
+```
+
+### `from:` misses a change that passes through `unavailable`
+
+`from:` is compared with the state immediately before the change. When the entity drops out between
+the two states you name (`on` → `unavailable` → `off`, a routine Wi-Fi or Zigbee blip), the second
+step starts from `unavailable`, so a `from: "on"` / `to: "off"` trigger never fires and the
+automation misses the edge. When missing it matters (switching something off once a sensor clears),
+name only `to:`:
+
+```yaml
+# WRONG — misses on → unavailable → off
+triggers:
+  - trigger: state
+    entity_id: binary_sensor.motion_input
+    from: "on"
+    to: "off"
+
+# RIGHT — fires on every change into off, including the return from unavailable
+triggers:
+  - trigger: state
+    entity_id: binary_sensor.motion_input
+    to: "off"
+```
+
+The `to:`-only form also fires when the entity comes back from `unavailable` already in the target
+state, so guard the action with a state condition when a repeat run would do harm.
+
+The state-based purpose-specific triggers `motion.cleared` and `occupancy.cleared` skip every change
+that starts from `unavailable` or `unknown`, so they miss the same edge. Where it must not be missed, use
+the `to:`-only state trigger in their place.
+
 ### Numeric State Trigger
 
 Fires when crossing a threshold.

{ha_mcp_dev-9.0.0.dev3202 → ha_mcp_dev-9.0.0.dev3203}/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/references/yaml-only-integrations.md

@@ -35,3 +35,5 @@ A YAML edit changes nothing until the integration re-reads the file. Which actio
 - **`homeassistant.restart`** — the fallback for platform-style YAML, which has no reload action. **Confirm with the user first:** it briefly interrupts every automation and integration, not just the one you edited.
 
 Run `homeassistant.check_config` first. `homeassistant.restart` validates the config itself and refuses to restart when it fails, so the risk isn't a broken instance — it's that a reload silently leaves the old config running, or that you spend the user's restart to discover a typo.
+
+`template.reload` does not reload `custom_templates` macros; call `homeassistant.reload_custom_templates` (see [Reloading Custom Templates Macros](template-guidelines.md#reloading-custom-templates-macros)).