mcp-hangar 0.2.0__py3-none-any.whl

mcp_hangar/domain/model/tool_catalog.py

@@ -0,0 +1,105 @@
+"""Tool catalog value object for providers."""
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+
+@dataclass(frozen=True)
+class ToolSchema:
+    """
+    Schema for a tool provided by a provider.
+
+    Immutable value object containing tool metadata.
+    """
+
+    name: str
+    description: str
+    input_schema: Dict[str, Any]
+    output_schema: Optional[Dict[str, Any]] = None
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary representation."""
+        result = {
+            "name": self.name,
+            "description": self.description,
+            "inputSchema": self.input_schema,
+        }
+        if self.output_schema is not None:
+            result["outputSchema"] = self.output_schema
+        return result
+
+
+class ToolCatalog:
+    """
+    Catalog of tools provided by a provider.
+
+    This is a mutable collection that can be updated when tools are
+    discovered or refreshed. Thread safety is handled by the aggregate.
+    """
+
+    def __init__(self, tools: Optional[Dict[str, ToolSchema]] = None):
+        self._tools: Dict[str, ToolSchema] = dict(tools or {})
+
+    def has(self, tool_name: str) -> bool:
+        """Check if a tool exists in the catalog."""
+        return tool_name in self._tools
+
+    def get(self, tool_name: str) -> Optional[ToolSchema]:
+        """Get a tool schema by name."""
+        return self._tools.get(tool_name)
+
+    def list_names(self) -> List[str]:
+        """Get list of all tool names."""
+        return list(self._tools.keys())
+
+    def list_tools(self) -> List[ToolSchema]:
+        """Get list of all tool schemas."""
+        return list(self._tools.values())
+
+    def count(self) -> int:
+        """Get number of tools in catalog."""
+        return len(self._tools)
+
+    def add(self, tool: ToolSchema) -> None:
+        """Add or update a tool in the catalog."""
+        self._tools[tool.name] = tool
+
+    def remove(self, tool_name: str) -> bool:
+        """Remove a tool from the catalog. Returns True if removed."""
+        if tool_name in self._tools:
+            del self._tools[tool_name]
+            return True
+        return False
+
+    def clear(self) -> None:
+        """Remove all tools from the catalog."""
+        self._tools.clear()
+
+    def update_from_list(self, tool_list: List[dict]) -> None:
+        """
+        Update catalog from a list of tool dictionaries.
+
+        This is typically used when refreshing tools from a provider response.
+        """
+        self._tools.clear()
+        for t in tool_list:
+            tool = ToolSchema(
+                name=t["name"],
+                description=t.get("description", ""),
+                input_schema=t.get("inputSchema", {}),
+                output_schema=t.get("outputSchema"),
+            )
+            self._tools[tool.name] = tool
+
+    def to_dict(self) -> Dict[str, ToolSchema]:
+        """Get a copy of the internal tools dictionary."""
+        return dict(self._tools)
+
+    def __contains__(self, tool_name: str) -> bool:
+        return tool_name in self._tools
+
+    def __len__(self) -> int:
+        return len(self._tools)
+
+    def __iter__(self):
+        return iter(self._tools.values())

mcp_hangar/domain/policies/__init__.py

@@ -0,0 +1,19 @@
+"""Domain policies for MCP Hangar.
+
+Policies encapsulate domain rules and classification logic that can be
+applied across different contexts without coupling to specific aggregates.
+"""
+
+from .provider_health import (
+    classify_provider_health,
+    classify_provider_health_from_provider,
+    ProviderHealthClassification,
+    to_health_status_string,
+)
+
+__all__ = [
+    "ProviderHealthClassification",
+    "classify_provider_health",
+    "classify_provider_health_from_provider",
+    "to_health_status_string",
+]

mcp_hangar/domain/policies/provider_health.py

@@ -0,0 +1,187 @@
+"""Provider health classification policy.
+
+This module centralizes the logic that maps a Provider's state + health tracker
+signals into a user-facing health classification.
+
+Why this exists:
+- Avoids duplicating "health status" mapping logic across query handlers / APIs.
+- Keeps interpretation of state and failures as a domain-level policy.
+- Allows the policy to evolve without touching CQRS read mapping.
+
+This policy is intentionally small and pure (no I/O, no imports from infrastructure).
+
+Usage (typical):
+    from mcp_hangar.domain.policies.provider_health import classify_provider_health
+
+    health_status = classify_provider_health(
+        state=provider.state,
+        consecutive_failures=provider.health.consecutive_failures,
+    )
+
+Or, if you already have a HealthTracker-like object:
+    health_status = classify_provider_health_from_provider(provider)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from ..value_objects import HealthStatus, ProviderState
+
+
+class _HealthView(Protocol):
+    """Minimal health-tracker view required by the policy.
+
+    Defines the interface for accessing health metrics from any
+    health-tracker-like object.
+    """
+
+    @property
+    def consecutive_failures(self) -> int:
+        """Get the count of consecutive failures."""
+        ...
+
+
+class _ProviderView(Protocol):
+    """Minimal provider view required by the policy.
+
+    Defines the interface for accessing provider state and health
+    from any provider-like object.
+    """
+
+    @property
+    def state(self) -> ProviderState:
+        """Get the current provider state."""
+        ...
+
+    @property
+    def health(self) -> _HealthView:
+        """Get the health tracker view."""
+        ...
+
+
+def _normalize_state(state: Any) -> ProviderState:
+    """Convert a loose/legacy state representation to ProviderState."""
+    if isinstance(state, ProviderState):
+        return state
+
+    # Some call sites may pass enum-like objects with `.value`
+    value = getattr(state, "value", None)
+    if value is not None:
+        state_str = str(value).lower()
+    else:
+        state_str = str(state).lower()
+
+    for s in ProviderState:
+        if s.value == state_str:
+            return s
+
+    # If unknown, treat as DEAD from a health classification standpoint
+    # (conservative default).
+    return ProviderState.DEAD
+
+
+@dataclass(frozen=True)
+class ProviderHealthClassification:
+    """Result of applying the classification policy."""
+
+    status: HealthStatus
+    reason: str
+    consecutive_failures: int
+
+    def to_dict(self) -> dict:
+        return {
+            "status": str(self.status),
+            "reason": self.reason,
+            "consecutive_failures": self.consecutive_failures,
+        }
+
+
+def classify_provider_health(
+    *,
+    state: Any,
+    consecutive_failures: int = 0,
+) -> ProviderHealthClassification:
+    """Classify provider health from state and failure count.
+
+    Rules (current):
+    - READY + 0 failures -> HEALTHY
+    - READY + >0 failures -> DEGRADED
+    - DEGRADED -> DEGRADED
+    - DEAD -> UNHEALTHY
+    - COLD / INITIALIZING -> UNKNOWN
+
+    Notes:
+    - This is a *classification*, not the same as "can accept requests".
+      That rule is handled by ProviderState.can_accept_requests and other domain logic.
+    """
+    st = _normalize_state(state)
+    failures = int(consecutive_failures or 0)
+
+    if st == ProviderState.READY:
+        if failures <= 0:
+            return ProviderHealthClassification(
+                status=HealthStatus.HEALTHY,
+                reason="ready_no_failures",
+                consecutive_failures=failures,
+            )
+        return ProviderHealthClassification(
+            status=HealthStatus.DEGRADED,
+            reason="ready_with_failures",
+            consecutive_failures=failures,
+        )
+
+    if st == ProviderState.DEGRADED:
+        return ProviderHealthClassification(
+            status=HealthStatus.DEGRADED,
+            reason="provider_state_degraded",
+            consecutive_failures=failures,
+        )
+
+    if st == ProviderState.DEAD:
+        return ProviderHealthClassification(
+            status=HealthStatus.UNHEALTHY,
+            reason="provider_state_dead",
+            consecutive_failures=failures,
+        )
+
+    if st in (ProviderState.COLD, ProviderState.INITIALIZING):
+        return ProviderHealthClassification(
+            status=HealthStatus.UNKNOWN,
+            reason=f"provider_state_{st.value}",
+            consecutive_failures=failures,
+        )
+
+    # Fallback (shouldn't happen due to normalization)
+    return ProviderHealthClassification(
+        status=HealthStatus.UNKNOWN,
+        reason="unknown_state",
+        consecutive_failures=failures,
+    )
+
+
+def classify_provider_health_from_provider(
+    provider: _ProviderView,
+) -> ProviderHealthClassification:
+    """Convenience wrapper to classify health from a provider-like object."""
+    return classify_provider_health(
+        state=provider.state,
+        consecutive_failures=provider.health.consecutive_failures,
+    )
+
+
+def to_health_status_string(
+    *,
+    state: Any,
+    consecutive_failures: int = 0,
+) -> str:
+    """Legacy helper: return the `HealthStatus.value` string.
+
+    This exists to minimize changes in read model mapping code while still routing
+    logic through a single policy.
+    """
+    return classify_provider_health(
+        state=state,
+        consecutive_failures=consecutive_failures,
+    ).status.value

