claude-mpm 3.9.9__py3-none-any.whl → 4.0.3__py3-none-any.whl

claude_mpm/services/mcp_gateway/core/__init__.py

@@ -5,42 +5,35 @@ MCP Gateway Core Module
 Core interfaces and base classes for the MCP Gateway service.
 """
 
-from .interfaces import (
-    IMCPServer,
-    IMCPToolRegistry,
-    IMCPConfiguration,
-    IMCPToolAdapter,
-    IMCPLifecycle,
-    IMCPCommunication,
-)
-
-from .base import (
-    BaseMCPService,
-    MCPServiceState,
-)
-
+from .base import BaseMCPService, MCPServiceState
 from .exceptions import (
-    MCPException,
+    MCPCommunicationError,
     MCPConfigurationError,
-    MCPToolNotFoundError,
+    MCPException,
     MCPServerError,
-    MCPCommunicationError,
+    MCPToolNotFoundError,
     MCPValidationError,
 )
+from .interfaces import (
+    IMCPCommunication,
+    IMCPConfiguration,
+    IMCPGateway,
+    IMCPLifecycle,
+    IMCPToolAdapter,
+    IMCPToolRegistry,
+)
 
 __all__ = [
     # Interfaces
-    "IMCPServer",
+    "IMCPGateway",
     "IMCPToolRegistry",
     "IMCPConfiguration",
     "IMCPToolAdapter",
     "IMCPLifecycle",
     "IMCPCommunication",
-    
     # Base classes
     "BaseMCPService",
     "MCPServiceState",
-    
     # Exceptions
     "MCPException",
     "MCPConfigurationError",
@@ -48,4 +41,4 @@ __all__ = [
     "MCPServerError",
     "MCPCommunicationError",
     "MCPValidationError",
-]
+]

claude_mpm/services/mcp_gateway/core/base.py

@@ -7,18 +7,18 @@ Base implementations for MCP Gateway services.
 Part of ISS-0034: Infrastructure Setup - MCP Gateway Project Foundation
 """
 
-from enum import Enum
-from typing import Any, Dict, Optional
 import asyncio
 import logging
-from pathlib import Path
+from enum import Enum
+from typing import Any, Dict, Optional
 
-from claude_mpm.services.core.base import BaseService
 from claude_mpm.core.logger import get_logger
+from claude_mpm.services.core.base import BaseService
 
 
 class MCPServiceState(Enum):
     """MCP service lifecycle states."""
+
     UNINITIALIZED = "uninitialized"
     INITIALIZING = "initializing"
     INITIALIZED = "initialized"
@@ -32,20 +32,24 @@ class MCPServiceState(Enum):
 class BaseMCPService(BaseService):
     """
     Base class for all MCP Gateway services.
-    
+
     Extends the claude-mpm BaseService with MCP-specific functionality
     including state management, health monitoring, and async lifecycle support.
-    
+
     WHY: We extend BaseService to maintain consistency with the claude-mpm
     architecture while adding MCP-specific capabilities. This ensures all
     MCP services integrate seamlessly with the existing service container
     and dependency injection system.
     """
-    
-    def __init__(self, service_name: Optional[str] = None, config: Optional[Dict[str, Any]] = None):
+
+    def __init__(
+        self,
+        service_name: Optional[str] = None,
+        config: Optional[Dict[str, Any]] = None,
+    ):
         """
         Initialize MCP service.
-        
+
         Args:
             service_name: Name of the service for logging
             config: Service-specific configuration
@@ -56,34 +60,37 @@ class BaseMCPService(BaseService):
             "healthy": False,
             "state": self._state.value,
             "last_check": None,
-            "details": {}
+            "details": {},
         }
         self._state_lock = asyncio.Lock()
         self._initialization_task = None
         self._shutdown_task = None
-    
+
     async def initialize(self) -> bool:
         """
         Initialize the MCP service.
-        
+
         This method manages state transitions and ensures thread-safe initialization.
         Subclasses should override _do_initialize() for custom initialization logic.
