mcp-hangar 0.2.0__py3-none-any.whl

mcp_hangar/application/mcp/tooling.py

@@ -0,0 +1,158 @@
+"""MCP tool wiring utilities.
+
+This module provides a decorator for MCP tool functions to standardize:
+- rate limiting
+- input validation
+- consistent error mapping
+- structured security logging hooks
+
+It is intentionally framework-agnostic: it does not import FastMCP directly.
+The decorator is meant to be applied to functions already registered via
+`@mcp.tool(...)` in `registry/server.py`.
+
+Design notes:
+- The decorator takes callables for rate limiting, validation, and error mapping.
+- It keeps the wrapped function signature compatible with MCP tool calling.
+- There is no async support here (current tools are sync). If you add async tools,
+  we can extend this with an async-aware wrapper.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import wraps
+from typing import Any, Callable, Dict, Optional, TypeVar
+
+from ...logging_config import get_logger
+
+logger = get_logger(__name__)
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+@dataclass(frozen=True)
+class ToolErrorPayload:
+    """Normalized error payload returned to MCP client.
+
+    MCP tools often return structured output; we keep this minimal and stable.
+    """
+
+    error: str
+    error_type: str
+    details: Dict[str, Any]
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "error": self.error,
+            "type": self.error_type,
+            "details": self.details,
+        }
+
+
+def _default_error_mapper(exc: Exception) -> ToolErrorPayload:
+    """Fallback error mapper."""
+    return ToolErrorPayload(
+        error=str(exc) or "unknown error",
+        error_type=type(exc).__name__,
+        details={},
+    )
+
+
+def mcp_tool_wrapper(
+    *,
+    tool_name: str,
+    rate_limit_key: Callable[..., str],
+    check_rate_limit: Callable[[str], None],
+    validate: Optional[Callable[..., None]] = None,
+    error_mapper: Optional[Callable[[Exception], ToolErrorPayload]] = None,
+    on_error: Optional[Callable[[Exception, Dict[str, Any]], None]] = None,
+) -> Callable[[F], F]:
+    """Decorator to standardize MCP tool behavior.
+
+    Args:
+        tool_name: Human-readable tool name (used in error payload metadata).
+        rate_limit_key: Callable that builds a rate limit bucket key from args/kwargs.
+        check_rate_limit: Callable that enforces rate limit for the computed key.
+                          Should raise (e.g. RateLimitExceeded) when exceeded.
+        validate: Optional callable to validate inputs. Should raise ValueError on invalid input.
+                  Signature should match the wrapped tool function.
+        error_mapper: Optional callable mapping Exception -> ToolErrorPayload.
+                      If omitted, a minimal default is used.
+        on_error: Optional hook called on exception with (exc, context_dict).
+
+    Returns:
+        Decorated function.
+    """
+    mapper = error_mapper or _default_error_mapper
+
+    def decorator(func: F) -> F:
+        @wraps(func)
+        def wrapped(*args: Any, **kwargs: Any) -> Any:
+            # Rate limit first (cheapest check) to reduce abuse surface.
+            key = rate_limit_key(*args, **kwargs)
+            check_rate_limit(key)
+
+            # Validate inputs if provided.
+            if validate is not None:
+                validate(*args, **kwargs)
+
+            try:
+                return func(*args, **kwargs)
+            except Exception as exc:
+                # Optional error hook (e.g. security auditing).
+                if on_error is not None:
+                    try:
+                        on_error(
+                            exc,
+                            {
+                                "tool": tool_name,
+                                "rate_limit_key": key,
+                                "args_count": len(args),
+                                "kwargs_keys": list(kwargs.keys()),
+                            },
+                        )
+                    except (TypeError, ValueError, RuntimeError) as hook_err:
+                        # Never let the error hook override the original failure.
+                        # Log but don't propagate hook errors.
+                        logger.debug(
+                            "error_hook_failed",
+                            tool=tool_name,
+                            hook_error=str(hook_err),
+                        )
+
+                payload = mapper(exc)
+                # Return a stable, tool-friendly dict. MCP will surface this as tool error.
+                return payload.to_dict()
+
+        return wrapped  # type: ignore[misc]
+
+    return decorator
+
+
+def key_global(*_: Any, **__: Any) -> str:
+    """Rate limit key for globally-scoped tools."""
+    return "global"
+
+
+def key_per_provider(provider: str, *_: Any, **__: Any) -> str:
+    """Rate limit key scoped per provider."""
+    return f"provider:{provider}"
+
+
+def key_registry_invoke(provider: str, tool: str, *_: Any, **__: Any) -> str:
+    """Rate limit key specialized for tool invocation (per provider)."""
+    # Keep it coarse by default to avoid key explosion; include tool name if desired.
+    return f"registry_invoke:{provider}"
+
+
+def chain_validators(*validators: Callable[..., None]) -> Callable[..., None]:
+    """Combine multiple validators into a single callable.
+
+    Each validator is called in order. First exception stops the chain.
+    """
+
+    def _combined(*args: Any, **kwargs: Any) -> None:
+        for v in validators:
+            v(*args, **kwargs)
+
+    return _combined

mcp_hangar/application/ports/__init__.py

@@ -0,0 +1,9 @@
+"""Application ports - interfaces for external dependencies."""
+
+from .observability import NullObservabilityAdapter, ObservabilityPort, SpanHandle
+
+__all__ = [
+    "ObservabilityPort",
+    "SpanHandle",
+    "NullObservabilityAdapter",
+]

mcp_hangar/application/ports/observability.py

@@ -0,0 +1,237 @@
+"""Port for observability integrations (Langfuse, OpenTelemetry, etc.).
+
+This module defines the interface for tracing tool invocations and recording
+metrics. Implementations adapt external observability platforms to this contract.
+
+Example usage:
+    observability = get_observability_adapter(config)
+    span = observability.start_tool_span("math", "add", {"a": 1, "b": 2})
+    try:
+        result = provider.invoke(...)
+        span.end_success(result)
+    except Exception as e:
+        span.end_error(e)
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class TraceContext:
+    """Value object for trace context propagation across MCP calls.
+
+    Enables correlation of traces from external LLM applications
+    through MCP Hangar to individual provider invocations.
+
+    Attributes:
+        trace_id: Unique identifier for the trace.
+        span_id: Identifier for the parent span (optional).
+        user_id: User identifier for attribution (optional).
+        session_id: Session identifier for grouping (optional).
+    """
+
+    trace_id: str
+    span_id: str | None = None
+    user_id: str | None = None
+    session_id: str | None = None
+
+
+@dataclass
+class SpanData:
+    """Data collected during a traced span.
+
+    Attributes:
+        name: Human-readable span name.
+        input_data: Input parameters for the operation.
+        output_data: Result of the operation (set on completion).
+        metadata: Additional context for the span.
+        error: Error if the span ended with failure.
+        duration_ms: Duration of the span in milliseconds.
+    """
+
+    name: str
+    input_data: dict[str, Any] = field(default_factory=dict)
+    output_data: Any = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    error: Exception | None = None
+    duration_ms: float | None = None
+
+
+class SpanHandle(ABC):
+    """Handle for an active observability span.
+
+    Implementations should capture timing and allow setting
+    success/failure status with output data.
+    """
+
+    @abstractmethod
+    def end_success(self, output: Any) -> None:
+        """End the span with a successful outcome.
+
+        Args:
+            output: The result data from the traced operation.
+        """
+        ...
+
+    @abstractmethod
+    def end_error(self, error: Exception) -> None:
+        """End the span with an error.
+
+        Args:
+            error: The exception that caused the failure.
+        """
+        ...
+
+    @abstractmethod
+    def set_metadata(self, key: str, value: Any) -> None:
+        """Add metadata to the span.
+
+        Args:
+            key: Metadata key.
+            value: Metadata value (must be JSON-serializable).
+        """
+        ...
+
+
+class ObservabilityPort(ABC):
+    """Port interface for observability integrations.
+
+    Implementations adapt external platforms (Langfuse, OpenTelemetry, etc.)
+    to provide tracing and scoring capabilities for MCP tool invocations.
+    """
+
+    @abstractmethod
+    def start_tool_span(
+        self,
+        provider_name: str,
+        tool_name: str,
+        input_params: dict[str, Any],
+        trace_context: TraceContext | None = None,
+    ) -> SpanHandle:
+        """Start a traced span for a tool invocation.
+
+        Args:
+            provider_name: Name of the MCP provider.
+            tool_name: Name of the tool being invoked.
+            input_params: Input arguments for the tool.
+            trace_context: Optional context for trace propagation.
+
+        Returns:
+            Handle to manage the span lifecycle.
+        """
+        ...
+
+    @abstractmethod
+    def record_score(
+        self,
+        trace_id: str,
+        name: str,
+        value: float,
+        comment: str | None = None,
+    ) -> None:
+        """Record a score/metric on a trace.
+
+        Useful for recording provider health, latency, or quality metrics.
+
+        Args:
+            trace_id: The trace to attach the score to.
+            name: Score name (e.g., "provider_health", "latency_ms").
+            value: Numeric score value.
+            comment: Optional description.
+        """
+        ...
+
+    @abstractmethod
+    def record_health_check(
+        self,
+        provider_name: str,
+        healthy: bool,
+        latency_ms: float,
+        trace_id: str | None = None,
+    ) -> None:
+        """Record a health check result.
+
+        Args:
+            provider_name: Name of the provider.
+            healthy: Whether the health check passed.
+            latency_ms: Health check latency in milliseconds.
+            trace_id: Optional trace to attach the result to.
+        """
+        ...
+
+    @abstractmethod
+    def flush(self) -> None:
+        """Flush any pending events to the backend."""
+        ...
+
+    @abstractmethod
+    def shutdown(self) -> None:
+        """Gracefully shutdown with final flush."""
+        ...
+
+
+class NullSpanHandle(SpanHandle):
+    """No-op span handle when observability is disabled."""
+
+    def end_success(self, output: Any) -> None:
+        """No-op success."""
+        pass
+
+    def end_error(self, error: Exception) -> None:
+        """No-op error."""
+        pass
+
+    def set_metadata(self, key: str, value: Any) -> None:
+        """No-op metadata."""
+        pass
+
+
+class NullObservabilityAdapter(ObservabilityPort):
+    """No-op implementation when observability is disabled.
+
+    This adapter silently discards all tracing and scoring calls,
+    allowing the application to run without any observability overhead.
+    """
+
+    def start_tool_span(
+        self,
+        provider_name: str,
+        tool_name: str,
+        input_params: dict[str, Any],
+        trace_context: TraceContext | None = None,
+    ) -> SpanHandle:
+        """Return a no-op span handle."""
+        return NullSpanHandle()
+
+    def record_score(
+        self,
+        trace_id: str,
+        name: str,
+        value: float,
+        comment: str | None = None,
+    ) -> None:
+        """Discard the score."""
+        pass
+
+    def record_health_check(
+        self,
+        provider_name: str,
+        healthy: bool,
+        latency_ms: float,
+        trace_id: str | None = None,
+    ) -> None:
+        """Discard the health check result."""
+        pass
+
+    def flush(self) -> None:
+        """No-op flush."""
+        pass
+
+    def shutdown(self) -> None:
+        """No-op shutdown."""
+        pass

