ha-mcp-dev 6.3.1.dev137__py3-none-any.whl

ha_mcp/tools/tools_config_info.py

@@ -0,0 +1,258 @@
+"""
+Configuration information tool for Home Assistant MCP Server.
+
+This module provides an informational tool that explains how Home Assistant
+configuration works when accessed remotely via ha-mcp, and provides guidance
+on generating configuration snippets.
+"""
+
+import logging
+from typing import Annotated, Any
+
+from pydantic import Field
+
+from .helpers import log_tool_usage
+
+logger = logging.getLogger(__name__)
+
+
+def register_config_info_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
+    """Register configuration information tools with the MCP server."""
+
+    @mcp.tool(
+        annotations={
+            "idempotentHint": True,
+            "readOnlyHint": True,
+            "tags": ["information", "configuration"],
+            "title": "Home Assistant Configuration Info",
+        }
+    )
+    @log_tool_usage
+    async def ha_config_info(
+        config_type: Annotated[
+            str,
+            Field(
+                default="general",
+                description=(
+                    "Type of configuration information to retrieve. "
+                    "Options: 'general' (default), 'automation', 'script', 'dashboard', "
+                    "'integration', or 'yaml'. Use 'general' for an overview of how "
+                    "configuration works via ha-mcp."
+                ),
+            ),
+        ] = "general",
+    ) -> dict[str, Any]:
+        """
+        Get information about Home Assistant configuration access via ha-mcp.
+
+        **IMPORTANT FOR AI AGENTS:**
+        Home Assistant accessed via ha-mcp is a REMOTE system accessed through
+        REST and WebSocket APIs. Configuration files are NOT accessible on the
+        local filesystem where this MCP server runs.
+
+        **DO NOT:**
+        - Search for configuration.yaml or other HA config files on disk
+        - Attempt to read HA configuration files from the filesystem
+        - Try to modify configuration files directly
+        - Assume HA is running on the same machine as this MCP server
+
+        **DO:**
+        - Use ha-mcp tools to query configuration via the API
+        - Generate configuration snippets for the user to copy/paste
+        - Direct users to the Home Assistant UI for configuration changes
+        - Suggest configuration examples based on user needs
+
+        **CONFIGURATION ACCESS:**
+        - Automations: Use ha_config_* tools (list, get, create, update, delete)
+        - Scripts: Use ha_config_script_* tools
+        - Dashboards: Use ha_config_dashboard_* tools
+        - Integrations: Most are configured via UI, some via YAML
+        - YAML files: Not directly accessible via ha-mcp
+
+        **GENERATING SNIPPETS:**
+        When users need configuration examples:
+        1. Generate valid YAML/JSON snippets based on their requirements
+        2. Provide clear instructions on where to add the configuration
+        3. Explain any required steps (restart, reload, etc.)
+        4. Link to relevant Home Assistant documentation
+
+        **FEATURE REQUESTS:**
+        If users need direct configuration file access or advanced features:
+        - Suggest filing a feature request at:
+          https://github.com/homeassistant-ai/ha-mcp/issues/new
+        - Explain the current capabilities and limitations
+        - Provide workarounds using existing tools
+
+        Returns information specific to the requested config_type.
+        """
+        info: dict[str, Any] = {
+            "success": True,
+            "config_type": config_type,
+            "ha_access_method": "Remote via REST/WebSocket APIs",
+            "filesystem_access": False,
+        }
+
+        if config_type == "general":
+            info["message"] = (
+                "Home Assistant is accessed remotely via REST and WebSocket APIs. "
+                "Configuration files (configuration.yaml, etc.) are NOT accessible "
+                "on the local filesystem. Use ha-mcp tools to query and modify "
+                "configuration via the API, or generate configuration snippets "
+                "for users to manually add."
+            )
+            info["available_tools"] = [
+                "ha_config_* - Automation management",
+                "ha_config_script_* - Script management",
+                "ha_config_dashboard_* - Dashboard management",
+                "ha_config_helper_* - Helper entity management",
+                "ha_get_config - Get basic HA configuration info",
+                "ha_list_entities - List all entities",
+                "ha_search_* - Search entities, services, etc.",
+            ]
+            info["not_available"] = [
+                "Direct file system access to configuration.yaml",
+                "Direct file system access to automations.yaml",
+                "Direct file system access to scripts.yaml",
+                "Direct file system access to secrets.yaml",
+            ]
+
+        elif config_type == "automation":
+            info["message"] = (
+                "Automations can be managed via ha_config_* tools. "
+                "For YAML-based automations, generate snippets for users to add manually."
+            )
+            info["tools"] = [
+                "ha_config_list_automations - List all automations",
+                "ha_config_get_automation - Get automation details",
+                "ha_config_create_automation - Create new automation",
+                "ha_config_update_automation - Update existing automation",
+                "ha_config_delete_automation - Delete automation",
+                "ha_trigger_automation - Manually trigger automation",
+            ]
+            info["snippet_example"] = {
+                "description": "Example automation snippet",
+                "yaml": """# Add to automations.yaml or via HA UI
+- alias: "Example Automation"
+  description: "Turn on light when motion detected"
+  trigger:
+    - platform: state
+      entity_id: binary_sensor.motion_sensor
+      to: "on"
+  condition: []
+  action:
+    - service: light.turn_on
+      target:
+        entity_id: light.living_room
+      data:
+        brightness: 255""",
+            }
+
+        elif config_type == "script":
+            info["message"] = (
+                "Scripts can be managed via ha_config_script_* tools. "
+                "For YAML-based scripts, generate snippets for users to add manually."
+            )
+            info["tools"] = [
+                "ha_config_list_scripts - List all scripts",
+                "ha_config_get_script - Get script details",
+                "ha_config_create_script - Create new script",
+                "ha_config_update_script - Update existing script",
+                "ha_config_delete_script - Delete script",
+                "ha_execute_script - Run a script",
+            ]
+            info["snippet_example"] = {
+                "description": "Example script snippet",
+                "yaml": """# Add to scripts.yaml or via HA UI
+good_night:
+  alias: "Good Night"
+  description: "Turn off all lights and lock doors"
+  sequence:
+    - service: light.turn_off
+      target:
+        area_id: all
+    - service: lock.lock
+      target:
+        entity_id: lock.front_door""",
+            }
+
+        elif config_type == "dashboard":
+            info["message"] = (
+                "Dashboards can be managed via ha_config_dashboard_* tools. "
+                "Dashboard configuration is stored in the HA database, not YAML files."
+            )
+            info["tools"] = [
+                "ha_config_get_dashboard(list_only=True) - List all dashboards",
+                "ha_config_get_dashboard(url_path=...) - Get dashboard configuration",
+                "ha_config_set_dashboard - Create/update dashboard",
+                "ha_config_delete_dashboard - Delete dashboard",
+            ]
+            info["note"] = (
+                "Dashboard YAML configuration is for Lovelace cards, not file access. "
+                "Use the dashboard tools to manage dashboards programmatically."
+            )
+
+        elif config_type == "integration":
+            info["message"] = (
+                "Most integrations are configured via the Home Assistant UI. "
+                "Some integrations support YAML configuration, but files are not "
+                "accessible via ha-mcp."
+            )
+            info["recommendations"] = [
+                "Use ha_get_integration() to see installed integrations",
+                "Generate YAML snippets for manual addition to configuration.yaml",
+                "Direct users to Settings > Devices & Services in HA UI",
+                "Provide documentation links for specific integrations",
+            ]
+            info["snippet_example"] = {
+                "description": "Example integration configuration",
+                "yaml": """# Add to configuration.yaml
+mqtt:
+  broker: 192.168.1.100
+  port: 1883
+  username: !secret mqtt_username
+  password: !secret mqtt_password
+
+sensor:
+  - platform: mqtt
+    name: "Temperature"
+    state_topic: "home/temperature"
+    unit_of_measurement: "°C\"""",
+            }
+
+        elif config_type == "yaml":
+            info["message"] = (
+                "YAML configuration files (configuration.yaml, automations.yaml, etc.) "
+                "are NOT accessible via ha-mcp. Generate snippets for users to add manually."
+            )
+            info["workflow"] = [
+                "1. Ask user what configuration they need",
+                "2. Generate valid YAML snippet based on requirements",
+                "3. Explain which file to edit (configuration.yaml, automations.yaml, etc.)",
+                "4. Provide instructions on reloading/restarting HA",
+                "5. Link to relevant documentation",
+            ]
+            info["common_files"] = {
+                "configuration.yaml": "Main configuration file",
+                "automations.yaml": "Automation definitions (or use UI)",
+                "scripts.yaml": "Script definitions (or use UI)",
+                "secrets.yaml": "Sensitive data (passwords, API keys, etc.)",
+                "customize.yaml": "Entity customization",
+                "groups.yaml": "Entity groups",
+                "scenes.yaml": "Scene definitions",
+            }
+            info["feature_request_url"] = (
+                "https://github.com/homeassistant-ai/ha-mcp/issues/new"
+            )
+            info["feature_request_note"] = (
+                "If direct file access is needed, file a feature request. "
+                "Explain your use case and why current tools are insufficient."
+            )
+
+        else:
+            info["success"] = False
+            info["error"] = (
+                f"Unknown config_type: {config_type}. "
+                "Valid options: general, automation, script, dashboard, integration, yaml"
+            )
+
+        return info

