ha-mcp-dev 7.1.0.dev300__tar.gz → 7.1.0.dev301__tar.gz

{ha_mcp_dev-7.1.0.dev300/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.1.0.dev301}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.1.0.dev300
+Version: 7.1.0.dev301
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -167,7 +167,7 @@ Spend less time configuring, more time enjoying your smart home.
 | **Automations** | `ha_config_get_automation`, `ha_config_set_automation`, `ha_config_remove_automation` |
 | **Scripts** | `ha_config_get_script`, `ha_config_set_script`, `ha_config_remove_script` |
 | **Helper Entities** | `ha_config_list_helpers`, `ha_config_set_helper`, `ha_config_remove_helper` |
-| **Dashboards** | `ha_config_get_dashboard`, `ha_config_set_dashboard`, `ha_config_delete_dashboard`, `ha_get_dashboard_guide`, `ha_get_card_documentation` |
+| **Dashboards** | `ha_config_get_dashboard`, `ha_config_set_dashboard`, `ha_config_delete_dashboard` + dashboard skill references |
 | **Areas & Floors** | `ha_config_list_areas`, `ha_config_set_area`, `ha_config_remove_area`, `ha_config_list_floors`, `ha_config_set_floor`, `ha_config_remove_floor` |
 | **Labels** | `ha_config_get_label`, `ha_config_set_label`, `ha_config_remove_label`, `ha_manage_entity_labels` |
 | **Zones** | `ha_get_zone`, `ha_set_zone`, `ha_remove_zone` |
@@ -183,7 +183,7 @@ Spend less time configuring, more time enjoying your smart home.
 | **Automation Traces** | `ha_get_automation_traces` |
 | **System & Updates** | `ha_check_config`, `ha_restart`, `ha_reload_core`, `ha_get_system_info`, `ha_get_system_health`, `ha_get_updates` |
 | **Backup & Restore** | `ha_backup_create`, `ha_backup_restore` |
-| **Utility** | `ha_get_logbook`, `ha_eval_template`, `ha_get_domain_docs`, `ha_get_integration` |
+| **Utility** | `ha_get_logbook`, `ha_eval_template`, `ha_get_integration` |
 
 </details>
 