mcp_hangar/application/queries/__init__.py

@@ -0,0 +1,52 @@
+"""Query handlers for CQRS."""
+
+from .auth_handlers import (
+    CheckPermissionHandler,
+    GetApiKeyCountHandler,
+    GetApiKeysByPrincipalHandler,
+    GetRoleHandler,
+    GetRolesForPrincipalHandler,
+    ListBuiltinRolesHandler,
+    register_auth_query_handlers,
+)
+from .auth_queries import (
+    CheckPermissionQuery,
+    GetApiKeyCountQuery,
+    GetApiKeysByPrincipalQuery,
+    GetRoleQuery,
+    GetRolesForPrincipalQuery,
+    ListBuiltinRolesQuery,
+)
+from .handlers import (
+    GetProviderHandler,
+    GetProviderHealthHandler,
+    GetProviderToolsHandler,
+    GetSystemMetricsHandler,
+    ListProvidersHandler,
+    register_all_handlers,
+)
+
+__all__ = [
+    # Provider Query Handlers
+    "ListProvidersHandler",
+    "GetProviderHandler",
+    "GetProviderToolsHandler",
+    "GetProviderHealthHandler",
+    "GetSystemMetricsHandler",
+    "register_all_handlers",
+    # Auth Queries
+    "GetApiKeysByPrincipalQuery",
+    "GetApiKeyCountQuery",
+    "GetRolesForPrincipalQuery",
+    "GetRoleQuery",
+    "ListBuiltinRolesQuery",
+    "CheckPermissionQuery",
+    # Auth Query Handlers
+    "GetApiKeysByPrincipalHandler",
+    "GetApiKeyCountHandler",
+    "GetRolesForPrincipalHandler",
+    "GetRoleHandler",
+    "ListBuiltinRolesHandler",
+    "CheckPermissionHandler",
+    "register_auth_query_handlers",
+]

