ha-mcp-dev 8.6.0.dev3035__tar.gz → 8.6.0.dev3038__tar.gz

{ha_mcp_dev-8.6.0.dev3035 → ha_mcp_dev-8.6.0.dev3038}/PKG-INFO

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

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

{ha_mcp_dev-8.6.0.dev3035 → ha_mcp_dev-8.6.0.dev3038}/pyproject.toml.orig

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

@@ -1,7 +1,7 @@
 ---
 name: home-assistant-best-practices
 description: >
-  Best practices for HA automations, helpers, scripts, and dashboards.
+  Home Assistant (HA) best practices. Load first, before answering or exploring, on any HA request.
 
   TRIGGER THIS SKILL WHEN:
   - Creating or editing automations, scripts, scenes, dashboards, blueprints
@@ -23,7 +23,7 @@ description: >
   - Existing state changed with no recovery path
   - Jinja copy-pasted between templates
 metadata:
-  version: "45"
+  version: "49"
 ---
 
 # Home Assistant Best Practices
@@ -58,7 +58,6 @@ A purpose-specific trigger takes `entity_id` in its `target:` as well, so one kn
 - `{{ states('x') | float > 25 }}` → `numeric_state` condition with `above: 25`
 - `{{ is_state('x', 'on') and is_state('y', 'on') }}` → `condition: and` with state conditions
 - `{{ now().hour >= 9 }}` → `condition: time` with `after: "09:00:00"`
