mcp-hangar 0.2.0__py3-none-any.whl

mcp_hangar/__init__.py

@@ -0,0 +1,139 @@
+"""MCP Registry - Hot-load provider management.
+
+This package provides a production-grade registry for managing MCP (Model Context Protocol)
+providers with hot-loading, health monitoring, and automatic garbage collection.
+
+New code should use:
+- Provider aggregate from mcp_hangar.domain.model
+- Domain exceptions from mcp_hangar.domain.exceptions
+- Value objects from mcp_hangar.domain.value_objects
+
+Legacy imports are maintained for backward compatibility.
+"""
+
+# Domain layer - preferred imports for new code
+from .domain.exceptions import (
+    CannotStartProviderError,
+    ClientError,
+    ClientNotConnectedError,
+    ClientTimeoutError,
+    ConfigurationError,
+    InvalidStateTransitionError,
+    MCPError,
+    ProviderDegradedError,
+    ProviderError,
+    ProviderNotFoundError,
+    ProviderNotReadyError,
+    ProviderStartError,
+    RateLimitExceeded,
+    ToolError,
+    ToolInvocationError,
+    ToolNotFoundError,
+    ToolTimeoutError,
+    ValidationError,
+)
+from .domain.model import Provider
+from .domain.value_objects import (
+    CorrelationId,
+    HealthStatus,
+    ProviderConfig,
+    ProviderId,
+    ProviderMode,
+    ProviderState,
+    ToolArguments,
+    ToolName,
+)
+
+# UX Improvements - Rich errors, retry, progress
+from .errors import (
+    ConfigurationError as HangarConfigurationError,
+    HangarError,
+    is_retryable,
+    map_exception_to_hangar_error,
+    NetworkError,
+    ProviderCrashError,
+    ProviderDegradedError as HangarProviderDegradedError,
+    ProviderNotFoundError as HangarProviderNotFoundError,
+    ProviderProtocolError,
+    RateLimitError,
+    TimeoutError as HangarTimeoutError,
+    ToolNotFoundError as HangarToolNotFoundError,
+    TransientError,
+)
+
+# Legacy imports - for backward compatibility (re-exports from domain)
+from .models import ToolSchema
+from .progress import (
+    create_progress_tracker,
+    get_stage_message,
+    ProgressCallback,
+    ProgressEvent,
+    ProgressStage,
+    ProgressTracker,
+)
+from .retry import BackoffStrategy, get_retry_policy, get_retry_store, RetryPolicy, RetryResult, with_retry
+from .stdio_client import StdioClient
+
+__all__ = [
+    # Domain - Provider aggregate (preferred)
+    "Provider",
+    # Domain - Value Objects
+    "ProviderId",
+    "ToolName",
+    "CorrelationId",
+    "ProviderState",
+    "ProviderMode",
+    "HealthStatus",
+    "ProviderConfig",
+    "ToolArguments",
+    # Domain - Exceptions
+    "MCPError",
+    "ProviderError",
+    "ProviderNotFoundError",
+    "ProviderStartError",
+    "ProviderDegradedError",
+    "CannotStartProviderError",
+    "ProviderNotReadyError",
+    "InvalidStateTransitionError",
+    "ToolError",
+    "ToolNotFoundError",
+    "ToolInvocationError",
+    "ToolTimeoutError",
+    "ClientError",
+    "ClientNotConnectedError",
+    "ClientTimeoutError",
+    "ValidationError",
+    "ConfigurationError",
+    "RateLimitExceeded",
+    # UX - Rich Errors
+    "HangarError",
+    "TransientError",
+    "ProviderProtocolError",
+    "ProviderCrashError",
+    "NetworkError",
+    "HangarConfigurationError",
+    "HangarProviderNotFoundError",
+    "HangarToolNotFoundError",
+    "HangarTimeoutError",
+    "RateLimitError",
+    "HangarProviderDegradedError",
+    "map_exception_to_hangar_error",
+    "is_retryable",
+    # UX - Retry
+    "RetryPolicy",
+    "BackoffStrategy",
+    "RetryResult",
+    "get_retry_policy",
+    "get_retry_store",
+    "with_retry",
+    # UX - Progress
+    "ProgressStage",
+    "ProgressEvent",
+    "ProgressTracker",
+    "ProgressCallback",
+    "create_progress_tracker",
+    "get_stage_message",
+    # Legacy - for backward compatibility
+    "ToolSchema",
+    "StdioClient",
+]