-        
+
         Returns:
             True if initialization successful, False otherwise
         """
         async with self._state_lock:
-            if self._state not in [MCPServiceState.UNINITIALIZED, MCPServiceState.STOPPED]:
+            if self._state not in [
+                MCPServiceState.UNINITIALIZED,
+                MCPServiceState.STOPPED,
+            ]:
                 self.log_warning(f"Cannot initialize from state {self._state.value}")
                 return False
-            
+
             self._state = MCPServiceState.INITIALIZING
             self.log_info("Initializing MCP service")
-        
+
         try:
             # Call subclass initialization
             success = await self._do_initialize()
-            
+
             async with self._state_lock:
                 if success:
                     self._state = MCPServiceState.INITIALIZED
@@ -96,35 +103,35 @@ class BaseMCPService(BaseService):
                     self._health_status["healthy"] = False
                     self._health_status["state"] = self._state.value
                     self.log_error("MCP service initialization failed")
-                
+
                 return success
-                
+
         except Exception as e:
             async with self._state_lock:
                 self._state = MCPServiceState.ERROR
                 self._health_status["healthy"] = False
                 self._health_status["state"] = self._state.value
                 self._health_status["details"]["error"] = str(e)
-            
+
             self.log_error(f"Exception during initialization: {e}")
             return False
-    
+
     async def _do_initialize(self) -> bool:
         """
         Perform actual initialization logic.
-        
+
         Subclasses should override this method to implement custom initialization.
-        
+
         Returns:
             True if initialization successful
         """
         # Default implementation - subclasses should override
         return True
-    
+
     async def start(self) -> bool:
         """
         Start the MCP service.
-        
+
         Returns:
             True if startup successful
         """
@@ -132,13 +139,13 @@ class BaseMCPService(BaseService):
             if self._state != MCPServiceState.INITIALIZED:
                 self.log_warning(f"Cannot start from state {self._state.value}")
                 return False
-            
+
             self._state = MCPServiceState.STARTING
             self.log_info("Starting MCP service")
-        
+
         try:
             success = await self._do_start()
-            
+
             async with self._state_lock:
                 if success:
                     self._state = MCPServiceState.RUNNING
@@ -150,35 +157,35 @@ class BaseMCPService(BaseService):
                     self._health_status["healthy"] = False
                     self._health_status["state"] = self._state.value
                     self.log_error("MCP service startup failed")
-                
+
                 return success
-                
+
         except Exception as e:
             async with self._state_lock:
                 self._state = MCPServiceState.ERROR
                 self._health_status["healthy"] = False
                 self._health_status["state"] = self._state.value
                 self._health_status["details"]["error"] = str(e)
-            
+
             self.log_error(f"Exception during startup: {e}")
             return False
-    
+
     async def _do_start(self) -> bool:
         """
         Perform actual startup logic.
-        
+
         Subclasses should override this method to implement custom startup.
-        
+
         Returns:
             True if startup successful
         """
         # Default implementation - subclasses should override
         return True
-    
+
     async def shutdown(self) -> None:
         """
         Shutdown the MCP service gracefully.
-        
+
         This method manages state transitions and ensures clean shutdown.
         Subclasses should override _do_shutdown() for custom shutdown logic.
         """
@@ -186,106 +193,110 @@ class BaseMCPService(BaseService):
             if self._state in [MCPServiceState.STOPPED, MCPServiceState.STOPPING]:
                 self.log_warning(f"Already in state {self._state.value}")
                 return
-            
+
             self._state = MCPServiceState.STOPPING
             self.log_info("Shutting down MCP service")
-        
+
         try:
             await self._do_shutdown()
-            
+
             async with self._state_lock:
                 self._state = MCPServiceState.STOPPED
                 self._shutdown = True
                 self._health_status["healthy"] = False
                 self._health_status["state"] = self._state.value
                 self.log_info("MCP service shutdown complete")
-                
+
         except Exception as e:
             async with self._state_lock:
                 self._state = MCPServiceState.ERROR
                 self._health_status["healthy"] = False
                 self._health_status["state"] = self._state.value
                 self._health_status["details"]["error"] = str(e)
-            
+
             self.log_error(f"Exception during shutdown: {e}")
-    
+
     async def _do_shutdown(self) -> None:
         """
         Perform actual shutdown logic.
-        
+
         Subclasses should override this method to implement custom shutdown.
         """
         # Default implementation - subclasses should override
         pass
-    
+
     async def restart(self) -> bool:
         """
         Restart the MCP service.
-        
+
         Returns:
             True if restart successful
         """
         self.log_info("Restarting MCP service")
-        
+
         # Shutdown if running
         if self._state == MCPServiceState.RUNNING:
             await self.shutdown()
-        
+
         # Re-initialize
         if not await self.initialize():
             return False
-        
+
         # Start again
         return await self.start()
-    
+
     def get_state(self) -> str:
         """
         Get current service state.
