mcp-hangar 0.2.0__py3-none-any.whl

mcp_hangar/server/cli.py

@@ -0,0 +1,161 @@
+"""Command Line Interface for MCP Hangar Server.
+
+This module handles CLI argument parsing and environment variable resolution.
+It is designed to be pure - no side effects, no logging setup, no server startup.
+
+Usage:
+    from mcp_hangar.server.cli import parse_args, CLIConfig
+
+    config = parse_args()
+    # or for testing:
+    config = parse_args(["--http", "--port", "9000"])
+"""
+
+import argparse
+from dataclasses import dataclass
+import os
+from typing import List, Optional
+
+
+@dataclass(frozen=True)
+class CLIConfig:
+    """Parsed CLI configuration.
+
+    This is a frozen dataclass to ensure immutability after parsing.
+    All values are resolved from CLI arguments and environment variables.
+    """
+
+    http_mode: bool
+    """Whether to run in HTTP mode (True) or stdio mode (False)."""
+
+    http_host: str
+    """Host to bind HTTP server to."""
+
+    http_port: int
+    """Port to bind HTTP server to."""
+
+    config_path: Optional[str]
+    """Path to config.yaml file."""
+
+    log_file: Optional[str]
+    """Path to log file for server output."""
+
+    log_level: str
+    """Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)."""
+
+    json_logs: bool
+    """Whether to format logs as JSON."""
+
+
+def parse_args(args: Optional[List[str]] = None) -> CLIConfig:
+    """Parse command line arguments.
+
+    Resolves values in this order (later overrides earlier):
+    1. Default values
+    2. Environment variables
+    3. CLI arguments
+
+    Args:
+        args: Optional argument list (for testing). Uses sys.argv if None.
+
+    Returns:
+        Parsed CLIConfig dataclass with all resolved values.
+
+    Examples:
+        # Default parsing from sys.argv
+        config = parse_args()
+
+        # Testing with specific arguments
+        config = parse_args(["--http", "--port", "9000"])
+        assert config.http_mode is True
+        assert config.http_port == 9000
+    """
+    parser = argparse.ArgumentParser(
+        description="MCP Hangar - Production-grade MCP provider registry",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  mcp-hangar --config config.yaml
+  mcp-hangar --config config.yaml --http --port 8000
+  mcp-hangar --http --host 0.0.0.0 --port 9000
+
+Environment Variables:
+  MCP_MODE          Set to "http" to enable HTTP mode
+  MCP_HTTP_HOST     HTTP server host (default: 0.0.0.0)
+  MCP_HTTP_PORT     HTTP server port (default: 8000)
+  MCP_LOG_LEVEL     Log level (default: INFO)
+  MCP_JSON_LOGS     Set to "true" for JSON formatted logs
+""",
+    )
+
+    parser.add_argument(
+        "--http",
+        action="store_true",
+        help="Run HTTP server mode instead of stdio",
+    )
+    parser.add_argument(
+        "--host",
+        type=str,
+        default=None,
+        help="HTTP server host (default: 0.0.0.0)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=None,
+        help="HTTP server port (default: 8000)",
+    )
+    parser.add_argument(
+        "--config",
+        type=str,
+        default=None,
+        help="Path to config.yaml file",
+    )
+    parser.add_argument(
+        "--log-file",
+        type=str,
+        default=None,
+        help="Path to log file for server output",
+    )
+    parser.add_argument(
+        "--log-level",
+        type=str,
+        default=None,
+        choices=["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
+        help="Log level (default: INFO)",
+    )
+    parser.add_argument(
+        "--json-logs",
+        action="store_true",
+        help="Format logs as JSON",
+    )
+
+    parsed = parser.parse_args(args)
+
+    # Resolve values: defaults -> env -> CLI args
+    # Environment variable defaults
+    env_http_mode = os.getenv("MCP_MODE", "stdio") == "http"
+    env_http_host = os.getenv("MCP_HTTP_HOST", "0.0.0.0")
+    env_http_port = int(os.getenv("MCP_HTTP_PORT", "8000"))
+    env_log_level = os.getenv("MCP_LOG_LEVEL", "INFO").upper()
+    env_json_logs = os.getenv("MCP_JSON_LOGS", "false").lower() == "true"
+
+    # CLI overrides env
+    http_mode = parsed.http or env_http_mode
+    http_host = parsed.host if parsed.host is not None else env_http_host
+    http_port = parsed.port if parsed.port is not None else env_http_port
+    log_level = parsed.log_level if parsed.log_level is not None else env_log_level
+    json_logs = parsed.json_logs or env_json_logs
+
+    return CLIConfig(
+        http_mode=http_mode,
+        http_host=http_host,
+        http_port=http_port,
+        config_path=parsed.config,
+        log_file=parsed.log_file,
+        log_level=log_level,
+        json_logs=json_logs,
+    )
+
+
+__all__ = ["CLIConfig", "parse_args"]

mcp_hangar/server/config.py

@@ -0,0 +1,224 @@
+"""Configuration loading and provider registration.
+
+Uses ApplicationContext for dependency injection (DIP).
+
+Note: This module uses PROVIDERS and GROUPS from state.py for backward
+compatibility. The config is loaded during startup before context is
+fully initialized, so we populate the global collections which are then
+shared with ApplicationContext.
+"""
+
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import yaml
+
+from ..domain.model import LoadBalancerStrategy, Provider, ProviderGroup
+from ..domain.security.input_validator import validate_provider_id
+from ..logging_config import get_logger
+
+# Backward compatibility - config populates these collections
+# which are then shared with ApplicationContext
+from .state import get_group_rebalance_saga, GROUPS, PROVIDERS
+
+logger = get_logger(__name__)
+
+
+def load_config_from_file(config_path: str) -> Dict[str, Any]:
+    """
+    Load configuration from YAML file.
+
+    Args:
+        config_path: Path to YAML configuration file
+
+    Returns:
+        Configuration dictionary
+
+    Raises:
+        FileNotFoundError: If config file doesn't exist
+        yaml.YAMLError: If config file is invalid YAML
+    """
+    path = Path(config_path)
+    if not path.exists():
+        raise FileNotFoundError(f"Configuration file not found: {config_path}")
+
+    with open(path, "r") as f:
+        config = yaml.safe_load(f)
+
+    if not config or "providers" not in config:
+        raise ValueError(f"Invalid configuration: missing 'providers' section in {config_path}")
+
+    return config
+
+
+def load_config(config: Dict[str, Any]) -> None:
+    """
+    Load provider and group configuration.
+
+    Creates Provider aggregates and ProviderGroup aggregates based on mode.
+
+    Args:
+        config: Dictionary mapping provider IDs to provider spec dictionaries
+    """
+    for provider_id, spec_dict in config.items():
+        result = validate_provider_id(provider_id)
+        if not result.valid:
+            logger.warning("skipping_invalid_provider_id", provider_id=provider_id)
+            continue
+
+        mode = spec_dict.get("mode", "subprocess")
+
+        if mode == "group":
+            _load_group_config(provider_id, spec_dict)
+            continue
+
+        _load_provider_config(provider_id, spec_dict)
+
+
+def _parse_strategy(strategy_str: str, group_id: str) -> LoadBalancerStrategy:
+    """Parse load balancer strategy string."""
+    try:
+        return LoadBalancerStrategy(strategy_str)
+    except ValueError:
+        logger.warning(
+            "unknown_strategy_using_default",
+            strategy=strategy_str,
+            group_id=group_id,
+            default="round_robin",
+        )
+        return LoadBalancerStrategy.ROUND_ROBIN
+
+
+def _load_group_members(
+    group: ProviderGroup,
+    group_id: str,
+    members: List[Dict[str, Any]],
+) -> None:
+    """Load group members from configuration."""
+    saga = get_group_rebalance_saga()
+
+    for member_spec in members:
+        member_id = member_spec.get("id")
+        if not member_id:
+            logger.warning("skipping_group_member_without_id", group_id=group_id)
+            continue
+
+        result = validate_provider_id(member_id)
+        if not result.valid:
+            logger.warning("skipping_invalid_member_id", member_id=member_id)
+            continue
+
+        member_provider = _load_provider_config(member_id, member_spec)
+        group.add_member(
+            member_provider,
+            weight=member_spec.get("weight", 1),
+            priority=member_spec.get("priority", 1),
+        )
+
+        if saga:
+            saga.register_member(member_id, group_id)
+
+
+def _load_provider_config(provider_id: str, spec_dict: Dict[str, Any]) -> Provider:
+    """Load a single provider configuration."""
+    user = spec_dict.get("user")
+    if user == "current":
+        user = f"{os.getuid()}:{os.getgid()}"
+
+    tools_config = spec_dict.get("tools")
+    tools = None
+    if tools_config:
+        tools = []
+        for tool_spec in tools_config:
+            tools.append(
+                {
+                    "name": tool_spec.get("name"),
+                    "description": tool_spec.get("description", ""),
+                    "inputSchema": tool_spec.get("inputSchema", tool_spec.get("input_schema", {})),
+                    "outputSchema": tool_spec.get("outputSchema", tool_spec.get("output_schema")),
+                }
+            )
+
+    provider = Provider(
+        provider_id=provider_id,
+        mode=spec_dict.get("mode", "subprocess"),
+        command=spec_dict.get("command"),
+        image=spec_dict.get("image"),
+        endpoint=spec_dict.get("endpoint"),
+        env=spec_dict.get("env", {}),
+        idle_ttl_s=spec_dict.get("idle_ttl_s", 300),
+        health_check_interval_s=spec_dict.get("health_check_interval_s", 60),
+        max_consecutive_failures=spec_dict.get("max_consecutive_failures", 3),
+        volumes=spec_dict.get("volumes", []),
+        build=spec_dict.get("build"),
+        resources=spec_dict.get("resources", {"memory": "512m", "cpu": "1.0"}),
+        network=spec_dict.get("network", "none"),
+        read_only=spec_dict.get("read_only", True),
+        user=user,
+        description=spec_dict.get("description"),
+        tools=tools,
+    )
+    PROVIDERS[provider_id] = provider
+    logger.debug(
+        "provider_loaded",
+        provider_id=provider_id,
+        mode=spec_dict.get("mode", "subprocess"),
+    )
+    return provider
+
+
+def _load_group_config(group_id: str, spec_dict: Dict[str, Any]) -> None:
+    """Load a provider group configuration."""
+    strategy = _parse_strategy(spec_dict.get("strategy", "round_robin"), group_id)
+    health_config = spec_dict.get("health", {})
+    circuit_config = spec_dict.get("circuit_breaker", {})
+
+    group = ProviderGroup(
+        group_id=group_id,
+        strategy=strategy,
+        min_healthy=spec_dict.get("min_healthy", 1),
+        auto_start=spec_dict.get("auto_start", True),
+        unhealthy_threshold=health_config.get("unhealthy_threshold", 2),
+        healthy_threshold=health_config.get("healthy_threshold", 1),
+        circuit_failure_threshold=circuit_config.get("failure_threshold", 10),
+        circuit_reset_timeout_s=circuit_config.get("reset_timeout_s", 60.0),
+        description=spec_dict.get("description"),
+    )
+
+    _load_group_members(group, group_id, spec_dict.get("members", []))
+
+    GROUPS[group_id] = group
+    logger.info(
+        "group_loaded",
+        group_id=group_id,
+        member_count=group.total_count,
+        strategy=strategy.value,
+    )
+
+
+def load_configuration(config_path: Optional[str] = None) -> Dict[str, Any]:
+    """Load provider configuration from file or use defaults.
+
+    Returns:
+        Full configuration dictionary
+    """
+    if config_path is None:
+        config_path = os.getenv("MCP_CONFIG", "config.yaml")
+
+    if Path(config_path).exists():
+        logger.info("loading_config_from_file", config_path=config_path)
+        full_config = load_config_from_file(config_path)
+        load_config(full_config.get("providers", {}))
+        return full_config
+    else:
+        logger.info("config_not_found_using_default", config_path=config_path)
+        default_config = {
+            "math_subprocess": {
+                "mode": "subprocess",
+                "command": ["python", "-m", "examples.provider_math.server"],
+                "idle_ttl_s": 180,
+            },
+        }
+        load_config(default_config)
+        return {"providers": default_config}

mcp_hangar/server/context.py

@@ -0,0 +1,215 @@
+"""Application context for dependency injection.
+
+Provides a clean way to access application services without global state.
+Follows the Dependency Inversion Principle - high-level modules don't depend
+on low-level modules, both depend on abstractions.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional, Protocol, runtime_checkable, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..application.discovery import DiscoveryOrchestrator
+    from ..application.sagas import GroupRebalanceSaga
+    from ..bootstrap.runtime import Runtime
+    from ..domain.model import Provider, ProviderGroup
+    from ..domain.repository import IProviderRepository
+
+
+# =============================================================================
+# Protocol Interfaces (DIP - Dependency Inversion Principle)
+# =============================================================================
+
+
+@runtime_checkable
+class ICommandBus(Protocol):
+    """Interface for command bus."""
+
+    def send(self, command: Any) -> Any:
+        """Send a command and return result."""
+        ...
+
+
+@runtime_checkable
+class IQueryBus(Protocol):
+    """Interface for query bus."""
+
+    def execute(self, query: Any) -> Any:
+        """Execute a query and return result."""
+        ...
+
+
+@runtime_checkable
+class IEventBus(Protocol):
+    """Interface for event bus."""
+
+    def publish(self, event: Any) -> None:
+        """Publish an event."""
+        ...
+
+    def subscribe_to_all(self, handler: Any) -> None:
+        """Subscribe to all events."""
+        ...
+
+
+@runtime_checkable
+class IRateLimitResult(Protocol):
+    """Interface for rate limit check result."""
+
+    @property
+    def allowed(self) -> bool:
+        """Whether the request is allowed."""
+        ...
+
+    @property
+    def limit(self) -> int:
+        """The rate limit."""
+        ...
+
+
+@runtime_checkable
+class IRateLimiter(Protocol):
+    """Interface for rate limiter."""
+
+    def consume(self, key: str) -> IRateLimitResult:
+        """Check rate limit for a key."""
+        ...
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Get rate limiter statistics."""
+        ...
+
+
+@runtime_checkable
+class ISecurityHandler(Protocol):
+    """Interface for security handler."""
+
+    def log_rate_limit_exceeded(self, limit: int, window_seconds: int) -> None:
+        """Log rate limit exceeded event."""
+        ...
+
+    def log_validation_failed(
+        self,
+        field: str,
+        message: str,
+        provider_id: Optional[str] = None,
+        value: Optional[str] = None,
+    ) -> None:
+        """Log validation failure."""
+        ...
+
+    def handle(self, event: Any) -> None:
+        """Handle a security event."""
+        ...
+
+
+@dataclass
+class ApplicationContext:
+    """Dependency injection container for the application.
+
+    Instead of using global variables, components receive this context
+    which contains all dependencies they need. This makes testing easier
+    and dependencies explicit.
+
+    Attributes:
+        runtime: The application runtime with all infrastructure
+        groups: Provider groups for load balancing
+        discovery_orchestrator: Optional discovery service
+        group_rebalance_saga: Optional saga for group rebalancing
+    """
+
+    runtime: "Runtime"
+    groups: Dict[str, "ProviderGroup"] = field(default_factory=dict)
+    discovery_orchestrator: Optional["DiscoveryOrchestrator"] = None
+    group_rebalance_saga: Optional["GroupRebalanceSaga"] = None
+
+    @property
+    def repository(self) -> "IProviderRepository":
+        """Get the provider repository."""
+        return self.runtime.repository
+
+    @property
+    def command_bus(self) -> ICommandBus:
+        """Get the command bus."""
+        return self.runtime.command_bus
+
+    @property
+    def query_bus(self) -> IQueryBus:
+        """Get the query bus."""
+        return self.runtime.query_bus
+
+    @property
+    def event_bus(self) -> IEventBus:
+        """Get the event bus."""
+        return self.runtime.event_bus
+
+    @property
+    def rate_limiter(self) -> IRateLimiter:
+        """Get the rate limiter."""
+        return self.runtime.rate_limiter
+
+    @property
+    def security_handler(self) -> ISecurityHandler:
+        """Get the security handler."""
+        return self.runtime.security_handler
+
+    def get_provider(self, provider_id: str) -> Optional["Provider"]:
+        """Get a provider by ID."""
+        return self.runtime.repository.get(provider_id)
+
+    def provider_exists(self, provider_id: str) -> bool:
+        """Check if a provider exists."""
+        return self.runtime.repository.exists(provider_id)
+
+    def get_group(self, group_id: str) -> Optional["ProviderGroup"]:
+        """Get a group by ID."""
+        return self.groups.get(group_id)
+
+    def group_exists(self, group_id: str) -> bool:
+        """Check if a group exists."""
+        return group_id in self.groups
+
+
+# Singleton context - initialized lazily or explicitly
+_context: Optional[ApplicationContext] = None
+
+
+def get_context() -> ApplicationContext:
+    """Get the application context.
+
+    If context is not initialized, it will be lazily initialized
+    with the default runtime. This supports both:
+    - Explicit initialization via init_context() for full control
+    - Lazy initialization for backward compatibility with tests
+
+    Returns:
+        ApplicationContext instance
+    """
+    global _context
+    if _context is None:
+        # Lazy initialization with default runtime
+        from ..bootstrap.runtime import create_runtime
+
+        runtime = create_runtime()
+        _context = ApplicationContext(runtime=runtime)
+    return _context
+
+
+def init_context(runtime: "Runtime") -> ApplicationContext:
+    """Initialize the application context.
+
+    Args:
+        runtime: The application runtime
+
+    Returns:
+        Initialized ApplicationContext
+    """
+    global _context
+    _context = ApplicationContext(runtime=runtime)
+    return _context
+
+
+def reset_context() -> None:
+    """Reset context (for testing)."""
+    global _context
+    _context = None