mcp_hangar/domain/repository.py

@@ -0,0 +1,249 @@
+"""
+Repository interfaces for provider storage abstraction.
+
+The Repository pattern separates domain logic from data access logic,
+allowing the persistence mechanism to change without affecting business code.
+"""
+
+from abc import ABC, abstractmethod
+import threading
+from typing import Any, Dict, List, Optional
+
+# Type alias for provider-like objects (Provider aggregate)
+ProviderLike = Any
+
+
+class IProviderRepository(ABC):
+    """Abstract interface for provider storage.
+
+    This interface defines the contract for storing and retrieving providers,
+    allowing different implementations (in-memory, database, etc.) without
+    changing business logic.
+
+    Stores Provider aggregates.
+
+    Thread-safety is guaranteed by implementations.
+    """
+
+    @abstractmethod
+    def add(self, provider_id: str, provider: ProviderLike) -> None:
+        """Add or update a provider in the repository.
+
+        Args:
+            provider_id: Unique provider identifier
+            provider: Provider aggregate instance to store
+
+        Raises:
+            ValueError: If provider_id is empty or invalid
+        """
+        pass
+
+    @abstractmethod
+    def get(self, provider_id: str) -> Optional[ProviderLike]:
+        """Retrieve a provider by ID.
+
+        Args:
+            provider_id: Provider identifier to look up
+
+        Returns:
+            Provider if found, None otherwise
+        """
+        pass
+
+    @abstractmethod
+    def exists(self, provider_id: str) -> bool:
+        """Check if a provider exists in the repository.
+
+        Args:
+            provider_id: Provider identifier to check
+
+        Returns:
+            True if provider exists, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    def remove(self, provider_id: str) -> bool:
+        """Remove a provider from the repository.
+
+        Args:
+            provider_id: Provider identifier to remove
+
+        Returns:
+            True if provider was removed, False if not found
+        """
+        pass
+
+    @abstractmethod
+    def get_all(self) -> Dict[str, ProviderLike]:
+        """Get all providers as a dictionary.
+
+        Returns:
+            Dictionary mapping provider_id -> Provider
+            Returns a copy to prevent external modifications
+        """
+        pass
+
+    @abstractmethod
+    def get_all_ids(self) -> List[str]:
+        """Get all provider IDs.
+
+        Returns:
+            List of provider identifiers
+        """
+        pass
+
+    @abstractmethod
+    def count(self) -> int:
+        """Get the total number of providers.
+
+        Returns:
+            Number of providers in the repository
+        """
+        pass
+
+    @abstractmethod
+    def clear(self) -> None:
+        """Remove all providers from the repository.
+
+        This is primarily for testing and cleanup.
+        """
+        pass
+
+
+class InMemoryProviderRepository(IProviderRepository):
+    """In-memory implementation of provider repository.
+
+    This implementation stores providers in a dictionary with thread-safe
+    access using a read-write lock pattern.
+
+    Stores Provider aggregates.
+
+    Thread Safety:
+    - All operations are protected by a lock
+    - get_all() returns a snapshot copy
+    - Safe for concurrent access from multiple threads
+    """
+
+    def __init__(self):
+        """Initialize empty in-memory repository."""
+        self._providers: Dict[str, ProviderLike] = {}
+        self._lock = threading.RLock()
+
+    def add(self, provider_id: str, provider: ProviderLike) -> None:
+        """Add or update a provider in the repository.
+
+        Args:
+            provider_id: Unique provider identifier
+            provider: Provider aggregate instance to store
+
+        Raises:
+            ValueError: If provider_id is empty
+        """
+        if not provider_id:
+            raise ValueError("Provider ID cannot be empty")
+
+        with self._lock:
+            self._providers[provider_id] = provider
+
+    def get(self, provider_id: str) -> Optional[ProviderLike]:
+        """Retrieve a provider by ID.
+
+        Args:
+            provider_id: Provider identifier to look up
+
+        Returns:
+            Provider if found, None otherwise
+        """
+        with self._lock:
+            return self._providers.get(provider_id)
+
+    def exists(self, provider_id: str) -> bool:
+        """Check if a provider exists in the repository.
+
+        Args:
+            provider_id: Provider identifier to check
+
+        Returns:
+            True if provider exists, False otherwise
+        """
+        with self._lock:
+            return provider_id in self._providers
+
+    def remove(self, provider_id: str) -> bool:
+        """Remove a provider from the repository.
+
+        Args:
+            provider_id: Provider identifier to remove
+
+        Returns:
+            True if provider was removed, False if not found
+        """
+        with self._lock:
+            if provider_id in self._providers:
+                del self._providers[provider_id]
+                return True
+            return False
+
+    def get_all(self) -> Dict[str, ProviderLike]:
+        """Get all providers as a dictionary.
+
+        Returns:
+            Dictionary mapping provider_id -> Provider
+            Returns a copy to prevent external modifications
+        """
+        with self._lock:
+            return dict(self._providers)
+
+    def get_all_ids(self) -> List[str]:
+        """Get all provider IDs.
+
+        Returns:
+            List of provider identifiers
+        """
+        with self._lock:
+            return list(self._providers.keys())
+
+    def count(self) -> int:
+        """Get the total number of providers.
+
+        Returns:
+            Number of providers in the repository
+        """
+        with self._lock:
+            return len(self._providers)
+
+    def clear(self) -> None:
+        """Remove all providers from the repository.
+
+        This is primarily for testing and cleanup.
+        """
+        with self._lock:
+            self._providers.clear()
+
+    def __contains__(self, provider_id: str) -> bool:
+        """Support 'in' operator for checking existence.
+
+        Args:
+            provider_id: Provider identifier to check
+
+        Returns:
+            True if provider exists, False otherwise
+        """
+        return self.exists(provider_id)
+
+    def __len__(self) -> int:
+        """Support len() function.
+
+        Returns:
+            Number of providers in the repository
+        """
+        return self.count()
+
+    def __repr__(self) -> str:
+        """String representation for debugging.
+
+        Returns:
+            String showing repository type and provider count
+        """
+        return f"InMemoryProviderRepository(providers={self.count()})"

mcp_hangar/domain/security/__init__.py

@@ -0,0 +1,85 @@
+"""
+Security module for the MCP Registry.
+
+Provides security primitives including:
+- Input validation and sanitization
+- Command injection prevention
+- Rate limiting
+- Secrets management
+- Security audit logging utilities
+"""
+
+from .input_validator import (
+    InputValidator,
+    validate_arguments,
+    validate_command,
+    validate_docker_image,
+    validate_environment_variables,
+    validate_provider_id,
+    validate_timeout,
+    validate_tool_name,
+    ValidationResult,
+)
+from .rate_limiter import InMemoryRateLimiter, RateLimitConfig, RateLimiter, RateLimitResult
+from .roles import (
+    BUILTIN_ROLES,
+    get_builtin_role,
+    get_permission,
+    list_builtin_roles,
+    list_permissions,
+    PERMISSIONS,
+    ROLE_ADMIN,
+    ROLE_AUDITOR,
+    ROLE_DEVELOPER,
+    ROLE_PROVIDER_ADMIN,
+    ROLE_VIEWER,
+)
+from .sanitizer import (
+    sanitize_command_argument,
+    sanitize_environment_value,
+    sanitize_log_message,
+    sanitize_path,
+    Sanitizer,
+)
+from .secrets import is_sensitive_key, mask_sensitive_value, SecretsMask, SecureEnvironment
+
+__all__ = [
+    # Input Validation
+    "InputValidator",
+    "ValidationResult",
+    "validate_provider_id",
+    "validate_tool_name",
+    "validate_arguments",
+    "validate_timeout",
+    "validate_command",
+    "validate_docker_image",
+    "validate_environment_variables",
+    # Sanitization
+    "Sanitizer",
+    "sanitize_command_argument",
+    "sanitize_environment_value",
+    "sanitize_log_message",
+    "sanitize_path",
+    # Rate Limiting
+    "RateLimiter",
+    "RateLimitConfig",
+    "InMemoryRateLimiter",
+    "RateLimitResult",
+    # Secrets
+    "SecretsMask",
+    "SecureEnvironment",
+    "is_sensitive_key",
+    "mask_sensitive_value",
+    # Roles & Permissions
+    "BUILTIN_ROLES",
+    "PERMISSIONS",
+    "ROLE_ADMIN",
+    "ROLE_DEVELOPER",
+    "ROLE_PROVIDER_ADMIN",
+    "ROLE_VIEWER",
+    "ROLE_AUDITOR",
+    "get_builtin_role",
+    "get_permission",
+    "list_builtin_roles",
+    "list_permissions",
+]