ha-mcp-dev 8.6.0.dev2827__tar.gz → 8.6.0.dev2833__tar.gz

{ha_mcp_dev-8.6.0.dev2827 → ha_mcp_dev-8.6.0.dev2833}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.6.0.dev2827"
+version = "8.6.0.dev2833"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.15"
@@ -88,6 +88,9 @@ ha-mcp-oidc = "ha_mcp.__main__:main_oidc"
 module-name = "ha_mcp"
 source-exclude = [
     "src/ha_mcp/resources/skills-vendor/.*",
+    "src/ha_mcp/resources/skills-vendor/*.md",
+    "src/ha_mcp/resources/skills-vendor/evals",
+    "src/ha_mcp/resources/skills-vendor/scripts",
     "src/ha_mcp/settings_ui/AGENTS.md",
     "src/ha_mcp/settings_ui/CLAUDE.md",
 ]

{ha_mcp_dev-8.6.0.dev2827 → ha_mcp_dev-8.6.0.dev2833}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.6.0.dev2827"
+version = "8.6.0.dev2833"
 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
@@ -110,11 +110,15 @@ ha-mcp-oidc = "ha_mcp.__main__:main_oidc"
 # Explicit because publish-dev.yml renames the project to ha-mcp-dev, which
 # would otherwise make the module name ha_mcp_dev.
 module-name = "ha_mcp"
-# Every file under src/ha_mcp ships unless excluded here. The skills
-# submodule's git and CI files and the settings UI's agent guide are not
-# read at runtime.
+# Every file under src/ha_mcp ships unless excluded here. Of the skills
+# submodule only skills/ and LICENSE ship; its evals, scripts, docs, git and
+# CI files are not read at runtime, and neither is the settings UI's agent
+# guide.
 source-exclude = [
     "src/ha_mcp/resources/skills-vendor/.*",
+    "src/ha_mcp/resources/skills-vendor/*.md",
+    "src/ha_mcp/resources/skills-vendor/evals",
+    "src/ha_mcp/resources/skills-vendor/scripts",
     "src/ha_mcp/settings_ui/AGENTS.md",
     "src/ha_mcp/settings_ui/CLAUDE.md",
 ]

{ha_mcp_dev-8.6.0.dev2827 → ha_mcp_dev-8.6.0.dev2833}/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/SKILL.md

@@ -23,13 +23,19 @@ description: >
   - Existing state changed with no recovery path
   - Jinja copy-pasted between templates
 metadata:
-  version: "36"
+  version: "44"
 ---
 
 # Home Assistant Best Practices
 
 **Core principle:** Use native Home Assistant constructs wherever possible. Templates bypass validation, fail silently at runtime, and make debugging opaque.
 
