kailash 0.3.0__py3-none-any.whl → 0.3.2__py3-none-any.whl

kailash/mcp/utils/formatters.py

@@ -0,0 +1,293 @@
+"""
+Response formatting utilities for MCP servers.
+
+Provides consistent formatting for tool responses, making them more readable
+and structured for LLM consumption.
+"""
+
+import json
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Union
+
+
+class ResponseFormatter:
+    """Base class for response formatters."""
+
+    def format(self, data: Any, **kwargs) -> str:
+        """Format data into string representation."""
+        raise NotImplementedError
+
+
+class JSONFormatter(ResponseFormatter):
+    """Format responses as pretty-printed JSON."""
+
+    def __init__(self, indent: int = 2, ensure_ascii: bool = False):
+        self.indent = indent
+        self.ensure_ascii = ensure_ascii
+
+    def format(self, data: Any, **kwargs) -> str:
+        """Format data as JSON string."""
+        try:
+            return json.dumps(
+                data,
+                indent=self.indent,
+                ensure_ascii=self.ensure_ascii,
+                default=self._json_serializer,
+            )
+        except Exception as e:
+            return f"Error formatting JSON: {e}"
+
+    def _json_serializer(self, obj):
+        """Handle non-serializable objects."""
+        if isinstance(obj, datetime):
+            return obj.isoformat()
+        return str(obj)
+
+
+class MarkdownFormatter(ResponseFormatter):
+    """Format responses as Markdown for better readability."""
+
+    def format(self, data: Any, title: Optional[str] = None, **kwargs) -> str:
+        """Format data as Markdown."""
+        if isinstance(data, dict):
+            return self._format_dict(data, title)
+        elif isinstance(data, list):
+            return self._format_list(data, title)
+        else:
+            return self._format_simple(data, title)
+
+    def _format_dict(self, data: Dict[str, Any], title: Optional[str] = None) -> str:
+        """Format dictionary as Markdown."""
+        lines = []
+
+        if title:
+            lines.append(f"# {title}\n")
+
+        for key, value in data.items():
+            lines.append(f"**{key}**: {self._format_value(value)}")
+
+        return "\n".join(lines)
+
+    def _format_list(self, data: List[Any], title: Optional[str] = None) -> str:
+        """Format list as Markdown."""
+        lines = []
+
+        if title:
+            lines.append(f"# {title}\n")
+
+        for i, item in enumerate(data, 1):
+            if isinstance(item, dict):
+                lines.append(f"## {i}. Item")
+                for key, value in item.items():
+                    lines.append(f"- **{key}**: {self._format_value(value)}")
+                lines.append("")
+            else:
+                lines.append(f"{i}. {self._format_value(item)}")
+
+        return "\n".join(lines)
+
+    def _format_simple(self, data: Any, title: Optional[str] = None) -> str:
+        """Format simple value as Markdown."""
+        lines = []
+
+        if title:
+            lines.append(f"# {title}\n")
+
+        lines.append(str(data))
+        return "\n".join(lines)
+
+    def _format_value(self, value: Any) -> str:
+        """Format individual value."""
+        if isinstance(value, (list, tuple)) and len(value) <= 5:
+            return ", ".join(str(v) for v in value)
+        elif isinstance(value, dict) and len(value) <= 3:
+            return ", ".join(f"{k}: {v}" for k, v in value.items())
+        else:
+            return str(value)
+
+
+class TableFormatter(ResponseFormatter):
+    """Format tabular data as ASCII tables."""
+
+    def format(
+        self, data: List[Dict[str, Any]], headers: Optional[List[str]] = None, **kwargs
+    ) -> str:
+        """Format list of dictionaries as ASCII table."""
+        if not data:
+            return "No data available"
+
+        if not isinstance(data, list) or not all(
+            isinstance(item, dict) for item in data
+        ):
+            return "Data must be a list of dictionaries for table formatting"
+
+        # Determine headers
+        if headers is None:
+            headers = list(data[0].keys()) if data else []
+
+        # Calculate column widths
+        col_widths = {}
+        for header in headers:
+            col_widths[header] = len(header)
+
+        for row in data:
+            for header in headers:
+                value = str(row.get(header, ""))
+                col_widths[header] = max(col_widths[header], len(value))
+
+        # Build table
+        lines = []
+
+        # Header row
+        header_line = " | ".join(header.ljust(col_widths[header]) for header in headers)
+        lines.append(header_line)
+
+        # Separator
+        separator = "-+-".join("-" * col_widths[header] for header in headers)
+        lines.append(separator)
+
+        # Data rows
+        for row in data:
+            row_line = " | ".join(
+                str(row.get(header, "")).ljust(col_widths[header]) for header in headers
+            )
+            lines.append(row_line)
+
+        return "\n".join(lines)
+
+
+class SearchResultFormatter(ResponseFormatter):
+    """Specialized formatter for search results."""
+
+    def format(
+        self,
+        results: List[Dict[str, Any]],
+        query: Optional[str] = None,
+        total_count: Optional[int] = None,
+        **kwargs,
+    ) -> str:
+        """Format search results with query context."""
+        lines = []
+
+        # Header
+        if query:
+            lines.append(f"# Search Results for: '{query}'\n")
+        else:
+            lines.append("# Search Results\n")
+
+        # Summary
+        result_count = len(results)
+        if total_count and total_count > result_count:
+            lines.append(f"Showing {result_count} of {total_count} results\n")
+        else:
+            lines.append(f"Found {result_count} results\n")
+
+        # Results
+        for i, result in enumerate(results, 1):
+            lines.append(f"## {i}. {result.get('name', result.get('title', 'Result'))}")
+
+            # Score if available
+            if "_relevance_score" in result:
+                score = result["_relevance_score"]
+                lines.append(f"**Relevance**: {score:.2f}")
+
+            # Description
+            if "description" in result:
+                lines.append(f"{result['description']}")
+
+            # Additional fields
+            for key, value in result.items():
+                if key not in ["name", "title", "description", "_relevance_score"]:
+                    if isinstance(value, (list, tuple)):
+                        if value:  # Only show non-empty lists
+                            lines.append(
+                                f"**{key.title()}**: {', '.join(str(v) for v in value)}"
+                            )
+                    elif value:  # Only show non-empty values
+                        lines.append(f"**{key.title()}**: {value}")
+
+            lines.append("")  # Empty line between results
+
+        return "\n".join(lines)
+
+
+class MetricsFormatter(ResponseFormatter):
+    """Specialized formatter for metrics data."""
+
+    def format(self, metrics: Dict[str, Any], **kwargs) -> str:
+        """Format metrics data in human-readable format."""
+        lines = []
+        lines.append("# Server Metrics\n")
+
+        # Server stats
+        if "server" in metrics:
+            server = metrics["server"]
+            lines.append("## Server Statistics")
+            lines.append(
+                f"- **Uptime**: {self._format_duration(server.get('uptime_seconds', 0))}"
+            )
+            lines.append(f"- **Total Calls**: {server.get('total_calls', 0):,}")
+            lines.append(f"- **Total Errors**: {server.get('total_errors', 0):,}")
+            lines.append(f"- **Error Rate**: {server.get('overall_error_rate', 0):.2%}")
+            lines.append(f"- **Calls/Second**: {server.get('calls_per_second', 0):.2f}")
+            lines.append("")
+
+        # Tool stats
+        if "tools" in metrics and metrics["tools"]:
+            lines.append("## Tool Statistics")
+            for tool_name, stats in metrics["tools"].items():
+                lines.append(f"### {tool_name}")
+                lines.append(f"- **Calls**: {stats.get('calls', 0):,}")
+                lines.append(f"- **Errors**: {stats.get('errors', 0):,}")
+                lines.append(f"- **Error Rate**: {stats.get('error_rate', 0):.2%}")
+
+                if "avg_latency" in stats:
+                    lines.append(f"- **Avg Latency**: {stats['avg_latency']:.3f}s")
+                    lines.append(f"- **P95 Latency**: {stats['p95_latency']:.3f}s")
+
+                lines.append("")
+
+        return "\n".join(lines)
+
+    def _format_duration(self, seconds: float) -> str:
+        """Format duration in human-readable format."""
+        if seconds < 60:
+            return f"{seconds:.1f} seconds"
+        elif seconds < 3600:
+            return f"{seconds/60:.1f} minutes"
+        elif seconds < 86400:
+            return f"{seconds/3600:.1f} hours"
+        else:
+            return f"{seconds/86400:.1f} days"
+
+
+# Default formatter instances
+json_formatter = JSONFormatter()
+markdown_formatter = MarkdownFormatter()
+table_formatter = TableFormatter()
+search_formatter = SearchResultFormatter()
+metrics_formatter = MetricsFormatter()
+
+
+def format_response(data: Any, format_type: str = "json", **kwargs) -> str:
+    """
+    Format response using specified formatter.
+
+    Args:
+        data: Data to format
+        format_type: Type of formatting ("json", "markdown", "table", "search", "metrics")
+        **kwargs: Additional formatting options
+
+    Returns:
+        Formatted string
+    """
+    formatters = {
+        "json": json_formatter,
+        "markdown": markdown_formatter,
+        "table": table_formatter,
+        "search": search_formatter,
+        "metrics": metrics_formatter,
+    }
+
+    formatter = formatters.get(format_type, json_formatter)
+    return formatter.format(data, **kwargs)

