mcp-hangar 0.2.0__py3-none-any.whl

mcp_hangar/server/tools/registry.py

@@ -0,0 +1,320 @@
+"""Registry management tools: list, start, stop, status.
+
+Uses ApplicationContext for dependency injection (DIP).
+Separates commands (write) from queries (read) following CQRS.
+"""
+
+import time
+from typing import Optional
+
+from mcp.server.fastmcp import FastMCP
+
+from ...application.commands import StartProviderCommand, StopProviderCommand
+from ...application.mcp.tooling import key_global, mcp_tool_wrapper
+from ...infrastructure.query_bus import ListProvidersQuery
+from ..context import get_context
+from ..validation import check_rate_limit, tool_error_hook, tool_error_mapper, validate_provider_id_input
+
+# Server start time for uptime calculation
+_server_start_time: float = time.time()
+
+
+def registry_list(state_filter: Optional[str] = None) -> dict:
+    """
+    List all providers and groups with status and metadata.
+
+    This is a QUERY operation - no side effects, only reads data.
+
+    Args:
+        state_filter: Optional filter by state (cold, ready, degraded, dead)
+
+    Returns:
+        Dictionary with 'providers' and 'groups' keys
+    """
+    ctx = get_context()
+
+    # Query via CQRS query bus
+    query = ListProvidersQuery(state_filter=state_filter)
+    summaries = ctx.query_bus.execute(query)
+
+    # Read groups from context
+    groups_list = []
+    for group_id, group in ctx.groups.items():
+        group_info = group.to_status_dict()
+        if state_filter and group_info.get("state") != state_filter:
+            continue
+        groups_list.append(group_info)
+
+    return {
+        "providers": [s.to_dict() for s in summaries],
+        "groups": groups_list,
+    }
+
+
+def register_registry_tools(mcp: FastMCP) -> None:
+    """Register registry management tools with MCP server."""
+
+    @mcp.tool(name="registry_list")
+    @mcp_tool_wrapper(
+        tool_name="registry_list",
+        rate_limit_key=key_global,
+        check_rate_limit=lambda key: check_rate_limit("registry_list"),
+        validate=None,
+        error_mapper=lambda exc: tool_error_mapper(exc),
+        on_error=tool_error_hook,
+    )
+    def _registry_list(state_filter: Optional[str] = None) -> dict:
+        return registry_list(state_filter)
+
+    @mcp.tool(name="registry_start")
+    @mcp_tool_wrapper(
+        tool_name="registry_start",
+        rate_limit_key=lambda provider: f"registry_start:{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_start(provider: str) -> dict:
+        """
+        Explicitly start a provider or all members of a group.
+
+        This is a COMMAND operation - it changes state.
+
+        Args:
+            provider: Provider ID or Group ID to start
+
+        Returns:
+            Dictionary with provider/group state and tools
+
+        Raises:
+            ValueError: If provider ID is unknown or invalid
+        """
+        ctx = get_context()
+
+        # Check if it's a group first
+        if ctx.group_exists(provider):
+            group = ctx.get_group(provider)
+            started = group.start_all()
+            return {
+                "group": provider,
+                "state": group.state.value,
+                "members_started": started,
+                "healthy_count": group.healthy_count,
+                "total_members": group.total_count,
+            }
+
+        # Check provider exists
+        if not ctx.provider_exists(provider):
+            raise ValueError(f"unknown_provider: {provider}")
+
+        # Send command via CQRS command bus
+        command = StartProviderCommand(provider_id=provider)
+        return ctx.command_bus.send(command)
+
+    @mcp.tool(name="registry_stop")
+    @mcp_tool_wrapper(
+        tool_name="registry_stop",
+        rate_limit_key=lambda provider: f"registry_stop:{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_dict: tool_error_hook(exc, ctx_dict),
+    )
+    def registry_stop(provider: str) -> dict:
+        """
+        Explicitly stop a provider or all members of a group.
+
+        This is a COMMAND operation - it changes state.
+
+        Args:
+            provider: Provider ID or Group ID to stop
+
+        Returns:
+            Confirmation dictionary
+
+        Raises:
+            ValueError: If provider ID is unknown or invalid
+        """
+        ctx = get_context()
+
+        # Check if it's a group first
+        if ctx.group_exists(provider):
+            group = ctx.get_group(provider)
+            group.stop_all()
+            return {
+                "group": provider,
+                "state": group.state.value,
+                "stopped": True,
+            }
+
+        # Check provider exists
+        if not ctx.provider_exists(provider):
+            raise ValueError(f"unknown_provider: {provider}")
+
+        # Send command via CQRS command bus
+        command = StopProviderCommand(provider_id=provider)
+        return ctx.command_bus.send(command)
+
+    @mcp.tool(name="registry_status")
+    @mcp_tool_wrapper(
+        tool_name="registry_status",
+        rate_limit_key=key_global,
+        check_rate_limit=lambda key: check_rate_limit("registry_status"),
+        validate=None,
+        error_mapper=lambda exc: tool_error_mapper(exc),
+        on_error=tool_error_hook,
+    )
+    def registry_status() -> dict:
+        """
+        Get a comprehensive status overview of the MCP Registry.
+
+        Shows status of all providers with visual indicators:
+        - ✅ ready: Provider is running and healthy
+        - ⏸️  idle: Provider is cold, will start on first request
+        - 🔄 starting: Provider is starting up
+        - ❌ error: Provider has errors or is degraded
+
+        Returns:
+            Dictionary with providers, groups, health summary, and uptime
+        """
+        ctx = get_context()
+
+        # Get all providers
+        query = ListProvidersQuery(state_filter=None)
+        summaries = ctx.query_bus.execute(query)
+
+        # Format providers with status indicators
+        providers_status = []
+        healthy_count = 0
+        total_count = len(summaries)
+
+        for summary in summaries:
+            state = summary.state
+            indicator = _get_status_indicator(state)
+
+            provider_info = {
+                "id": summary.provider_id,
+                "indicator": indicator,
+                "state": state,
+                "mode": summary.mode,
+            }
+
+            # Add additional context based on state
+            if state == "ready":
+                healthy_count += 1
+                if hasattr(summary, "last_used_ago_s"):
+                    provider_info["last_used"] = _format_time_ago(summary.last_used_ago_s)
+            elif state == "cold":
+                provider_info["note"] = "Will start on first request"
+            elif state == "degraded":
+                if hasattr(summary, "consecutive_failures"):
+                    provider_info["consecutive_failures"] = summary.consecutive_failures
+
+            providers_status.append(provider_info)
+
+        # Get groups
+        groups_status = []
+        for group_id, group in ctx.groups.items():
+            group_info = {
+                "id": group_id,
+                "indicator": _get_status_indicator(group.state.value),
+                "state": group.state.value,
+                "healthy_members": group.healthy_count,
+                "total_members": group.total_count,
+            }
+            groups_status.append(group_info)
+
+        # Calculate uptime
+        uptime_s = time.time() - _server_start_time
+        uptime_formatted = _format_uptime(uptime_s)
+
+        return {
+            "providers": providers_status,
+            "groups": groups_status,
+            "summary": {
+                "healthy_providers": healthy_count,
+                "total_providers": total_count,
+                "uptime": uptime_formatted,
+                "uptime_seconds": round(uptime_s, 1),
+            },
+            "formatted": _format_status_dashboard(
+                providers_status, groups_status, healthy_count, total_count, uptime_formatted
+            ),
+        }
+
+
+def _get_status_indicator(state: str) -> str:
+    """Get visual indicator for provider state."""
+    indicators = {
+        "ready": "✅",
+        "cold": "⏸️",
+        "starting": "🔄",
+        "degraded": "⚠️",
+        "dead": "❌",
+        "error": "❌",
+    }
+    return indicators.get(state.lower(), "❓")
+
+
+def _format_time_ago(seconds: float) -> str:
+    """Format seconds as human-readable 'time ago' string."""
+    if seconds < 60:
+        return f"{int(seconds)}s ago"
+    elif seconds < 3600:
+        return f"{int(seconds / 60)}m ago"
+    else:
+        return f"{int(seconds / 3600)}h ago"
+
+
+def _format_uptime(seconds: float) -> str:
+    """Format uptime as human-readable string."""
+    hours = int(seconds // 3600)
+    minutes = int((seconds % 3600) // 60)
+    if hours > 0:
+        return f"{hours}h {minutes}m"
+    return f"{minutes}m"
+
+
+def _format_status_dashboard(
+    providers: list,
+    groups: list,
+    healthy: int,
+    total: int,
+    uptime: str,
+) -> str:
+    """Format status as ASCII dashboard."""
+    lines = [
+        "╭─────────────────────────────────────────────────╮",
+        "│ MCP-Hangar Status                               │",
+        "├─────────────────────────────────────────────────┤",
+    ]
+
+    # Providers
+    for p in providers:
+        indicator = p["indicator"]
+        name = p["id"][:15].ljust(15)
+        state = p["state"][:8].ljust(8)
+        extra = ""
+        if "last_used" in p:
+            extra = f"last: {p['last_used']}"
+        elif "note" in p:
+            extra = p["note"][:20]
+        line = f"│ {indicator} {name} {state} {extra[:22].ljust(22)}│"
+        lines.append(line)
+
+    # Groups
+    for g in groups:
+        indicator = g["indicator"]
+        name = g["id"][:15].ljust(15)
+        state = g["state"][:8].ljust(8)
+        extra = f"{g['healthy_members']}/{g['total_members']} healthy"
+        line = f"│ {indicator} {name} {state} {extra[:22].ljust(22)}│"
+        lines.append(line)
+
+    lines.append("├─────────────────────────────────────────────────┤")
+    lines.append(f"│ Health: {healthy}/{total} providers healthy".ljust(50) + "│")
+    lines.append(f"│ Uptime: {uptime}".ljust(50) + "│")
+    lines.append("╰─────────────────────────────────────────────────╯")
+
+    return "\n".join(lines)

mcp_hangar/server/validation.py

@@ -0,0 +1,113 @@
+"""Validation and error handling for MCP tools.
+
+This module provides validation functions that use the ApplicationContext
+for accessing rate limiter and security handler, following DIP.
+"""
+
+from ..application.mcp.tooling import ToolErrorPayload
+from ..domain.exceptions import RateLimitExceeded
+from ..domain.security.input_validator import (
+    validate_arguments,
+    validate_provider_id,
+    validate_timeout,
+    validate_tool_name,
+)
+from .context import get_context
+
+
+def check_rate_limit(key: str = "global") -> None:
+    """Check rate limit and raise exception if exceeded.
+
+    Gets rate limiter from application context (DIP).
+    """
+    ctx = get_context()
+    result = ctx.rate_limiter.consume(key)
+    if not result.allowed:
+        ctx.security_handler.log_rate_limit_exceeded(
+            limit=result.limit,
+            window_seconds=int(1.0 / result.limit) if result.limit else 1,
+        )
+        raise RateLimitExceeded(
+            limit=result.limit,
+            window_seconds=int(1.0 / result.limit) if result.limit else 1,
+        )
+
+
+def tool_error_mapper(exc: Exception) -> ToolErrorPayload:
+    """Map exceptions to a stable MCP tool error payload."""
+    return ToolErrorPayload(
+        error=str(exc) or "unknown error",
+        error_type=type(exc).__name__,
+        details={},
+    )
+
+
+def tool_error_hook(exc: Exception, context: dict) -> None:
+    """Best-effort hook for logging/security telemetry on tool failures.
+
+    Gets security handler from application context (DIP).
+
+    Args:
+        exc: The exception that occurred.
+        context: Additional context dict with provider_id, tool, etc.
+    """
+    try:
+        ctx = get_context()
+        ctx.security_handler.log_validation_failed(
+            field="tool",
+            message=f"{type(exc).__name__}: {str(exc) or 'unknown error'}",
+            provider_id=context.get("provider_id"),
+            value=context.get("provider_id"),
+        )
+    except (RuntimeError, AttributeError, TypeError):
+        # Context not initialized or handler missing - skip silently
+        pass
+
+
+def validate_provider_id_input(provider: str) -> None:
+    """Validate provider ID and raise exception if invalid."""
+    result = validate_provider_id(provider)
+    if not result.valid:
+        ctx = get_context()
+        ctx.security_handler.log_validation_failed(
+            field="provider",
+            message=(result.errors[0].message if result.errors else "Invalid provider ID"),
+            provider_id=provider,
+        )
+        raise ValueError(f"invalid_provider_id: {result.errors[0].message if result.errors else 'validation failed'}")
+
+
+def validate_tool_name_input(tool: str) -> None:
+    """Validate tool name and raise exception if invalid."""
+    result = validate_tool_name(tool)
+    if not result.valid:
+        ctx = get_context()
+        ctx.security_handler.log_validation_failed(
+            field="tool",
+            message=result.errors[0].message if result.errors else "Invalid tool name",
+        )
+        raise ValueError(f"invalid_tool_name: {result.errors[0].message if result.errors else 'validation failed'}")
+
+
+def validate_arguments_input(arguments: dict) -> None:
+    """Validate tool arguments and raise exception if invalid."""
+    result = validate_arguments(arguments)
+    if not result.valid:
+        ctx = get_context()
+        ctx.security_handler.log_validation_failed(
+            field="arguments",
+            message=result.errors[0].message if result.errors else "Invalid arguments",
+        )
+        raise ValueError(f"invalid_arguments: {result.errors[0].message if result.errors else 'validation failed'}")
+
+
+def validate_timeout_input(timeout: float) -> None:
+    """Validate timeout and raise exception if invalid."""
+    result = validate_timeout(timeout)
+    if not result.valid:
+        ctx = get_context()
+        ctx.security_handler.log_validation_failed(
+            field="timeout",
+            message=result.errors[0].message if result.errors else "Invalid timeout",
+        )
+        raise ValueError(f"invalid_timeout: {result.errors[0].message if result.errors else 'validation failed'}")

mcp_hangar/stdio_client.py

@@ -0,0 +1,229 @@
+"""Thread-safe stdio client with proper message correlation."""
+
+from dataclasses import dataclass
+import json
+from queue import Empty, Queue
+import subprocess
+import threading
+import time
+from typing import Any, Dict
+import uuid
+
+from .domain.exceptions import ClientError
+from .logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class PendingRequest:
+    """Tracks a pending RPC request waiting for a response."""
+
+    request_id: str
+    result_queue: Queue
+    started_at: float
+
+
+class StdioClient:
+    """
+    Thread-safe JSON-RPC client over stdio.
+    Handles message correlation, timeouts, and process lifecycle.
+    """
+
+    def __init__(self, popen: subprocess.Popen):
+        """
+        Initialize client with a running subprocess.
+
+        Args:
+            popen: subprocess.Popen instance with stdin/stdout pipes
+        """
+        self.process = popen
+        self.pending: Dict[str, PendingRequest] = {}
+        self.pending_lock = threading.Lock()
+        self.reader_thread = threading.Thread(target=self._reader_loop, daemon=True)
+        self.closed = False
+        self.reader_thread.start()
+
+    def _reader_loop(self):
+        """
+        Read stdout and dispatch responses to waiting callers.
+        Runs in a dedicated daemon thread.
+        """
+        logger.info("stdio_client_reader_started", pid=self.process.pid)
+        while not self.closed:
+            try:
+                line = self.process.stdout.readline()
+                if not line:
+                    # EOF reached, process died
+                    logger.warning("stdio_client_eof_on_stdout")
+                    self._capture_process_stderr()
+                    break
+
+                line = line.strip()
+                if not line:
+                    continue
+
+                try:
+                    msg = json.loads(line)
+                except json.JSONDecodeError as e:
+                    logger.error("stdio_client_malformed_json", preview=line[:100], error=str(e))
+                    continue
+
+                msg_id = msg.get("id")
+
+                if msg_id:
+                    # This is a response to a request
+                    with self.pending_lock:
+                        pending = self.pending.pop(msg_id, None)
+
+                    if pending:
+                        pending.result_queue.put(msg)
+                    else:
+                        logger.warning("stdio_client_unknown_request", request_id=msg_id)
+                else:
+                    # Unsolicited notification - log and ignore
+                    logger.debug("stdio_client_notification", message=msg)
+
+            except Exception as e:
+                logger.error("stdio_client_reader_error", error=str(e))
+                break
+
+        # Clean up on exit
+        self._cleanup_pending("reader_died")
+
+    def _capture_process_stderr(self) -> None:
+        """Capture and log stderr from the process for debugging."""
+        try:
+            # Log exit code
+            rc = self.process.poll()
+            if rc is not None:
+                logger.error("stdio_client_process_exited", exit_code=rc)
+
+            # Try to read stderr if available
+            stderr = getattr(self.process, "stderr", None)
+            if stderr:
+                try:
+                    # Read available stderr (non-blocking would be ideal, but read() works post-exit)
+                    err_bytes = stderr.read()
+                    if err_bytes:
+                        err_text = (
+                            err_bytes if isinstance(err_bytes, str) else err_bytes.decode(errors="replace")
+                        ).strip()
+                        if err_text:
+                            # Log first 2000 chars to avoid log spam
+                            if len(err_text) > 2000:
+                                err_text = err_text[:2000] + "... (truncated)"
+                            logger.error("stdio_client_process_stderr", stderr=err_text)
+                except Exception as read_err:
+                    logger.debug("stdio_client_stderr_read_failed", error=str(read_err))
+        except Exception as e:
+            logger.debug("stdio_client_capture_error", error=str(e))
+
+    def _cleanup_pending(self, error_msg: str):
+        """Clean up all pending requests on shutdown or error."""
+        with self.pending_lock:
+            for pending in self.pending.values():
+                pending.result_queue.put({"error": {"code": -1, "message": error_msg}})
+            self.pending.clear()
+
+    def call(self, method: str, params: Dict[str, Any], timeout: float = 15.0) -> Dict[str, Any]:
+        """
+        Synchronous RPC call with explicit timeout.
+
+        Args:
+            method: JSON-RPC method name
+            params: Method parameters
+            timeout: Timeout in seconds
+
+        Returns:
+            Response dictionary with either 'result' or 'error' key
+
+        Raises:
+            ClientError: If the client is closed or write fails
+            TimeoutError: If the request times out
+        """
+        if self.closed:
+            raise ClientError("client_closed")
+
+        request_id = str(uuid.uuid4())
+        result_queue = Queue(maxsize=1)
+
+        pending = PendingRequest(request_id=request_id, result_queue=result_queue, started_at=time.time())
+
+        with self.pending_lock:
+            self.pending[request_id] = pending
+
+        request = {
+            "jsonrpc": "2.0",
+            "id": request_id,
+            "method": method,
+            "params": params,
+        }
+
+        try:
+            request_str = json.dumps(request) + "\n"
+            logger.info(
+                "stdio_client_sending_request",
+                method=method,
+                pid=self.process.pid,
+                alive=self.process.poll() is None,
+            )
+            self.process.stdin.write(request_str)
+            self.process.stdin.flush()
+            logger.debug("stdio_client_request_sent")
+        except Exception as e:
+            logger.error("stdio_client_write_failed", error=str(e))
+            with self.pending_lock:
+                self.pending.pop(request_id, None)
+            raise ClientError(f"write_failed: {e}")
+
+        try:
+            response = result_queue.get(timeout=timeout)
+            return response
+        except Empty:
+            with self.pending_lock:
+                self.pending.pop(request_id, None)
+            raise TimeoutError(f"timeout: {method} after {timeout}s")
+
+    def is_alive(self) -> bool:
+        """Check if the underlying process is still running."""
+        return self.process.poll() is None
+
+    def close(self):
+        """
+        Graceful shutdown: attempt RPC shutdown, then terminate process.
+        Safe to call multiple times.
+        """
+        if self.closed:
+            return
+
+        self.closed = True
+
+        # Try graceful shutdown via RPC
+        try:
+            self.call("shutdown", {}, timeout=3.0)
+        except Exception as e:
+            logger.debug("stdio_client_shutdown_rpc_failed", error=str(e))
+
+        # Terminate process
+        try:
+            if self.process.poll() is None:
+                self.process.terminate()
+                try:
+                    self.process.wait(timeout=5.0)
+                except subprocess.TimeoutExpired:
+                    logger.warning("stdio_client_process_terminate_timeout")
+                    self.process.kill()
+                    self.process.wait()
+        except Exception as e:
+            logger.error("stdio_client_cleanup_error", error=str(e))
+
+        # Clean up any remaining pending requests
+        self._cleanup_pending("client_closed")
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+        return False