mcp-hangar 0.2.0__py3-none-any.whl

mcp_hangar/server/state.py

@@ -0,0 +1,117 @@
+"""Server state management - BACKWARD COMPATIBILITY MODULE.
+
+This module provides backward compatibility with code that relies on
+global state variables. New code should use ApplicationContext from
+context.py instead.
+
+DEPRECATED: Direct use of PROVIDERS, COMMAND_BUS, etc. is deprecated.
+Use get_context() from context.py for dependency injection.
+
+Example migration:
+    # Old (deprecated):
+    from ..state import COMMAND_BUS, PROVIDERS
+    COMMAND_BUS.send(command)
+
+    # New (recommended):
+    from ..context import get_context
+    ctx = get_context()
+    ctx.command_bus.send(command)
+"""
+
+from typing import Dict, Optional, TYPE_CHECKING
+
+from ..application.discovery import DiscoveryOrchestrator
+from ..application.sagas import GroupRebalanceSaga
+from ..bootstrap.runtime import create_runtime
+from ..domain.model import ProviderGroup
+from ..logging_config import get_logger
+
+if TYPE_CHECKING:
+    from ..domain.repository import IProviderRepository
+
+logger = get_logger(__name__)
+
+
+class ProviderDict:
+    """Dictionary-like wrapper around provider repository for backward compatibility."""
+
+    def __init__(self, repository: "IProviderRepository"):
+        self._repo = repository
+
+    def __getitem__(self, key: str):
+        provider = self._repo.get(key)
+        if provider is None:
+            raise KeyError(key)
+        return provider
+
+    def __setitem__(self, key: str, value):
+        self._repo.add(key, value)
+
+    def __contains__(self, key: str) -> bool:
+        return self._repo.exists(key)
+
+    def __len__(self) -> int:
+        return self._repo.count()
+
+    def get(self, key: str, default=None):
+        return self._repo.get(key) or default
+
+    def items(self):
+        return self._repo.get_all().items()
+
+    def keys(self):
+        return self._repo.get_all_ids()
+
+    def values(self):
+        return self._repo.get_all().values()
+
+
+# Runtime wiring
+_RUNTIME = create_runtime()
+
+# Convenience bindings
+PROVIDER_REPOSITORY = _RUNTIME.repository
+EVENT_BUS = _RUNTIME.event_bus
+COMMAND_BUS = _RUNTIME.command_bus
+QUERY_BUS = _RUNTIME.query_bus
+RATE_LIMIT_CONFIG = _RUNTIME.rate_limit_config
+RATE_LIMITER = _RUNTIME.rate_limiter
+INPUT_VALIDATOR = _RUNTIME.input_validator
+SECURITY_HANDLER = _RUNTIME.security_handler
+
+# Provider dict backed by repository
+PROVIDERS = ProviderDict(PROVIDER_REPOSITORY)
+
+# Provider Groups storage
+GROUPS: Dict[str, ProviderGroup] = {}
+
+# Saga and discovery instances (initialized in main())
+_GROUP_REBALANCE_SAGA: Optional[GroupRebalanceSaga] = None
+_DISCOVERY_ORCHESTRATOR: Optional[DiscoveryOrchestrator] = None
+
+
+def get_runtime():
+    """Get the runtime instance."""
+    return _RUNTIME
+
+
+def set_discovery_orchestrator(orchestrator: Optional[DiscoveryOrchestrator]) -> None:
+    """Set the discovery orchestrator instance."""
+    global _DISCOVERY_ORCHESTRATOR
+    _DISCOVERY_ORCHESTRATOR = orchestrator
+
+
+def get_discovery_orchestrator() -> Optional[DiscoveryOrchestrator]:
+    """Get the discovery orchestrator instance."""
+    return _DISCOVERY_ORCHESTRATOR
+
+
+def set_group_rebalance_saga(saga: Optional[GroupRebalanceSaga]) -> None:
+    """Set the group rebalance saga instance."""
+    global _GROUP_REBALANCE_SAGA
+    _GROUP_REBALANCE_SAGA = saga
+
+
+def get_group_rebalance_saga() -> Optional[GroupRebalanceSaga]:
+    """Get the group rebalance saga instance."""
+    return _GROUP_REBALANCE_SAGA

