kailash 0.6.2__py3-none-any.whl → 0.6.4__py3-none-any.whl

kailash/mcp/server_enhanced.py

@@ -1,449 +0,0 @@
-"""
-Enhanced MCP Server with production-ready capabilities.
-
-This module provides an enhanced MCP server that includes caching, configuration,
-metrics, and other production features by default, while maintaining compatibility
-with the official Anthropic FastMCP framework.
-"""
-
-import asyncio
-import functools
-import logging
-from pathlib import Path
-from typing import Any, Callable, Dict, Optional, TypeVar, Union
-
-from .utils import CacheManager, ConfigManager, MetricsCollector, format_response
-
-logger = logging.getLogger(__name__)
-
-F = TypeVar("F", bound=Callable[..., Any])
-
-
-class EnhancedMCPServer:
-    """
-    Production-ready MCP server with enhanced capabilities.
-
-    Features included by default:
-    - Caching with TTL support
-    - Hierarchical configuration management
-    - Metrics collection and monitoring
-    - Response formatting utilities
-    - Error handling and logging
-
-    All features can be disabled if not needed.
-    """
-
-    def __init__(
-        self,
-        name: str,
-        config_file: Optional[Union[str, Path]] = None,
-        enable_cache: bool = True,
-        cache_ttl: int = 300,
-        enable_metrics: bool = True,
-        enable_formatting: bool = True,
-    ):
-        """
-        Initialize enhanced MCP server.
-
-        Args:
-            name: Server name
-            config_file: Optional configuration file path
-            enable_cache: Whether to enable caching (default: True)
-            cache_ttl: Default cache TTL in seconds (default: 300)
-            enable_metrics: Whether to enable metrics collection (default: True)
-            enable_formatting: Whether to enable response formatting (default: True)
-        """
-        self.name = name
-
-        # Initialize configuration
-        self.config = ConfigManager(config_file)
-
-        # Set default configuration values
-        self.config.update(
-            {
-                "server": {"name": name, "version": "1.0.0", "transport": "stdio"},
-                "cache": {
-                    "enabled": enable_cache,
-                    "default_ttl": cache_ttl,
-                    "max_size": 128,
-                },
-                "metrics": {
-                    "enabled": enable_metrics,
-                    "collect_performance": True,
-                    "collect_usage": True,
-                },
-                "formatting": {
-                    "enabled": enable_formatting,
-                    "default_format": "markdown",
-                },
-            }
-        )
-
-        # Initialize components
-        self.cache = CacheManager(
-            enabled=self.config.get("cache.enabled", enable_cache),
-            default_ttl=self.config.get("cache.default_ttl", cache_ttl),
-        )
-
-        self.metrics = MetricsCollector(
-            enabled=self.config.get("metrics.enabled", enable_metrics),
-            collect_performance=self.config.get("metrics.collect_performance", True),
-            collect_usage=self.config.get("metrics.collect_usage", True),
-        )
-
-        # FastMCP server instance (initialized lazily)
-        self._mcp = None
-        self._running = False
-
-        # Tool registry for management
-        self._tool_registry: Dict[str, Dict[str, Any]] = {}
-
-    def _init_mcp(self):
-        """Initialize FastMCP server."""
-        if self._mcp is not None:
-            return
-
-        try:
-            from mcp.server.fastmcp import FastMCP
-
-            self._mcp = FastMCP(self.name)
-            logger.info(f"Initialized FastMCP server: {self.name}")
-        except ImportError:
-            logger.error(
-                "FastMCP not available. Install with: pip install 'mcp[server]'"
-            )
-            raise
-
-    def tool(
-        self,
-        cache_key: Optional[str] = None,
-        cache_ttl: Optional[int] = None,
-        format_response: Optional[str] = None,
-    ):
-        """
-        Enhanced tool decorator with optional caching and metrics.
-
-        Args:
-            cache_key: Optional cache key for caching results
-            cache_ttl: Optional TTL override for this tool
-            format_response: Optional response format ("json", "markdown", "table", etc.)
-
-        Returns:
-            Decorated function with enhanced capabilities
-
-        Example:
-            @server.tool(cache_key="weather", cache_ttl=600, format_response="markdown")
-            async def get_weather(city: str) -> dict:
-                # Expensive API call - will be cached for 10 minutes
-                return await fetch_weather_data(city)
-        """
-
-        def decorator(func: F) -> F:
-            if self._mcp is None:
-                self._init_mcp()
-
-            # Get function name for registration
-            tool_name = func.__name__
-
-            # Create enhanced wrapper
-            enhanced_func = self._create_enhanced_tool(
-                func, tool_name, cache_key, cache_ttl, format_response
-            )
-
-            # Register with FastMCP
-            mcp_tool = self._mcp.tool()(enhanced_func)
-
-            # Track in registry
-            self._tool_registry[tool_name] = {
-                "function": mcp_tool,
-                "original_function": func,
-                "cached": cache_key is not None,
-                "cache_key": cache_key,
-                "cache_ttl": cache_ttl,
-                "format_response": format_response,
-            }
-
-            logger.debug(
-                f"Registered tool: {tool_name} (cached: {cache_key is not None})"
-            )
-            return mcp_tool
-
-        return decorator
-
-    def _create_enhanced_tool(
-        self,
-        func: F,
-        tool_name: str,
-        cache_key: Optional[str],
-        cache_ttl: Optional[int],
-        response_format: Optional[str],
-    ) -> F:
-        """Create enhanced tool function with caching, metrics, and formatting."""
-
-        @functools.wraps(func)
-        def sync_wrapper(*args, **kwargs):
-            # Apply metrics tracking
-            start_time = None
-            if self.metrics.enabled:
-                import time
-
-                start_time = time.time()
-
-            try:
-                # Try cache first if enabled
-                if cache_key and self.cache.enabled:
-                    cache = self.cache.get_cache(cache_key, ttl=cache_ttl)
-                    cache_lookup_key = self.cache._create_cache_key(
-                        tool_name, args, kwargs
-                    )
-
-                    result = cache.get(cache_lookup_key)
-                    if result is not None:
-                        logger.debug(f"Cache hit for {tool_name}")
-                        if self.metrics.enabled:
-                            latency = time.time() - start_time
-                            self.metrics.track_tool_call(tool_name, latency, True)
-                        return self._format_response(result, response_format)
-
-                # Execute function
-                result = func(*args, **kwargs)
-
-                # Cache result if enabled
-                if cache_key and self.cache.enabled:
-                    cache.set(cache_lookup_key, result)
-                    logger.debug(f"Cached result for {tool_name}")
-
-                # Track success metrics
-                if self.metrics.enabled:
-                    latency = time.time() - start_time
-                    self.metrics.track_tool_call(tool_name, latency, True)
-
-                return self._format_response(result, response_format)
-
-            except Exception as e:
-                # Track error metrics
-                if self.metrics.enabled and start_time:
-                    latency = time.time() - start_time
-                    self.metrics.track_tool_call(
-                        tool_name, latency, False, type(e).__name__
-                    )
-
-                logger.error(f"Error in tool {tool_name}: {e}")
-                raise
-
-        @functools.wraps(func)
-        async def async_wrapper(*args, **kwargs):
-            # Apply metrics tracking
-            start_time = None
-            if self.metrics.enabled:
-                import time
-
-                start_time = time.time()
-
-            try:
-                # Try cache first if enabled
-                if cache_key and self.cache.enabled:
-                    cache = self.cache.get_cache(cache_key, ttl=cache_ttl)
-                    cache_lookup_key = self.cache._create_cache_key(
-                        tool_name, args, kwargs
-                    )
-
-                    result = cache.get(cache_lookup_key)
-                    if result is not None:
-                        logger.debug(f"Cache hit for {tool_name}")
-                        if self.metrics.enabled:
-                            latency = time.time() - start_time
-                            self.metrics.track_tool_call(tool_name, latency, True)
-                        return self._format_response(result, response_format)
-
-                # Execute function
-                result = await func(*args, **kwargs)
-
-                # Cache result if enabled
-                if cache_key and self.cache.enabled:
-                    cache.set(cache_lookup_key, result)
-                    logger.debug(f"Cached result for {tool_name}")
-
-                # Track success metrics
-                if self.metrics.enabled:
-                    latency = time.time() - start_time
-                    self.metrics.track_tool_call(tool_name, latency, True)
-
-                return self._format_response(result, response_format)
-
-            except Exception as e:
-                # Track error metrics
-                if self.metrics.enabled and start_time:
-                    latency = time.time() - start_time
-                    self.metrics.track_tool_call(
-                        tool_name, latency, False, type(e).__name__
-                    )
-
-                logger.error(f"Error in tool {tool_name}: {e}")
-                raise
-
-        # Return appropriate wrapper based on function type
-        if asyncio.iscoroutinefunction(func):
-            return async_wrapper
-        else:
-            return sync_wrapper
-
-    def _format_response(self, result: Any, response_format: Optional[str]) -> Any:
-        """Format response if formatting is enabled."""
-        if not self.config.get("formatting.enabled", True) or not response_format:
-            return result
-
-        try:
-            return format_response(result, response_format)
-        except Exception as e:
-            logger.warning(f"Failed to format response: {e}")
-            return result
-
-    def resource(self, uri: str):
-        """
-        Add resource with metrics tracking.
-
-        Args:
-            uri: Resource URI pattern
-
-        Returns:
-            Decorated function
-        """
-
-        def decorator(func: F) -> F:
-            if self._mcp is None:
-                self._init_mcp()
-
-            # Wrap with metrics if enabled
-            if self.metrics.enabled:
-                func = self.metrics.track_tool(f"resource:{uri}")(func)
-
-            return self._mcp.resource(uri)(func)
-
-        return decorator
-
-    def prompt(self, name: str):
-        """
-        Add prompt with metrics tracking.
-
-        Args:
-            name: Prompt name
-
-        Returns:
-            Decorated function
-        """
-
-        def decorator(func: F) -> F:
-            if self._mcp is None:
-                self._init_mcp()
-
-            # Wrap with metrics if enabled
-            if self.metrics.enabled:
-                func = self.metrics.track_tool(f"prompt:{name}")(func)
-
-            return self._mcp.prompt(name)(func)
-
-        return decorator
-
-    def get_tool_stats(self) -> Dict[str, Any]:
-        """Get statistics for all registered tools."""
-        stats = {
-            "registered_tools": len(self._tool_registry),
-            "cached_tools": sum(1 for t in self._tool_registry.values() if t["cached"]),
-            "tools": {},
-        }
-
-        for tool_name, tool_info in self._tool_registry.items():
-            stats["tools"][tool_name] = {
-                "cached": tool_info["cached"],
-                "cache_key": tool_info.get("cache_key"),
-                "format_response": tool_info.get("format_response"),
-            }
-
-        return stats
-
-    def get_server_stats(self) -> Dict[str, Any]:
-        """Get comprehensive server statistics."""
-        stats = {
-            "server": {
-                "name": self.name,
-                "running": self._running,
-                "config": self.config.to_dict(),
-            },
-            "tools": self.get_tool_stats(),
-        }
-
-        if self.metrics.enabled:
-            stats["metrics"] = self.metrics.export_metrics()
-
-        if self.cache.enabled:
-            stats["cache"] = self.cache.stats()
-
-        return stats
-
-    def clear_cache(self, cache_name: Optional[str] = None) -> None:
-        """Clear cache(s)."""
-        if cache_name:
-            cache = self.cache.get_cache(cache_name)
-            cache.clear()
-            logger.info(f"Cleared cache: {cache_name}")
-        else:
-            self.cache.clear_all()
-            logger.info("Cleared all caches")
-
-    def run(self):
-        """Run the MCP server."""
-        if self._mcp is None:
-            self._init_mcp()
-
-        logger.info(f"Starting enhanced MCP server: {self.name}")
-        logger.info(f"Cache enabled: {self.cache.enabled}")
-        logger.info(f"Metrics enabled: {self.metrics.enabled}")
-
-        self._running = True
-
-        try:
-            self._mcp.run()
-        except KeyboardInterrupt:
-            logger.info("Server stopped by user")
-        except Exception as e:
-            logger.error(f"Server error: {e}")
-            raise
-        finally:
-            self._running = False
-
-
-# For backward compatibility, make EnhancedMCPServer the default MCPServer
-MCPServer = EnhancedMCPServer
-
-
-class SimpleMCPServer(EnhancedMCPServer):
-    """
-    Simplified MCP server with minimal configuration.
-
-    This inherits all enhanced capabilities but disables some features
-    by default for simpler use cases.
-    """
-
-    def __init__(self, name: str, description: str = ""):
-        """
-        Initialize simple MCP server.
-
-        Args:
-            name: Server name
-            description: Server description
-        """
-        # Initialize with some features disabled for simplicity
-        super().__init__(
-            name=name,
-            enable_cache=False,  # Disable cache by default
-            enable_metrics=False,  # Disable metrics by default
-            enable_formatting=True,  # Keep formatting for better output
-        )
-
-        self.description = description
-
-        # Update config for simple use
-        self.config.update(
-            {"server": {"name": name, "description": description, "version": "1.0.0"}}
-        )

kailash/mcp/utils/cache.py

@@ -1,267 +0,0 @@
-"""
-Caching utilities for MCP servers.
-
-Provides LRU cache, TTL support, and decorators for method-level caching.
-Based on patterns from production MCP server implementations.
-"""
-
-import asyncio
-import functools
-import logging
-import threading
-import time
-from typing import Any, Callable, Dict, Optional, Tuple, TypeVar
-
-logger = logging.getLogger(__name__)
-
-F = TypeVar("F", bound=Callable[..., Any])
-
-
-class LRUCache:
-    """
-    Thread-safe LRU cache with TTL (time-to-live) support.
-
-    Features:
-    - Configurable maximum size
-    - TTL expiration for entries
-    - Thread-safe operations
-    - Performance statistics
-    """
-
-    def __init__(self, max_size: int = 128, ttl: int = 300):
-        """
-        Initialize LRU cache.
-
-        Args:
-            max_size: Maximum number of entries to store
-            ttl: Time-to-live in seconds (0 = no expiration)
-        """
-        self.max_size = max_size
-        self.ttl = ttl
-        self._cache: Dict[str, Tuple[Any, float]] = {}
-        self._access_order: Dict[str, float] = {}
-        self._lock = threading.RLock()
-
-        # Statistics
-        self._hits = 0
-        self._misses = 0
-        self._evictions = 0
-
-    def get(self, key: str) -> Optional[Any]:
-        """Get value from cache if it exists and hasn't expired."""
-        with self._lock:
-            if key not in self._cache:
-                self._misses += 1
-                return None
-
-            value, timestamp = self._cache[key]
-
-            # Check TTL expiration
-            if self.ttl > 0 and time.time() - timestamp > self.ttl:
-                del self._cache[key]
-                del self._access_order[key]
-                self._misses += 1
-                return None
-
-            # Update access time for LRU
-            self._access_order[key] = time.time()
-            self._hits += 1
-            return value
-
-    def set(self, key: str, value: Any) -> None:
-        """Set value in cache, evicting LRU items if necessary."""
-        with self._lock:
-            current_time = time.time()
-
-            # If key exists, update it
-            if key in self._cache:
-                self._cache[key] = (value, current_time)
-                self._access_order[key] = current_time
-                return
-
-            # Check if we need to evict
-            if len(self._cache) >= self.max_size:
-                self._evict_lru()
-
-            # Add new entry
-            self._cache[key] = (value, current_time)
-            self._access_order[key] = current_time
-
-    def _evict_lru(self) -> None:
-        """Evict least recently used item."""
-        if not self._access_order:
-            return
-
-        lru_key = min(self._access_order.keys(), key=self._access_order.get)
-        del self._cache[lru_key]
-        del self._access_order[lru_key]
-        self._evictions += 1
-
-    def clear(self) -> None:
-        """Clear all entries from cache."""
-        with self._lock:
-            self._cache.clear()
-            self._access_order.clear()
-
-    def stats(self) -> Dict[str, Any]:
-        """Get cache performance statistics."""
-        with self._lock:
-            total_requests = self._hits + self._misses
-            hit_rate = self._hits / total_requests if total_requests > 0 else 0
-
-            return {
-                "hits": self._hits,
-                "misses": self._misses,
-                "evictions": self._evictions,
-                "hit_rate": hit_rate,
-                "size": len(self._cache),
-                "max_size": self.max_size,
-                "ttl": self.ttl,
-            }
-
-
-class CacheManager:
-    """
-    High-level cache management with multiple caching strategies.
-
-    Provides easy-to-use caching for MCP servers with different cache types
-    for different use cases.
-    """
-
-    def __init__(self, enabled: bool = True, default_ttl: int = 300):
-        """
-        Initialize cache manager.
-
-        Args:
-            enabled: Whether caching is enabled
-            default_ttl: Default TTL for cache entries
-        """
-        self.enabled = enabled
-        self.default_ttl = default_ttl
-        self._caches: Dict[str, LRUCache] = {}
-
-    def get_cache(
-        self, name: str, max_size: int = 128, ttl: Optional[int] = None
-    ) -> LRUCache:
-        """Get or create a named cache."""
-        if name not in self._caches:
-            cache_ttl = ttl if ttl is not None else self.default_ttl
-            self._caches[name] = LRUCache(max_size=max_size, ttl=cache_ttl)
-        return self._caches[name]
-
-    def cached(self, cache_name: str = "default", ttl: Optional[int] = None):
-        """
-        Decorator to cache function results.
-
-        Args:
-            cache_name: Name of cache to use
-            ttl: TTL for this specific cache
-
-        Returns:
-            Decorated function with caching
-        """
-
-        def decorator(func: F) -> F:
-            if not self.enabled:
-                return func
-
-            cache = self.get_cache(cache_name, ttl=ttl)
-
-            @functools.wraps(func)
-            def sync_wrapper(*args, **kwargs):
-                # Create cache key from function name and arguments
-                cache_key = self._create_cache_key(func.__name__, args, kwargs)
-
-                # Try to get from cache
-                result = cache.get(cache_key)
-                if result is not None:
-                    logger.debug(f"Cache hit for {func.__name__}: {cache_key}")
-                    return result
-
-                # Execute function and cache result
-                logger.debug(f"Cache miss for {func.__name__}: {cache_key}")
-                result = func(*args, **kwargs)
-                cache.set(cache_key, result)
-                return result
-
-            @functools.wraps(func)
-            async def async_wrapper(*args, **kwargs):
-                # Create cache key from function name and arguments
-                cache_key = self._create_cache_key(func.__name__, args, kwargs)
-
-                # Try to get from cache
-                result = cache.get(cache_key)
-                if result is not None:
-                    logger.debug(f"Cache hit for {func.__name__}: {cache_key}")
-                    return result
-
-                # Execute function and cache result
-                logger.debug(f"Cache miss for {func.__name__}: {cache_key}")
-                result = await func(*args, **kwargs)
-                cache.set(cache_key, result)
-                return result
-
-            # Return appropriate wrapper based on function type
-            if asyncio.iscoroutinefunction(func):
-                return async_wrapper
-            else:
-                return sync_wrapper
-
-        return decorator
-
-    def _create_cache_key(self, func_name: str, args: tuple, kwargs: dict) -> str:
-        """Create a cache key from function name and arguments."""
-        # Convert args and kwargs to string representation
-        args_str = str(args) if args else ""
-        kwargs_str = str(sorted(kwargs.items())) if kwargs else ""
-        return f"{func_name}:{args_str}:{kwargs_str}"
-
-    def clear_all(self) -> None:
-        """Clear all caches."""
-        for cache in self._caches.values():
-            cache.clear()
-
-    def stats(self) -> Dict[str, Dict[str, Any]]:
-        """Get statistics for all caches."""
-        return {name: cache.stats() for name, cache in self._caches.items()}
-
-
-# Global cache manager instance
-_global_cache_manager = CacheManager()
-
-
-def cached_query(cache_name: str = "query", ttl: int = 300, enabled: bool = True):
-    """
-    Simple decorator for caching query results.
-
-    This is a convenience decorator that uses the global cache manager.
-
-    Args:
-        cache_name: Name of cache to use
-        ttl: Time-to-live for cache entries
-        enabled: Whether caching is enabled
-
-    Example:
-        @cached_query("search", ttl=600)
-        async def search_data(query: str) -> list:
-            # Expensive search operation
-            return results
-    """
-
-    def decorator(func: F) -> F:
-        if not enabled:
-            return func
-
-        return _global_cache_manager.cached(cache_name, ttl=ttl)(func)
-
-    return decorator
-
-
-def get_cache_stats() -> Dict[str, Dict[str, Any]]:
-    """Get statistics for the global cache manager."""
-    return _global_cache_manager.stats()
-
-
-def clear_all_caches() -> None:
-    """Clear all caches in the global cache manager."""
-    _global_cache_manager.clear_all()