mcp_hangar/application/__init__.py

@@ -0,0 +1 @@
+"""Application layer - Use cases and event handlers."""

mcp_hangar/application/commands/__init__.py

@@ -0,0 +1,67 @@
+"""Command handlers for CQRS."""
+
+from .auth_commands import (
+    AssignRoleCommand,
+    CreateApiKeyCommand,
+    CreateCustomRoleCommand,
+    ListApiKeysCommand,
+    RevokeApiKeyCommand,
+    RevokeRoleCommand,
+)
+from .auth_handlers import (
+    AssignRoleHandler,
+    CreateApiKeyHandler,
+    CreateCustomRoleHandler,
+    ListApiKeysHandler,
+    register_auth_command_handlers,
+    RevokeApiKeyHandler,
+    RevokeRoleHandler,
+)
+from .commands import (
+    Command,
+    HealthCheckCommand,
+    InvokeToolCommand,
+    ShutdownIdleProvidersCommand,
+    StartProviderCommand,
+    StopProviderCommand,
+)
+from .handlers import (
+    HealthCheckHandler,
+    InvokeToolHandler,
+    register_all_handlers,
+    ShutdownIdleProvidersHandler,
+    StartProviderHandler,
+    StopProviderHandler,
+)
+
+__all__ = [
+    # Commands
+    "Command",
+    "StartProviderCommand",
+    "StopProviderCommand",
+    "InvokeToolCommand",
+    "HealthCheckCommand",
+    "ShutdownIdleProvidersCommand",
+    # Auth Commands
+    "CreateApiKeyCommand",
+    "RevokeApiKeyCommand",
+    "ListApiKeysCommand",
+    "AssignRoleCommand",
+    "RevokeRoleCommand",
+    "CreateCustomRoleCommand",
+    # Handlers
+    "StartProviderHandler",
+    "StopProviderHandler",
+    "InvokeToolHandler",
+    "HealthCheckHandler",
+    "ShutdownIdleProvidersHandler",
+    "register_all_handlers",
+    # Auth Handlers
+    "CreateApiKeyHandler",
+    "RevokeApiKeyHandler",
+    "ListApiKeysHandler",
+    "AssignRoleHandler",
+    "RevokeRoleHandler",
+    "CreateCustomRoleHandler",
+    "register_auth_command_handlers",
+]

mcp_hangar/application/commands/auth_commands.py

