PraisonAI 3.0.0__py3-none-any.whl

praisonai/mcp_server/adapters/tools_bridge.py

@@ -0,0 +1,280 @@
+"""
+Registry Bridge Adapter
+
+Bridges praisonaiagents.tools registry/lazy TOOL_MAPPINGS into
+praisonai.mcp_server registry WITHOUT duplicating tool definitions
+or importing tools eagerly.
+
+This adapter:
+- Enumerates available tools (metadata only)
+- Loads tool handler lazily on first call
+- Handles name collisions with clear errors
+- Is optional and safe-by-default
+"""
+
+import logging
+from typing import Any, Callable, Dict, List, Optional, Set
+
+logger = logging.getLogger(__name__)
+
+# Track registered tools to avoid duplicates
+_registered_tools: Set[str] = set()
+_bridge_enabled: bool = False
+
+
+def is_bridge_available() -> bool:
+    """Check if praisonaiagents.tools is available."""
+    try:
+        import importlib.util
+        spec = importlib.util.find_spec("praisonaiagents.tools")
+        return spec is not None
+    except (ImportError, ModuleNotFoundError):
+        return False
+
+
+def get_tool_mappings() -> Dict[str, Any]:
+    """Get TOOL_MAPPINGS from praisonaiagents.tools."""
+    try:
+        from praisonaiagents.tools import TOOL_MAPPINGS
+        return TOOL_MAPPINGS
+    except ImportError:
+        return {}
+
+
+def _create_lazy_handler(module_path: str, class_name: Optional[str], tool_name: str) -> Callable:
+    """
+    Create a lazy handler that imports the tool only when called.
+    
+    Args:
+        module_path: Python module path
+        class_name: Optional class name within module
+        tool_name: Tool name for error messages
+        
+    Returns:
+        Callable that lazily loads and executes the tool
+    """
+    _cached_handler = None
+    
+    def lazy_handler(**kwargs) -> Any:
+        nonlocal _cached_handler
+        
+        if _cached_handler is None:
+            try:
+                import importlib
+                mod = importlib.import_module(module_path)
+                
+                if class_name:
+                    tool_class = getattr(mod, class_name)
+                    tool_instance = tool_class()
+                    if hasattr(tool_instance, 'run'):
+                        _cached_handler = tool_instance.run
+                    elif hasattr(tool_instance, '__call__'):
+                        _cached_handler = tool_instance
+                    else:
+                        raise AttributeError(f"Tool class {class_name} has no run or __call__ method")
+                else:
+                    # Function-based tool
+                    func_name = tool_name.split('.')[-1]
+                    if hasattr(mod, func_name):
+                        _cached_handler = getattr(mod, func_name)
+                    elif hasattr(mod, 'run'):
+                        _cached_handler = mod.run
+                    else:
+                        raise AttributeError(f"Module {module_path} has no {func_name} or run function")
+                        
+            except Exception as e:
+                logger.error(f"Failed to load tool {tool_name}: {e}")
+                raise RuntimeError(f"Tool {tool_name} failed to load: {e}")
+        
+        return _cached_handler(**kwargs)
+    
+    return lazy_handler
+
+
+def _infer_tool_hints(tool_name: str) -> Dict[str, bool]:
+    """
+    Infer tool annotation hints from tool name/category.
+    
+    Args:
+        tool_name: Full tool name (e.g., "praisonai.memory.show")
+        
+    Returns:
+        Dict with readOnlyHint, destructiveHint, idempotentHint, openWorldHint
+    """
+    name_lower = tool_name.lower()
+    
+    # Default hints per MCP 2025-11-25 spec
+    hints = {
+        "read_only_hint": False,
+        "destructive_hint": True,
+        "idempotent_hint": False,
+        "open_world_hint": True,
+    }
+    
+    # Read-only patterns
+    read_only_patterns = ['show', 'list', 'get', 'read', 'search', 'find', 'query', 'info', 'status']
+    for pattern in read_only_patterns:
+        if pattern in name_lower:
+            hints["read_only_hint"] = True
+            hints["destructive_hint"] = False
+            break
+    
+    # Idempotent patterns
+    idempotent_patterns = ['set', 'update', 'configure']
+    for pattern in idempotent_patterns:
+        if pattern in name_lower:
+            hints["idempotent_hint"] = True
+            break
+    
+    # Closed-world patterns (internal tools)
+    closed_world_patterns = ['memory', 'session', 'config', 'local']
+    for pattern in closed_world_patterns:
+        if pattern in name_lower:
+            hints["open_world_hint"] = False
+            break
+    
+    return hints
+
+
+def _extract_category(tool_name: str) -> Optional[str]:
+    """Extract category from tool name."""
+    parts = tool_name.split('.')
+    if len(parts) >= 2:
+        return parts[-2]  # e.g., "praisonai.memory.show" -> "memory"
+    return None
+
+
+def register_praisonai_tools(
+    namespace_prefix: str = "praisonai.agents.",
+    skip_on_collision: bool = True,
+) -> int:
+    """
+    Bridge praisonaiagents tools to MCP registry.
+    
+    Args:
+        namespace_prefix: Prefix to add to tool names to avoid collisions
+        skip_on_collision: If True, skip tools that already exist; if False, raise error
+        
+    Returns:
+        Number of tools registered
+    """
+    global _bridge_enabled
+    
+    if not is_bridge_available():
+        logger.debug("praisonaiagents.tools not available, skipping bridge")
+        return 0
+    
+    from ..registry import get_tool_registry, MCPToolDefinition
+    
+    registry = get_tool_registry()
+    tool_mappings = get_tool_mappings()
+    
+    registered_count = 0
+    
+    for tool_name, mapping_info in tool_mappings.items():
+        # Handle different mapping formats
+        if isinstance(mapping_info, tuple):
+            if len(mapping_info) >= 2:
+                module_path, class_name = mapping_info[0], mapping_info[1]
+            else:
+                module_path, class_name = mapping_info[0], None
+        elif isinstance(mapping_info, str):
+            module_path, class_name = mapping_info, None
+        else:
+            logger.warning(f"Unknown mapping format for {tool_name}: {type(mapping_info)}")
+            continue
+        
+        # Create namespaced name
+        full_name = f"{namespace_prefix}{tool_name}"
+        
+        # Check for collision
+        if full_name in _registered_tools:
+            if skip_on_collision:
+                logger.debug(f"Skipping duplicate tool: {full_name}")
+                continue
+            else:
+                raise ValueError(f"Tool name collision: {full_name}")
+        
+        # Check if already in registry
+        existing = registry.get(full_name)
+        if existing is not None:
+            if skip_on_collision:
+                logger.debug(f"Tool already registered: {full_name}")
+                continue
+            else:
+                raise ValueError(f"Tool already in registry: {full_name}")
+        
+        try:
+            # Create lazy handler
+            handler = _create_lazy_handler(module_path, class_name, tool_name)
+            
+            # Infer hints
+            hints = _infer_tool_hints(tool_name)
+            category = _extract_category(tool_name)
+            
+            # Create tool definition
+            tool_def = MCPToolDefinition(
+                name=full_name,
+                description=f"PraisonAI Agents tool: {tool_name}",
+                handler=handler,
+                input_schema={"type": "object", "properties": {}},  # Will be refined on first call
+                category=category,
+                **hints,
+            )
+            
+            # Register directly to avoid re-processing
+            registry._tools[full_name] = tool_def
+            _registered_tools.add(full_name)
+            registered_count += 1
+            
+            logger.debug(f"Registered bridged tool: {full_name}")
+            
+        except Exception as e:
+            logger.warning(f"Failed to register tool {tool_name}: {e}")
+            continue
+    
+    _bridge_enabled = True
+    logger.info(f"Registry bridge registered {registered_count} tools from praisonaiagents")
+    
+    return registered_count
+
+
+def unregister_bridged_tools() -> int:
+    """
+    Remove all bridged tools from the registry.
+    
+    Returns:
+        Number of tools removed
+    """
+    global _bridge_enabled
+    
+    from ..registry import get_tool_registry
+    
+    registry = get_tool_registry()
+    removed_count = 0
+    
+    for tool_name in list(_registered_tools):
+        if tool_name in registry._tools:
+            del registry._tools[tool_name]
+            removed_count += 1
+    
+    _registered_tools.clear()
+    _bridge_enabled = False
+    
+    logger.info(f"Removed {removed_count} bridged tools")
+    return removed_count
+
+
+def is_bridge_enabled() -> bool:
+    """Check if the bridge is currently enabled."""
+    return _bridge_enabled
+
+
+def get_bridged_tool_count() -> int:
+    """Get the number of bridged tools."""
+    return len(_registered_tools)
+
+
+def list_bridged_tools() -> List[str]:
+    """List all bridged tool names."""
+    return list(_registered_tools)

