claude-mpm 4.0.17__py3-none-any.whl → 4.0.20__py3-none-any.whl

claude_mpm/services/mcp_gateway/core/singleton_manager.py

@@ -0,0 +1,312 @@
+"""
+MCP Gateway Singleton Manager
+============================
+
+Provides singleton management for MCP Gateway instances to ensure only one
+gateway is running per claude-mpm installation.
+
+WHY: MCP gateways are stdio-based protocol handlers that should have only one
+instance per installation to avoid conflicts and resource contention.
+
+DESIGN DECISIONS:
+- File-based locking for cross-process coordination
+- PID tracking for instance validation
+- Automatic cleanup on process termination
+- Thread-safe singleton pattern
+"""
+
+import asyncio
+import fcntl
+import json
+import os
+import signal
+import threading
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from claude_mpm.config.paths import paths
+from claude_mpm.core.logger import get_logger
+
+
+class MCPGatewayManager:
+    """
+    Singleton manager for MCP Gateway instances.
+    
+    Ensures only one gateway instance is running per installation using
+    file-based locking and PID tracking.
+    """
+    
+    _instance: Optional['MCPGatewayManager'] = None
+    _lock = threading.Lock()
+    
+    def __new__(cls):
+        """Singleton pattern implementation."""
+        with cls._lock:
+            if cls._instance is None:
+                cls._instance = super().__new__(cls)
+                cls._instance._initialized = False
+            return cls._instance
+    
+    def __init__(self):
+        """Initialize the gateway manager."""
+        if self._initialized:
+            return
+            
+        self.logger = get_logger("MCPGatewayManager")
+        self._initialized = True
+        
+        # Paths for coordination
+        self.mcp_dir = paths.claude_mpm_dir_hidden / "mcp"
+        self.lock_file = self.mcp_dir / "gateway.lock"
+        self.instance_file = self.mcp_dir / "gateway.json"
+        
+        # Ensure directory exists
+        self.mcp_dir.mkdir(parents=True, exist_ok=True)
+        
+        # Lock file handle
+        self._lock_fd: Optional[int] = None
+        self._current_instance: Optional[Dict[str, Any]] = None
+        
+        # Setup cleanup handlers
+        self._setup_cleanup_handlers()
+    
+    def _setup_cleanup_handlers(self):
+        """Setup signal handlers for cleanup on termination."""
+        def cleanup_handler(signum, frame):
+            self.logger.info(f"Received signal {signum}, cleaning up gateway")
+            self.cleanup()
+            
+        signal.signal(signal.SIGTERM, cleanup_handler)
+        signal.signal(signal.SIGINT, cleanup_handler)
+    
+    def acquire_lock(self) -> bool:
+        """
+        Acquire exclusive lock for gateway instance.
+        
+        Returns:
+            True if lock acquired successfully, False otherwise
+        """
+        try:
+            # Open lock file
+            self._lock_fd = os.open(self.lock_file, os.O_CREAT | os.O_WRONLY | os.O_TRUNC)
+            
+            # Try to acquire exclusive lock (non-blocking)
+            fcntl.flock(self._lock_fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            
+            # Write current PID to lock file
+            os.write(self._lock_fd, str(os.getpid()).encode())
+            os.fsync(self._lock_fd)
+            
+            self.logger.info(f"Acquired gateway lock (PID: {os.getpid()})")
+            return True
+            
+        except (OSError, IOError) as e:
+            if self._lock_fd:
+                try:
+                    os.close(self._lock_fd)
+                except:
+                    pass
+                self._lock_fd = None
+            
+            self.logger.debug(f"Failed to acquire gateway lock: {e}")
+            return False
+    
+    def release_lock(self):
+        """Release the gateway lock."""
+        if self._lock_fd:
+            try:
+                fcntl.flock(self._lock_fd, fcntl.LOCK_UN)
+                os.close(self._lock_fd)
+                self._lock_fd = None
+                
+                # Remove lock file
+                if self.lock_file.exists():
+                    self.lock_file.unlink()
+                    
+                self.logger.info("Released gateway lock")
+            except Exception as e:
+                self.logger.warning(f"Error releasing lock: {e}")
+    
+    def is_gateway_running(self) -> bool:
+        """
+        Check if a gateway instance is currently running.
+        
+        Returns:
+            True if gateway is running, False otherwise
+        """
+        instance_info = self.get_running_instance_info()
+        return instance_info is not None
+    
+    def get_running_instance_info(self) -> Optional[Dict[str, Any]]:
+        """
+        Get information about the currently running gateway instance.
+        
+        Returns:
+            Instance information dict or None if no instance running
+        """
+        if not self.instance_file.exists():
+            return None
+            
+        try:
+            with open(self.instance_file, 'r') as f:
+                instance_info = json.load(f)
+            
+            # Validate PID is still running
+            pid = instance_info.get('pid')
+            if pid and self._is_pid_running(pid):
+                return instance_info
+            else:
+                # Stale instance file, remove it
+                self.instance_file.unlink()
+                return None
+                
+        except (json.JSONDecodeError, OSError) as e:
+            self.logger.warning(f"Error reading instance file: {e}")
+            return None
+    
+    def _is_pid_running(self, pid: int) -> bool:
+        """Check if a PID is currently running."""
+        try:
+            os.kill(pid, 0)  # Signal 0 just checks if process exists
+            return True
+        except (OSError, ProcessLookupError):
+            return False
+    
+    def register_instance(self, gateway_name: str, version: str) -> bool:
+        """
+        Register a new gateway instance.
+        
+        Args:
+            gateway_name: Name of the gateway
+            version: Gateway version
+            
+        Returns:
+            True if registration successful, False otherwise
+        """
+        if not self.acquire_lock():
+            return False
+            
+        try:
+            instance_info = {
+                'pid': os.getpid(),
+                'gateway_name': gateway_name,
+                'version': version,
+                'started_at': time.time(),
+                'lock_file': str(self.lock_file),
+            }
+            
+            with open(self.instance_file, 'w') as f:
+                json.dump(instance_info, f, indent=2)
+            
+            self._current_instance = instance_info
+            self.logger.info(f"Registered gateway instance: {gateway_name} v{version}")
+            return True
+            
+        except Exception as e:
+            self.logger.error(f"Failed to register instance: {e}")
+            self.release_lock()
+            return False
+    
+    def cleanup(self):
+        """Clean up gateway instance and release resources."""
+        try:
+            # Remove instance file
+            if self.instance_file.exists():
+                self.instance_file.unlink()
+                
+            # Release lock
+            self.release_lock()
+            
+            self._current_instance = None
+            self.logger.info("Gateway cleanup completed")
+            
+        except Exception as e:
+            self.logger.warning(f"Error during cleanup: {e}")
+
+
+# Global functions for easy access
+_manager: Optional[MCPGatewayManager] = None
+
+
+def get_gateway_manager() -> MCPGatewayManager:
+    """Get the global gateway manager instance."""
+    global _manager
+    if _manager is None:
+        _manager = MCPGatewayManager()
+    return _manager
+
+
+def is_gateway_running() -> bool:
+    """Check if a gateway instance is currently running."""
+    return get_gateway_manager().is_gateway_running()
+
+
+def get_gateway_status() -> Optional[Dict[str, Any]]:
+    """Get status of running gateway instance."""
+    return get_gateway_manager().get_running_instance_info()
+
+
+async def start_global_gateway(gateway_name: str = "claude-mpm-mcp", version: str = "1.0.0") -> bool:
+    """
+    Start the global MCP gateway instance.
+
+    Args:
+        gateway_name: Name for the gateway
+        version: Gateway version
+
+    Returns:
+        True if started successfully, False otherwise
+    """
+    manager = get_gateway_manager()
+
+    # Check if already running
+    if manager.is_gateway_running():
+        instance_info = manager.get_running_instance_info()
+        manager.logger.info(f"Gateway already running (PID: {instance_info.get('pid')})")
+        return True
+
+    # Register new instance
+    if not manager.register_instance(gateway_name, version):
+        manager.logger.error("Failed to register gateway instance")
+        return False
+
+    # Import and start the gateway
+    try:
+        from ..main import MCPGatewayOrchestrator
+
+        orchestrator = MCPGatewayOrchestrator()
+
+        if not await orchestrator.initialize():
+            manager.logger.error("Failed to initialize gateway")
+            manager.cleanup()
+            return False
+
+        if not await orchestrator.start():
+            manager.logger.error("Failed to start gateway")
+            manager.cleanup()
+            return False
+
+        manager.logger.info("Global gateway started successfully")
+        return True
+
+    except Exception as e:
+        manager.logger.error(f"Error starting gateway: {e}")
+        manager.cleanup()
+        return False
+
+
+async def run_global_gateway():
+    """Run the global MCP gateway until shutdown."""
+    manager = get_gateway_manager()
+
+    try:
+        from ..main import MCPGatewayOrchestrator
+
+        orchestrator = MCPGatewayOrchestrator()
+        await orchestrator.run()
+
+    except Exception as e:
+        manager.logger.error(f"Error running gateway: {e}")
+    finally:
+        manager.cleanup()

claude_mpm/services/mcp_gateway/core/startup_verification.py

@@ -0,0 +1,315 @@
+"""
+MCP Gateway Startup Verification
+================================
+
+Provides startup verification and installation for MCP Gateway configuration.
+Ensures the gateway is properly configured with essential tools on startup.
+
+WHY: The MCP gateway should be automatically configured and verified on startup
+to provide a seamless experience with diagnostic tools, file summarizer, and
+ticket service.
+
+DESIGN DECISIONS:
+- Automatic configuration detection and installation
+- Essential tools verification (diagnostics, file summarizer, ticket service)
+- Graceful fallback when tools are unavailable
+- Non-blocking startup (warnings instead of failures)
+"""
+
+import asyncio
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from claude_mpm.config.paths import paths
+from claude_mpm.core.logger import get_logger
+
+from .singleton_manager import get_gateway_manager, is_gateway_running
+
+
+class MCPGatewayStartupVerifier:
+    """
+    Verifies and configures MCP Gateway on startup.
+    
+    Ensures the gateway is properly configured with essential tools and
+    provides diagnostic information about the gateway state.
+    """
+    
+    def __init__(self):
+        """Initialize the startup verifier."""
+        self.logger = get_logger("MCPGatewayStartupVerifier")
+        self.config_dir = paths.claude_mpm_dir_hidden / "mcp"
+        self.config_file = self.config_dir / "gateway_config.json"
+        
+        # Essential tools that should be available
+        self.essential_tools = [
+            "echo",  # Basic diagnostic tool
+            "calculator",  # Math operations
+            "system_info",  # System diagnostics
+            "health_check",  # Health diagnostics
+            "document_summarizer",  # File summarizer
+            "ticket",  # Ticket service (unified)
+        ]
+    
+    async def verify_and_configure(self) -> Dict[str, Any]:
+        """
+        Verify MCP gateway configuration and configure if needed.
+        
+        Returns:
+            Dictionary with verification results and status
+        """
+        self.logger.info("Starting MCP Gateway verification")
+        
+        results = {
+            "gateway_configured": False,
+            "singleton_manager": False,
+            "essential_tools": {},
+            "configuration_created": False,
+            "warnings": [],
+            "errors": [],
+        }
+        
+        try:
+            # 1. Verify singleton manager
+            results["singleton_manager"] = self._verify_singleton_manager()
+            
+            # 2. Ensure configuration directory exists
+            self._ensure_config_directory()
+            
+            # 3. Verify or create gateway configuration
+            config_created = await self._verify_gateway_configuration()
+            results["configuration_created"] = config_created
+            
+            # 4. Verify essential tools
+            tools_status = await self._verify_essential_tools()
+            results["essential_tools"] = tools_status
+            
+            # 5. Check overall gateway status
+            results["gateway_configured"] = self._assess_gateway_status(results)
+            
+            # Log summary
+            self._log_verification_summary(results)
+            
+            return results
+            
+        except Exception as e:
+            self.logger.error(f"Error during MCP Gateway verification: {e}")
+            results["errors"].append(f"Verification failed: {e}")
+            return results
+    
+    def _verify_singleton_manager(self) -> bool:
+        """Verify singleton manager is working."""
+        try:
+            manager = get_gateway_manager()
+            # Test basic functionality
+            running = is_gateway_running()
+            self.logger.debug(f"Singleton manager operational, gateway running: {running}")
+            return True
+        except Exception as e:
+            self.logger.warning(f"Singleton manager issue: {e}")
+            return False
+    
+    def _ensure_config_directory(self):
+        """Ensure MCP configuration directory exists."""
+        self.config_dir.mkdir(parents=True, exist_ok=True)
+        self.logger.debug(f"MCP config directory: {self.config_dir}")
+    
+    async def _verify_gateway_configuration(self) -> bool:
+        """Verify or create gateway configuration."""
+        if self.config_file.exists():
+            self.logger.debug("Gateway configuration file exists")
+            return False
+        
+        # Create default configuration
+        default_config = self._create_default_configuration()
+        
+        try:
+            import json
+            with open(self.config_file, 'w') as f:
+                json.dump(default_config, f, indent=2)
+            
+            self.logger.info(f"Created default gateway configuration: {self.config_file}")
+            return True
+            
+        except Exception as e:
+            self.logger.warning(f"Failed to create configuration: {e}")
+            return False
+    
+    def _create_default_configuration(self) -> Dict[str, Any]:
+        """Create default MCP gateway configuration."""
+        return {
+            "mcp": {
+                "server": {
+                    "name": "claude-mpm-mcp-gateway",
+                    "version": "1.0.0",
+                    "description": "Claude MPM MCP Gateway with essential tools"
+                },
+                "tools": {
+                    "enabled": True,
+                    "auto_discover": True,
+                    "timeout_default": 30,
+                    "max_concurrent": 10,
+                    "essential_tools": self.essential_tools
+                },
+                "logging": {
+                    "level": "INFO",
+                    "file": str(paths.logs_dir / "mcp_gateway.log")
+                },
+                "security": {
+                    "validate_schemas": True,
+                    "sanitize_inputs": True
+                }
+            }
+        }
+    
+    async def _verify_essential_tools(self) -> Dict[str, Dict[str, Any]]:
+        """Verify essential tools are available."""
+        tools_status = {}
+        
+        for tool_name in self.essential_tools:
+            status = await self._verify_tool(tool_name)
+            tools_status[tool_name] = status
+        
+        return tools_status
+    
+    async def _verify_tool(self, tool_name: str) -> Dict[str, Any]:
+        """Verify a specific tool is available."""
+        status = {
+            "available": False,
+            "initialized": False,
+            "error": None,
+        }
+        
+        try:
+            # Try to import and initialize the tool
+            tool_instance = await self._create_tool_instance(tool_name)
+            
+            if tool_instance:
+                status["available"] = True
+                
+                # Try to initialize
+                if hasattr(tool_instance, 'initialize'):
+                    initialized = await tool_instance.initialize()
+                    status["initialized"] = initialized
+                else:
+                    status["initialized"] = True
+                    
+        except Exception as e:
+            status["error"] = str(e)
+            self.logger.debug(f"Tool {tool_name} verification failed: {e}")
+        
+        return status
+    
+    async def _create_tool_instance(self, tool_name: str):
+        """Create an instance of the specified tool."""
+        tool_map = {
+            "echo": ("..tools.base_adapter", "EchoToolAdapter"),
+            "calculator": ("..tools.base_adapter", "CalculatorToolAdapter"),
+            "system_info": ("..tools.base_adapter", "SystemInfoToolAdapter"),
+            "health_check": ("..tools.health_check_tool", "HealthCheckTool"),
+            "document_summarizer": ("..tools.document_summarizer", "DocumentSummarizerTool"),
+            "ticket": ("..tools.unified_ticket_tool", "UnifiedTicketTool"),
+        }
+        
+        if tool_name not in tool_map:
+            return None
+        
+        module_path, class_name = tool_map[tool_name]
+        
+        try:
+            # Dynamic import
+            from importlib import import_module
+            module = import_module(module_path, package=__package__)
+            tool_class = getattr(module, class_name)
+            return tool_class()
+        except (ImportError, AttributeError) as e:
+            self.logger.debug(f"Could not import {tool_name}: {e}")
+            return None
+    
+    def _assess_gateway_status(self, results: Dict[str, Any]) -> bool:
+        """Assess overall gateway configuration status."""
+        # Gateway is considered configured if:
+        # 1. Singleton manager works
+        # 2. At least basic tools are available
+        # 3. No critical errors
+        
+        if not results["singleton_manager"]:
+            return False
+        
+        if results["errors"]:
+            return False
+        
+        # Check if at least basic diagnostic tools are available
+        essential_available = 0
+        for tool_name, status in results["essential_tools"].items():
+            if status.get("available", False):
+                essential_available += 1
+        
+        # Consider configured if at least 3 essential tools are available
+        return essential_available >= 3
+    
+    def _log_verification_summary(self, results: Dict[str, Any]):
+        """Log verification summary."""
+        if results["gateway_configured"]:
+            self.logger.info("✅ MCP Gateway verification completed successfully")
+        else:
+            self.logger.warning("⚠️ MCP Gateway verification completed with issues")
+        
+        # Log tool status
+        available_tools = []
+        unavailable_tools = []
+        
+        for tool_name, status in results["essential_tools"].items():
+            if status.get("available", False):
+                available_tools.append(tool_name)
+            else:
+                unavailable_tools.append(tool_name)
+        
+        if available_tools:
+            self.logger.info(f"Available tools: {', '.join(available_tools)}")
+        
+        if unavailable_tools:
+            self.logger.warning(f"Unavailable tools: {', '.join(unavailable_tools)}")
+        
+        # Log warnings and errors
+        for warning in results.get("warnings", []):
+            self.logger.warning(warning)
+        
+        for error in results.get("errors", []):
+            self.logger.error(error)
+
+
+# Global verification function
+async def verify_mcp_gateway_on_startup() -> Dict[str, Any]:
+    """
+    Verify MCP Gateway configuration on startup.
+    
+    This function should be called during application startup to ensure
+    the MCP gateway is properly configured.
+    
+    Returns:
+        Dictionary with verification results
+    """
+    verifier = MCPGatewayStartupVerifier()
+    return await verifier.verify_and_configure()
+
+
+def is_mcp_gateway_configured() -> bool:
+    """
+    Quick check if MCP gateway appears to be configured.
+    
+    Returns:
+        True if gateway appears configured, False otherwise
+    """
+    try:
+        # Check if singleton manager works
+        manager = get_gateway_manager()
+        
+        # Check if config directory exists
+        config_dir = paths.claude_mpm_dir_hidden / "mcp"
+        if not config_dir.exists():
+            return False
+        
+        return True
+        
+    except Exception:
+        return False

claude_mpm/services/mcp_gateway/main.py

@@ -256,6 +256,13 @@ class MCPGatewayOrchestrator:
         except Exception as e:
             self.logger.warning(f"Could not load basic tools: {e}")
 
+        # Optional: Health check tool
+        try:
+            from .tools.health_check_tool import HealthCheckTool
+            tools.append(HealthCheckTool())
+        except Exception as e:
+            self.logger.warning(f"Could not load health check tool: {e}")
+
         # Optional: Document summarizer
         if DocumentSummarizerTool is not None:
             try: