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

ha_mcp/client/websocket_listener.py

@@ -0,0 +1,340 @@
+"""
+Background WebSocket listener for Home Assistant state changes.
+
+This module provides a background service that listens to Home Assistant
+WebSocket events and updates operation status in real-time.
+"""
+
+import asyncio
+import logging
+from datetime import datetime
+from typing import Any
+
+from ..config import get_global_settings
+from ..utils.operation_manager import get_operation_manager, update_pending_operations
+from .websocket_client import HomeAssistantWebSocketClient, get_websocket_client
+
+logger = logging.getLogger(__name__)
+
+
+class WebSocketListenerService:
+    """Background service for listening to Home Assistant WebSocket events."""
+
+    def __init__(self) -> None:
+        """Initialize the WebSocket listener service."""
+        self.settings = get_global_settings()
+        self.operation_manager = get_operation_manager()
+        self.websocket_client: HomeAssistantWebSocketClient | None = None
+        self.listener_task: asyncio.Task | None = None
+        self.cleanup_task: asyncio.Task | None = None
+        self.running = False
+        self._event_loop: asyncio.AbstractEventLoop | None = None
+        self.stats: dict[str, Any] = {
+            "events_processed": 0,
+            "operations_updated": 0,
+            "connection_errors": 0,
+            "last_event_time": None,
+            "start_time": None,
+        }
+
+    async def start(self) -> bool:
+        """Start the WebSocket listener service.
+
+        Returns:
+            True if service started successfully
+        """
+        if self.running:
+            logger.warning("WebSocket listener already running")
+            return True
+
+        try:
+            # Get WebSocket client
+            self.websocket_client = await get_websocket_client()
+
+            # Subscribe to state change events
+            await self.websocket_client.subscribe_events("state_changed")
+
+            # Add event handler
+            self.websocket_client.add_event_handler(
+                "state_changed", self._handle_state_change
+            )
+
+            # Start background tasks
+            self.listener_task = asyncio.create_task(self._connection_monitor())
+            self.cleanup_task = asyncio.create_task(self._periodic_cleanup())
+
+            self.running = True
+            self.stats["start_time"] = datetime.now()
+
+            logger.info("WebSocket listener service started successfully")
+            return True
+
+        except Exception as e:
+            logger.error(f"Failed to start WebSocket listener service: {e}")
+            await self.stop()
+            return False
+
+    async def stop(self) -> None:
+        """Stop the WebSocket listener service."""
+        if not self.running:
+            return
+
+        self.running = False
+
+        # Cancel background tasks
+        if self.listener_task and not self.listener_task.done():
+            self.listener_task.cancel()
+            try:
+                await self.listener_task
+            except asyncio.CancelledError:
+                pass
+
+        if self.cleanup_task and not self.cleanup_task.done():
+            self.cleanup_task.cancel()
+            try:
+                await self.cleanup_task
+            except asyncio.CancelledError:
+                pass
+
+        # Remove event handler if WebSocket client exists
+        if self.websocket_client:
+            self.websocket_client.remove_event_handler(
+                "state_changed", self._handle_state_change
+            )
+
+        logger.info("WebSocket listener service stopped")
+
+    async def _handle_state_change(self, event: dict[str, Any]) -> None:
+        """Handle state change events from Home Assistant.
+
+        Args:
+            event: State change event data
+        """
+        try:
+            events_processed = self.stats["events_processed"]
+            if isinstance(events_processed, int):
+                self.stats["events_processed"] = events_processed + 1
+            self.stats["last_event_time"] = datetime.now()
+
+            # Extract event data
+            entity_id = event.get("entity_id")
+            new_state = event.get("new_state")
+            old_state = event.get("old_state")
+
+            if not entity_id or not new_state:
+                return
+
+            # Log significant state changes for debugging
+            if old_state and old_state.get("state") != new_state.get("state"):
+                logger.debug(
+                    f"State change: {entity_id} {old_state.get('state')} -> {new_state.get('state')}"
+                )
+
+            # Update pending operations
+            updated_ops = update_pending_operations(entity_id, new_state)
+            if updated_ops:
+                operations_updated = self.stats["operations_updated"]
+                if isinstance(operations_updated, int):
+                    self.stats["operations_updated"] = operations_updated + len(updated_ops)
+                logger.info(f"Updated {len(updated_ops)} operations for {entity_id}")
+
+        except Exception as e:
+            logger.error(f"Error handling state change event: {e}")
+
+    async def _connection_monitor(self) -> None:
+        """Monitor WebSocket connection health."""
+        while self.running:
+            try:
+                if self.websocket_client and self.websocket_client.is_connected:
+                    # Ping Home Assistant to check connection
+                    ping_success = await self.websocket_client.ping()
+                    if not ping_success:
+                        logger.warning("WebSocket ping failed")
+                        connection_errors = self.stats["connection_errors"]
+                        if isinstance(connection_errors, int):
+                            self.stats["connection_errors"] = connection_errors + 1
+                else:
+                    logger.warning("WebSocket connection lost")
+                    connection_errors = self.stats["connection_errors"]
+                    if isinstance(connection_errors, int):
+                        self.stats["connection_errors"] = connection_errors + 1
+
+                    # Try to reconnect
+                    try:
+                        self.websocket_client = await get_websocket_client()
+                        await self.websocket_client.subscribe_events("state_changed")
+                        self.websocket_client.add_event_handler(
+                            "state_changed", self._handle_state_change
+                        )
+                        logger.info("WebSocket reconnected successfully")
+                    except Exception as e:
+                        logger.error(f"WebSocket reconnection failed: {e}")
+
+                # Wait before next health check
+                await asyncio.sleep(30)  # Check every 30 seconds
+
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error(f"Connection monitor error: {e}")
+                await asyncio.sleep(30)
+
+    async def _periodic_cleanup(self) -> None:
+        """Periodic cleanup of expired operations."""
+        while self.running:
+            try:
+                # Clean up expired operations every 5 minutes
+                self.operation_manager.cleanup_expired_operations()
+                await asyncio.sleep(300)  # 5 minutes
+
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error(f"Cleanup task error: {e}")
+                await asyncio.sleep(300)
+
+    def get_status(self) -> dict[str, Any]:
+        """Get service status and statistics.
+
+        Returns:
+            Dictionary with service status and statistics
+        """
+        uptime: float | None = None
+        start_time = self.stats["start_time"]
+        if isinstance(start_time, datetime):
+            uptime = (datetime.now() - start_time).total_seconds()
+
+        return {
+            "running": self.running,
+            "websocket_connected": (
+                self.websocket_client.is_connected if self.websocket_client else False
+            ),
+            "uptime_seconds": uptime,
+            "statistics": {
+                **self.stats,
+                "last_event_time": (
+                    self.stats["last_event_time"].isoformat()
+                    if isinstance(self.stats["last_event_time"], datetime)
+                    else None
+                ),
+                "start_time": (
+                    self.stats["start_time"].isoformat()
+                    if isinstance(self.stats["start_time"], datetime)
+                    else None
+                ),
+            },
+            "operation_summary": self.operation_manager.get_operations_summary(),
+        }
+
+    async def force_reconnect(self) -> bool:
+        """Force a WebSocket reconnection.
+
+        Returns:
+            True if reconnection successful
+        """
+        try:
+            if self.websocket_client:
+                self.websocket_client.remove_event_handler(
+                    "state_changed", self._handle_state_change
+                )
+
+            self.websocket_client = await get_websocket_client()
+            await self.websocket_client.subscribe_events("state_changed")
+            self.websocket_client.add_event_handler(
+                "state_changed", self._handle_state_change
+            )
+
+            logger.info("Forced WebSocket reconnection successful")
+            return True
+
+        except Exception as e:
+            logger.error(f"Forced reconnection failed: {e}")
+            connection_errors = self.stats["connection_errors"]
+            if isinstance(connection_errors, int):
+                self.stats["connection_errors"] = connection_errors + 1
+            return False
+
+
+# Global listener service instance
+_listener_service: WebSocketListenerService | None = None
+_listener_lock: asyncio.Lock | None = None
+
+
+async def get_listener_service() -> WebSocketListenerService:
+    """Get the global WebSocket listener service instance."""
+    global _listener_service, _listener_lock
+    import asyncio
+
+    current_loop = asyncio.get_event_loop()
+
+    # Initialize lock if needed (lazy initialization for event loop compatibility)
+    if _listener_lock is None:
+        _listener_lock = asyncio.Lock()
+
+    # Use async lock to prevent race conditions during concurrent access
+    async with _listener_lock:
+        # If event loop changed or service doesn't exist, create new instance
+        if _listener_service is None or (
+            hasattr(_listener_service, "_event_loop")
+            and _listener_service._event_loop != current_loop
+        ):
+            # Stop existing service if it exists
+            if _listener_service is not None:
+                try:
+                    await _listener_service.stop()
+                except Exception as e:
+                    logger.debug(f"Error stopping previous listener service: {e}")
+
+            _listener_service = WebSocketListenerService()
+            _listener_service._event_loop = current_loop
+
+    return _listener_service
+
+
+async def start_websocket_listener() -> bool:
+    """Start the global WebSocket listener service."""
+    service = await get_listener_service()
+    if service.running:
+        logger.debug("WebSocket listener service already running")
+        return True
+    return await service.start()
+
+
+async def stop_websocket_listener() -> None:
+    """Stop the global WebSocket listener service."""
+    global _listener_service
+    if _listener_service:
+        await _listener_service.stop()
+        _listener_service = None
+
+
+async def get_listener_status() -> dict[str, Any]:
+    """Get WebSocket listener service status."""
+    service = await get_listener_service()
+    return service.get_status()
+
+
+class WebSocketContextManager:
+    """Context manager for WebSocket listener lifecycle."""
+
+    def __init__(self) -> None:
+        self.service: WebSocketListenerService | None = None
+
+    async def __aenter__(self) -> WebSocketListenerService:
+        """Start WebSocket listener."""
+        service = await get_listener_service()
+        success = await service.start()
+        if not success:
+            raise Exception("Failed to start WebSocket listener")
+        self.service = service
+        return service
+
+    async def __aexit__(self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: object) -> None:
+        """Stop WebSocket listener."""
+        if self.service:
+            await self.service.stop()
+
+
+def websocket_listener_context() -> WebSocketContextManager:
+    """Create a WebSocket listener context manager."""
+    return WebSocketContextManager()