praisonai/mcp_server/auth/__init__.py

@@ -0,0 +1,48 @@
+"""
+MCP Authentication and Authorization Module
+
+Implements OAuth 2.1 and OpenID Connect support per MCP 2025-11-25 specification.
+
+Features:
+- API Key authentication
+- OAuth 2.1 authorization framework
+- OpenID Connect Discovery
+- Client ID Metadata Documents
+- Incremental scope handling
+- WWW-Authenticate challenges
+"""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .oauth import OAuthConfig, OAuthManager
+    from .oidc import OIDCDiscovery, OIDCConfig
+    from .api_key import APIKeyAuth
+    from .scopes import ScopeManager, ScopeChallenge
+
+__all__ = [
+    "OAuthConfig",
+    "OAuthManager",
+    "OIDCDiscovery",
+    "OIDCConfig",
+    "APIKeyAuth",
+    "ScopeManager",
+    "ScopeChallenge",
+]
+
+
+def __getattr__(name: str):
+    """Lazy load auth components."""
+    if name in ("OAuthConfig", "OAuthManager"):
+        from .oauth import OAuthConfig, OAuthManager
+        return OAuthConfig if name == "OAuthConfig" else OAuthManager
+    elif name in ("OIDCDiscovery", "OIDCConfig"):
+        from .oidc import OIDCDiscovery, OIDCConfig
+        return OIDCDiscovery if name == "OIDCDiscovery" else OIDCConfig
+    elif name == "APIKeyAuth":
+        from .api_key import APIKeyAuth
+        return APIKeyAuth
+    elif name in ("ScopeManager", "ScopeChallenge"):
+        from .scopes import ScopeManager, ScopeChallenge
+        return ScopeManager if name == "ScopeManager" else ScopeChallenge
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

