Expose automation category in ha_config_set_automation and ha_config_get_automation

[sbericsson]

Feature Request

Summary

The ha_config_set_automation and ha_config_get_automation tools do not expose
the category field for automations. Attempting to pass category in the config
payload returns a validation error:

  Message malformed: extra keys not allowed @ data['category']

Current behavior

• ha_config_get_automation returns the automation config but omits the category
  field even when one is set in the UI.
• ha_config_set_automation rejects configs that include a category key.

Expected behavior

• ha_config_get_automation should include the category field in its response
  when set.
• ha_config_set_automation should accept an optional category field and persist
  it to the entity registry.

Why this matters

When managing automations programmatically (e.g., via an AI assistant), there's no
way to assign categories without dropping into the HA UI manually. Categories are a
first-class organizational feature in the Automations UI and should be manageable
through the same API surface as the rest of the automation config.

Workaround

Currently requires manual UI interaction:
Settings → Automations & Scenes → select automations → ⋮ menu → "Add to category".

Notes

The category for automations is stored in the entity registry (not the automation
YAML config), so this may require the tool to make a separate entity_registry/update
call after saving the automation config. The relevant HA WebSocket API is
entity_registry/update with categories: {"automation.automations": "<category_id>"}.

Sources:

• https://github.com/homeassistant-ai/ha-mcp

[github-actions]

🔍 Analysis

The ha_config_get_automation and ha_config_set_automation tools currently interact only with Home Assistant's automation configuration REST API (/api/config/automation/config/{id}). This API is designed to handle the YAML-based configuration of an automation (triggers, conditions, actions, etc.).

However, in Home Assistant, categories are not stored in the automation's YAML configuration. Instead, they are managed via the Entity Registry. Because the REST API used by these tools is strictly for YAML config, it does not return the category field and rejects any attempt to include it in a request, leading to the error: Message malformed: extra keys not allowed @ data['category'].

To support categories, these tools must be extended to perform a secondary operation via the Home Assistant WebSocket API to fetch or update the entity's registry entry under the automation.automations scope.

🛠️ Suggested Steps

1. Update ha_config_get_automation: Modify the tool to resolve the automation's entity_id and then call the config/entity_registry/get WebSocket command. Extract the category from categories["automation.automations"] and merge it into the returned configuration.
2. Update ha_config_set_automation: Modify the tool to extract the category field from the input before sending the YAML config to the REST API. After a successful creation or update, call the config/entity_registry/update WebSocket command with the categories payload.
3. Extend Entity Tools: (Optional but recommended) Update ha_get_entity and ha_set_entity in src/ha_mcp/tools/tools_entities.py to support the categories field generally, which would allow managing categories for any entity type (scripts, scenes, sensors, etc.).

📊 Technical Analysis (for maintainers)

Root Cause

The automation configuration management tools rely on the REST API /api/config/automation/config/{id}, which is restricted to the schema defined in homeassistant/components/automation/config.py. Categories (and labels) are part of the RegistryEntry in homeassistant/helpers/entity_registry.py. Updating an automation's category requires a WebSocket call to config/entity_registry/update with the scope automation.automations.

Affected Code

• src/ha_mcp/tools/tools_config_automations.py - Contains the logic for ha_config_get_automation and ha_config_set_automation.
• src/ha_mcp/tools/tools_entities.py - (Optional) General entity registry tools that should also support categories.

Proposed Fix