mcp_hangar/server/tools/__init__.py

@@ -0,0 +1,16 @@
+"""MCP Tools modules."""
+
+from .discovery import register_discovery_tools
+from .groups import register_group_tools
+from .health import register_health_tools
+from .provider import register_provider_tools
+from .registry import register_registry_tools, registry_list
+
+__all__ = [
+    "register_registry_tools",
+    "register_provider_tools",
+    "register_health_tools",
+    "register_discovery_tools",
+    "register_group_tools",
+    "registry_list",
+]

mcp_hangar/server/tools/discovery.py

@@ -0,0 +1,186 @@
+"""Discovery tools: discover, sources, approve, quarantine.
+
+Uses ApplicationContext for dependency injection (DIP).
+"""
+
+import asyncio
+import concurrent.futures
+
+from mcp.server.fastmcp import FastMCP
+
+from ...application.mcp.tooling import key_global, mcp_tool_wrapper
+from ..context import get_context
+from ..validation import check_rate_limit, tool_error_hook, tool_error_mapper, validate_provider_id_input
+
+
+def register_discovery_tools(mcp: FastMCP) -> None:
+    """Register discovery tools with MCP server."""
+
+    @mcp.tool(name="registry_discover")
+    @mcp_tool_wrapper(
+        tool_name="registry_discover",
+        rate_limit_key=key_global,
+        check_rate_limit=lambda key: check_rate_limit("registry_discover"),
+        validate=None,
+        error_mapper=lambda exc: tool_error_mapper(exc),
+        on_error=tool_error_hook,
+    )
+    def registry_discover() -> dict:
+        """
+        Trigger immediate discovery cycle across all configured sources.
+
+        Returns:
+            Dictionary with discovery statistics
+        """
+        orchestrator = get_context().discovery_orchestrator
+        if orchestrator is None:
+            return {"error": "Discovery not configured. Enable discovery in config.yaml"}
+
+        try:
+            loop = asyncio.get_event_loop()
+            if loop.is_running():
+                with concurrent.futures.ThreadPoolExecutor() as executor:
+                    future = executor.submit(asyncio.run, orchestrator.trigger_discovery())
+                    result = future.result(timeout=60)
+            else:
+                result = loop.run_until_complete(orchestrator.trigger_discovery())
+        except RuntimeError:
+            result = asyncio.run(orchestrator.trigger_discovery())
+
+        return result
+
+    @mcp.tool(name="registry_discovered")
+    @mcp_tool_wrapper(
+        tool_name="registry_discovered",
+        rate_limit_key=key_global,
+        check_rate_limit=lambda key: check_rate_limit("registry_discovered"),
+        validate=None,
+        error_mapper=lambda exc: tool_error_mapper(exc),
+        on_error=tool_error_hook,
+    )
+    def registry_discovered() -> dict:
+        """
+        List all discovered providers pending registration.
+
+        Returns:
+            Dictionary with 'pending' key containing list of pending providers
+        """
+        orchestrator = get_context().discovery_orchestrator
+        if orchestrator is None:
+            return {"error": "Discovery not configured. Enable discovery in config.yaml"}
+
+        pending = orchestrator.get_pending_providers()
+        return {
+            "pending": [
+                {
+                    "name": p.name,
+                    "source": p.source_type,
+                    "mode": p.mode,
+                    "discovered_at": p.discovered_at.isoformat(),
+                    "fingerprint": p.fingerprint,
+                }
+                for p in pending
+            ]
+        }
+
+    @mcp.tool(name="registry_quarantine")
+    @mcp_tool_wrapper(
+        tool_name="registry_quarantine",
+        rate_limit_key=key_global,
+        check_rate_limit=lambda key: check_rate_limit("registry_quarantine"),
+        validate=None,
+        error_mapper=lambda exc: tool_error_mapper(exc),
+        on_error=tool_error_hook,
+    )
+    def registry_quarantine() -> dict:
+        """
+        List quarantined providers with failure reasons.
+
+        Returns:
+            Dictionary with 'quarantined' key containing list of quarantined providers
+        """
+        orchestrator = get_context().discovery_orchestrator
+        if orchestrator is None:
+            return {"error": "Discovery not configured. Enable discovery in config.yaml"}
+
+        quarantined = orchestrator.get_quarantined()
+        return {
+            "quarantined": [
+                {
+                    "name": name,
+                    "source": data["provider"]["source_type"],
+                    "reason": data["reason"],
+                    "quarantine_time": data["quarantine_time"],
+                }
+                for name, data in quarantined.items()
+            ]
+        }
+
+    @mcp.tool(name="registry_approve")
+    @mcp_tool_wrapper(
+        tool_name="registry_approve",
+        rate_limit_key=lambda provider: f"registry_approve:{provider}",
+        check_rate_limit=check_rate_limit,
+        validate=validate_provider_id_input,
+        error_mapper=lambda exc: tool_error_mapper(exc),
+        on_error=lambda exc, ctx: tool_error_hook(exc, ctx),
+    )
+    def registry_approve(provider: str) -> dict:
+        """
+        Approve a quarantined provider for registration.
+
+        Args:
+            provider: Name of the quarantined provider to approve
+
+        Returns:
+            Dictionary with approval result
+        """
+        orchestrator = get_context().discovery_orchestrator
+        if orchestrator is None:
+            return {"error": "Discovery not configured. Enable discovery in config.yaml"}
+
+        try:
+            loop = asyncio.get_event_loop()
+            if loop.is_running():
+                with concurrent.futures.ThreadPoolExecutor() as executor:
+                    future = executor.submit(asyncio.run, orchestrator.approve_provider(provider))
+                    result = future.result(timeout=60)
+            else:
+                result = loop.run_until_complete(orchestrator.approve_provider(provider))
+        except RuntimeError:
+            result = asyncio.run(orchestrator.approve_provider(provider))
+
+        return result
+
+    @mcp.tool(name="registry_sources")
+    @mcp_tool_wrapper(
+        tool_name="registry_sources",
+        rate_limit_key=key_global,
+        check_rate_limit=lambda key: check_rate_limit("registry_sources"),
+        validate=None,
+        error_mapper=lambda exc: tool_error_mapper(exc),
+        on_error=tool_error_hook,
+    )
+    def registry_sources() -> dict:
+        """
+        List configured discovery sources with health status.
+
+        Returns:
+            Dictionary with 'sources' key containing list of source status
+        """
+        orchestrator = get_context().discovery_orchestrator
+        if orchestrator is None:
+            return {"error": "Discovery not configured. Enable discovery in config.yaml"}
+
+        try:
+            loop = asyncio.get_event_loop()
+            if loop.is_running():
+                with concurrent.futures.ThreadPoolExecutor() as executor:
+                    future = executor.submit(asyncio.run, orchestrator.get_sources_status())
+                    sources = future.result(timeout=30)
+            else:
+                sources = loop.run_until_complete(orchestrator.get_sources_status())
+        except RuntimeError:
+            sources = asyncio.run(orchestrator.get_sources_status())
+
+        return {"sources": sources}