-- `wait_template: "{{ is_state(...) }}"` → `wait_for_trigger` with state trigger (caveat: different behavior when state is already true — see [safe-refactoring #trigger-restructuring](references/safe-refactoring.md#trigger-restructuring))
 
 ### 2. Check for built-in helper or Template Helper
 Read [helper-selection](references/helper-selection.md) before creating a template sensor.
@@ -108,7 +107,7 @@ Read [device-control #buttonremote-patterns](references/device-control.md#button
 | Anti-pattern | Use instead | Why | Reference |
 |--------------|-------------|-----|-----------|
 | `condition: template` with `float > 25` | `condition: numeric_state` | Validated at load, not runtime | [triggers-and-conditions #native-conditions](references/triggers-and-conditions.md#native-conditions) |
-| `wait_template: "{{ is_state(...) }}"` | `wait_for_trigger` with state trigger | Event-driven, not polling; waits for *change* (see [safe-refactoring #trigger-restructuring](references/safe-refactoring.md#trigger-restructuring) for semantic differences) | [automation-actions #wait-actions](references/automation-actions.md#wait-actions) |
+| `wait_for_trigger` with a state trigger for a condition that may already hold | `wait_template` | A state trigger fires only on a transition, so the wait lasts until the entity leaves the state and re-enters it, or forever without a `timeout` (see [safe-refactoring #trigger-restructuring](references/safe-refactoring.md#trigger-restructuring)) | [automation-actions #wait-actions](references/automation-actions.md#wait-actions) |
 | `device_id` in triggers | `entity_id` (or `device_ieee` for ZHA) | device_id breaks on re-add | [device-control #entity-id-vs-device-id](references/device-control.md#entity-id-vs-device-id) |
 | `event` trigger on an integration's bus event (e.g. `hue_event`) for a button that has an `event.*` entity | `event.received` targeting that entity, with values read from its `event_types` attribute | The entity can be renamed and survives a re-add when the integration keeps a stable unique ID; bus event data differs per integration | [device-control #buttonremote-patterns](references/device-control.md#buttonremote-patterns) |
 | `numeric_state` trigger driving a costly action, unguarded | Condition rejecting `unavailable`/`unknown` in `trigger.from_state` | A restart or blip re-arms the trigger, so an unchanged value fires with no crossing (the guard also drops real crossings) | [triggers-and-conditions #unavailable-arms-a-numeric-state-trigger](references/triggers-and-conditions.md#unavailable-arms-a-numeric-state-trigger) |
@@ -155,7 +154,7 @@ Read each file whose row matches the task before you answer:
 | [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 available card types or fetching card-specific documentation |
+| [dashboard-cards](references/dashboard-cards.md) | Looking up built-in card types (core, energy, legacy) or where to read a card's fields |
 | [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-8.6.0.dev3035 → ha_mcp_dev-8.6.0.dev3038}/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/references/automation-actions.md

@@ -19,9 +19,9 @@ This document covers the `actions:` block of automations and scripts, plus `mode
 
 ## Wait Actions
 
-### wait_for_trigger (Preferred)
+### wait_for_trigger
 
-Event-driven wait. More efficient than polling.
+Waits for a trigger to fire after the wait starts. Use it to wait for an event or a transition. If the entity is already in the target state, a state trigger fires only after the entity leaves that state and re-enters it.
 
 ```yaml
 # Wait for door to close
@@ -44,12 +44,14 @@ Event-driven wait. More efficient than polling.
         action: "CLOSE_DOOR"
 ```
 
-### wait_template (Use Sparingly)
+### wait_template
 
-Polls until template is true. **Immediately continues if already true.**
+Waits until the template is true. HA re-renders it when a referenced entity changes state, and at the start of every minute if it uses `now()`. **Immediately continues if already true.** Use it to wait for a condition that may already hold.
+
+Entities the template names directly re-render it on every change. A template that iterates a domain, such as `states.light`, re-renders at most once per second, and one that iterates all states at most once per minute, so it can react late.
 
 ```yaml
-# Only use when wait_for_trigger cannot express the condition
+# Continues at once if the temperature is already above 25
 - wait_template: "{{ states('sensor.temperature') | float > 25 }}"
   timeout:
     minutes: 10

ha_mcp_dev-8.6.0.dev3038/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/references/dashboard-cards.md

@@ -0,0 +1,51 @@
+# Dashboard Card Types
+
+A card's visual editor in the running instance shows fields that instance accepts, at its installed version. It is not the full list: a card can accept YAML-only options its editor omits, and a custom card may have no editor at all. A field missing from the editor is not proof that it is invalid. The lists below are the built-in cards the card picker offers as of 2026.10. Custom cards have a `custom:` type and depend on what the instance has installed.
+
+## Where to Read a Card's Fields
+
+Pick the first row that matches what you have. If your tools are behind a tool search, one query decides whether a row matches; do not repeat it. A tool that returns an error does not match. Do not install anything, or ask the user to, to reach a higher row.
+
+| You have | Read the card's fields from |
+|----------|-----------------------------|
+| A tool that returns a card's fields from the instance | That tool, for built-in and installed custom cards |
+| A browser on the HA UI | The card's visual editor (edit the dashboard, add or edit the card) |
+| A tool that opens URLs | The card's docs page (see [Card Docs Pages](#card-docs-pages)). It describes the latest release and no custom cards |
+| None of these | The fields in [dashboard-guide](dashboard-guide.md) if it covers the card, otherwise the fields you know. Tell the user they are not checked against the instance, and give the card's docs link (see [Card Docs Pages](#card-docs-pages)) |
+
+## Available Card Types
+
+**Core:** alarm-panel, area, button, calendar, clock, conditional, distribution, entities, entity-filter, entity, gauge, glance, grid, heading, history-graph, horizontal-stack, humidifier, iframe, light, logbook, map, markdown, media-control, picture-elements, picture-entity, picture-glance, picture, plant-status, sensor, shortcut, statistic, statistics-graph, thermostat, tile, todo-list, vertical-stack, weather-forecast
+
+**Energy:** energy-carbon-consumed-gauge, energy-compare, energy-date-selection, energy-devices-detail-graph, energy-devices-graph, energy-distribution, energy-gas-graph, energy-grid-balance, energy-grid-neutrality-gauge, energy-sankey, energy-self-sufficiency-gauge, energy-solar-consumed-gauge, energy-solar-graph, energy-sources-table, energy-usage-graph, energy-water-graph, power-sankey, power-sources-graph, water-flow-sankey, water-sankey
+
+**Legacy:** `shopping-list` still renders but cannot be added from the UI. Use `todo-list`.
+
+## Card Docs Pages
+
+| Use | URL |
+|-----|-----|
+| To read with a tool that opens URLs | `https://raw.githubusercontent.com/home-assistant/home-assistant.io/refs/heads/current/source/_dashboards/{page}.markdown` |
+| To give the user as a link | `https://www.home-assistant.io/dashboards/{page}/` |
+
+| Card | `{page}` |
+|------|----------|
+| Core or legacy card | the card type (e.g., `tile`, `grid`, `button`) |
+| Any energy card | `energy` (one page for all of them). Its example writes `energy-compare-card`; the type is `energy-compare` |
+| View type (`masonry`, `panel`, `sections`, `sidebar`) | the view type. It is the view's `"type"`, not a card: see [dashboard-guide #view-types](dashboard-guide.md#view-types) |
+
+## Quick Card Selection Guide
+
+| Need | Card |
+|------|------|
+| Control any entity | `tile` (modern default) |
+| Layout multiple cards in columns | `grid` |
+| One-tap launcher: navigate, URL, Assist or an action | `shortcut` (2026.5+), e.g. `{"type": "shortcut", "tap_action": {"action": "assist"}}`; text key `label`. `button` with a `tap_action` only before 2026.5 |
+| Room overview with controls | `area` |
+| Historical data graph | `history-graph` or `statistics-graph` |
+| Sensor value display | `sensor` or `gauge` |
+| Proportional data across entities | `distribution` |
+| Show/hide cards conditionally | `conditional` |
+| Embed external page | `iframe` |
+| Rich text / instructions | `markdown` |
+| Camera or image with overlays | `picture-elements` |

{ha_mcp_dev-8.6.0.dev3035 → ha_mcp_dev-8.6.0.dev3038}/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/references/dashboard-guide.md

@@ -148,10 +148,10 @@ views: []
 | **Modern Primary** | tile, area, shortcut, button, grid |
 | **Container** | vertical-stack, horizontal-stack, grid |
 | **Logic** | conditional, entity-filter |
-| **Display** | sensor, history-graph, statistics-graph, gauge, energy, calendar, distribution |
+| **Display** | sensor, history-graph, statistics-graph, gauge, calendar, distribution, the energy cards |
 | **Legacy Control** | entity, entities, light, thermostat (use tile instead) |
 
-**Default:** Use `tile` card for most entities. Use [dashboard-cards](dashboard-cards.md) to look up all card types or fetch card-specific docs.
+**Default:** Use `tile` card for most entities. Use [dashboard-cards](dashboard-cards.md) to look up all card types and where to read a card's fields.
 
 ### Tile Card
 

{ha_mcp_dev-8.6.0.dev3035 → ha_mcp_dev-8.6.0.dev3038}/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/references/domain-docs.md

@@ -10,8 +10,6 @@ https://raw.githubusercontent.com/home-assistant/home-assistant.io/refs/heads/cu
 
 Replace `{domain}` with the integration name (e.g., `light`, `climate`, `mqtt`).
 
-If the MCP server registers resource URI templates for domain docs, prefer those over raw GitHub fetches.
-
 ## Fetching Trigger, Condition, and Action Docs
 
 Since 2026.7, every purpose-specific trigger and condition — and every action — has a dedicated doc page covering what it does, when to use it, its config shape, options, and worked examples. Fetch the page instead of guessing keys or options:

{ha_mcp_dev-8.6.0.dev3035 → ha_mcp_dev-8.6.0.dev3038}/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/references/safe-refactoring.md

@@ -128,7 +128,7 @@ Verify the new helper produces the same values as the old template sensor. Check
 When converting `device_id` triggers to `entity_id` triggers, or replacing `wait_template` with `wait_for_trigger`:
 
 **Behavioral equivalence (Step 1):**
-`wait_for_trigger` waits for a state *change*; `wait_template` polls for *current state*. These differ when the target state is already true at wait start: `wait_for_trigger` blocks indefinitely, `wait_template` returns immediately.
+`wait_for_trigger` waits for a state *change*; `wait_template` checks the *current state* and re-renders when a referenced entity changes. These differ when the target state is already true at wait start: `wait_for_trigger` waits for the next matching trigger (the entity must leave the state and re-enter it), or for the timeout if one is set; `wait_template` returns immediately.
 
 **Automation callers (Step 2):**
 Search for scripts or other automations that call the automation you are restructuring via `automation.trigger` or `automation.turn_on`. Renaming or splitting an automation changes its entity_id and breaks these callers.

{ha_mcp_dev-8.6.0.dev3035 → ha_mcp_dev-8.6.0.dev3038}/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/references/template-guidelines.md

@@ -178,7 +178,6 @@ Do NOT use templates when a native alternative exists:
 | `{{ states('x') \| float > 25 }}` | `condition: numeric_state` with `above: 25` |
 | `{{ now().hour >= 9 }}` | `condition: time` with `after: "09:00:00"` |
 | `{{ is_state('sun.sun', 'below_horizon') }}` | `condition: sun` with `after: sunset` |
-| `wait_template: "{{ is_state(...) }}"` | `wait_for_trigger` with state trigger |
 | Template sensor summing values | `min_max` helper with `type: sum` |
 | Template binary sensor with threshold | `threshold` helper |
 | Template sensor averaging over time | `statistics` helper |

ha_mcp_dev-8.6.0.dev3035/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/references/dashboard-cards.md

@@ -1,37 +0,0 @@
-# Dashboard Card Types
-
-Home Assistant provides 39 built-in card types. For card-specific documentation, fetch from GitHub on demand.
-
-## Available Card Types
-
-alarm-panel, area, button, calendar, clock, conditional, distribution, energy, entities, entity-filter, entity, gauge, glance, grid, heading, history-graph, horizontal-stack, humidifier, iframe, light, logbook, map, markdown, media-control, picture-elements, picture-entity, picture-glance, picture, plant-status, sensor, shopping-list, shortcut, statistic, statistics-graph, thermostat, tile, todo-list, vertical-stack, weather-forecast
-
-**Note:** The HA docs URL pattern also covers 4 view types (`masonry`, `panel`, `sections`, `sidebar`) — these are set at the view level via `"type"` in view config, NOT inside card arrays. See [dashboard-guide #view-types](dashboard-guide.md#view-types).
-
-## Fetching Card Documentation
-
-To get detailed documentation for a specific card type, fetch from the Home Assistant docs:
-
-```
-https://raw.githubusercontent.com/home-assistant/home-assistant.io/refs/heads/current/source/_dashboards/{card_type}.markdown
-```
-
-Replace `{card_type}` with the card name from the list above (e.g., `tile`, `grid`, `button`).
-
-If the MCP server registers resource URI templates for card docs, prefer those over raw GitHub fetches.
-
-## Quick Card Selection Guide
-
-| Need | Card |
-|------|------|
-| Control any entity | `tile` (modern default) |
-| Layout multiple cards in columns | `grid` |
-| One-tap launcher: navigate, URL, Assist or an action | `shortcut` (2026.5+), e.g. `{"type": "shortcut", "tap_action": {"action": "assist"}}`; text key `label`. `button` with a `tap_action` only before 2026.5 |
-| Room overview with controls | `area` |
-| Historical data graph | `history-graph` or `statistics-graph` |
-| Sensor value display | `sensor` or `gauge` |
-| Proportional data across entities | `distribution` |
-| Show/hide cards conditionally | `conditional` |
-| Embed external page | `iframe` |
-| Rich text / instructions | `markdown` |
-| Camera or image with overlays | `picture-elements` |