-        
+
         Returns:
             Service state string
         """
         return self._state.value
-    
+
     def is_healthy(self) -> bool:
         """
         Check if service is healthy.
-        
+
         Returns:
             True if service is healthy
         """
         return self._health_status["healthy"]
-    
+
     def get_health_status(self) -> Dict[str, Any]:
         """
         Get detailed health status.
-        
+
         Returns:
             Health status information
         """
         return self._health_status.copy()
-    
-    def update_health_status(self, healthy: bool, details: Optional[Dict[str, Any]] = None) -> None:
+
+    def update_health_status(
+        self, healthy: bool, details: Optional[Dict[str, Any]] = None
+    ) -> None:
         """
         Update health status.
-        
+
         Args:
             healthy: Whether service is healthy
             details: Additional health details
         """
         from datetime import datetime
-        
+
         self._health_status["healthy"] = healthy
         self._health_status["last_check"] = datetime.now().isoformat()
-        
+
         if details:
             self._health_status["details"].update(details)
-    
+
     # Additional logging methods for MCP-specific events
-    def log_mcp_event(self, event_type: str, data: Optional[Dict[str, Any]] = None) -> None:
+    def log_mcp_event(
+        self, event_type: str, data: Optional[Dict[str, Any]] = None
+    ) -> None:
         """
         Log an MCP-specific event.
-        
+
         Args:
             event_type: Type of MCP event
             data: Event data
@@ -294,11 +305,13 @@ class BaseMCPService(BaseService):
         if data:
             message += f" - {data}"
         self.log_info(message)
-    
-    def log_tool_invocation(self, tool_name: str, success: bool, duration: Optional[float] = None) -> None:
+
+    def log_tool_invocation(
+        self, tool_name: str, success: bool, duration: Optional[float] = None
+    ) -> None:
         """
         Log a tool invocation.
-        
+
         Args:
             tool_name: Name of the tool invoked
             success: Whether invocation was successful
@@ -308,8 +321,8 @@ class BaseMCPService(BaseService):
         message = f"Tool invocation: {tool_name} {status}"
         if duration:
             message += f" ({duration:.3f}s)"
-        
+
         if success:
             self.log_info(message)
         else:
-            self.log_warning(message)
+            self.log_warning(message)

claude_mpm/services/mcp_gateway/core/exceptions.py

@@ -7,22 +7,22 @@ Custom exceptions for MCP Gateway operations.
 Part of ISS-0034: Infrastructure Setup - MCP Gateway Project Foundation
 """
 
-from typing import Optional, Any, Dict
+from typing import Any, Dict, Optional
 
 
 class MCPException(Exception):
     """
     Base exception for all MCP Gateway errors.
-    
+
     WHY: We create a base exception to allow catching all MCP-related
     errors in a single except block while still being able to handle
     specific error types when needed.
     """
-    
+
     def __init__(self, message: str, details: Optional[Dict[str, Any]] = None):
         """
         Initialize MCP exception.
-        
+
         Args:
             message: Error message
             details: Additional error details
@@ -30,7 +30,7 @@ class MCPException(Exception):
         super().__init__(message)
         self.message = message
         self.details = details or {}
-    
+
     def __str__(self) -> str:
         """String representation of the exception."""
         if self.details:
@@ -41,19 +41,23 @@ class MCPException(Exception):
 class MCPConfigurationError(MCPException):
     """
     Raised when MCP configuration is invalid or cannot be loaded.
-    
+
     Common scenarios:
     - Missing required configuration fields
     - Invalid configuration values
     - Configuration file not found
     - YAML parsing errors
     """
-    
-    def __init__(self, message: str, config_key: Optional[str] = None, 
-                 expected_type: Optional[str] = None):
+
+    def __init__(
+        self,
+        message: str,
+        config_key: Optional[str] = None,
+        expected_type: Optional[str] = None,
+    ):
         """
         Initialize configuration error.
-        
+
         Args:
             message: Error message
             config_key: Configuration key that caused the error
@@ -64,54 +68,58 @@ class MCPConfigurationError(MCPException):
             details["config_key"] = config_key
         if expected_type:
             details["expected_type"] = expected_type
-        
+
         super().__init__(message, details)
 
 
 class MCPToolNotFoundError(MCPException):
     """
     Raised when a requested tool is not found in the registry.
-    
+
     This error occurs when:
     - Attempting to invoke a non-existent tool
     - Trying to unregister a tool that isn't registered
     - Searching for a tool that doesn't exist
     """