--- a/src/ha_mcp/tools/tools_config_automations.py
+++ b/src/ha_mcp/tools/tools_config_automations.py
@@ -211,7 +211,7 @@
         """
         Retrieve Home Assistant automation configuration.
 
-        Returns the complete configuration including triggers, conditions, actions, and mode settings.
+        Returns the complete configuration including triggers, conditions, actions, mode settings, and category.
 
         EXAMPLES:
         - Get automation: ha_config_get_automation("automation.morning_routine")
@@ -223,6 +223,29 @@
             config_result = await client.get_automation_config(identifier)
             # Normalize config for round-trip compatibility (GET → SET)
             normalized_config = _normalize_config_for_roundtrip(config_result)
+
+            # Resolve entity_id to fetch category from registry
+            entity_id = identifier if identifier.startswith("automation.") else None
+            if not entity_id:
+                try:
+                    states = await client.get_states()
+                    for state in states:
+                        if state.get("entity_id", "").startswith("automation.") and state.get("attributes", {}).get("id") == identifier:
+                            entity_id = state.get("entity_id")
+                            break
+                except Exception:
+                    pass
+
+            if entity_id:
+                reg_res = await client.send_websocket_message({
+                    "type": "config/entity_registry/get",
+                    "entity_id": entity_id
+                })
+                if reg_res.get("success"):
+                    categories = reg_res.get("result", {}).get("categories", {})
+                    if "automation.automations" in categories:
+                        normalized_config["category"] = categories["automation.automations"]
+
             return {
                 "success": True,
                 "action": "get",
@@ -262,7 +285,7 @@
         config: Annotated[
             str | dict[str, Any],
             Field(
-                description="Complete automation configuration with required fields: 'alias', 'trigger', 'action'. Optional: 'description', 'condition', 'mode', 'max', 'initial_state', 'variables'"
+                description="Complete automation configuration with required fields: 'alias', 'trigger', 'action'. Optional: 'description', 'category', 'condition', 'mode', 'max', 'initial_state', 'variables'"
             ),
         ],
         identifier: Annotated[
@@ -288,7 +311,7 @@
         - action: List of actions to execute
 
         OPTIONAL CONFIG FIELDS (Regular Automations):
-        - description: Detailed description of the user's intent (RECOMMENDED: helps safely modify implementation later)
+        - description: Detailed description of the user's intent
+        - category: Automation category ID (organizational)
         - condition: Additional conditions that must be met
         - mode: 'single' (default), 'restart', 'queued', 'parallel'
         - max: Maximum concurrent executions (for queued/parallel modes)
@@ -403,6 +426,9 @@
 
             config_dict = cast(dict[str, Any], parsed_config)
 
+            # Extract category before sending to HA REST API (which rejects unknown keys)
+            category = config_dict.pop("category", None)
+
             # Normalize field names (triggers -> trigger, actions -> action, etc.)
             config_dict = _normalize_automation_config(config_dict)
 
@@ -425,6 +451,19 @@
 
             result = await client.upsert_automation_config(config_dict, identifier)
 
+            # Apply category to entity registry if provided
+            actual_entity_id = result.get("entity_id")
+            if category and actual_entity_id:
+                try:
+                    await client.send_websocket_message({
+                        "type": "config/entity_registry/update",
+                        "entity_id": actual_entity_id,
+                        "categories": {"automation.automations": category}
+                    })
+                except Exception as e:
+                    logger.warning(f"Failed to set category for {actual_entity_id}: {e}")
+                    result["warning"] = f"Automation created but failed to set category: {e}"
+
             # Wait for automation to be queryable
             wait_bool = coerce_bool_param(wait, "wait", default=True)
             entity_id = result.get("entity_id")

Related Issues/PRs

• No similar issues found.

---

🤖 Automated analysis by Issue Bot

[kingpanther13]

Related to #677 and #608

[kingpanther13]

This is related to #677 (which implements standalone category CRUD tools + category assignment via ha_set_entity, closing #608).

Once #677 is merged, the plan would be a follow-up PR that exposes the category parameter directly on all four domain-specific config tools — not just ha_config_set_automation/ha_config_get_automation, but also the equivalent tools for scripts, scenes, and helpers, since all four domains support categories in HA.

That follow-up PR would build on #677's foundation (the category registry tools and entity registry integration) and add the convenience of single-call category assignment on each domain-specific config tool.

[github-actions]

✅ This issue has been addressed in the dev channel!

A fix for this issue has been merged to master (PR #850) and is available for testing in the dev channel.

Test the fix before the next stable release (biweekly Wednesday):
📖 Dev Channel Documentation

Quick start

# Run dev version
uvx ha-mcp-dev

# Check version
uvx ha-mcp-dev --version

Docker:

docker pull ghcr.io/homeassistant-ai/ha-mcp:dev
docker run --rm -i \
  -e HOMEASSISTANT_URL=http://your-ha:8123 \
  -e HOMEASSISTANT_TOKEN=your_token \
  ghcr.io/homeassistant-ai/ha-mcp:dev

---

After testing:

• ✅ If it's fixed: Great! Feel free to comment here to confirm
• ❌ If still broken: Open a new issue and reference Expose automation category in ha_config_set_automation and ha_config_get_automation #702
  • Closed issues can't be reopened by reporters
  • A new issue helps us track the problem properly