mcp_hangar/application/queries/auth_handlers.py

@@ -0,0 +1,237 @@
+"""Authentication and Authorization query handlers.
+
+Implements CQRS query handlers for auth read operations.
+These handlers only read data, never modify state.
+"""
+
+from typing import Any
+
+from ...domain.contracts.authentication import IApiKeyStore
+from ...domain.contracts.authorization import IRoleStore
+from ...domain.security.roles import BUILTIN_ROLES
+from ...infrastructure.query_bus import QueryHandler
+from ...logging_config import get_logger
+from .auth_queries import (
+    CheckPermissionQuery,
+    GetApiKeyCountQuery,
+    GetApiKeysByPrincipalQuery,
+    GetRoleQuery,
+    GetRolesForPrincipalQuery,
+    ListBuiltinRolesQuery,
+)
+
+logger = get_logger(__name__)
+
+
+# =============================================================================
+# API Key Query Handlers
+# =============================================================================
+
+
+class GetApiKeysByPrincipalHandler(QueryHandler):
+    """Handler for GetApiKeysByPrincipalQuery."""
+
+    def __init__(self, api_key_store: IApiKeyStore):
+        self._store = api_key_store
+
+    def handle(self, query: GetApiKeysByPrincipalQuery) -> dict[str, Any]:
+        """Get all API keys for a principal.
+
+        Returns:
+            Dict with list of key metadata.
+        """
+        keys = self._store.list_keys(query.principal_id)
+
+        if not query.include_revoked:
+            keys = [k for k in keys if not k.revoked]
+
+        return {
+            "principal_id": query.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
+            ],
+            "total": len(keys),
+            "active": sum(1 for k in keys if not k.revoked),
+        }
+
+
+class GetApiKeyCountHandler(QueryHandler):
+    """Handler for GetApiKeyCountQuery."""
+
+    def __init__(self, api_key_store: IApiKeyStore):
+        self._store = api_key_store
+
+    def handle(self, query: GetApiKeyCountQuery) -> dict[str, Any]:
+        """Get count of active API keys for a principal.
+
+        Returns:
+            Dict with key count.
+        """
+        count = self._store.count_keys(query.principal_id)
+
+        return {
+            "principal_id": query.principal_id,
+            "active_keys": count,
+        }
+
+
+# =============================================================================
+# Role Query Handlers
+# =============================================================================
+
+
+class GetRolesForPrincipalHandler(QueryHandler):
+    """Handler for GetRolesForPrincipalQuery."""
+
+    def __init__(self, role_store: IRoleStore):
+        self._store = role_store
+
+    def handle(self, query: GetRolesForPrincipalQuery) -> dict[str, Any]:
+        """Get all roles assigned to a principal.
+
+        Returns:
+            Dict with list of roles.
+        """
+        roles = self._store.get_roles_for_principal(
+            principal_id=query.principal_id,
+            scope=query.scope,
+        )
+
+        return {
+            "principal_id": query.principal_id,
+            "scope": query.scope,
+            "roles": [
+                {
+                    "name": r.name,
+                    "description": r.description,
+                    "permissions": [str(p) for p in r.permissions],
+                }
+                for r in roles
+            ],
+            "count": len(roles),
+        }
+
+
+class GetRoleHandler(QueryHandler):
+    """Handler for GetRoleQuery."""
+
+    def __init__(self, role_store: IRoleStore):
+        self._store = role_store
+
+    def handle(self, query: GetRoleQuery) -> dict[str, Any]:
+        """Get a specific role by name.
+
+        Returns:
+            Dict with role details or None.
+        """
+        role = self._store.get_role(query.role_name)
+
+        if role is None:
+            return {"role": None, "found": False}
+
+        return {
+            "found": True,
+            "role": {
+                "name": role.name,
+                "description": role.description,
+                "permissions": [str(p) for p in role.permissions],
+                "permissions_count": len(role.permissions),
+            },
+        }
+
+
+class ListBuiltinRolesHandler(QueryHandler):
+    """Handler for ListBuiltinRolesQuery."""
+
+    def handle(self, query: ListBuiltinRolesQuery) -> dict[str, Any]:
+        """List all built-in roles.
+
+        Returns:
+            Dict with list of built-in roles.
+        """
+        return {
+            "roles": [
+                {
+                    "name": name,
+                    "description": role.description,
+                    "permissions_count": len(role.permissions),
+                }
+                for name, role in BUILTIN_ROLES.items()
+            ],
+            "count": len(BUILTIN_ROLES),
+        }
+
+
+class CheckPermissionHandler(QueryHandler):
+    """Handler for CheckPermissionQuery."""
+
+    def __init__(self, role_store: IRoleStore):
+        self._store = role_store
+
+    def handle(self, query: CheckPermissionQuery) -> dict[str, Any]:
+        """Check if a principal has a specific permission.
+
+        Returns:
+            Dict with permission check result.
+        """
+        roles = self._store.get_roles_for_principal(query.principal_id)
+
+        for role in roles:
+            if role.has_permission(
+                resource_type=query.resource_type,
+                action=query.action,
+                resource_id=query.resource_id,
+            ):
+                return {
+                    "principal_id": query.principal_id,
+                    "action": query.action,
+                    "resource_type": query.resource_type,
+                    "resource_id": query.resource_id,
+                    "allowed": True,
+                    "granted_by_role": role.name,
+                }
+
+        return {
+            "principal_id": query.principal_id,
+            "action": query.action,
+            "resource_type": query.resource_type,
+            "resource_id": query.resource_id,
+            "allowed": False,
+            "granted_by_role": None,
+        }
+
+
+def register_auth_query_handlers(
+    query_bus,
+    api_key_store: IApiKeyStore | None = None,
+    role_store: IRoleStore | None = None,
+) -> None:
+    """Register all auth query handlers with the query bus.
+
+    Args:
+        query_bus: QueryBus 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:
+        query_bus.register(GetApiKeysByPrincipalQuery, GetApiKeysByPrincipalHandler(api_key_store))
+        query_bus.register(GetApiKeyCountQuery, GetApiKeyCountHandler(api_key_store))
+        logger.info("auth_api_key_query_handlers_registered")
+
+    if role_store:
+        query_bus.register(GetRolesForPrincipalQuery, GetRolesForPrincipalHandler(role_store))
+        query_bus.register(GetRoleQuery, GetRoleHandler(role_store))
+        query_bus.register(CheckPermissionQuery, CheckPermissionHandler(role_store))
+        logger.info("auth_role_query_handlers_registered")
+
+    # ListBuiltinRolesQuery doesn't need a store
+    query_bus.register(ListBuiltinRolesQuery, ListBuiltinRolesHandler())
+    logger.info("auth_builtin_roles_query_handler_registered")