@@ -202,7 +202,7 @@ Skills from `homeassistant-ai/skills` are bundled and served as [MCP resources](
 | Setting | Default | Description |
 |---------|---------|-------------|
 | `ENABLE_SKILLS` | `true` | Serve skills as MCP resources. Resources are not auto-injected into context — clients must explicitly request them. |
-| `ENABLE_SKILLS_AS_TOOLS` | `false` | Also expose skills via `list_resources`/`read_resource` tools for clients that don't support MCP resources natively. |
+| `ENABLE_SKILLS_AS_TOOLS` | `true` | Expose skills and doc resources via `list_resources`/`read_resource` tools. Resource-capable clients can set to `false` to reduce tool count. |
 
 Skills can still be installed manually for clients that prefer local skill files — see the [skills repo](https://github.com/homeassistant-ai/skills) for instructions.
 

{ha_mcp_dev-7.1.0.dev300 → ha_mcp_dev-7.1.0.dev301}/README.md

@@ -138,7 +138,7 @@ Spend less time configuring, more time enjoying your smart home.
 | **Automations** | `ha_config_get_automation`, `ha_config_set_automation`, `ha_config_remove_automation` |
 | **Scripts** | `ha_config_get_script`, `ha_config_set_script`, `ha_config_remove_script` |
 | **Helper Entities** | `ha_config_list_helpers`, `ha_config_set_helper`, `ha_config_remove_helper` |
-| **Dashboards** | `ha_config_get_dashboard`, `ha_config_set_dashboard`, `ha_config_delete_dashboard`, `ha_get_dashboard_guide`, `ha_get_card_documentation` |
+| **Dashboards** | `ha_config_get_dashboard`, `ha_config_set_dashboard`, `ha_config_delete_dashboard` + dashboard skill references |
 | **Areas & Floors** | `ha_config_list_areas`, `ha_config_set_area`, `ha_config_remove_area`, `ha_config_list_floors`, `ha_config_set_floor`, `ha_config_remove_floor` |
 | **Labels** | `ha_config_get_label`, `ha_config_set_label`, `ha_config_remove_label`, `ha_manage_entity_labels` |
 | **Zones** | `ha_get_zone`, `ha_set_zone`, `ha_remove_zone` |
@@ -154,7 +154,7 @@ Spend less time configuring, more time enjoying your smart home.
 | **Automation Traces** | `ha_get_automation_traces` |
 | **System & Updates** | `ha_check_config`, `ha_restart`, `ha_reload_core`, `ha_get_system_info`, `ha_get_system_health`, `ha_get_updates` |
 | **Backup & Restore** | `ha_backup_create`, `ha_backup_restore` |
-| **Utility** | `ha_get_logbook`, `ha_eval_template`, `ha_get_domain_docs`, `ha_get_integration` |
+| **Utility** | `ha_get_logbook`, `ha_eval_template`, `ha_get_integration` |
 
 </details>
 
@@ -173,7 +173,7 @@ Skills from `homeassistant-ai/skills` are bundled and served as [MCP resources](
 | Setting | Default | Description |
 |---------|---------|-------------|
 | `ENABLE_SKILLS` | `true` | Serve skills as MCP resources. Resources are not auto-injected into context — clients must explicitly request them. |
-| `ENABLE_SKILLS_AS_TOOLS` | `false` | Also expose skills via `list_resources`/`read_resource` tools for clients that don't support MCP resources natively. |
+| `ENABLE_SKILLS_AS_TOOLS` | `true` | Expose skills and doc resources via `list_resources`/`read_resource` tools. Resource-capable clients can set to `false` to reduce tool count. |
 
 Skills can still be installed manually for clients that prefer local skill files — see the [skills repo](https://github.com/homeassistant-ai/skills) for instructions.
 

{ha_mcp_dev-7.1.0.dev300 → ha_mcp_dev-7.1.0.dev301}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.1.0.dev300"
+version = "7.1.0.dev301"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"
@@ -52,7 +52,7 @@ package-dir = {"" = "src", "tests" = "tests"}
 packages = { find = { where = ["src", "."], include = ["ha_mcp*", "tests"] } }
 
 [tool.setuptools.package-data]
-ha_mcp = ["py.typed", "_pypi_marker", "resources/*.md", "resources/*.json", "resources/skills-vendor/**/*"]
+ha_mcp = ["py.typed", "_pypi_marker", "resources/skills-vendor/**/*"]
 
 [tool.mypy]
 python_version = "3.13"

{ha_mcp_dev-7.1.0.dev300 → ha_mcp_dev-7.1.0.dev301}/src/ha_mcp/config.py

@@ -90,9 +90,11 @@ class Settings(BaseSettings):
     # Resources are not auto-injected — clients must explicitly request them.
     enable_skills: bool = Field(True, alias="ENABLE_SKILLS")
 
-    # Expose skills as tools (list_resources/read_resource) for clients
-    # that don't support MCP resources natively.
-    enable_skills_as_tools: bool = Field(False, alias="ENABLE_SKILLS_AS_TOOLS")
+    # Expose skills and doc resources as tools (list_resources/read_resource)
+    # for clients that don't support MCP resources natively.
+    # Defaults to True so all clients can access documentation and skills.
+    # Resource-capable clients can set to False to reduce tool count.
+    enable_skills_as_tools: bool = Field(True, alias="ENABLE_SKILLS_AS_TOOLS")
 
     # Tool search transform — replaces the full tool catalog with a unified
     # BM25 search tool and categorized call proxies (read/write/delete).

{ha_mcp_dev-7.1.0.dev300 → ha_mcp_dev-7.1.0.dev301}/src/ha_mcp/errors.py

@@ -137,7 +137,7 @@ DEFAULT_SUGGESTIONS: dict[ErrorCode, list[str]] = {
         "Entity domain must match the original domain",
     ],
     ErrorCode.SERVICE_NOT_FOUND: [
-        "Use ha_get_domain_docs() to see available services",
+        "Use ha_get_skill_home_assistant_best_practices for documentation",
         "Check the service name spelling",
         "Verify the domain supports this service",
     ],
@@ -148,7 +148,7 @@ DEFAULT_SUGGESTIONS: dict[ErrorCode, list[str]] = {
     ErrorCode.SERVICE_INVALID_ACTION: [
         "Check available actions for this domain",
         "Common actions: turn_on, turn_off, toggle",
-        "Use ha_get_domain_docs() for service documentation",
+        "Use ha_get_skill_home_assistant_best_practices for documentation",
     ],
     ErrorCode.SERVICE_CALL_FAILED: [
         "Check the service parameters are correct",
@@ -161,7 +161,7 @@ DEFAULT_SUGGESTIONS: dict[ErrorCode, list[str]] = {
     ],
     ErrorCode.CONFIG_INVALID: [
         "Review the configuration format",
-        "Use ha_get_domain_docs() for configuration help",
+        "Use ha_get_skill_home_assistant_best_practices for configuration help",
     ],
     ErrorCode.CONFIG_MISSING_REQUIRED_FIELDS: [
         "Check documentation for required fields",

{ha_mcp_dev-7.1.0.dev300 → ha_mcp_dev-7.1.0.dev301}/src/ha_mcp/resources/skills-vendor/.claude/settings.json

@@ -1,5 +1,7 @@
 {
-  "enabledPlugins": {},
+  "enabledPlugins": {
+    "skill-creator@claude-plugins-official": true
+  },
   "extraKnownMarketplaces": {
     "anthropic-agent-skills": {
       "source": {

{ha_mcp_dev-7.1.0.dev300 → ha_mcp_dev-7.1.0.dev301}/src/ha_mcp/resources/skills-vendor/AGENTS.md

@@ -26,6 +26,7 @@ description: >
 
 Constraints from CONTRIBUTING.md:
 - Max **500 lines** per SKILL.md
+- `metadata.version` must be `0` on new skills (CI assigns real version on merge; do not edit manually)
 - Reference files must be **one level deep** only (e.g. `references/example.yaml`)
 - Use **forward slashes** in all file paths
 - Optional subdirectories: `references/` (additional docs), `scripts/` (utility scripts), `assets/` (static resources)
@@ -36,6 +37,7 @@ Constraints from CONTRIBUTING.md:
 - **Conciseness** — provide patterns and quick-reference tables, not tutorials
 - **Consistent terminology** — one term per concept throughout a skill
 - **Symptom-based triggering** — the `description` frontmatter should describe observable agent behaviors that signal the skill is needed
+- **No tool names** — reference HA REST APIs and concepts, never specific MCP tool names (e.g. `ha_rename_entity`); tool names vary by agent setup
 
 ## Validation
 

{ha_mcp_dev-7.1.0.dev300 → ha_mcp_dev-7.1.0.dev301}/src/ha_mcp/resources/skills-vendor/CLAUDE.md

@@ -26,6 +26,7 @@ description: >
 
 Constraints from CONTRIBUTING.md:
 - Max **500 lines** per SKILL.md
+- `metadata.version` must be `0` on new skills (CI assigns real version on merge; do not edit manually)
 - Reference files must be **one level deep** only (e.g. `references/example.yaml`)
 - Use **forward slashes** in all file paths
 - Optional subdirectories: `references/` (additional docs), `scripts/` (utility scripts), `assets/` (static resources)
@@ -36,6 +37,7 @@ Constraints from CONTRIBUTING.md:
 - **Conciseness** — provide patterns and quick-reference tables, not tutorials
 - **Consistent terminology** — one term per concept throughout a skill
 - **Symptom-based triggering** — the `description` frontmatter should describe observable agent behaviors that signal the skill is needed
+- **No tool names** — reference HA REST APIs and concepts, never specific MCP tool names (e.g. `ha_rename_entity`); tool names vary by agent setup
 
 ## Validation
 

{ha_mcp_dev-7.1.0.dev300 → ha_mcp_dev-7.1.0.dev301}/src/ha_mcp/resources/skills-vendor/CONTRIBUTING.md

@@ -18,7 +18,7 @@ skills/
 ### SKILL.md requirements
 
 - **YAML frontmatter** with `name` (letters, numbers, hyphens only; 64 chars max) and `description` (1024 chars max).
-- **`metadata.version`** using [semver](https://semver.org/) (e.g. `"1.0.0"`). Bump the version in every PR that changes skill content. CI enforces this.
+- **`metadata.version`** a monotonically incrementing integer (e.g. `1`). Set to `0` when creating a new skill — CI assigns the real version automatically on merge. Do not edit this field manually.
 - **`description`** in third person. Describe what the skill does and when to use it. Include keywords that help agents match tasks. Don't summarize the skill's workflow.
 - **Body** under 500 lines. Split into reference files if approaching this limit.
 - **Reference files** one level deep from SKILL.md—no nested references.
@@ -34,6 +34,10 @@ See Anthropic's [skill authoring best practices](https://docs.anthropic.com/en/d
 
 **Consistent terminology.** Choose one term for each concept and stick to it throughout the skill.
 
+**Don't couple skills to specific tool names.** Reference HA concepts and REST APIs instead of naming specific MCP tools (e.g. `ha_rename_entity`, `ha_get_integration`). Tool names change and not all agents have the same toolset; the underlying HA APIs and concepts are stable.
+
+**No opinionated conventions.** Skills in this repo are applied to any HA installation. Naming conventions, code style preferences, and other user-space opinions belong in a personal skill or instance-level `CLAUDE.md`, not here. Only include guidance that reflects official HA behaviour or well-established community consensus.
+
 ## Reporting Skill Problems
 
 When a skill misleads your agent — broken dashboards, failed automations, wrong configurations — first search existing issues for the same skill and failure. If a matching issue exists, react with thumbs-up or comment with additional context. Otherwise, open a new issue with the **Report Bad Skill Advice** template. Let the agent fill it out — it holds the full context and can trace the failure to its source in the skill.

{ha_mcp_dev-7.1.0.dev300 → ha_mcp_dev-7.1.0.dev301}/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/SKILL.md

@@ -1,22 +1,27 @@
 ---
 name: home-assistant-best-practices
 description: >
-  Best practices for Home Assistant automations, helpers, scripts, and device controls.
+  Best practices for HA automations, helpers, scripts, device controls, and dashboards.
 
   TRIGGER THIS SKILL WHEN:
-  - Creating or editing HA automations, scripts, or scenes
+  - Creating/editing automations, scripts, scenes, or dashboards
   - Choosing between template sensors and built-in helpers
   - Writing or restructuring triggers, conditions, or automation modes
   - Setting up Zigbee button/remote automations (ZHA or Zigbee2MQTT)
-  - Renaming entities or migrating device_id references to entity_id
-
-  SYMPTOMS THAT TRIGGER THIS SKILL:
-  - Agent uses Jinja2 templates where native conditions, triggers, or helpers exist
-  - Agent uses device_id instead of entity_id in triggers/actions
-  - Agent modifies entity IDs or config objects without checking all consumers
+  - Renaming entities or migrating device_id to entity_id
+  - Configuring dashboard cards or picking helpers to feed them
+  - Looking up card types or domain-specific documentation
+
+  SYMPTOMS:
+  - Agent uses Jinja2 templates where native conditions/triggers/helpers exist
+  - Agent uses device_id instead of entity_id
+  - Agent modifies entity IDs without checking consumers
   - Agent chooses wrong automation mode (e.g., single for motion lights)
+  - Agent hard-codes values or picks raw sensor over derived helper
+  - Agent searches for HA config files on disk or generates YAML snippets
+  - Agent tells user to edit configuration.yaml for UI-configured integrations
 metadata:
-  version: "1.0.0"
+  version: 2
 ---
 
 # Home Assistant Best Practices
@@ -42,7 +47,7 @@ Before writing any template, check `references/automation-patterns.md` for nativ
 - `{{ 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 `references/safe-refactoring.md#trigger-restructuring`)
 
-### 2. Check for built-in helper
+### 2. Check for built-in helper or Template Helper
 Before creating a template sensor, check `references/helper-selection.md`.
 
 **Common substitutions:**
@@ -52,6 +57,11 @@ Before creating a template sensor, check `references/helper-selection.md`.
 - Cross threshold detection → `threshold` integration
 - Consumption tracking → `utility_meter` helper
 
+**If no built-in helper fits, use a Template Helper — not YAML.**
+Create it via the HA config flow (MCP tool or API) or via the UI:
+Settings → Devices & Services → Helpers → Create Helper → Template.
+Only write `template:` YAML if explicitly requested or if neither path is available.
+
 ### 3. Select correct automation mode
 Default `single` mode is often wrong. See `references/automation-patterns.md#automation-modes`.
 
@@ -86,6 +96,10 @@ See `references/device-control.md#zigbee-buttonremote-patterns`.
 | Template sensor for sum/mean | `min_max` helper | Declarative, handles unavailable states | `references/helper-selection.md#numeric-aggregation` |
 | Template binary sensor with threshold | `threshold` helper | Built-in hysteresis support | `references/helper-selection.md#threshold` |
 | Renaming entity IDs without impact analysis | Follow `references/safe-refactoring.md` workflow | Renames break dashboards, scripts, and scenes silently | `references/safe-refactoring.md#entity-renames` |
+| `template:` sensor/binary sensor in YAML | Template Helper (UI or config flow API) | Requires file edit and config reload; harder to manage | `references/template-guidelines.md` |
+| Searching for or reading HA config files on disk | Use the HA REST/WebSocket API to manage config programmatically | HA is a remote system accessed via APIs; config files are not on the local filesystem | — |
+| 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 | `references/automation-patterns.md`, `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 | — |
 
 ---
 
@@ -100,4 +114,7 @@ Read these when you need detailed information:
 | `references/helper-selection.md` | Deciding whether to use a built-in helper vs template sensor | `#numeric-aggregation`, `#rate-and-change`, `#time-based-tracking`, `#counting-and-timing`, `#scheduling`, `#entity-grouping`, `#decision-matrix` |
 | `references/template-guidelines.md` | Confirming templates ARE appropriate for a use case | `#when-templates-are-appropriate`, `#when-to-avoid-templates`, `#template-sensor-best-practices`, `#common-patterns`, `#error-handling` |
 | `references/device-control.md` | Writing service calls, Zigbee button automations, or using target: | `#entity-id-vs-device-id`, `#service-calls-best-practices`, `#zigbee-buttonremote-patterns`, `#domain-specific-patterns` |
+| `references/dashboard-guide.md` | Designing or modifying Lovelace dashboards — layout, view types, sections, custom cards, CSS styling, HACS | `#dashboard-structure`, `#view-types`, `#built-in-cards`, `#features`, `#custom-cards`, `#css-styling`, `#common-pitfalls` |
+| `references/dashboard-cards.md` | Looking up available card types or fetching card-specific documentation | — |
+| `references/domain-docs.md` | Looking up integration or domain documentation for service calls, entity attributes, or configuration | — |
 | `references/examples.yaml` | Need compound examples combining multiple best practices | — |

ha_mcp_dev-7.1.0.dev301/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/evals/evals.json

@@ -0,0 +1,53 @@
+{
+  "skill_name": "home-assistant-best-practices",
+  "evals": [
+    {
+      "id": 1,
+      "eval_name": "vacuum-last-clean",
+      "prompt": "create a sensor that shows my vacuum's last clean time in a human-readable format",
+      "expected_output": "Recommends creating a Template Helper (via UI or config flow/MCP), NOT writing a template: block in configuration.yaml",
+      "assertions": [
+        {
+          "id": "recommends_template_helper",
+          "description": "Response recommends Template Helper (UI or API/MCP) rather than YAML template: block"
+        },
+        {
+          "id": "no_yaml_template_first",
+          "description": "Response does NOT lead with or exclusively suggest writing template: YAML in configuration.yaml"
+        }
+      ]
+    },
+    {
+      "id": 2,
+      "eval_name": "media-player-song",
+      "prompt": "I want a sensor showing my media player's current song title",
+      "expected_output": "Recommends creating a Template Helper (via UI or config flow/MCP) for attribute extraction, not YAML",
+      "assertions": [
+        {
+          "id": "recommends_template_helper",
+          "description": "Response recommends Template Helper (UI or API/MCP) rather than YAML template: block"
+        },
+        {
+          "id": "no_yaml_template_first",
+          "description": "Response does NOT lead with or exclusively suggest writing template: YAML in configuration.yaml"
+        }
+      ]
+    },
+    {
+      "id": 3,
+      "eval_name": "avg-temperature",
+      "prompt": "create a sensor that averages my 3 room temperature sensors",
+      "expected_output": "Recommends min_max helper (built-in integration), NOT Template Helper or YAML template",
+      "assertions": [
+        {
+          "id": "recommends_min_max",
+          "description": "Response recommends the min_max integration helper with type: mean"
+        },
+        {
+          "id": "no_template_needed",
+          "description": "Response does NOT recommend a template sensor (YAML or UI helper) as the primary solution"
+        }
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,36 @@
+# Dashboard Card Types
+
+Home Assistant provides 37 built-in card types. For card-specific documentation, fetch from GitHub on demand.
+
+## Available Card Types
+
+alarm-panel, area, button, calendar, clock, conditional, 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, 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 `references/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` |
+| Navigation button | `button` with `tap_action: navigate` |
+| Room overview with controls | `area` |
+| Historical data graph | `history-graph` or `statistics-graph` |
+| Sensor value display | `sensor` or `gauge` |
+| Show/hide cards conditionally | `conditional` |
+| Embed external page | `iframe` |
+| Rich text / instructions | `markdown` |
+| Camera or image with overlays | `picture-elements` |