ha_mcp/tools/tools_config_scripts.py

@@ -0,0 +1,267 @@
+"""
+Configuration management tools for Home Assistant scripts.
+
+This module provides tools for retrieving, creating, updating, and removing
+Home Assistant script configurations.
+"""
+
+import logging
+from typing import Annotated, Any, cast
+
+from pydantic import Field
+
+from .helpers import log_tool_usage
+from .util_helpers import parse_json_param
+
+logger = logging.getLogger(__name__)
+
+
+def register_config_script_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
+    """Register Home Assistant script configuration tools."""
+
+    @mcp.tool(
+        annotations={
+            "idempotentHint": True,
+            "readOnlyHint": True,
+            "tags": ["script"],
+            "title": "Get Script Config",
+        }
+    )
+    @log_tool_usage
+    async def ha_config_get_script(
+        script_id: Annotated[
+            str, Field(description="Script identifier (e.g., 'morning_routine')")
+        ],
+    ) -> dict[str, Any]:
+        """
+        Retrieve Home Assistant script configuration.
+
+        Returns the complete configuration for a script, including sequence, mode, fields, and other settings.
+
+        EXAMPLES:
+        - Get script: ha_config_get_script("morning_routine")
+        - Get script: ha_config_get_script("backup_script")
+
+        For detailed script configuration help, use: ha_get_domain_docs("script")
+        """
+        try:
+            config_result = await client.get_script_config(script_id)
+            return {
+                "success": True,
+                "action": "get",
+                "script_id": script_id,
+                "config": config_result,
+            }
+        except Exception as e:
+            logger.error(f"Error getting script: {e}")
+            return {
+                "success": False,
+                "action": "get",
+                "script_id": script_id,
+                "error": str(e),
+                "suggestions": [
+                    "Verify script_id exists using ha_search_entities(domain_filter='script')",
+                    "Check Home Assistant connection",
+                    "Use ha_get_domain_docs('script') for configuration help",
+                ],
+            }
+
+    @mcp.tool(
+        annotations={
+            "destructiveHint": True,
+            "tags": ["script"],
+            "title": "Create or Update Script",
+        }
+    )
+    @log_tool_usage
+    async def ha_config_set_script(
+        script_id: Annotated[
+            str, Field(description="Script identifier (e.g., 'morning_routine')")
+        ],
+        config: Annotated[
+            str | dict[str, Any],
+            Field(
+                description="Script configuration dictionary with 'sequence' (required) and optional fields like 'alias', 'description', 'icon', 'mode', 'max', 'fields'"
+            ),
+        ],
+    ) -> dict[str, Any]:
+        """
+        Create or update a Home Assistant script.
+
+        Creates a new script or updates an existing one with the provided configuration.
+
+        Required config fields:
+            - sequence: List of actions to execute
+
+        Optional config fields:
+            - alias: Display name (defaults to script_id)
+            - description: Script description
+            - icon: Icon to display
+            - mode: Execution mode ('single', 'restart', 'queued', 'parallel')
+            - max: Maximum concurrent executions (for queued/parallel modes)
+            - fields: Input parameters for the script
+
+        IMPORTANT: The 'config' parameter must be passed as a proper dictionary/object.
+
+        EXAMPLES:
+
+        Create basic delay script:
+        ha_config_set_script("wait_script", {
+            "sequence": [{"delay": {"seconds": 5}}],
+            "alias": "Wait 5 Seconds",
+            "description": "Simple delay script"
+        })
+
+        Create service call script:
+        ha_config_set_script("blink_light", {
+            "sequence": [
+                {"service": "light.turn_on", "target": {"entity_id": "light.living_room"}},
+                {"delay": {"seconds": 2}},
+                {"service": "light.turn_off", "target": {"entity_id": "light.living_room"}}
+            ],
+            "alias": "Light Blink",
+            "mode": "single"
+        })
+
+        Create script with parameters:
+        ha_config_set_script("backup_script", {
+            "alias": "Backup with Reference",
+            "description": "Create backup with optional reference parameter",
+            "fields": {
+                "reference": {
+                    "name": "Reference",
+                    "description": "Optional reference for backup identification",
+                    "selector": {"text": None}
+                }
+            },
+            "sequence": [
+                {
+                    "action": "hassio.backup_partial",
+                    "data": {
+                        "compressed": False,
+                        "homeassistant": True,
+                        "homeassistant_exclude_database": True,
+                        "name": "Backup_{{ reference | default('auto') }}_{{ now().strftime('%Y%m%d_%H%M%S') }}"
+                    }
+                }
+            ]
+        })
+
+        Update script:
+        ha_config_set_script("morning_routine", {
+            "sequence": [
+                {"service": "light.turn_on", "target": {"area_id": "bedroom"}},
+                {"service": "climate.set_temperature", "target": {"entity_id": "climate.bedroom"}, "data": {"temperature": 22}}
+            ],
+            "alias": "Updated Morning Routine"
+        })
+
+        PREFER NATIVE ACTIONS OVER TEMPLATES:
+        Before using template-based logic in scripts, check if native actions exist:
+        - Use `choose` action instead of template-based service names
+        - Use `if/then/else` action instead of template conditions
+        - Use `repeat` action with `for_each` instead of template loops
+        - Use `wait_for_trigger` instead of `wait_template` when waiting for state changes
+        - Use native action variables instead of complex template calculations
+
+        For detailed script configuration help, use: ha_get_domain_docs("script")
+
+        Note: Scripts use Home Assistant's action syntax. Check the documentation for advanced
+        features like conditions, variables, parallel execution, and service call options.
+        """
+        try:
+            # Parse JSON config if provided as string
+            try:
+                parsed_config = parse_json_param(config, "config")
+            except ValueError as e:
+                return {
+                    "success": False,
+                    "error": f"Invalid config parameter: {e}",
+                    "provided_config_type": type(config).__name__,
+                }
+
+            # Ensure config is a dict
+            if parsed_config is None or not isinstance(parsed_config, dict):
+                return {
+                    "success": False,
+                    "error": "Config parameter must be a JSON object",
+                    "provided_type": type(parsed_config).__name__,
+                }
+
+            config_dict = cast(dict[str, Any], parsed_config)
+
+            if "sequence" not in config_dict:
+                return {
+                    "success": False,
+                    "error": "config must include 'sequence' field",
+                    "required_fields": ["sequence"],
+                }
+
+            result = await client.upsert_script_config(config_dict, script_id)
+            return {
+                "success": True,
+                **result,
+                "config_provided": config_dict,
+            }
+
+        except Exception as e:
+            logger.error(f"Error upserting script: {e}")
+            return {
+                "success": False,
+                "script_id": script_id,
+                "error": str(e),
+                "suggestions": [
+                    "Ensure config includes 'sequence' field",
+                    "Validate sequence actions syntax",
+                    "Check entity_ids exist if using service calls",
+                    "Use ha_search_entities(domain_filter='script') to find scripts",
+                    "Use ha_get_domain_docs('script') for configuration help",
+                ],
+            }
+
+    @mcp.tool(
+        annotations={
+            "destructiveHint": True,
+            "idempotentHint": True,
+            "tags": ["script"],
+            "title": "Remove Script",
+        }
+    )
+    @log_tool_usage
+    async def ha_config_remove_script(
+        script_id: Annotated[
+            str, Field(description="Script identifier to delete (e.g., 'old_script')")
+        ],
+    ) -> dict[str, Any]:
+        """
+        Delete a Home Assistant script.
+
+        EXAMPLES:
+        - Delete script: ha_config_remove_script("old_script")
+        - Delete script: ha_config_remove_script("temporary_script")
+
+        **IMPORTANT LIMITATION:**
+        This tool can only delete scripts created via the Home Assistant UI.
+        Scripts defined in YAML configuration files (scripts.yaml or configuration.yaml)
+        cannot be deleted through the API and will return a 405 Method Not Allowed error.
+
+        To remove YAML-defined scripts, you must edit the configuration file directly.
+
+        **WARNING:** Deleting a script that is used by automations may cause those automations to fail.
+        """
+        try:
+            result = await client.delete_script_config(script_id)
+            return {"success": True, "action": "delete", **result}
+        except Exception as e:
+            logger.error(f"Error deleting script: {e}")
+            return {
+                "success": False,
+                "action": "delete",
+                "script_id": script_id,
+                "error": str(e),
+                "suggestions": [
+                    "Verify script_id exists using ha_search_entities(domain_filter='script')",
+                    "Check if script is being used by automations",
+                    "Use ha_get_domain_docs('script') for configuration help",
+                ],
+            }