@@ -0,0 +1,118 @@
+"""Authentication and Authorization commands.
+
+Commands represent user intentions for auth operations:
+- API Key management (create, revoke)
+- Role assignment (assign, revoke)
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from .commands import Command
+
+# =============================================================================
+# API Key Commands
+# =============================================================================
+
+
+@dataclass(frozen=True)
+class CreateApiKeyCommand(Command):
+    """Command to create a new API key.
+
+    Attributes:
+        principal_id: Principal ID the key authenticates as.
+        name: Human-readable name for the key.
+        created_by: Principal creating the key.
+        expires_at: Optional expiration datetime.
+        groups: Optional groups to assign.
+        tenant_id: Optional tenant for multi-tenancy.
+    """
+
+    principal_id: str
+    name: str
+    created_by: str = "system"
+    expires_at: datetime | None = None
+    groups: frozenset[str] = field(default_factory=frozenset)
+    tenant_id: str | None = None
+
+
+@dataclass(frozen=True)
+class RevokeApiKeyCommand(Command):
+    """Command to revoke an API key.
+
+    Attributes:
+        key_id: Unique identifier of the key to revoke.
+        revoked_by: Principal revoking the key.
+        reason: Optional reason for revocation.
+    """
+
+    key_id: str
+    revoked_by: str = "system"
+    reason: str = ""
+
+
+@dataclass(frozen=True)
+class ListApiKeysCommand(Command):
+    """Command to list API keys for a principal.
+
+    Attributes:
+        principal_id: Principal whose keys to list.
+    """
+
+    principal_id: str
+
+
+# =============================================================================
+# Role Commands
+# =============================================================================
+
+
+@dataclass(frozen=True)
+class AssignRoleCommand(Command):
+    """Command to assign a role to a principal.
+
+    Attributes:
+        principal_id: Principal receiving the role.
+        role_name: Name of the role to assign.
+        scope: Scope of the assignment (global, tenant:X, etc.).
+        assigned_by: Principal making the assignment.
+    """
+
+    principal_id: str
+    role_name: str
+    scope: str = "global"
+    assigned_by: str = "system"
+
+
+@dataclass(frozen=True)
+class RevokeRoleCommand(Command):
+    """Command to revoke a role from a principal.
+
+    Attributes:
+        principal_id: Principal losing the role.
+        role_name: Name of the role to revoke.
+        scope: Scope from which to revoke.
+        revoked_by: Principal making the revocation.
+    """
+
+    principal_id: str
+    role_name: str
+    scope: str = "global"
+    revoked_by: str = "system"
+
+
+@dataclass(frozen=True)
+class CreateCustomRoleCommand(Command):
+    """Command to create a custom role.
+
+    Attributes:
+        role_name: Name for the new role.
+        description: Human-readable description.
+        permissions: Set of permission strings (format: "resource:action:id").
+        created_by: Principal creating the role.
+    """
+
+    role_name: str
+    description: str = ""
+    permissions: frozenset[str] = field(default_factory=frozenset)
+    created_by: str = "system"

mcp_hangar/application/commands/auth_handlers.py

@@ -0,0 +1,296 @@
+"""Authentication and Authorization command handlers.
+
+Implements CQRS command handlers for auth operations.
+All handlers emit domain events via the event bus.
+"""
+
+from typing import Any
+
+from ...domain.contracts.authentication import IApiKeyStore
+from ...domain.contracts.authorization import IRoleStore
+from ...domain.value_objects import Permission, Role
+from ...infrastructure.command_bus import CommandHandler
+from ...logging_config import get_logger
+from .auth_commands import (
+    AssignRoleCommand,
+    CreateApiKeyCommand,
+    CreateCustomRoleCommand,
+    ListApiKeysCommand,
+    RevokeApiKeyCommand,
+    RevokeRoleCommand,
+)
+
+logger = get_logger(__name__)
+
+
+# =============================================================================
+# API Key Command Handlers
+# =============================================================================
+
+
+class CreateApiKeyHandler(CommandHandler):
+    """Handler for CreateApiKeyCommand.
+
+    Creates a new API key and returns the raw key value.
+    Note: The raw key is only returned once - it cannot be retrieved later.
+    """
+
+    def __init__(self, api_key_store: IApiKeyStore):
+        self._store = api_key_store
+
+    def handle(self, command: CreateApiKeyCommand) -> dict[str, Any]:
+        """Create a new API key.
+
+        Returns:
+            Dict with key_id (for management) and raw_key (for authentication).
+            The raw_key is only shown once!
+        """
+        logger.info(
+            "creating_api_key",
+            principal_id=command.principal_id,
+            name=command.name,
+            created_by=command.created_by,
+        )
+
+        raw_key = self._store.create_key(
+            principal_id=command.principal_id,
+            name=command.name,
+            expires_at=command.expires_at,
+            groups=command.groups,
+            tenant_id=command.tenant_id,
+            created_by=command.created_by,
+        )
+
+        # Get the key_id from the list (the raw_key is not stored)
+        keys = self._store.list_keys(command.principal_id)
+        key_metadata = next((k for k in keys if k.name == command.name), None)
+
+        return {
+            "key_id": key_metadata.key_id if key_metadata else None,
+            "raw_key": raw_key,
+            "principal_id": command.principal_id,
+            "name": command.name,
+            "expires_at": command.expires_at.isoformat() if command.expires_at else None,
+            "warning": "Save this key now - it cannot be retrieved later!",
+        }
+
+
+class RevokeApiKeyHandler(CommandHandler):
+    """Handler for RevokeApiKeyCommand.
+
+    Revokes an API key, making it unusable for authentication.
+    """
+
+    def __init__(self, api_key_store: IApiKeyStore):
+        self._store = api_key_store
+
+    def handle(self, command: RevokeApiKeyCommand) -> dict[str, Any]:
+        """Revoke an API key.
+
+        Returns:
+            Dict with revocation status.
+        """
+        logger.info(
+            "revoking_api_key",
+            key_id=command.key_id,
+            revoked_by=command.revoked_by,
+            reason=command.reason,
+        )
+
+        success = self._store.revoke_key(
+            key_id=command.key_id,
+            revoked_by=command.revoked_by,
+            reason=command.reason,
+        )
+
+        return {
+            "key_id": command.key_id,
+            "revoked": success,
+            "revoked_by": command.revoked_by,
+            "reason": command.reason,
+        }
+
+
+class ListApiKeysHandler(CommandHandler):
+    """Handler for ListApiKeysCommand.
+
+    Note: This is technically a query, but kept as command for simplicity.
+    In a strict CQRS implementation, this would be a query handler.
+    """
+
+    def __init__(self, api_key_store: IApiKeyStore):
+        self._store = api_key_store
+
+    def handle(self, command: ListApiKeysCommand) -> dict[str, Any]:
+        """List API keys for a principal.
+
+        Returns:
+            Dict with list of key metadata (not the actual keys).
+        """
+        keys = self._store.list_keys(command.principal_id)
+
+        return {
+            "principal_id": command.principal_id,
+            "keys": [
+                {
+                    "key_id": k.key_id,
+                    "name": k.name,
+                    "created_at": k.created_at.isoformat() if k.created_at else None,
+                    "expires_at": k.expires_at.isoformat() if k.expires_at else None,
+                    "last_used_at": k.last_used_at.isoformat() if k.last_used_at else None,
+                    "revoked": k.revoked,
+                }
+                for k in keys
+            ],
+            "count": len(keys),
+        }
+
+
+# =============================================================================
+# Role Command Handlers
+# =============================================================================
+
+
+class AssignRoleHandler(CommandHandler):
+    """Handler for AssignRoleCommand.
+
+    Assigns a role to a principal with optional scope.
+    """
+
+    def __init__(self, role_store: IRoleStore):
+        self._store = role_store
+
+    def handle(self, command: AssignRoleCommand) -> dict[str, Any]:
+        """Assign a role to a principal.
+
+        Returns:
+            Dict with assignment confirmation.
+        """
+        logger.info(
+            "assigning_role",
+            principal_id=command.principal_id,
+            role_name=command.role_name,
+            scope=command.scope,
+            assigned_by=command.assigned_by,
+        )
+
+        self._store.assign_role(
+            principal_id=command.principal_id,
+            role_name=command.role_name,
+            scope=command.scope,
+            assigned_by=command.assigned_by,
+        )
+
+        return {
+            "principal_id": command.principal_id,
+            "role_name": command.role_name,
+            "scope": command.scope,
+            "assigned": True,
+            "assigned_by": command.assigned_by,
+        }
+
+
+class RevokeRoleHandler(CommandHandler):
+    """Handler for RevokeRoleCommand.
+
+    Revokes a role from a principal.
+    """
+
+    def __init__(self, role_store: IRoleStore):
+        self._store = role_store
+
+    def handle(self, command: RevokeRoleCommand) -> dict[str, Any]:
+        """Revoke a role from a principal.
+
+        Returns:
+            Dict with revocation confirmation.
+        """
+        logger.info(
+            "revoking_role",
+            principal_id=command.principal_id,
+            role_name=command.role_name,
+            scope=command.scope,
+            revoked_by=command.revoked_by,
+        )
+
+        self._store.revoke_role(
+            principal_id=command.principal_id,
+            role_name=command.role_name,
+            scope=command.scope,
+            revoked_by=command.revoked_by,
+        )
+
+        return {
+            "principal_id": command.principal_id,
+            "role_name": command.role_name,
+            "scope": command.scope,
+            "revoked": True,
+            "revoked_by": command.revoked_by,
+        }
+
+
+class CreateCustomRoleHandler(CommandHandler):
+    """Handler for CreateCustomRoleCommand.
+
+    Creates a custom role with specified permissions.
+    """
+
+    def __init__(self, role_store: IRoleStore):
+        self._store = role_store
+
+    def handle(self, command: CreateCustomRoleCommand) -> dict[str, Any]:
+        """Create a custom role.
+
+        Returns:
+            Dict with role creation confirmation.
+        """
+        logger.info(
+            "creating_custom_role",
+            role_name=command.role_name,
+            permissions_count=len(command.permissions),
+            created_by=command.created_by,
+        )
+
+        # Parse permission strings to Permission objects
+        permissions = frozenset(Permission.parse(p) for p in command.permissions)
+
+        role = Role(
+            name=command.role_name,
+            description=command.description,
+            permissions=permissions,
+        )
+
+        self._store.add_role(role)
+
+        return {
+            "role_name": command.role_name,
+            "description": command.description,
+            "permissions_count": len(permissions),
+            "created": True,
+            "created_by": command.created_by,
+        }
+
+
+def register_auth_command_handlers(
+    command_bus,
+    api_key_store: IApiKeyStore | None = None,
+    role_store: IRoleStore | None = None,
+) -> None:
+    """Register all auth command handlers with the command bus.
+
+    Args:
+        command_bus: CommandBus instance.
+        api_key_store: API key store (optional, handlers skipped if None).
+        role_store: Role store (optional, handlers skipped if None).
+    """
+    if api_key_store:
+        command_bus.register(CreateApiKeyCommand, CreateApiKeyHandler(api_key_store))
+        command_bus.register(RevokeApiKeyCommand, RevokeApiKeyHandler(api_key_store))
+        command_bus.register(ListApiKeysCommand, ListApiKeysHandler(api_key_store))
+        logger.info("auth_api_key_handlers_registered")
+
+    if role_store:
+        command_bus.register(AssignRoleCommand, AssignRoleHandler(role_store))
+        command_bus.register(RevokeRoleCommand, RevokeRoleHandler(role_store))
+        command_bus.register(CreateCustomRoleCommand, CreateCustomRoleHandler(role_store))
+        logger.info("auth_role_handlers_registered")

mcp_hangar/application/commands/commands.py

@@ -0,0 +1,59 @@
+"""Application commands - represent user intentions.
+
+Commands are immutable data structures that represent actions to be performed.
+They are named in imperative form (StartProvider, not ProviderStarted).
+"""
+
+from abc import ABC
+from dataclasses import dataclass, field
+from typing import Any, Dict
+
+
+@dataclass(frozen=True)
+class Command(ABC):
+    """Base class for all commands.
+
+    Commands are immutable and represent a request to perform an action.
+    They should be named in imperative form (StartProvider, not ProviderStarted).
+    """
+
+    pass
+
+
+@dataclass(frozen=True)
+class StartProviderCommand(Command):
+    """Command to start a provider."""
+
+    provider_id: str
+
+
+@dataclass(frozen=True)
+class StopProviderCommand(Command):
+    """Command to stop a provider."""
+
+    provider_id: str
+    reason: str = "user_request"
+
+
+@dataclass(frozen=True)
+class InvokeToolCommand(Command):
+    """Command to invoke a tool on a provider."""
+
+    provider_id: str
+    tool_name: str
+    arguments: Dict[str, Any] = field(default_factory=dict)
+    timeout: float = 30.0
+
+
+@dataclass(frozen=True)
+class HealthCheckCommand(Command):
+    """Command to perform health check on a provider."""
+
+    provider_id: str
+
+
+@dataclass(frozen=True)
+class ShutdownIdleProvidersCommand(Command):
+    """Command to shutdown all idle providers."""
+
+    pass