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

claude_mpm/services/mcp_gateway/__init__.py

@@ -0,0 +1,138 @@
+"""
+MCP Gateway Service Module
+==========================
+
+This module provides the Model Context Protocol (MCP) gateway implementation for Claude MPM.
+It enables integration with MCP-compatible tools and services through a standardized interface.
+
+Part of ISS-0034: Infrastructure Setup - MCP Gateway Project Foundation
+
+The MCP Gateway follows the claude-mpm service-oriented architecture with:
+- Interface-based contracts for all components
+- Dependency injection for service resolution
+- Lazy loading for performance optimization
+- Comprehensive error handling and logging
+
+Structure:
+- core/: Core interfaces and base classes for MCP services
+- server/: MCP server implementation and lifecycle management
+- tools/: Tool registry and tool adapter implementations
+- config/: Configuration management for MCP Gateway
+- registry/: Service discovery and registration
+"""
+
+# Version information
+__version__ = "0.1.0"
+
+# Lazy imports to prevent circular dependencies and improve startup performance
+def __getattr__(name):
+    """Lazy import mechanism for MCP Gateway components."""
+    
+    # Core interfaces and base classes
+    if name == "IMCPServer":
+        from .core.interfaces import IMCPServer
+        return IMCPServer
+    elif name == "IMCPToolRegistry":
+        from .core.interfaces import IMCPToolRegistry
+        return IMCPToolRegistry
+    elif name == "IMCPConfiguration":
+        from .core.interfaces import IMCPConfiguration
+        return IMCPConfiguration
+    elif name == "IMCPToolAdapter":
+        from .core.interfaces import IMCPToolAdapter
+        return IMCPToolAdapter
+    elif name == "BaseMCPService":
+        from .core.base import BaseMCPService
+        return BaseMCPService
+    
+    # Server implementations
+    elif name == "MCPServer":
+        from .server.mcp_server import MCPServer
+        return MCPServer
+    elif name == "StdioHandler":
+        from .server.stdio_handler import StdioHandler
+        return StdioHandler
+    elif name == "AlternativeStdioHandler":
+        from .server.stdio_handler import AlternativeStdioHandler
+        return AlternativeStdioHandler
+    
+    # Tool registry and adapters
+    elif name == "ToolRegistry":
+        from .registry.tool_registry import ToolRegistry
+        return ToolRegistry
+    elif name == "BaseToolAdapter":
+        from .tools.base_adapter import BaseToolAdapter
+        return BaseToolAdapter
+    elif name == "EchoToolAdapter":
+        from .tools.base_adapter import EchoToolAdapter
+        return EchoToolAdapter
+    elif name == "CalculatorToolAdapter":
+        from .tools.base_adapter import CalculatorToolAdapter
+        return CalculatorToolAdapter
+    elif name == "SystemInfoToolAdapter":
+        from .tools.base_adapter import SystemInfoToolAdapter
+        return SystemInfoToolAdapter
+    
+    # Configuration management
+    elif name == "MCPConfiguration":
+        from .config.configuration import MCPConfiguration
+        return MCPConfiguration
+    elif name == "MCPConfigLoader":
+        from .config.config_loader import MCPConfigLoader
+        return MCPConfigLoader
+    
+    # Service registry
+    elif name == "MCPServiceRegistry":
+        from .registry.service_registry import MCPServiceRegistry
+        return MCPServiceRegistry
+    
+    # Exceptions
+    elif name == "MCPException":
+        from .core.exceptions import MCPException
+        return MCPException
+    elif name == "MCPConfigurationError":
+        from .core.exceptions import MCPConfigurationError
+        return MCPConfigurationError
+    elif name == "MCPToolNotFoundError":
+        from .core.exceptions import MCPToolNotFoundError
+        return MCPToolNotFoundError
+    elif name == "MCPServerError":
+        from .core.exceptions import MCPServerError
+        return MCPServerError
+    
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+# Public API exports
+__all__ = [
+    # Core interfaces
+    "IMCPServer",
+    "IMCPToolRegistry",
+    "IMCPConfiguration",
+    "IMCPToolAdapter",
+    "BaseMCPService",
+    
+    # Server implementations
+    "MCPServer",
+    "StdioHandler",
+    "AlternativeStdioHandler",
+    
+    # Tool management
+    "ToolRegistry",
+    "BaseToolAdapter",
+    "EchoToolAdapter",
+    "CalculatorToolAdapter",
+    "SystemInfoToolAdapter",
+    
+    # Configuration
+    "MCPConfiguration",
+    "MCPConfigLoader",
+    
+    # Service registry
+    "MCPServiceRegistry",
+    
+    # Exceptions
+    "MCPException",
+    "MCPConfigurationError",
+    "MCPToolNotFoundError",
+    "MCPServerError",
+]