ha_mcp/tools/tools_entities.py

@@ -0,0 +1,76 @@
+"""
+Entity management tools for Home Assistant MCP server.
+
+This module provides tools for managing entity lifecycle and properties
+via the Home Assistant entity registry API.
+"""
+
+import logging
+from typing import Annotated, Any
+
+from pydantic import Field
+
+from .helpers import exception_to_structured_error, log_tool_usage
+from .util_helpers import coerce_bool_param
+
+logger = logging.getLogger(__name__)
+
+
+def register_entity_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
+    """Register entity management tools with the MCP server."""
+
+    @mcp.tool(
+        annotations={
+            "destructiveHint": True,
+            "idempotentHint": True,
+            "tags": ["entity"],
+            "title": "Set Entity Enabled",
+        }
+    )
+    @log_tool_usage
+    async def ha_set_entity_enabled(
+        entity_id: Annotated[
+            str, Field(description="Entity ID (e.g., 'sensor.temperature')")
+        ],
+        enabled: Annotated[
+            bool | str, Field(description="True to enable, False to disable")
+        ],
+    ) -> dict[str, Any]:
+        """Enable/disable entity. Disabled entities don't appear in UI.
+
+        Use ha_search_entities() or ha_get_device() to find entity IDs.
+        """
+        try:
+            enabled_bool = coerce_bool_param(enabled, "enabled")
+
+            message = {
+                "type": "config/entity_registry/update",
+                "entity_id": entity_id,
+                "disabled_by": None if enabled_bool else "user",
+            }
+
+            result = await client.send_websocket_message(message)
+
+            if result.get("success"):
+                entity_entry = result.get("result", {}).get("entity_entry", {})
+                return {
+                    "success": True,
+                    "entity_id": entity_id,
+                    "enabled": entity_entry.get("disabled_by") is None,
+                    "message": f"Entity {'enabled' if enabled_bool else 'disabled'}",
+                }
+            else:
+                error = result.get("error", {})
+                error_msg = (
+                    error.get("message", str(error))
+                    if isinstance(error, dict)
+                    else str(error)
+                )
+                return {
+                    "success": False,
+                    "error": f"Failed to {'enable' if enabled_bool else 'disable'}: {error_msg}",
+                    "entity_id": entity_id,
+                }
+        except Exception as e:
+            logger.error(f"Error setting entity enabled: {e}")
+            return exception_to_structured_error(e, context={"entity_id": entity_id})