mcp_hangar/server/tools/groups.py

@@ -0,0 +1,75 @@
+"""Group management tools.
+
+Uses ApplicationContext for dependency injection (DIP).
+"""
+
+from mcp.server.fastmcp import FastMCP
+
+from ...application.mcp.tooling import key_global, mcp_tool_wrapper
+from ..context import get_context
+from ..validation import check_rate_limit, tool_error_hook, tool_error_mapper, validate_provider_id_input
+
+
+def register_group_tools(mcp: FastMCP) -> None:
+    """Register group management tools with MCP server."""
+
+    @mcp.tool(name="registry_group_list")
+    @mcp_tool_wrapper(
+        tool_name="registry_group_list",
+        rate_limit_key=key_global,
+        check_rate_limit=lambda key: check_rate_limit("registry_group_list"),
+        validate=None,
+        error_mapper=lambda exc: tool_error_mapper(exc),
+        on_error=tool_error_hook,
+    )
+    def registry_group_list() -> dict:
+        """
+        List all provider groups with detailed status.
+
+        This is a QUERY operation - read only.
+
+        Returns:
+            Dictionary with 'groups' key containing list of group info
+        """
+        ctx = get_context()
+        return {"groups": [group.to_status_dict() for group in ctx.groups.values()]}
+
+    @mcp.tool(name="registry_group_rebalance")
+    @mcp_tool_wrapper(
+        tool_name="registry_group_rebalance",
+        rate_limit_key=lambda group: f"registry_group_rebalance:{group}",
+        check_rate_limit=check_rate_limit,
+        validate=validate_provider_id_input,
+        error_mapper=lambda exc: tool_error_mapper(exc),
+        on_error=lambda exc, ctx_dict: tool_error_hook(exc, ctx_dict),
+    )
+    def registry_group_rebalance(group: str) -> dict:
+        """
+        Manually trigger rebalancing for a group.
+
+        This is a COMMAND operation - it changes state.
+
+        Args:
+            group: Group ID to rebalance
+
+        Returns:
+            Dictionary with group status after rebalancing
+
+        Raises:
+            ValueError: If group ID is unknown
+        """
+        ctx = get_context()
+
+        if not ctx.group_exists(group):
+            raise ValueError(f"unknown_group: {group}")
+
+        g = ctx.get_group(group)
+        g.rebalance()
+
+        return {
+            "group_id": group,
+            "state": g.state.value,
+            "healthy_count": g.healthy_count,
+            "total_members": g.total_count,
+            "members_in_rotation": [m.id for m in g.members if m.in_rotation],
+        }