claude_mpm/services/mcp_gateway/config/__init__.py

@@ -0,0 +1,17 @@
+"""
+MCP Gateway Configuration Module
+=================================
+
+Configuration management for the MCP Gateway service.
+"""
+
+from .configuration import MCPConfiguration
+from .config_loader import MCPConfigLoader
+from .config_schema import MCPConfigSchema, validate_config
+
+__all__ = [
+    "MCPConfiguration",
+    "MCPConfigLoader",
+    "MCPConfigSchema",
+    "validate_config",
+]

claude_mpm/services/mcp_gateway/config/config_loader.py

@@ -0,0 +1,232 @@
+"""
+MCP Gateway Configuration Loader
+================================
+
+Handles loading and discovery of MCP configuration files.
+
+Part of ISS-0034: Infrastructure Setup - MCP Gateway Project Foundation
+"""
+
+import os
+from pathlib import Path
+from typing import Optional, List
+import yaml
+
+from claude_mpm.core.logger import get_logger
+
+
+class MCPConfigLoader:
+    """
+    Configuration loader for MCP Gateway.
+    
+    This class handles discovering and loading configuration files from
+    standard locations, supporting both user and system configurations.
+    
+    WHY: We separate configuration loading from the main configuration
+    service to support multiple configuration sources and provide a clean
+    abstraction for configuration discovery.
+    """
+    
+    # Standard configuration file search paths
+    CONFIG_SEARCH_PATHS = [
+        # User-specific configurations
+        Path("~/.claude/mcp/config.yaml"),
+        Path("~/.claude/mcp_gateway.yaml"),
+        Path("~/.config/claude-mpm/mcp_gateway.yaml"),
+        
+        # Project-specific configurations
+        Path("./mcp_gateway.yaml"),
+        Path("./config/mcp_gateway.yaml"),
+        Path("./.claude/mcp_gateway.yaml"),
+        
+        # System-wide configurations
+        Path("/etc/claude-mpm/mcp_gateway.yaml"),
+    ]
+    
+    def __init__(self):
+        """Initialize configuration loader."""
+        self.logger = get_logger("MCPConfigLoader")
+    
+    def find_config_file(self) -> Optional[Path]:
+        """
+        Find the first available configuration file.
+        
+        Searches through standard locations and returns the first
+        existing configuration file.
+        
+        Returns:
+            Path to configuration file if found, None otherwise
+        """
+        for config_path in self.CONFIG_SEARCH_PATHS:
+            expanded_path = config_path.expanduser()
+            if expanded_path.exists() and expanded_path.is_file():
+                self.logger.info(f"Found configuration file: {expanded_path}")
+                return expanded_path
+        
+        self.logger.debug("No configuration file found in standard locations")
+        return None
+    
+    def load_from_file(self, config_path: Path) -> Optional[dict]:
+        """
+        Load configuration from a specific file.
+        
+        Args:
+            config_path: Path to configuration file
+            
+        Returns:
+            Configuration dictionary if successful, None otherwise
+        """
+        try:
+            expanded_path = config_path.expanduser()
+            
+            if not expanded_path.exists():
+                self.logger.error(f"Configuration file not found: {expanded_path}")
+                return None
+            
+            with open(expanded_path, 'r') as f:
+                config = yaml.safe_load(f)
+            
+            self.logger.info(f"Configuration loaded from {expanded_path}")
+            return config or {}
+            
+        except yaml.YAMLError as e:
+            self.logger.error(f"Failed to parse YAML configuration: {e}")
+            return None
+        except Exception as e:
+            self.logger.error(f"Failed to load configuration: {e}")
+            return None
+    
+    def load_from_env(self) -> dict:
+        """
+        Load configuration from environment variables.
+        
+        Environment variables follow the pattern: MCP_GATEWAY_<SECTION>_<KEY>
+        
+        Returns:
+            Configuration dictionary built from environment variables
+        """
+        config = {}
+        prefix = "MCP_GATEWAY_"
+        
+        for env_key, env_value in os.environ.items():
+            if not env_key.startswith(prefix):
+                continue
+            
+            # Parse environment variable into configuration path
+            config_path = env_key[len(prefix):].lower().split('_')
+            
+            # Build nested configuration structure
+            current = config
+            for part in config_path[:-1]:
+                if part not in current:
+                    current[part] = {}
+                current = current[part]
+            
+            # Set the value
+            key = config_path[-1]
+            try:
+                # Try to parse as JSON for complex types
+                import json
+                current[key] = json.loads(env_value)
+            except:
+                # Fall back to string value
+                current[key] = env_value
+            
+            self.logger.debug(f"Loaded from environment: {env_key}")
+        
+        return config
+    
+    def load(self, config_path: Optional[Path] = None) -> dict:
+        """
+        Load configuration from all sources.
+        
+        Loads configuration in the following priority order:
+        1. Default configuration
+        2. File configuration (if found or specified)
+        3. Environment variable overrides
+        
+        Args:
+            config_path: Optional specific configuration file path
+            
+        Returns:
+            Merged configuration dictionary
+        """
+        from .configuration import MCPConfiguration
+        
+        # Start with defaults
+        config = MCPConfiguration.DEFAULT_CONFIG.copy()
+        
+        # Load from file
+        file_path = config_path or self.find_config_file()
+        if file_path:
+            file_config = self.load_from_file(file_path)
+            if file_config:
+                config = self._merge_configs(config, file_config)
+        
+        # Apply environment overrides
+        env_config = self.load_from_env()
+        if env_config:
+            config = self._merge_configs(config, env_config)
+        
+        return config
+    
+    def _merge_configs(self, base: dict, overlay: dict) -> dict:
+        """
+        Recursively merge two configuration dictionaries.
+        
+        Args:
+            base: Base configuration
+            overlay: Configuration to merge in
+            
+        Returns:
+            Merged configuration
+        """
+        result = base.copy()
+        
+        for key, value in overlay.items():
+            if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+                result[key] = self._merge_configs(result[key], value)
+            else:
+                result[key] = value
+        
+        return result
+    
+    def create_default_config(self, path: Path) -> bool:
+        """
+        Create a default configuration file.
+        
+        Args:
+            path: Path where to create the configuration file
+            
+        Returns:
+            True if file created successfully
+        """
+        from .configuration import MCPConfiguration
+        
+        try:
+            expanded_path = path.expanduser()
+            expanded_path.parent.mkdir(parents=True, exist_ok=True)
+            
+            with open(expanded_path, 'w') as f:
+                yaml.dump(
+                    MCPConfiguration.DEFAULT_CONFIG,
+                    f,
+                    default_flow_style=False,
+                    sort_keys=True
+                )
+            
+            self.logger.info(f"Created default configuration at {expanded_path}")
+            return True
+            
+        except Exception as e:
+            self.logger.error(f"Failed to create default configuration: {e}")
+            return False
+    
+    def list_config_locations(self) -> List[str]:
+        """
+        List all configuration file search locations.
+        
+        Returns:
+            List of configuration file paths (as strings)
+        """
+        return [str(path.expanduser()) for path in self.CONFIG_SEARCH_PATHS]