ha_mcp/config.py

@@ -0,0 +1,175 @@
+"""
+Configuration management for Home Assistant MCP Server.
+"""
+
+import os
+
+# Load environment variables from .env file with HAMCP_ENV_FILE support
+# Use absolute path to ensure .env is found regardless of cwd
+from pathlib import Path
+
+from dotenv import load_dotenv
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+project_root = Path(__file__).parent.parent.parent
+
+# Demo environment token - use HOMEASSISTANT_TOKEN="demo" to connect to the public demo
+# Demo server: https://ha-mcp-demo-server.qc-h.net (login: mcp/mcp, resets weekly)
+DEMO_TOKEN = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiIxOTE5ZTZlMTVkYjI0Mzk2YTQ4YjFiZTI1MDM1YmU2YSIsImlhdCI6MTc1NzI4OTc5NiwiZXhwIjoyMDcyNjQ5Nzk2fQ.Yp9SSAjm2gvl9Xcu96FFxS8SapHxWAVzaI0E3cD9xac"
+
+# Support for different environment files via HAMCP_ENV_FILE
+env_file = os.getenv("HAMCP_ENV_FILE", ".env")
+env_path = project_root / env_file
+
+# Load the specified environment file (silently, since env vars may come from other sources)
+if env_path.exists():
+    load_dotenv(env_path)
+else:
+    # Fallback to default .env
+    default_env_path = project_root / ".env"
+    if default_env_path.exists():
+        load_dotenv(default_env_path)
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment variables."""
+
+    # Home Assistant connection
+    # In OAuth mode, these are optional and provided per-request
+    homeassistant_url: str = Field(default="http://oauth-mode", alias="HOMEASSISTANT_URL")
+    homeassistant_token: str = Field(default="oauth-mode-token", alias="HOMEASSISTANT_TOKEN")
+
+    # Server configuration
+    timeout: int = Field(30, alias="HA_TIMEOUT")
+    max_retries: int = Field(3, alias="HA_MAX_RETRIES")
+
+    # Tool configuration
+    fuzzy_threshold: int = Field(60, alias="FUZZY_THRESHOLD")
+    entity_search_limit: int = Field(20, alias="ENTITY_SEARCH_LIMIT")
+
+    # Backup tool configuration
+    backup_hint: str = Field("normal", alias="BACKUP_HINT")
+
+    # WebSocket configuration (essential for async operations)
+    enable_websocket: bool = Field(True, alias="ENABLE_WEBSOCKET")
+
+    # Development/Debug configuration
+    debug: bool = Field(False, alias="DEBUG")
+    log_level: str = Field("INFO", alias="LOG_LEVEL")
+
+    # MCP Server configuration
+    mcp_server_name: str = Field("ha-mcp", alias="MCP_SERVER_NAME")
+    mcp_server_version: str = Field("0.1.0", alias="MCP_SERVER_VERSION")
+
+    # Environment configuration
+    environment: str = Field("development", alias="ENVIRONMENT")
+
+    # Tool filtering - comma-separated list of module names to enable
+    # Special values: "all" (default), "automation" (automation-related tools only)
+    # Examples: "tools_config_automations,tools_config_scripts,tools_traces"
+    enabled_tool_modules: str = Field("all", alias="ENABLED_TOOL_MODULES")
+
+    # Dashboard partial update tools (jq_transform, find_card)
+    # These are token-efficient alternatives to full config replacement.
+    # Disable when using clients with programmatic tool use (future).
+    enable_dashboard_partial_tools: bool = Field(True, alias="ENABLE_DASHBOARD_PARTIAL_TOOLS")
+
+    @property
+    def env_file_name(self) -> str:
+        """Get the current environment file name."""
+        return os.getenv("HAMCP_ENV_FILE", ".env")
+
+    @field_validator("homeassistant_url")
+    @classmethod
+    def validate_homeassistant_url(cls, v: str) -> str:
+        """Ensure URL is properly formatted."""
+        # Allow OAuth mode placeholder
+        if v == "http://oauth-mode":
+            return v
+        if not v.startswith(("http://", "https://")):
+            raise ValueError("Home Assistant URL must start with http:// or https://")
+        return v.rstrip("/")  # Remove trailing slash
+
+    @field_validator("homeassistant_token")
+    @classmethod
+    def validate_homeassistant_token(cls, v: str) -> str:
+        """Ensure token is not empty. Use 'demo' for public demo environment."""
+        # Allow OAuth mode placeholder
+        if v == "oauth-mode-token":
+            return v
+        if not v or v == "your_long_lived_access_token_here":
+            raise ValueError("Home Assistant token must be provided")
+        # Replace "demo" with actual demo token for easy onboarding
+        if v.lower() == "demo":
+            return DEMO_TOKEN
+        return v
+
+    @field_validator("fuzzy_threshold")
+    @classmethod
+    def validate_fuzzy_threshold(cls, v: int) -> int:
+        """Ensure fuzzy threshold is reasonable."""
+        if not 0 <= v <= 100:
+            raise ValueError("Fuzzy threshold must be between 0 and 100")
+        return v
+
+    @field_validator("log_level")
+    @classmethod
+    def validate_log_level(cls, v: str) -> str:
+        """Ensure log level is valid."""
+        valid_levels = ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+        if v.upper() not in valid_levels:
+            raise ValueError(f"Log level must be one of {valid_levels}")
+        return v.upper()
+
+    @field_validator("backup_hint")
+    @classmethod
+    def validate_backup_hint(cls, v: str) -> str:
+        """Ensure backup hint is valid."""
+        valid_hints = ["strong", "normal", "weak", "auto"]
+        if v.lower() not in valid_hints:
+            raise ValueError(f"Backup hint must be one of {valid_hints}")
+        return v.lower()
+
+    model_config = SettingsConfigDict(
+        env_file=".env", env_file_encoding="utf-8", case_sensitive=False, extra="allow"
+    )
+
+
+def get_settings() -> Settings:
+    """Get application settings."""
+    return Settings()  # type: ignore[call-arg]
+
+
+def validate_settings() -> tuple[bool, str | None]:
+    """
+    Validate settings and return (is_valid, error_message).
+
+    Returns:
+        tuple: (True, None) if valid, (False, error_message) if invalid
+    """
+    try:
+        settings = get_settings()
+
+        # Additional validation
+        if not settings.homeassistant_url:
+            return False, "Home Assistant URL is required"
+
+        if not settings.homeassistant_token:
+            return False, "Home Assistant token is required"
+
+        return True, None
+    except Exception as e:
+        return False, str(e)
+
+
+# Global settings instance
+_settings: Settings | None = None
+
+
+def get_global_settings() -> Settings:
+    """Get global settings instance (singleton pattern)."""
+    global _settings
+    if _settings is None:
+        _settings = get_settings()
+    return _settings