-    
+
     def __init__(self, tool_name: str, available_tools: Optional[list] = None):
         """
         Initialize tool not found error.
-        
+
         Args:
             tool_name: Name of the tool that wasn't found
             available_tools: List of available tool names for reference
         """
         message = f"Tool '{tool_name}' not found in registry"
         details = {"tool_name": tool_name}
-        
+
         if available_tools:
             details["available_tools"] = available_tools
             message += f". Available tools: {', '.join(available_tools)}"
-        
+
         super().__init__(message, details)
 
 
 class MCPServerError(MCPException):
     """
     Raised when MCP server encounters an error.
-    
+
     Common scenarios:
     - Server initialization failure
     - Port binding issues
     - Server crash during operation
     - Invalid server state transitions
     """
-    
-    def __init__(self, message: str, server_state: Optional[str] = None, 
-                 error_code: Optional[int] = None):
+
+    def __init__(
+        self,
+        message: str,
+        server_state: Optional[str] = None,
+        error_code: Optional[int] = None,
+    ):
         """
         Initialize server error.
-        
+
         Args:
             message: Error message
             server_state: Current server state when error occurred
@@ -122,26 +130,30 @@ class MCPServerError(MCPException):
             details["server_state"] = server_state
         if error_code:
             details["error_code"] = error_code
-        
+
         super().__init__(message, details)
 
 
 class MCPCommunicationError(MCPException):
     """
     Raised when communication with MCP client fails.
-    
+
     This includes:
     - Stdio communication failures
     - Message parsing errors
     - Protocol violations
     - Timeout errors
     """
-    
-    def __init__(self, message: str, direction: Optional[str] = None, 
-                 raw_data: Optional[str] = None):
+
+    def __init__(
+        self,
+        message: str,
+        direction: Optional[str] = None,
+        raw_data: Optional[str] = None,
+    ):
         """
         Initialize communication error.
-        
+
         Args:
             message: Error message
             direction: Direction of communication ("send" or "receive")
@@ -154,26 +166,31 @@ class MCPCommunicationError(MCPException):
             details["raw_data"] = raw_data
         elif raw_data:
             details["raw_data"] = raw_data[:1000] + "... (truncated)"
-        
+
         super().__init__(message, details)
 
 
 class MCPValidationError(MCPException):
     """
     Raised when validation fails.
-    
+
     Used for:
     - Tool parameter validation
     - Schema validation
     - Input validation
     - Response validation
     """
-    
-    def __init__(self, message: str, field: Optional[str] = None, 
-                 expected: Optional[Any] = None, actual: Optional[Any] = None):
+
+    def __init__(
+        self,
+        message: str,
+        field: Optional[str] = None,
+        expected: Optional[Any] = None,
+        actual: Optional[Any] = None,
+    ):
         """
         Initialize validation error.
-        
+
         Args:
             message: Error message
             field: Field that failed validation
@@ -187,47 +204,44 @@ class MCPValidationError(MCPException):
             details["expected"] = str(expected)
         if actual is not None:
             details["actual"] = str(actual)
-        
+
         super().__init__(message, details)
 
 
 class MCPTimeoutError(MCPException):
     """
     Raised when an operation times out.
-    
+
     Common scenarios:
     - Tool invocation timeout
     - Server startup timeout
     - Communication timeout
     """
-    
+
     def __init__(self, operation: str, timeout_seconds: float):
         """
         Initialize timeout error.
-        
+
         Args:
             operation: Operation that timed out
             timeout_seconds: Timeout duration in seconds
         """
         message = f"Operation '{operation}' timed out after {timeout_seconds} seconds"
-        details = {
-            "operation": operation,
-            "timeout_seconds": timeout_seconds
-        }
+        details = {"operation": operation, "timeout_seconds": timeout_seconds}
         super().__init__(message, details)
 
 
 class MCPAuthenticationError(MCPException):
     """
     Raised when authentication fails.
-    
+
     For future use when MCP supports authentication.
     """
-    
+
     def __init__(self, message: str, auth_method: Optional[str] = None):
         """
         Initialize authentication error.
-        
+
         Args:
             message: Error message
             auth_method: Authentication method that failed
@@ -235,5 +249,5 @@ class MCPAuthenticationError(MCPException):
         details = {}
         if auth_method:
             details["auth_method"] = auth_method
-        
-        super().__init__(message, details)
+
+        super().__init__(message, details)