claude_mpm/services/mcp_gateway/config/config_schema.py

@@ -0,0 +1,234 @@
+"""
+MCP Gateway Configuration Schema
+================================
+
+Defines and validates the configuration schema for MCP Gateway.
+
+Part of ISS-0034: Infrastructure Setup - MCP Gateway Project Foundation
+"""
+
+from typing import Any, Dict, List, Optional
+from dataclasses import dataclass
+
+
+@dataclass
+class MCPConfigSchema:
+    """
+    Configuration schema definition for MCP Gateway.
+    
+    This class defines the structure and validation rules for
+    MCP Gateway configuration.
+    """
+    
+    # Schema version for migration support
+    SCHEMA_VERSION = "1.0.0"
+    
+    # Configuration schema definition
+    SCHEMA = {
+        "mcp": {
+            "type": "object",
+            "required": True,
+            "properties": {
+                "server": {
+                    "type": "object",
+                    "required": True,
+                    "properties": {
+                        "name": {"type": "string", "required": True},
+                        "version": {"type": "string", "required": True},
+                        "description": {"type": "string", "required": False},
+                        "communication": {
+                            "type": "object",
+                            "required": True,
+                            "properties": {
+                                "type": {
+                                    "type": "string",
+                                    "required": True,
+                                    "enum": ["stdio", "websocket", "http"]
+                                },
+                                "timeout": {
+                                    "type": "number",
+                                    "required": False,
+                                    "min": 1,
+                                    "max": 3600
+                                },
+                                "buffer_size": {
+                                    "type": "integer",
+                                    "required": False,
+                                    "min": 1024,
+                                    "max": 1048576
+                                },
+                            }
+                        },
+                        "capabilities": {
+                            "type": "object",
+                            "required": False,
+                            "properties": {
+                                "tools": {"type": "boolean", "required": False},
+                                "resources": {"type": "boolean", "required": False},
+                                "prompts": {"type": "boolean", "required": False},
+                            }
+                        },
+                    }
+                },
+                "tools": {
+                    "type": "object",
+                    "required": False,
+                    "properties": {
+                        "enabled": {"type": "boolean", "required": False},
+                        "auto_discover": {"type": "boolean", "required": False},
+                        "discovery_paths": {
+                            "type": "array",
+                            "required": False,
+                            "items": {"type": "string"}
+                        },
+                        "timeout_default": {
+                            "type": "number",
+                            "required": False,
+                            "min": 1,
+                            "max": 300
+                        },
+                        "max_concurrent": {
+                            "type": "integer",
+                            "required": False,
+                            "min": 1,
+                            "max": 100
+                        },
+                    }
+                },
+                "logging": {
+                    "type": "object",
+                    "required": False,
+                    "properties": {
+                        "level": {
+                            "type": "string",
+                            "required": False,
+                            "enum": ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+                        },
+                        "file": {"type": "string", "required": False},
+                        "max_size": {"type": "string", "required": False},
+                        "max_files": {
+                            "type": "integer",
+                            "required": False,
+                            "min": 1,
+                            "max": 100
+                        },
+                        "format": {
+                            "type": "string",
+                            "required": False,
+                            "enum": ["json", "text"]
+                        },
+                    }
+                },
+                "security": {
+                    "type": "object",
+                    "required": False,
+                    "properties": {
+                        "validate_schemas": {"type": "boolean", "required": False},
+                        "sanitize_inputs": {"type": "boolean", "required": False},
+                        "max_request_size": {
+                            "type": "integer",
+                            "required": False,
+                            "min": 1024,
+                            "max": 104857600  # 100MB max
+                        },
+                        "allowed_tools": {
+                            "type": "array",
+                            "required": False,
+                            "items": {"type": "string"}
+                        },
+                        "blocked_tools": {
+                            "type": "array",
+                            "required": False,
+                            "items": {"type": "string"}
+                        },
+                    }
+                },
+            }
+        }
+    }
+
+
+def validate_config(config: Dict[str, Any], schema: Optional[Dict[str, Any]] = None) -> List[str]:
+    """
+    Validate configuration against schema.
+    
+    Args:
+        config: Configuration dictionary to validate
+        schema: Schema to validate against (uses default if not provided)
+        
+    Returns:
+        List of validation errors (empty if valid)
+    """
+    if schema is None:
+        schema = MCPConfigSchema.SCHEMA
+    
+    errors = []
+    
+    def validate_value(value: Any, spec: Dict[str, Any], path: str) -> None:
+        """Recursively validate a value against its specification."""
+        
+        # Check type
+        expected_type = spec.get("type")
+        if expected_type:
+            if expected_type == "object" and not isinstance(value, dict):
+                errors.append(f"{path}: Expected object, got {type(value).__name__}")
+                return
+            elif expected_type == "array" and not isinstance(value, list):
+                errors.append(f"{path}: Expected array, got {type(value).__name__}")
+                return
+            elif expected_type == "string" and not isinstance(value, str):
+                errors.append(f"{path}: Expected string, got {type(value).__name__}")
+                return
+            elif expected_type == "number" and not isinstance(value, (int, float)):
+                errors.append(f"{path}: Expected number, got {type(value).__name__}")
+                return
+            elif expected_type == "integer" and not isinstance(value, int):
+                errors.append(f"{path}: Expected integer, got {type(value).__name__}")
+                return
+            elif expected_type == "boolean" and not isinstance(value, bool):
+                errors.append(f"{path}: Expected boolean, got {type(value).__name__}")
+                return
+        
+        # Check enum values
+        if "enum" in spec and value not in spec["enum"]:
+            errors.append(f"{path}: Value '{value}' not in allowed values: {spec['enum']}")
+        
+        # Check numeric constraints
+        if isinstance(value, (int, float)):
+            if "min" in spec and value < spec["min"]:
+                errors.append(f"{path}: Value {value} is less than minimum {spec['min']}")
+            if "max" in spec and value > spec["max"]:
+                errors.append(f"{path}: Value {value} is greater than maximum {spec['max']}")
+        
+        # Validate object properties
+        if expected_type == "object" and isinstance(value, dict):
+            properties = spec.get("properties", {})
+            for prop_name, prop_spec in properties.items():
+                prop_path = f"{path}.{prop_name}"
+                
+                if prop_name in value:
+                    validate_value(value[prop_name], prop_spec, prop_path)
+                elif prop_spec.get("required", False):
+                    errors.append(f"{prop_path}: Required field missing")
+        
+        # Validate array items
+        if expected_type == "array" and isinstance(value, list):
+            item_spec = spec.get("items", {})
+            for i, item in enumerate(value):
+                validate_value(item, item_spec, f"{path}[{i}]")
+    
+    # Start validation from root
+    validate_value(config, {"type": "object", "properties": schema}, "config")
+    
+    return errors
+
+
+def generate_config_template() -> Dict[str, Any]:
+    """
+    Generate a configuration template with all possible options.
+    
+    Returns:
+        Configuration template dictionary
+    """
+    from ..config.configuration import MCPConfiguration
+    return MCPConfiguration.DEFAULT_CONFIG