praisonai/mcp_server/auth/api_key.py

@@ -0,0 +1,291 @@
+"""
+API Key Authentication for MCP
+
+Simple API key authentication for MCP servers.
+"""
+
+import hashlib
+import hmac
+import logging
+import secrets
+import time
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class APIKey:
+    """API Key representation."""
+    key_id: str
+    key_hash: str
+    name: Optional[str] = None
+    scopes: List[str] = field(default_factory=list)
+    created_at: float = field(default_factory=time.time)
+    expires_at: Optional[float] = None
+    last_used_at: Optional[float] = None
+    metadata: Dict[str, str] = field(default_factory=dict)
+    
+    def is_expired(self) -> bool:
+        if self.expires_at is None:
+            return False
+        return time.time() >= self.expires_at
+    
+    def has_scope(self, scope: str) -> bool:
+        if not self.scopes:
+            return True  # No scope restriction
+        return scope in self.scopes or "*" in self.scopes
+
+
+class APIKeyAuth:
+    """
+    API Key authentication manager.
+    
+    Supports:
+    - Key generation and validation
+    - Scope-based authorization
+    - Key rotation
+    - Rate limiting (optional)
+    """
+    
+    def __init__(
+        self,
+        keys: Optional[Dict[str, APIKey]] = None,
+        allow_env_key: bool = True,
+        env_key_name: str = "MCP_API_KEY",
+    ):
+        """
+        Initialize API key auth.
+        
+        Args:
+            keys: Pre-configured API keys
+            allow_env_key: Allow API key from environment
+            env_key_name: Environment variable name for API key
+        """
+        self._keys: Dict[str, APIKey] = keys or {}
+        self._allow_env_key = allow_env_key
+        self._env_key_name = env_key_name
+        self._env_key_hash: Optional[str] = None
+        
+        # Load env key if configured
+        if allow_env_key:
+            self._load_env_key()
+    
+    def _load_env_key(self) -> None:
+        """Load API key from environment."""
+        import os
+        env_key = os.environ.get(self._env_key_name)
+        if env_key:
+            self._env_key_hash = self._hash_key(env_key)
+            logger.debug(f"Loaded API key from {self._env_key_name}")
+    
+    def _hash_key(self, key: str) -> str:
+        """Hash an API key for storage."""
+        return hashlib.sha256(key.encode()).hexdigest()
+    
+    def generate_key(
+        self,
+        name: Optional[str] = None,
+        scopes: Optional[List[str]] = None,
+        expires_in: Optional[int] = None,
+        metadata: Optional[Dict[str, str]] = None,
+    ) -> tuple[str, APIKey]:
+        """
+        Generate a new API key.
+        
+        Args:
+            name: Key name/description
+            scopes: Allowed scopes
+            expires_in: Expiration in seconds
+            metadata: Additional metadata
+            
+        Returns:
+            Tuple of (raw_key, APIKey)
+        """
+        # Generate key
+        raw_key = f"mcp_{secrets.token_urlsafe(32)}"
+        key_id = secrets.token_hex(8)
+        key_hash = self._hash_key(raw_key)
+        
+        expires_at = None
+        if expires_in:
+            expires_at = time.time() + expires_in
+        
+        api_key = APIKey(
+            key_id=key_id,
+            key_hash=key_hash,
+            name=name,
+            scopes=scopes or [],
+            expires_at=expires_at,
+            metadata=metadata or {},
+        )
+        
+        self._keys[key_id] = api_key
+        
+        return raw_key, api_key
+    
+    def validate(
+        self,
+        key: str,
+        required_scope: Optional[str] = None,
+    ) -> tuple[bool, Optional[APIKey]]:
+        """
+        Validate an API key.
+        
+        Args:
+            key: Raw API key
+            required_scope: Required scope for authorization
+            
+        Returns:
+            Tuple of (is_valid, api_key)
+        """
+        key_hash = self._hash_key(key)
+        
+        # Check environment key
+        if self._env_key_hash and hmac.compare_digest(key_hash, self._env_key_hash):
+            # Env key has all scopes
+            return True, None
+        
+        # Check stored keys
+        for api_key in self._keys.values():
+            if hmac.compare_digest(key_hash, api_key.key_hash):
+                if api_key.is_expired():
+                    return False, None
+                
+                if required_scope and not api_key.has_scope(required_scope):
+                    return False, api_key
+                
+                # Update last used
+                api_key.last_used_at = time.time()
+                
+                return True, api_key
+        
+        return False, None
+    
+    def validate_header(
+        self,
+        auth_header: str,
+        required_scope: Optional[str] = None,
+    ) -> tuple[bool, Optional[APIKey]]:
+        """
+        Validate Authorization header.
+        
+        Supports:
+        - Bearer <key>
+        - ApiKey <key>
+        
+        Args:
+            auth_header: Authorization header value
+            required_scope: Required scope
+            
+        Returns:
+            Tuple of (is_valid, api_key)
+        """
+        if not auth_header:
+            return False, None
+        
+        parts = auth_header.split(" ", 1)
+        if len(parts) != 2:
+            return False, None
+        
+        scheme, key = parts
+        if scheme.lower() not in ("bearer", "apikey"):
+            return False, None
+        
+        return self.validate(key, required_scope)
+    
+    def revoke(self, key_id: str) -> bool:
+        """Revoke an API key."""
+        if key_id in self._keys:
+            del self._keys[key_id]
+            return True
+        return False
+    
+    def list_keys(self) -> List[APIKey]:
+        """List all API keys (without hashes)."""
+        return list(self._keys.values())
+    
+    def add_key(
+        self,
+        raw_key: str,
+        name: Optional[str] = None,
+        scopes: Optional[List[str]] = None,
+    ) -> APIKey:
+        """
+        Add a pre-existing API key.
+        
+        Args:
+            raw_key: Raw API key
+            name: Key name
+            scopes: Allowed scopes
+            
+        Returns:
+            APIKey instance
+        """
+        key_id = secrets.token_hex(8)
+        key_hash = self._hash_key(raw_key)
+        
+        api_key = APIKey(
+            key_id=key_id,
+            key_hash=key_hash,
+            name=name,
+            scopes=scopes or [],
+        )
+        
+        self._keys[key_id] = api_key
+        return api_key
+
+
+def create_auth_middleware(
+    api_key_auth: APIKeyAuth,
+    required_scope: Optional[str] = None,
+    exclude_paths: Optional[List[str]] = None,
+):
+    """
+    Create authentication middleware for Starlette/FastAPI.
+    
+    Args:
+        api_key_auth: APIKeyAuth instance
+        required_scope: Required scope for all requests
+        exclude_paths: Paths to exclude from auth
+        
+    Returns:
+        Middleware class
+    """
+    exclude_paths = exclude_paths or ["/health", "/"]
+    
+    try:
+        from starlette.middleware.base import BaseHTTPMiddleware
+        from starlette.requests import Request
+        from starlette.responses import JSONResponse
+    except ImportError:
+        raise ImportError("starlette required for middleware")
+    
+    class AuthMiddleware(BaseHTTPMiddleware):
+        async def dispatch(self, request: Request, call_next):
+            # Skip excluded paths
+            if request.url.path in exclude_paths:
+                return await call_next(request)
+            
+            # Get auth header
+            auth_header = request.headers.get("Authorization", "")
+            
+            # Validate
+            is_valid, api_key = api_key_auth.validate_header(
+                auth_header, required_scope
+            )
+            
+            if not is_valid:
+                return JSONResponse(
+                    {"error": "Unauthorized"},
+                    status_code=401,
+                    headers={"WWW-Authenticate": "Bearer"},
+                )
+            
+            # Add key info to request state
+            request.state.api_key = api_key
+            
+            return await call_next(request)
+    
+    return AuthMiddleware