+**No tool reaches the HA API?** Do not stop to ask for access. If you can drive a browser on the HA web UI, make the change there, but first show the user the exact change and wait for their OK before you save: approving a click does not show them what it writes. Otherwise give the user the complete config to create in the UI (for an automation, the YAML for the editor's **Edit in YAML** mode; for a helper, its form fields), and name the entity IDs you assumed. Config that can only be written in YAML is edited with the File editor app (or in the config folder on a Container install): keep a copy of the file first, then check the configuration and run the matching reload in the **YAML** tab of **Tools** (named **Developer Tools** before 2026.8; restart if it isn't listed).
+
+**A feature marked with a release (2026.5+) depends on the instance's version.** Read it before choosing: `version` in `GET /api/config`, or **Settings → About** in the UI. On that release or later, use the feature and do not offer the older way as an equal choice. If you cannot read the version, assume a current release and name the older fallback with the version it needs.
+
+**Read the matching reference before you answer.** This page only summarizes the files in [Reference Files](#reference-files); the exact keys, fields and working examples are in them. Read every file whose row matches the task, and only those: do not load all reference files upfront.
+
 ## Decision Workflow
 
 Follow this sequence when creating any automation:
@@ -41,17 +47,21 @@ If your change affects entity IDs, display names, or cross-component references
 Steps 1-5 below apply to new config or pattern evaluation.
 
 ### 1. Check for a purpose-specific, then generic native, trigger/condition
-Since 2026.7 the default building blocks are purpose-specific triggers/conditions — `<domain>.<name>` keys (motion detected, battery low, door opened) with area/floor/label targets. Check for one that matches the intent first, then a generic native trigger/condition, and only then a template. See [automation-patterns #purpose-specific-triggers--conditions-default-since-20267](references/automation-patterns.md#purpose-specific-triggers--conditions-default-since-20267).
+Since 2026.7 the default building blocks are purpose-specific triggers/conditions — `<domain>.<name>` keys (motion detected, battery low, door opened) with area/floor/label targets. Check for one that matches the intent first, then a generic native trigger/condition, and only then a template. Read [triggers-and-conditions #purpose-specific-triggers--conditions-default-since-20267](references/triggers-and-conditions.md#purpose-specific-triggers--conditions-default-since-20267) before writing the trigger.
+
+A purpose-specific trigger takes `entity_id` in its `target:` as well, so one known sensor is not a reason to fall back to `trigger: state`. Write the automation with the purpose-specific trigger; do not offer it only as an optional upgrade.
 
 **Common substitutions:**
+- `trigger: state` on a motion, occupancy or door `binary_sensor` → `motion.detected`/`motion.cleared`, `occupancy.detected`/`occupancy.cleared` or `door.opened`/`door.closed` with `target: {entity_id: ...}`, or `area_id` when the area is known
 - List of individual sensor entities in a trigger → one purpose-specific trigger with an area/floor/label `target:`
+- `delay` after `motion.detected` for "no motion anywhere for N minutes" → `motion.cleared` with `options: {behavior: all, for: ...}`, which fires once every targeted sensor has been clear that long (`unavailable` and `unknown` sensors are left out of the count)
 - `{{ 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
-Before creating a template sensor, check [helper-selection](references/helper-selection.md).
+Read [helper-selection](references/helper-selection.md) before creating a template sensor.
 
 **Common substitutions:**
 - Sum/average multiple sensors → `min_max` integration
@@ -70,7 +80,7 @@ the config needs a key the flow has no field for — trigger-based templates and
 are the common ones. Then use managed YAML editing ([yaml-only-integrations](references/yaml-only-integrations.md)), not a hand-edit.
 
 ### 3. Select correct automation mode
-Default `single` mode is often wrong. See [automation-patterns #automation-modes](references/automation-patterns.md#automation-modes).
+Default `single` mode is often wrong. See [automation-actions #automation-modes](references/automation-actions.md#automation-modes).
 
 | Scenario | Mode |
 |----------|------|
@@ -85,11 +95,11 @@ Default `single` mode is often wrong. See [automation-patterns #automation-modes
 **Exception:** Zigbee2MQTT autodiscovered device triggers are acceptable.
 
 ### 5. For buttons and remotes
-- **Any integration exposing an `event.*` entity:** Use `event.received` targeting that entity — a normal entity, so it can be renamed and survives a re-add when the integration keeps a stable unique ID
+- **Any integration exposing an `event.*` entity:** Use `event.received` targeting that entity (see the anti-pattern row below)
 - **ZHA:** No event entities — use an `event` trigger with `device_ieee` (persistent)
 - **Z2M:** Event entities are experimental and off by default — use a `device` trigger (autodiscovered) or `mqtt` trigger
 
-See [device-control #buttonremote-patterns](references/device-control.md#buttonremote-patterns).
+Read [device-control #buttonremote-patterns](references/device-control.md#buttonremote-patterns) before writing the trigger.
 
 ---
 
@@ -97,28 +107,30 @@ See [device-control #buttonremote-patterns](references/device-control.md#buttonr
 
 | Anti-pattern | Use instead | Why | Reference |
 |--------------|-------------|-----|-----------|
-| `condition: template` with `float > 25` | `condition: numeric_state` | Validated at load, not runtime | [automation-patterns #native-conditions](references/automation-patterns.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-patterns #wait-actions](references/automation-patterns.md#wait-actions) |
+| `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) |
 | `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) |
-| `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) | [automation-patterns #unavailable-arms-a-numeric-state-trigger](references/automation-patterns.md#unavailable-arms-a-numeric-state-trigger) |
-| `mode: single` for motion lights | `mode: restart` | Re-triggers must reset the timer | [automation-patterns #automation-modes](references/automation-patterns.md#automation-modes) |
-| `enabled: false` as a top-level key in `automations.yaml` | `automation.turn_off` (temporary) or entity registry disable (permanent) | Not a valid top-level key — rejected during schema validation; automation loads as `unavailable` | [automation-patterns #disabling-automations](references/automation-patterns.md#disabling-automations) |
+| `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) |
+| `mode: single` for motion lights | `mode: restart` | Re-triggers must reset the timer | [automation-actions #automation-modes](references/automation-actions.md#automation-modes) |
+| `enabled: false` as a top-level key in `automations.yaml` | `automation.turn_off` (temporary) or entity registry disable (permanent) | Not a valid top-level key — rejected during schema validation; automation loads as `unavailable` | [automation-actions #disabling-automations](references/automation-actions.md#disabling-automations) |
 | Template sensor for sum/mean | `min_max` helper | Declarative, handles unavailable states | [helper-selection #numeric-aggregation](references/helper-selection.md#numeric-aggregation) |
 | Template binary sensor with threshold | `threshold` helper | Built-in hysteresis support | [helper-selection #threshold](references/helper-selection.md#threshold) |
 | Renaming entity IDs without impact analysis | Follow [safe-refactoring](references/safe-refactoring.md) workflow | Renames break dashboards, scripts, scenes, Config-Entry data, and storage dashboards silently | [safe-refactoring #entity-renames](references/safe-refactoring.md#entity-renames) |
 | Renaming members of Config-Entry-based groups (UI groups) without updating membership | Update group membership via Options Flow after the registry rename | The entity registry rename does not update `options.entities` in the Config Entry — group silently breaks | [safe-refactoring #config-entry-groups](references/safe-refactoring.md#config-entry-groups) |
-| Renaming entities used by Config-Entry integrations (Better/Generic Thermostat, Min/Max, Threshold) without patching Config-Entry data | Scan and patch `core.config_entries` `data`+`options` fields | These integrations store entity_ids in Config Entry — not updated by entity registry renames | [safe-refactoring #config-entry-data--blind-spots-for-entity-registry-renames](references/safe-refactoring.md#config-entry-data--blind-spots-for-entity-registry-renames) |
+| Renaming entities used by Min/Max helpers or custom Config-Entry integrations (e.g. Better Thermostat) without checking their Config-Entry data | Scan the config entries' `data`+`options`; re-select the renamed entity in the Min/Max Options Flow. An integration that keeps it in `data` (Better Thermostat) has no API fix: tell the user and take a full backup before the rename | They store entity_ids in the Config Entry, and a registry rename does not update them; single-source helpers such as Threshold (since 2025.6) and Generic Thermostat update themselves | [safe-refactoring #config-entry-data--blind-spots-for-entity-registry-renames](references/safe-refactoring.md#config-entry-data--blind-spots-for-entity-registry-renames) |
 | `template:` sensor/binary sensor in YAML | Template Helper via the config flow | A flow helper reloads in place and stays UI-editable; a `template:` entry needs a config reload and does not. Exceptions are real — trigger-based templates and `attributes:` have no flow field | [helper-selection #template-helpers](references/helper-selection.md#template-helpers) |
 | Editing `.storage/` files or other HA internal state directly | Use the HA REST/WebSocket API to manage state and config entries | `.storage/` files are HA's internal state database; direct edits bypass validation, risk corruption, and can be silently overwritten by HA | — |
 | Writing raw YAML to `configuration.yaml` by hand for YAML-only integrations | Use managed YAML config editing with backup and validation | Unmanaged writes risk syntax errors, have no backup, and skip `check_config` — managed editing provides all three | [yaml-only-integrations](references/yaml-only-integrations.md) |
-| Generating YAML snippets for automations/scripts/scenes | Use the HA config API to create automations/scripts programmatically | API calls validate config, avoid syntax errors, and don't require manual file edits or restarts | [automation-patterns](references/automation-patterns.md), [examples.yaml](references/examples.yaml) |
+| Generating YAML snippets for automations/scripts/scenes | Use the HA config API to create automations/scripts programmatically; with no API access, give the config for the UI editor instead | API calls validate config, avoid syntax errors, and don't require manual file edits or restarts | [triggers-and-conditions](references/triggers-and-conditions.md), [automation-actions](references/automation-actions.md), [examples.yaml](references/examples.yaml) |
 | Telling user to edit `configuration.yaml` for integrations | Direct user to Settings > Devices & Services in the HA UI | Most integrations are UI-configured; YAML integration config is rare and integration-specific | — |
 | Referring to HA "add-ons" | Use the term "Apps" | HA renamed add-ons to Apps in 2026.2 — "Apps are standalone applications that run alongside Home Assistant" | — |
-| `vacuum.send_command` with vendor room IDs | `vacuum.clean_area` with HA `area_id` (if segments are mapped) | Uses native HA areas, works across integrations — but requires segment-to-area mapping in entity settings first | [device-control #vacuum-control](references/device-control.md#vacuum-control) |
-| Using `color_temp` (mireds) in light actions | Use `color_temp_kelvin` | The `color_temp` parameter was removed in 2026.3; only Kelvin is supported | [device-control #lights](references/device-control.md#lights) |
-| Person/Device Tracker `entered_home`/`left_home` device triggers or `is_home`/`is_not_home` conditions | `state` trigger `to: home` / `to: not_home`, or `state` condition | These were removed in 2026.5 — state triggers and conditions are the correct replacements | [automation-patterns #presence-and-person-triggers-and-conditions-removed-in-20265](references/automation-patterns.md#presence-and-person-triggers-and-conditions-removed-in-20265) |
-| Entity list in a trigger where an area/floor/label target fits | Purpose-specific trigger with `target: {area_id: ...}` | Automation follows area membership as devices change — no stale entity lists | [automation-patterns #purpose-specific-triggers--conditions-default-since-20267](references/automation-patterns.md#purpose-specific-triggers--conditions-default-since-20267) |
-| Old purpose-specific keys (`battery.low`, `vacuum.docked`, `timer.time_remaining`, ...) or trigger `behavior: any`/`last` | Renamed 2026.7 keys (`battery.became_low`, ...) and `behavior: each`/`all` | Old keys no longer load; old behavior values raise a repair issue and face removal | [automation-patterns #purpose-specific-triggers--conditions-default-since-20267](references/automation-patterns.md#purpose-specific-triggers--conditions-default-since-20267) |
+| `vacuum.send_command` with vendor room IDs | `vacuum.clean_area` with HA area IDs in `cleaning_area_id` (if segments are mapped) | Uses native HA areas, works across integrations — but requires segment-to-area mapping in entity settings first | [device-control #vacuum-control](references/device-control.md#vacuum-control) |
+| Using `color_temp` (mireds) in light actions | Use `color_temp_kelvin` with the value converted: Kelvin = 1,000,000 ÷ mireds (500 mireds = 2000 K) | The `color_temp` parameter was removed in 2026.3; only Kelvin is supported, and HA accepts any positive number there, so a mireds value copied across is read as Kelvin (500 mireds becomes 500 K) | [device-control #lights](references/device-control.md#lights) |
+| Saving states or attributes in `variables:`, or hard-coding values, to put devices back after a temporary change | `scene.create` with `snapshot_entities` before the change, then `scene.turn_on` on that scene | The snapshot keeps each entity's own state, including a light that was off, in one call; variables need a template per attribute and a restore step per entity | [scenes #snapshot--restore-scenecreate](references/scenes.md#snapshot--restore-scenecreate) |
+| Person/Device Tracker `entered_home`/`left_home` device triggers or `is_home`/`is_not_home` conditions | `state` trigger `to: home` / `to: not_home`, or `state` condition | These were removed in 2026.5 — state triggers and conditions are the correct replacements | [triggers-and-conditions #presence-and-person-triggers-and-conditions-removed-in-20265](references/triggers-and-conditions.md#presence-and-person-triggers-and-conditions-removed-in-20265) |
+| Entity list in a trigger where an area/floor/label target fits | Purpose-specific trigger with `target: {area_id: ...}` | Automation follows area membership as devices change — no stale entity lists | [triggers-and-conditions #purpose-specific-triggers--conditions-default-since-20267](references/triggers-and-conditions.md#purpose-specific-triggers--conditions-default-since-20267) |
+| Old purpose-specific keys (`battery.low`, `vacuum.docked`, `timer.time_remaining`, ...) or trigger `behavior: any`/`last` | Renamed 2026.7 keys (`battery.became_low`, ...) and `behavior: each`/`all` (renamed 2026.6) | Old keys no longer load; old behavior values raise a repair issue and face removal | [triggers-and-conditions #purpose-specific-triggers--conditions-default-since-20267](references/triggers-and-conditions.md#purpose-specific-triggers--conditions-default-since-20267) |
 | AppDaemon: callbacks in `__init__`, uncancelled `run_in` timers, state in instance variables, hardcoded entity IDs | Register in `initialize()`, cancel before rescheduling, persist via `input_*` helpers, pass IDs through `self.args` | Each fails silently, resets on reload, or blocks reuse | [appdaemon #appdaemon-specific-anti-patterns](references/appdaemon.md#appdaemon-specific-anti-patterns) |
 | Blueprints: hardcoded entities, free text where a selector belongs, `!input` inside a template, missing `source_url` | Typed `!input` selectors; bind an input to `variables:` before templating it; always set `source_url` | Hardcoding defeats reuse, text lets typos through, and `!input` is a YAML tag rather than a template value | [blueprint-guide #common-pitfalls](references/blueprint-guide.md#common-pitfalls) |
 | Backups: full restore to undo one object edit, no backup before an irreversible operation (registry deletion, integration removal, Core/OS upgrade), calling an action "reversible" without naming its inverse | Roll the single object back; take the backup *before*; name the exact inverse or treat it as irreversible | A full restore reverts every unrelated change since and restarts HA; a backup taken afterward captures the damage | [backups #when-a-full-backup-earns-its-cost](references/backups.md#when-a-full-backup-earns-its-cost) |
@@ -130,17 +142,18 @@ See [device-control #buttonremote-patterns](references/device-control.md#buttonr
 
 ## Reference Files
 
-Read these when you need detailed information:
+Read each file whose row matches the task before you answer:
 
 | File | When to read |
 |------|--------------|
 | [safe-refactoring](references/safe-refactoring.md) | Renaming entities or their display names, replacing helpers, restructuring automations, or any modification to existing config |
-| [automation-patterns](references/automation-patterns.md) | Writing triggers, conditions, waits, variables, or choosing automation modes; capturing action responses; documenting/annotating steps; disabling automations; `continue_on_error`, admin-only actions (`Unauthorized`) in scripts, stopping a sequence, repeat, if/then vs choose, parallel, trigger IDs |
+| [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 |
 | [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; snapshot-vs-script distinction |
+| [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 |
 | [domain-docs](references/domain-docs.md) | Looking up integration/domain documentation, or the dedicated doc page for a specific trigger, condition, or action |