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

ha_mcp/tools/enhanced.py

@@ -0,0 +1,191 @@
+"""
+Enhanced documentation and domain information for Home Assistant MCP Tools.
+
+This module provides domain information and documentation helpers.
+All MCP tools are now consolidated in tools_registry.py to eliminate duplication.
+"""
+
+from typing import Any
+
+# Top 25 Most Critical Home Assistant Domains
+TOP_25_DOMAINS = [
+    # Critical control domains (8)
+    "light",
+    "switch",
+    "climate",
+    "media_player",
+    "lock",
+    "cover",
+    "fan",
+    "vacuum",
+    # Essential monitoring (4)
+    "sensor",
+    "binary_sensor",
+    "device_tracker",
+    "weather",
+    # Critical input helpers (5)
+    "input_number",
+    "input_boolean",
+    "input_text",
+    "input_datetime",
+    "input_select",
+    # Automation core (3)
+    "automation",
+    "script",
+    "scene",
+    # High importance (5)
+    "camera",
+    "alarm_control_panel",
+    "button",
+    "siren",
+    "timer",
+]
+
+
+class EnhancedToolsMixin:
+    """Mixin class to add enhanced documentation and domain information to MCP server."""
+
+    def register_enhanced_tools(self) -> None:
+        """Enhanced tools are now consolidated in tools_registry.py to eliminate duplication."""
+        # This mixin now focuses on domain information and documentation helpers
+        pass
+
+    def get_domain_info(self, domain: str) -> dict[str, Any]:
+        """Get domain-specific information for enhanced documentation."""
+        return self._get_domain_info(domain)
+
+    def get_domain_insights(
+        self, domain: str, entity_state: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Get domain-specific insights for entity state."""
+        return self._get_domain_insights(domain, entity_state)
+
+    def get_domain_actions(self, domain: str) -> list[str]:
+        """Get available actions for domain."""
+        return self._get_domain_actions(domain)
+
+    def get_parameter_guidance(
+        self, domain: str, entity_state: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Get parameter guidance for domain."""
+        return self._get_parameter_guidance(domain, entity_state)
+
+    # Helper methods for enhanced functionality
+
+    def _get_domain_info(self, domain: str) -> dict[str, Any]:
+        """Get domain-specific information."""
+        domain_info = {
+            "light": {
+                "type": "control",
+                "complexity": "high",
+                "parameters": ["brightness", "color", "temperature"],
+            },
+            "switch": {
+                "type": "control",
+                "complexity": "low",
+                "parameters": ["basic_on_off"],
+            },
+            "climate": {
+                "type": "control",
+                "complexity": "high",
+                "parameters": ["temperature", "mode", "preset"],
+            },
+            "input_boolean": {
+                "type": "input",
+                "complexity": "low",
+                "parameters": ["toggle"],
+            },
+            "input_number": {
+                "type": "input",
+                "complexity": "medium",
+                "parameters": ["value", "min", "max"],
+            },
+            "sensor": {
+                "type": "monitoring",
+                "complexity": "low",
+                "parameters": ["read_only"],
+            },
+            "automation": {
+                "type": "system",
+                "complexity": "medium",
+                "parameters": ["trigger", "enable"],
+            },
+        }
+
+        return domain_info.get(
+            domain, {"type": "unknown", "complexity": "medium", "parameters": ["basic"]}
+        )
+
+    def _get_domain_insights(
+        self, domain: str, entity_state: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Get domain-specific insights for entity state."""
+        insights: dict[str, Any] = {"domain": domain, "recommendations": []}
+
+        if domain == "light":
+            if entity_state.get("state") == "on":
+                insights["recommendations"].append(
+                    "Can adjust brightness, color, or turn off"
+                )
+            else:
+                insights["recommendations"].append(
+                    "Can turn on with optional brightness/color"
+                )
+
+        elif domain == "input_boolean":
+            current_state = entity_state.get("state")
+            insights["recommendations"].append(
+                f"Can toggle from {current_state} to {'off' if current_state == 'on' else 'on'}"
+            )
+
+        elif domain == "input_number":
+            current_value = entity_state.get("state", 0)
+            min_val = entity_state.get("attributes", {}).get("min", 0)
+            max_val = entity_state.get("attributes", {}).get("max", 100)
+            insights["recommendations"].append(
+                f"Can set value between {min_val}-{max_val} (current: {current_value})"
+            )
+
+        return insights
+
+    def _get_domain_actions(self, domain: str) -> list[str]:
+        """Get available actions for domain."""
+        actions = {
+            "light": ["turn_on", "turn_off", "toggle"],
+            "switch": ["turn_on", "turn_off", "toggle"],
+            "climate": ["set_temperature", "set_hvac_mode", "set_preset_mode"],
+            "input_boolean": ["turn_on", "turn_off", "toggle"],
+            "input_number": ["set_value", "increment", "decrement"],
+            "input_text": ["set_value"],
+            "automation": ["trigger", "turn_on", "turn_off"],
+            "scene": ["turn_on"],
+        }
+
+        return actions.get(domain, ["turn_on", "turn_off"])
+
+    def _get_parameter_guidance(
+        self, domain: str, entity_state: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Get parameter guidance for domain."""
+        guidance = {}
+
+        if domain == "light":
+            guidance = {
+                "brightness_pct": "0-100 percentage (user-friendly)",
+                "color_temp_kelvin": "2000-6500K (warm to cool)",
+                "rgb_color": "[red, green, blue] values 0-255 each",
+            }
+        elif domain == "climate":
+            attributes = entity_state.get("attributes", {})
+            guidance = {
+                "temperature": f"Range: {attributes.get('min_temp', 'unknown')}-{attributes.get('max_temp', 'unknown')}",
+                "hvac_mode": f"Options: {attributes.get('hvac_modes', 'unknown')}",
+                "preset_mode": f"Options: {attributes.get('preset_modes', 'unknown')}",
+            }
+        elif domain == "input_number":
+            attributes = entity_state.get("attributes", {})
+            guidance = {
+                "value": f"Range: {attributes.get('min', 0)}-{attributes.get('max', 100)}, Step: {attributes.get('step', 1)}"
+            }
+
+        return guidance

ha_mcp/tools/helpers.py

@@ -0,0 +1,184 @@
+"""
+Reusable helper functions for MCP tools.
+
+Centralized utilities that can be shared across multiple tool implementations.
+"""
+
+import functools
+import logging
+import time
+from typing import Any
+
+from ..client.rest_client import (
+    HomeAssistantAPIError,
+    HomeAssistantAuthError,
+    HomeAssistantConnectionError,
+)
+from ..client.websocket_client import HomeAssistantWebSocketClient
+from ..errors import (
+    ErrorCode,
+    create_auth_error,
+    create_connection_error,
+    create_entity_not_found_error,
+    create_error_response,
+    create_timeout_error,
+    create_validation_error,
+)
+from ..utils.usage_logger import log_tool_call
+
+logger = logging.getLogger(__name__)
+
+
+async def get_connected_ws_client(
+    base_url: str, token: str
+) -> tuple[HomeAssistantWebSocketClient | None, dict[str, Any] | None]:
+    """
+    Create and connect a WebSocket client.
+
+    Args:
+        base_url: Home Assistant base URL
+        token: Authentication token
+
+    Returns:
+        Tuple of (ws_client, error_dict). If connection fails, ws_client is None.
+    """
+    ws_client = HomeAssistantWebSocketClient(base_url, token)
+    connected = await ws_client.connect()
+    if not connected:
+        return None, create_connection_error(
+            "Failed to connect to Home Assistant WebSocket",
+            details="WebSocket connection could not be established",
+        )
+    return ws_client, None
+
+
+def exception_to_structured_error(
+    error: Exception,
+    context: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """
+    Convert an exception to a structured error response.
+
+    This function maps common exception types to appropriate error codes
+    and creates informative error responses.
+
+    Args:
+        error: The exception to convert
+        context: Additional context to include in the response
+
+    Returns:
+        Structured error response dictionary
+    """
+    error_str = str(error).lower()
+    error_msg = str(error)
+
+    # Handle specific exception types
+    if isinstance(error, HomeAssistantConnectionError):
+        if "timeout" in error_str:
+            return create_connection_error(error_msg, timeout=True)
+        return create_connection_error(error_msg)
+
+    if isinstance(error, HomeAssistantAuthError):
+        if "expired" in error_str:
+            return create_auth_error(error_msg, expired=True)
+        return create_auth_error(error_msg)
+
+    if isinstance(error, HomeAssistantAPIError):
+        # Check for specific error patterns
+        if error.status_code == 404:
+            # Entity or resource not found
+            entity_id = context.get("entity_id") if context else None
+            if entity_id:
+                return create_entity_not_found_error(entity_id, details=error_msg)
+            return create_error_response(
+                ErrorCode.RESOURCE_NOT_FOUND,
+                error_msg,
+                context=context,
+            )
+        if error.status_code == 401:
+            return create_auth_error(error_msg)
+        if error.status_code == 400:
+            return create_validation_error(error_msg, context=context)
+
+        # Generic API error
+        return create_error_response(
+            ErrorCode.SERVICE_CALL_FAILED,
+            error_msg,
+            context=context,
+        )
+
+    if isinstance(error, TimeoutError):
+        operation = context.get("operation", "request") if context else "request"
+        timeout_seconds = context.get("timeout_seconds", 30) if context else 30
+        return create_timeout_error(operation, timeout_seconds, details=error_msg)
+
+    if isinstance(error, ValueError):
+        return create_validation_error(error_msg)
+
+    # Check for common error patterns in error message
+    if "not found" in error_str or "404" in error_str:
+        entity_id = context.get("entity_id") if context else None
+        if entity_id:
+            return create_entity_not_found_error(entity_id, details=error_msg)
+        return create_error_response(
+            ErrorCode.RESOURCE_NOT_FOUND,
+            error_msg,
+            context=context,
+        )
+
+    if "timeout" in error_str:
+        return create_timeout_error("operation", 30, details=error_msg)
+
+    if "connection" in error_str or "connect" in error_str:
+        return create_connection_error(error_msg)
+
+    if "auth" in error_str or "token" in error_str or "401" in error_str:
+        return create_auth_error(error_msg)
+
+    # Default to internal error
+    return create_error_response(
+        ErrorCode.INTERNAL_ERROR,
+        error_msg,
+        details="An unexpected error occurred",
+        context=context,
+    )
+
+
+def log_tool_usage(func: Any) -> Any:
+    """
+    Decorator to automatically log MCP tool usage.
+
+    Tracks execution time, success/failure, and response size for all tool calls.
+    """
+
+    @functools.wraps(func)
+    async def wrapper(*args: Any, **kwargs: Any) -> Any:
+        start_time = time.time()
+        tool_name = func.__name__
+        success = True
+        error_message = None
+        response_size = None
+
+        try:
+            result = await func(*args, **kwargs)
+            if isinstance(result, str):
+                response_size = len(result.encode("utf-8"))
+            elif hasattr(result, "__len__"):
+                response_size = len(str(result).encode("utf-8"))
+            return result
+        except Exception as e:
+            success = False
+            error_message = str(e)
+            raise
+        finally:
+            execution_time_ms = (time.time() - start_time) * 1000
+            log_tool_call(
+                tool_name=tool_name,
+                parameters=kwargs,
+                execution_time_ms=execution_time_ms,
+                success=success,
+                error_message=error_message,
+                response_size_bytes=response_size,
+            )
+
+    return wrapper

ha_mcp/tools/registry.py

@@ -0,0 +1,199 @@
+"""
+Tools registry for Smart MCP Server - manages registration of all MCP tools.
+
+This module uses lazy auto-discovery to find and register all tool modules.
+Tool modules are discovered at startup but only imported when first accessed,
+improving server startup time significantly (especially for binary distributions).
+
+Adding a new tools module is simple:
+1. Create tools_*.py file with a register_*_tools(mcp, client, **kwargs) function
+2. The function will be auto-discovered and registered lazily
+
+No changes to this file are needed when adding new tool modules!
+
+Tool filtering:
+Set ENABLED_TOOL_MODULES environment variable to filter which tools are loaded:
+- "all" (default): Load all tools
+- "automation": Load only automation-related tools (automations, scripts, traces, blueprints)
+- Comma-separated list: Load specific modules (e.g., "tools_config_automations,tools_search")
+"""
+
+import logging
+import pkgutil
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Modules that don't follow the tools_*.py naming convention
+# These are handled explicitly for backward compatibility
+EXPLICIT_MODULES = {
+    "backup": "register_backup_tools",
+}
+
+# Preset module groups for common use cases
+MODULE_PRESETS = {
+    "automation": [
+        "tools_config_automations",
+        "tools_config_scripts",
+        "tools_traces",
+        "tools_blueprints",
+        "tools_search",  # Useful for finding entities in automations
+    ],
+}
+
+
+class ToolsRegistry:
+    """Manages registration of all MCP tools for the smart server.
+
+    Implements lazy loading pattern: tool modules are discovered at startup
+    but only imported and registered when the server starts accepting connections.
+    This significantly improves startup time for binary distributions.
+
+    Tool filtering is controlled via ENABLED_TOOL_MODULES environment variable:
+    - "all": Load all tools (default)
+    - "automation": Load automation-related tools only
+    - Comma-separated list: Load specific modules
+    """
+
+    def __init__(self, server: Any, enabled_modules: str = "all") -> None:
+        self.server = server
+        self.client = server.client
+        self.mcp = server.mcp
+        self._enabled_modules = enabled_modules
+        # These are now lazily initialized via server properties
+        self._smart_tools = None
+        self._device_tools = None
+        self._modules_registered = False
+        # Discover modules at init time (fast - no imports)
+        self._discovered_modules = self._discover_tool_modules()
+
+    @property
+    def smart_tools(self) -> Any:
+        """Lazily get smart_tools from server."""
+        if self._smart_tools is None:
+            self._smart_tools = self.server.smart_tools
+        return self._smart_tools
+
+    @property
+    def device_tools(self) -> Any:
+        """Lazily get device_tools from server."""
+        if self._device_tools is None:
+            self._device_tools = self.server.device_tools
+        return self._device_tools
+
+    def _get_enabled_module_list(self) -> set[str] | None:
+        """Parse enabled_modules config into a set of module names.
+
+        Returns None if all modules should be enabled.
+        """
+        if self._enabled_modules.lower() == "all":
+            return None
+
+        # Check for preset names
+        if self._enabled_modules.lower() in MODULE_PRESETS:
+            return set(MODULE_PRESETS[self._enabled_modules.lower()])
+
+        # Parse comma-separated list
+        modules = {m.strip() for m in self._enabled_modules.split(",") if m.strip()}
+        return modules if modules else None
+
+    def _discover_tool_modules(self) -> list[str]:
+        """Discover tool module names without importing them.
+
+        This is a fast operation that only reads file names.
+        Returns list of module names that follow the tools_*.py convention,
+        filtered by ENABLED_TOOL_MODULES configuration.
+        """
+        enabled_set = self._get_enabled_module_list()
+        discovered = []
+        package_path = Path(__file__).parent
+
+        for module_info in pkgutil.iter_modules([str(package_path)]):
+            module_name = module_info.name
+            if module_name.startswith("tools_"):
+                # Filter if enabled_set is specified
+                if enabled_set is None or module_name in enabled_set:
+                    discovered.append(module_name)
+
+        # Add explicit modules (only if enabled or no filter)
+        for module_name in EXPLICIT_MODULES.keys():
+            if enabled_set is None or module_name in enabled_set:
+                discovered.append(module_name)
+
+        if enabled_set is not None:
+            logger.info(
+                f"Tool filtering active: {len(discovered)} modules enabled "
+                f"(filter: {self._enabled_modules})"
+            )
+        else:
+            logger.debug(f"Discovered {len(discovered)} tool modules (not yet imported)")
+
+        return discovered
+
+    def register_all_tools(self) -> None:
+        """Register all tools with the MCP server using lazy auto-discovery.
+
+        Tool modules are imported and registered only when this method is called,
+        which happens after the MCP server is ready to accept connections.
+        """
+        if self._modules_registered:
+            logger.debug("Tools already registered, skipping")
+            return
+
+        import importlib
+
+        # Build kwargs with all available dependencies (lazy access)
+        kwargs = {
+            "smart_tools": self.smart_tools,
+            "device_tools": self.device_tools,
+        }
+
+        registered_count = 0
+
+        # Import and register tools_*.py modules
+        for module_name in self._discovered_modules:
+            # Skip explicit modules - handled separately
+            if module_name in EXPLICIT_MODULES:
+                continue
+
+            try:
+                module = importlib.import_module(f".{module_name}", "ha_mcp.tools")
+
+                # Find the register function (convention: register_*_tools)
+                register_func = None
+                for attr_name in dir(module):
+                    if attr_name.startswith("register_") and attr_name.endswith("_tools"):
+                        register_func = getattr(module, attr_name)
+                        break
+
+                if register_func:
+                    register_func(self.mcp, self.client, **kwargs)
+                    registered_count += 1
+                    logger.debug(f"Registered tools from {module_name}")
+                else:
+                    logger.warning(
+                        f"Module {module_name} has no register_*_tools function"
+                    )
+
+            except Exception as e:
+                logger.error(f"Failed to register tools from {module_name}: {e}")
+                raise
+
+        # Register explicit modules (those not following tools_*.py convention)
+        # Only register if they were included in discovered modules (respects filtering)
+        for module_name, func_name in EXPLICIT_MODULES.items():
+            if module_name not in self._discovered_modules:
+                continue
+            try:
+                module = importlib.import_module(f".{module_name}", "ha_mcp.tools")
+                register_func = getattr(module, func_name)
+                register_func(self.mcp, self.client, **kwargs)
+                registered_count += 1
+                logger.debug(f"Registered tools from {module_name}")
+            except Exception as e:
+                logger.error(f"Failed to register tools from {module_name}: {e}")
+                raise
+
+        self._modules_registered = True
+        logger.info(f"Auto-discovery registered tools from {registered_count} modules")