mcp_hangar/server/tools/health.py

@@ -0,0 +1,301 @@
+"""Health and metrics tools.
+
+Uses ApplicationContext for dependency injection (DIP).
+All operations are QUERY operations - read only, no side effects.
+"""
+
+from typing import Any, Dict, List
+
+from mcp.server.fastmcp import FastMCP
+
+from ... import metrics as m
+from ...application.mcp.tooling import key_global, mcp_tool_wrapper
+from ...logging_config import get_logger
+from ..context import get_context
+from ..validation import check_rate_limit, tool_error_hook, tool_error_mapper
+
+logger = get_logger(__name__)
+
+# =============================================================================
+# Metrics Processing Helpers
+# =============================================================================
+
+
+def _collect_samples_from_collector(collector: Any) -> List[Any]:
+    """Extract metric samples from a Prometheus collector.
+
+    Args:
+        collector: Prometheus metric collector instance.
+
+    Returns:
+        List of metric samples extracted from the collector.
+    """
+    if not hasattr(collector, "collect"):
+        return []
+
+    collected = collector.collect()
+    if isinstance(collected, list):
+        return collected
+
+    if isinstance(collected, tuple):
+        samples = []
+        for item in collected:
+            if isinstance(item, list):
+                samples.extend(item)
+            elif hasattr(item, "labels"):
+                samples.append(item)
+        return samples
+
+    return []
+
+
+def _process_tool_calls_metric(
+    name: str, labels: Dict[str, str], value: float, tool_calls: Dict[str, Dict[str, int]]
+) -> None:
+    """Process tool_calls metric sample and update aggregation dict.
+
+    Args:
+        name: Metric name.
+        labels: Metric labels dict.
+        value: Metric value.
+        tool_calls: Dict to accumulate tool call counts.
+    """
+    if "tool_calls" not in name:
+        return
+
+    provider = labels.get("provider", "unknown")
+    tool = labels.get("tool", "unknown")
+    key = f"{provider}.{tool}"
+
+    if key not in tool_calls:
+        tool_calls[key] = {"count": 0, "errors": 0}
+
+    if "error" in name:
+        tool_calls[key]["errors"] = int(value)
+    else:
+        tool_calls[key]["count"] = int(value)
+
+
+def _process_invocations_metric(
+    name: str, labels: Dict[str, str], value: float, providers: Dict[str, Dict[str, Any]]
+) -> None:
+    """Process invocations metric sample and update provider stats.
+
+    Args:
+        name: Metric name.
+        labels: Metric labels dict.
+        value: Metric value.
+        providers: Dict to accumulate provider invocation counts.
+    """
+    if "invocations" not in name or "provider" not in labels:
+        return
+
+    provider = labels.get("provider")
+    if provider and provider in providers:
+        providers[provider]["invocations"] = int(value)
+
+
+def _process_discovery_metric(
+    name: str, labels: Dict[str, str], value: float, discovery: Dict[str, Dict[str, Any]]
+) -> None:
+    """Process discovery metric sample and update discovery stats.
+
+    Args:
+        name: Metric name.
+        labels: Metric labels dict.
+        value: Metric value.
+        discovery: Dict to accumulate discovery statistics.
+    """
+    if "discovery" not in name:
+        return
+
+    source = labels.get("source_type", labels.get("source", "unknown"))
+    if not source:
+        return
+
+    if source not in discovery:
+        discovery[source] = {}
+
+    if "cycle" in name:
+        discovery[source]["cycles"] = int(value)
+    elif "providers" in name:
+        status = labels.get("status", "total")
+        discovery[source][f"providers_{status}"] = int(value)
+
+
+def _process_error_metric(name: str, labels: Dict[str, str], value: float, errors: Dict[str, int]) -> None:
+    """Process error metric sample and update error counts.
+
+    Args:
+        name: Metric name.
+        labels: Metric labels dict.
+        value: Metric value.
+        errors: Dict to accumulate error counts by type.
+    """
+    if "error" not in name.lower():
+        return
+
+    error_type = labels.get("error_type", labels.get("type", name))
+    errors[error_type] = errors.get(error_type, 0) + int(value)
+
+
+def _process_metric_sample(sample: Any, result: Dict[str, Any]) -> None:
+    """Process a single metric sample and update result dict.
+
+    Routes the sample to appropriate processor based on metric name.
+
+    Args:
+        sample: Metric sample with labels and value attributes.
+        result: Result dict to update with processed metrics.
+    """
+    if not hasattr(sample, "labels") or not hasattr(sample, "value"):
+        return
+
+    labels = sample.labels or {}
+    value = sample.value
+    name = getattr(sample, "name", "")
+
+    _process_tool_calls_metric(name, labels, value, result["tool_calls"])
+    _process_invocations_metric(name, labels, value, result["providers"])
+    _process_discovery_metric(name, labels, value, result["discovery"])
+    _process_error_metric(name, labels, value, result["errors"])
+
+
+def register_health_tools(mcp: FastMCP) -> None:
+    """Register health and metrics tools with MCP server."""
+
+    @mcp.tool(name="registry_health")
+    @mcp_tool_wrapper(
+        tool_name="registry_health",
+        rate_limit_key=key_global,
+        check_rate_limit=lambda key: check_rate_limit("registry_health"),
+        validate=None,
+        error_mapper=lambda exc: tool_error_mapper(exc),
+        on_error=tool_error_hook,
+    )
+    def registry_health() -> dict:
+        """
+        Get registry health status including security metrics.
+
+        This is a QUERY operation - read only.
+
+        Returns:
+            Dictionary with health information
+        """
+        ctx = get_context()
+        rate_limit_stats = ctx.rate_limiter.get_stats()
+
+        # Get all providers via repository
+        all_providers = ctx.repository.get_all()
+        providers = list(all_providers.values())
+        state_counts = {}
+        for p in providers:
+            state = str(p.state)
+            state_counts[state] = state_counts.get(state, 0) + 1
+
+        group_state_counts = {}
+        total_group_members = 0
+        healthy_group_members = 0
+        for group in ctx.groups.values():
+            state = group.state.value
+            group_state_counts[state] = group_state_counts.get(state, 0) + 1
+            total_group_members += group.total_count
+            healthy_group_members += group.healthy_count
+
+        return {
+            "status": "healthy",
+            "providers": {
+                "total": len(providers),
+                "by_state": state_counts,
+            },
+            "groups": {
+                "total": len(ctx.groups),
+                "by_state": group_state_counts,
+                "total_members": total_group_members,
+                "healthy_members": healthy_group_members,
+            },
+            "security": {
+                "rate_limiting": rate_limit_stats,
+            },
+        }
+
+    @mcp.tool(name="registry_metrics")
+    @mcp_tool_wrapper(
+        tool_name="registry_metrics",
+        rate_limit_key=key_global,
+        check_rate_limit=lambda key: check_rate_limit("registry_metrics"),
+        validate=None,
+        error_mapper=lambda exc: tool_error_mapper(exc),
+        on_error=tool_error_hook,
+    )
+    def registry_metrics(format: str = "json") -> dict:
+        """
+        Get detailed metrics for all providers, groups, and system components.
+
+        This is a QUERY operation - read only.
+
+        Args:
+            format: Output format - 'json' (structured) or 'prometheus' (raw text)
+
+        Returns:
+            Dictionary with comprehensive metrics
+        """
+        ctx = get_context()
+
+        if format == "prometheus":
+            return {"metrics": m.REGISTRY.render()}
+
+        result: Dict[str, Any] = {
+            "providers": {},
+            "groups": {},
+            "tool_calls": {},
+            "discovery": {},
+            "errors": {},
+            "performance": {},
+        }
+
+        # Provider metrics via repository
+        all_providers = ctx.repository.get_all()
+        for provider in all_providers.values():
+            pid = provider.provider_id
+            result["providers"][pid] = {
+                "state": str(provider.state),
+                "mode": provider._mode.value if hasattr(provider, "_mode") else "unknown",
+                "tools_count": len(provider.tools) if provider.tools else 0,
+                "invocations": 0,
+                "errors": 0,
+                "avg_latency_ms": 0,
+            }
+
+        # Collect metrics from registry
+        for name, collector in m.REGISTRY._collectors.items():
+            try:
+                samples = _collect_samples_from_collector(collector)
+                for sample in samples:
+                    # Add collector name to sample for processing
+                    if not hasattr(sample, "name"):
+                        sample.name = name
+                    _process_metric_sample(sample, result)
+            except (AttributeError, TypeError, ValueError) as e:
+                # Skip malformed collectors gracefully
+                logger.debug("metrics_collector_error", collector=name, error=str(e))
+                continue
+
+        # Group metrics
+        for group in ctx.groups.values():
+            result["groups"][group.name] = {
+                "state": group.state.value,
+                "strategy": group.strategy,
+                "total_members": group.total_count,
+                "healthy_members": group.healthy_count,
+            }
+
+        # Summary stats
+        result["summary"] = {
+            "total_providers": len(result["providers"]),
+            "total_groups": len(result["groups"]),
+            "total_tool_calls": sum(tc.get("count", 0) for tc in result["tool_calls"].values()),
+            "total_errors": sum(result["errors"].values()),
+        }
+
+        return result