kailash/mcp/utils/metrics.py

@@ -0,0 +1,418 @@
+"""
+Metrics collection for MCP servers.
+
+Provides comprehensive monitoring of MCP server performance including:
+- Tool usage statistics
+- Performance metrics (latency, throughput)
+- Cache performance
+- Error rates
+"""
+
+import asyncio
+import functools
+import logging
+import threading
+import time
+from collections import defaultdict, deque
+from typing import Any, Callable, Dict, List, Optional, TypeVar
+
+logger = logging.getLogger(__name__)
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class MetricsCollector:
+    """
+    Comprehensive metrics collection for MCP servers.
+
+    Tracks:
+    - Tool call frequency and latency
+    - Error rates and types
+    - Cache performance
+    - System resource usage
+    """
+
+    def __init__(
+        self,
+        enabled: bool = True,
+        collect_performance: bool = True,
+        collect_usage: bool = True,
+        history_size: int = 1000,
+    ):
+        """
+        Initialize metrics collector.
+
+        Args:
+            enabled: Whether metrics collection is enabled
+            collect_performance: Whether to collect performance metrics
+            collect_usage: Whether to collect usage statistics
+            history_size: Number of recent events to keep in memory
+        """
+        self.enabled = enabled
+        self.collect_performance = collect_performance
+        self.collect_usage = collect_usage
+        self.history_size = history_size
+
+        # Thread safety
+        self._lock = threading.RLock()
+
+        # Usage metrics
+        self._tool_calls = defaultdict(int)
+        self._tool_errors = defaultdict(int)
+        self._tool_latencies = defaultdict(list)
+
+        # Performance history
+        self._recent_calls = deque(maxlen=history_size)
+        self._recent_errors = deque(maxlen=history_size)
+
+        # System metrics
+        self._start_time = time.time()
+        self._total_calls = 0
+        self._total_errors = 0
+
+    def track_tool_call(
+        self,
+        tool_name: str,
+        latency: float,
+        success: bool = True,
+        error_type: Optional[str] = None,
+    ) -> None:
+        """Record a tool call metric."""
+        if not self.enabled:
+            return
+
+        with self._lock:
+            current_time = time.time()
+
+            # Update counters
+            self._total_calls += 1
+            if self.collect_usage:
+                self._tool_calls[tool_name] += 1
+
+            # Track latency
+            if self.collect_performance:
+                self._tool_latencies[tool_name].append(latency)
+                # Keep only recent latencies to prevent memory growth
+                if len(self._tool_latencies[tool_name]) > 100:
+                    self._tool_latencies[tool_name] = self._tool_latencies[tool_name][
+                        -100:
+                    ]
+
+            # Track errors
+            if not success:
+                self._total_errors += 1
+                if self.collect_usage:
+                    self._tool_errors[tool_name] += 1
+
+                if self.collect_performance:
+                    self._recent_errors.append(
+                        {
+                            "tool": tool_name,
+                            "timestamp": current_time,
+                            "error_type": error_type,
+                        }
+                    )
+
+            # Track recent calls
+            if self.collect_performance:
+                self._recent_calls.append(
+                    {
+                        "tool": tool_name,
+                        "timestamp": current_time,
+                        "latency": latency,
+                        "success": success,
+                    }
+                )
+
+    def track_tool(self, tool_name: Optional[str] = None):
+        """
+        Decorator to automatically track tool call metrics.
+
+        Args:
+            tool_name: Optional tool name override
+
+        Returns:
+            Decorated function with metrics tracking
+        """
+
+        def decorator(func: F) -> F:
+            if not self.enabled:
+                return func
+
+            actual_tool_name = tool_name or func.__name__
+
+            @functools.wraps(func)
+            def sync_wrapper(*args, **kwargs):
+                start_time = time.time()
+                success = True
+                error_type = None
+
+                try:
+                    result = func(*args, **kwargs)
+                    return result
+                except Exception as e:
+                    success = False
+                    error_type = type(e).__name__
+                    raise
+                finally:
+                    latency = time.time() - start_time
+                    self.track_tool_call(actual_tool_name, latency, success, error_type)
+
+            @functools.wraps(func)
+            async def async_wrapper(*args, **kwargs):
+                start_time = time.time()
+                success = True
+                error_type = None
+
+                try:
+                    result = await func(*args, **kwargs)
+                    return result
+                except Exception as e:
+                    success = False
+                    error_type = type(e).__name__
+                    raise
+                finally:
+                    latency = time.time() - start_time
+                    self.track_tool_call(actual_tool_name, latency, success, error_type)
+
+            # Return appropriate wrapper based on function type
+            if asyncio.iscoroutinefunction(func):
+                return async_wrapper
+            else:
+                return sync_wrapper
+
+        return decorator
+
+    def get_tool_stats(self) -> Dict[str, Dict[str, Any]]:
+        """Get statistics for all tools."""
+        with self._lock:
+            stats = {}
+
+            for tool_name in set(
+                list(self._tool_calls.keys()) + list(self._tool_errors.keys())
+            ):
+                calls = self._tool_calls[tool_name]
+                errors = self._tool_errors[tool_name]
+                latencies = self._tool_latencies.get(tool_name, [])
+
+                tool_stats = {
+                    "calls": calls,
+                    "errors": errors,
+                    "error_rate": errors / calls if calls > 0 else 0,
+                }
+
+                if latencies:
+                    tool_stats.update(
+                        {
+                            "avg_latency": sum(latencies) / len(latencies),
+                            "min_latency": min(latencies),
+                            "max_latency": max(latencies),
+                            "p95_latency": self._percentile(latencies, 95),
+                            "p99_latency": self._percentile(latencies, 99),
+                        }
+                    )
+
+                stats[tool_name] = tool_stats
+
+            return stats
+
+    def get_server_stats(self) -> Dict[str, Any]:
+        """Get overall server statistics."""
+        with self._lock:
+            uptime = time.time() - self._start_time
+
+            stats = {
+                "uptime_seconds": uptime,
+                "total_calls": self._total_calls,
+                "total_errors": self._total_errors,
+                "overall_error_rate": (
+                    self._total_errors / self._total_calls
+                    if self._total_calls > 0
+                    else 0
+                ),
+                "calls_per_second": self._total_calls / uptime if uptime > 0 else 0,
+            }
+
+            # Recent activity
+            if self.collect_performance:
+                recent_window = 300  # 5 minutes
+                current_time = time.time()
+
+                recent_calls = [
+                    call
+                    for call in self._recent_calls
+                    if current_time - call["timestamp"] <= recent_window
+                ]
+
+                if recent_calls:
+                    recent_latencies = [call["latency"] for call in recent_calls]
+                    recent_errors = sum(
+                        1 for call in recent_calls if not call["success"]
+                    )
+
+                    stats.update(
+                        {
+                            "recent_calls_5min": len(recent_calls),
+                            "recent_errors_5min": recent_errors,
+                            "recent_error_rate_5min": recent_errors / len(recent_calls),
+                            "recent_avg_latency_5min": sum(recent_latencies)
+                            / len(recent_latencies),
+                            "recent_p95_latency_5min": self._percentile(
+                                recent_latencies, 95
+                            ),
+                        }
+                    )
+
+            return stats
+
+    def get_error_summary(self) -> Dict[str, Any]:
+        """Get summary of recent errors."""
+        with self._lock:
+            if not self.collect_performance:
+                return {"error": "Performance collection disabled"}
+
+            recent_window = 3600  # 1 hour
+            current_time = time.time()
+
+            recent_errors = [
+                error
+                for error in self._recent_errors
+                if current_time - error["timestamp"] <= recent_window
+            ]
+
+            # Group by error type
+            error_types = defaultdict(int)
+            for error in recent_errors:
+                error_types[error.get("error_type", "Unknown")] += 1
+
+            # Group by tool
+            error_tools = defaultdict(int)
+            for error in recent_errors:
+                error_tools[error["tool"]] += 1
+
+            return {
+                "total_recent_errors": len(recent_errors),
+                "error_types": dict(error_types),
+                "error_by_tool": dict(error_tools),
+                "window_hours": 1,
+            }
+
+    def _percentile(self, values: List[float], percentile: int) -> float:
+        """Calculate percentile value."""
+        if not values:
+            return 0.0
+
+        sorted_values = sorted(values)
+        k = (len(sorted_values) - 1) * percentile / 100
+        f = int(k)
+        c = k - f
+
+        if f == len(sorted_values) - 1:
+            return sorted_values[f]
+        else:
+            return sorted_values[f] * (1 - c) + sorted_values[f + 1] * c
+
+    def export_metrics(self, format: str = "dict") -> Any:
+        """
+        Export all metrics in specified format.
+
+        Args:
+            format: Export format ("dict", "json", "prometheus")
+
+        Returns:
+            Metrics in requested format
+        """
+        with self._lock:
+            metrics = {
+                "server": self.get_server_stats(),
+                "tools": self.get_tool_stats(),
+                "errors": self.get_error_summary(),
+                "collection_config": {
+                    "enabled": self.enabled,
+                    "collect_performance": self.collect_performance,
+                    "collect_usage": self.collect_usage,
+                    "history_size": self.history_size,
+                },
+            }
+
+            if format == "dict":
+                return metrics
+            elif format == "json":
+                import json
+
+                return json.dumps(metrics, indent=2)
+            elif format == "prometheus":
+                return self._export_prometheus(metrics)
+            else:
+                raise ValueError(f"Unsupported export format: {format}")
+
+    def _export_prometheus(self, metrics: Dict[str, Any]) -> str:
+        """Export metrics in Prometheus format."""
+        lines = []
+
+        # Server metrics
+        server = metrics["server"]
+        lines.append(f"mcp_server_uptime_seconds {server['uptime_seconds']}")
+        lines.append(f"mcp_server_total_calls {server['total_calls']}")
+        lines.append(f"mcp_server_total_errors {server['total_errors']}")
+        lines.append(f"mcp_server_error_rate {server['overall_error_rate']}")
+        lines.append(f"mcp_server_calls_per_second {server['calls_per_second']}")
+
+        # Tool metrics
+        for tool_name, tool_stats in metrics["tools"].items():
+            labels = f'{{tool="{tool_name}"}}'
+            lines.append(f"mcp_tool_calls{labels} {tool_stats['calls']}")
+            lines.append(f"mcp_tool_errors{labels} {tool_stats['errors']}")
+            lines.append(f"mcp_tool_error_rate{labels} {tool_stats['error_rate']}")
+
+            if "avg_latency" in tool_stats:
+                lines.append(
+                    f"mcp_tool_latency_avg{labels} {tool_stats['avg_latency']}"
+                )
+                lines.append(
+                    f"mcp_tool_latency_p95{labels} {tool_stats['p95_latency']}"
+                )
+                lines.append(
+                    f"mcp_tool_latency_p99{labels} {tool_stats['p99_latency']}"
+                )
+
+        return "\n".join(lines)
+
+    def reset(self) -> None:
+        """Reset all metrics."""
+        with self._lock:
+            self._tool_calls.clear()
+            self._tool_errors.clear()
+            self._tool_latencies.clear()
+            self._recent_calls.clear()
+            self._recent_errors.clear()
+            self._start_time = time.time()
+            self._total_calls = 0
+            self._total_errors = 0
+
+
+# Global metrics collector instance
+_global_metrics = MetricsCollector()
+
+
+def track_tool(tool_name: Optional[str] = None):
+    """
+    Convenience decorator using global metrics collector.
+
+    Args:
+        tool_name: Optional tool name override
+
+    Returns:
+        Decorated function with metrics tracking
+    """
+    return _global_metrics.track_tool(tool_name)
+
+
+def get_metrics() -> Dict[str, Any]:
+    """Get metrics from global collector."""
+    return _global_metrics.export_metrics()
+
+
+def reset_metrics() -> None:
+    """Reset global metrics."""
+    _global_metrics.reset()