ai-parrot 0.17.2__cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

parrot/mcp/__init__.py

@@ -0,0 +1,28 @@
+"""MCP integration for AI-Parrot."""
+
+from .integration import (
+    MCPEnabledMixin,
+    MCPServerConfig,
+    MCPToolManager,
+    MCPClient,
+    create_local_mcp_server,
+    create_http_mcp_server,
+    create_api_key_mcp_server,
+)
+from .config import AuthMethod
+from .oauth import APIKeyStore, ExternalOAuthValidator, APIKeyRecord
+
+__all__ = [
+    "MCPEnabledMixin",
+    "MCPServerConfig",
+    "MCPToolManager",
+    "MCPClient",
+    "create_local_mcp_server",
+    "create_http_mcp_server",
+    "create_api_key_mcp_server",
+    "AuthMethod",
+    "APIKeyStore",
+    "ExternalOAuthValidator",
+    "APIKeyRecord",
+]
+

parrot/mcp/adapter.py

@@ -0,0 +1,105 @@
+import logging
+import json
+from typing import Dict, Any
+
+from parrot.tools.abstract import AbstractTool, ToolResult
+
+class MCPToolAdapter:
+    """Adapts AI-Parrot AbstractTool to MCP tool format."""
+
+    def __init__(self, tool: AbstractTool):
+        self.tool = tool
+        self.logger = logging.getLogger(f"MCPToolAdapter.{tool.name}")
+
+    def to_mcp_tool_definition(self) -> Dict[str, Any]:
+        """Convert AbstractTool to MCP tool definition."""
+        # Extract schema from the tool's args_schema
+        input_schema = {}
+        if hasattr(self.tool, 'args_schema') and self.tool.args_schema:
+            try:
+                # Get the JSON schema from the Pydantic model
+                input_schema = self.tool.args_schema.model_json_schema()
+            except Exception as e:
+                self.logger.warning(f"Could not extract schema for {self.tool.name}: {e}")
+                input_schema = {"type": "object", "properties": {}}
+
+        return {
+            "name": self.tool.name or "unknown_tool",
+            "description": self.tool.description or f"Tool: {self.tool.name}",
+            "inputSchema": input_schema
+        }
+
+    async def execute(self, arguments: Dict[str, Any]) -> Dict[str, Any]:
+        """Execute the AI-Parrot tool and convert result to MCP format."""
+        try:
+            # Execute the tool
+            result = await self.tool._execute(**arguments)
+
+            # Convert ToolResult to MCP response format
+            if isinstance(result, ToolResult):
+                return self._toolresult_to_mcp(result)
+            else:
+                # Handle direct results (for backward compatibility)
+                return {
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": str(result)
+                        }
+                    ],
+                    "isError": False
+                }
+
+        except Exception as e:
+            self.logger.error(f"Tool execution failed: {e}")
+            return {
+                "content": [
+                    {
+                        "type": "text",
+                        "text": f"Error executing tool: {str(e)}"
+                    }
+                ],
+                "isError": True
+            }
+
+    def _toolresult_to_mcp(self, result: ToolResult) -> Dict[str, Any]:
+        """Convert ToolResult to MCP response format."""
+        content_items = []
+
+        if result.status == "success":
+            # Handle different result types
+            if isinstance(result.result, str):
+                content_items.append({
+                    "type": "text",
+                    "text": result.result
+                })
+            elif isinstance(result.result, dict):
+                content_items.append({
+                    "type": "text",
+                    "text": json.dumps(result.result, indent=2, default=str)
+                })
+            else:
+                content_items.append({
+                    "type": "text",
+                    "text": str(result.result)
+                })
+
+            # Add metadata if present
+            if result.metadata:
+                content_items.append({
+                    "type": "text",
+                    "text": f"\nMetadata: {json.dumps(result.metadata, indent=2, default=str)}"
+                })
+
+        else:
+            # Handle error case
+            error_text = result.error or "Unknown error occurred"
+            content_items.append({
+                "type": "text",
+                "text": f"Error: {error_text}"
+            })
+
+        return {
+            "content": content_items,
+            "isError": result.status != "success"
+        }

parrot/mcp/cli.py

@@ -0,0 +1,174 @@
+import asyncio
+import sys
+import importlib.util
+from importlib import import_module
+from pathlib import Path
+from typing import Optional
+import yaml
+import click
+from navconfig.logging import logging
+from .server import MCPServer, MCPServerConfig
+from ..tools.abstract import AbstractTool
+from ..tools.toolkit import AbstractToolkit
+from ..services.mcp.server import ParrotMCPServer, TransportConfig
+
+
+@click.group()
+def mcp():
+    """MCP server commands."""
+    pass
+
+
+@mcp.command()
+@click.argument('config_file', type=click.Path(exists=True))
+@click.option(
+    '--transport', type=click.Choice(['stdio', 'unix', 'http']), default=None,
+        help='Override transport from config')
+@click.option(
+    '--socket', type=str, default=None,
+            help='Unix socket path (for unix transport)')
+@click.option(
+    '--port', type=int, default=None,
+            help='Port (for http transport)')
+@click.option(
+    '--log-level', type=str, default='INFO',
+            help='Logging level')
+def serve(
+    config_file: str, transport: Optional[str], socket: Optional[str],
+        port: Optional[int], log_level: str):
+    """
+    Start an MCP server from a Python config file or YAML.
+
+    Examples:
+
+        # Python config file
+        parrot mcp serve workday_server.py --transport unix --socket /tmp/workday.sock
+
+        # YAML config file
+        parrot mcp serve mcp_config.yaml
+
+    Python config file should define 'mcp' variable:
+
+        # workday_server.py
+        from parrot.services import ParrotMCPServer
+        from parrot.toolkits.workday import WorkdayToolkit
+
+        mcp = ParrotMCPServer(
+            name="workday-mcp",
+            tools=WorkdayToolkit(redis_url="redis://localhost:6379/4")
+        )
+    """
+    config_path = Path(config_file)
+
+    if config_path.suffix in {'.yaml', '.yml'}:
+        mcp_server = _load_from_yaml(config_path)
+    elif config_path.suffix == '.py':
+        mcp_server = _load_from_python(config_path)
+    else:
+        click.echo(f"Error: Unsupported config file type: {config_path.suffix}", err=True)
+        sys.exit(1)
+
+    # Override settings from CLI
+    if transport:
+        # Need to update transport config
+        mcp_server.transport_configs = {
+            transport: _create_transport_config(transport, socket, port)
+        }
+
+    # Set log level
+    logging.getLogger().setLevel(log_level)
+
+    # Run the server
+    asyncio.run(_run_standalone_server(mcp_server))
+
+
+def _load_from_python(config_path: Path) -> 'ParrotMCPServer':
+    """Load ParrotMCPServer from Python file."""
+
+
+    spec = importlib.util.spec_from_file_location("mcp_config", config_path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+
+    if not hasattr(module, 'mcp'):
+        raise ValueError(
+            f"Config file {config_path} must define 'mcp' variable "
+            "containing a ParrotMCPServer instance"
+        )
+
+    return module.mcp
+
+
+def _load_from_yaml(config_path: Path) -> ParrotMCPServer:
+    """Load ParrotMCPServer from YAML file."""
+    with open(config_path) as f:
+        config = yaml.safe_load(f)
+
+    # Parse tools from YAML
+    tools_config = {
+        tool_entry['class']: tool_entry['module']
+        for tool_entry in config.get('tools', [])
+    }
+
+    # Parse transports
+    transports = config.get('transport', 'stdio')
+
+    return ParrotMCPServer(
+        name=config.get('name', 'ai-parrot-mcp'),
+        description=config.get('description', 'AI-Parrot MCP Server'),
+        transports=transports,
+        tools=tools_config,
+        **config.get('server_config', {})
+    )
+
+
+def _create_transport_config(transport: str, socket: Optional[str], port: Optional[int]):
+    """Create TransportConfig from CLI args."""
+    return TransportConfig(
+        transport=transport,
+        host="127.0.0.1" if transport == "http" else None,
+        port=port if transport == "http" else None,
+    )
+
+
+async def _run_standalone_server(mcp_server: ParrotMCPServer):
+    """Run MCP server in standalone mode (no aiohttp app)."""
+    logger = logging.getLogger("parrot.mcp.serve")
+
+    # Load tools
+    tools = await mcp_server._load_configured_tools()
+    if not tools:
+        logger.error("No tools configured")
+        sys.exit(1)
+
+    logger.info(f"Loaded {len(tools)} tools")
+
+    # Get transport config (should be single transport in CLI mode)
+    if len(mcp_server.transport_configs) != 1:
+        logger.error("CLI mode requires exactly one transport")
+        sys.exit(1)
+
+    transport_key, transport_config = list(mcp_server.transport_configs.items())[0]
+
+    # Create MCP server
+    config = MCPServerConfig(
+        name=mcp_server.name,
+        description=mcp_server.description,
+        transport=transport_config.transport,
+        host=transport_config.host,
+        port=transport_config.port,
+        socket_path=transport_config.socket_path if hasattr(transport_config, 'socket_path') else None,
+        log_level=mcp_server.log_level,
+    )
+
+    server = MCPServer(config)
+    server.register_tools(tools)
+
+    # Start and run
+    try:
+        logger.info(f"Starting MCP server in {transport_config.transport} mode...")
+        await server.start()
+    except KeyboardInterrupt:
+        logger.info("Interrupted by user")
+    finally:
+        await server.stop()

parrot/mcp/client.py

@@ -0,0 +1,119 @@
+import os
+import base64
+import logging
+from dataclasses import dataclass, field
+from typing import Dict, Any, Optional, List, Callable
+
+@dataclass
+class MCPClientConfig:
+    """Complete configuration for external MCP server connection."""
+    name: str
+
+    # Connection parameters
+    url: Optional[str] = None  # For HTTP/SSE servers
+    command: Optional[str] = None  # For stdio servers
+    args: Optional[List[str]] = None  # Command arguments
+    env: Optional[Dict[str, str]] = None  # Environment variables
+
+    # Authentication
+    auth_type: Optional[str] = None  # "oauth", "bearer", "basic", "api_key", "none"
+    auth_config: Dict[str, Any] = field(default_factory=dict)
+    # A token supplier hook the HTTP client will call to add headers (set by OAuthManager)
+    token_supplier: Optional[Callable[[], Optional[str]]] = None
+
+    # Transport type
+    transport: str = "auto"  # "auto", "stdio", "http", "sse" or "unix"
+    base_path: Optional[str] = None  # Base path for HTTP/SSE endpoints
+    events_path: Optional[str] = None  # SSE events path
+    # URL for Unix socket (for unix transport)
+    socket_path: Optional[str] = None
+
+    # Additional headers for HTTP transports
+    headers: Dict[str, str] = field(default_factory=dict)
+
+    # Connection settings
+    timeout: float = 30.0
+    retry_count: int = 3
+    startup_delay: float = 0.5
+
+    # Tool filtering
+    allowed_tools: Optional[List[str]] = None
+    blocked_tools: Optional[List[str]] = None
+
+    # Process management
+    kill_timeout: float = 5.0
+
+    # QUIC Configuration
+    quic_config: Any = None
+
+
+class MCPAuthHandler:
+    """Handles various authentication types for MCP servers."""
+
+    def __init__(self, auth_type: str, auth_config: Dict[str, Any]):
+        self.auth_type = auth_type.lower() if auth_type else None
+        self.auth_config = auth_config
+        self.logger = logging.getLogger("MCPAuthHandler")
+
+    async def get_auth_headers(self) -> Dict[str, str]:
+        """Get authentication headers based on auth type."""
+        if not self.auth_type or self.auth_type == "none":
+            return {}
+
+        if self.auth_type == "bearer":
+            return await self._get_bearer_headers()
+        elif self.auth_type == "oauth":
+            return await self._get_oauth_headers()
+        elif self.auth_type == "basic":
+            return await self._get_basic_headers()
+        elif self.auth_type == "api_key":
+            return await self._get_api_key_headers()
+        else:
+            self.logger.warning(f"Unknown auth type: {self.auth_type}")
+            return {}
+
+    async def _get_bearer_headers(self) -> Dict[str, str]:
+        """Get Bearer token headers."""
+        token = self.auth_config.get("token") or self.auth_config.get("access_token")
+        if not token:
+            raise ValueError("Bearer authentication requires 'token' or 'access_token' in auth_config")
+
+        return {"Authorization": f"Bearer {token}"}
+
+    async def _get_oauth_headers(self) -> Dict[str, str]:
+        """Get OAuth headers (simplified - assumes token is already available)."""
+        access_token = self.auth_config.get("access_token")
+        if not access_token:
+            # In a full implementation, you'd handle the OAuth flow here
+            raise ValueError("OAuth authentication requires 'access_token' in auth_config")
+
+        return {"Authorization": f"Bearer {access_token}"}
+
+    async def _get_basic_headers(self) -> Dict[str, str]:
+        """Get Basic authentication headers."""
+        username = self.auth_config.get("username")
+        password = self.auth_config.get("password")
+
+        if not username or not password:
+            raise ValueError("Basic authentication requires 'username' and 'password' in auth_config")
+
+        credentials = base64.b64encode(f"{username}:{password}".encode()).decode()
+        return {"Authorization": f"Basic {credentials}"}
+
+    async def _get_api_key_headers(self) -> Dict[str, str]:
+        """Get API key headers."""
+        api_key = self.auth_config.get("api_key")
+        header_name = self.auth_config.get("header_name", "X-API-Key")
+        use_bearer_prefix = self.auth_config.get("use_bearer_prefix", False)
+
+        if not api_key:
+            raise ValueError("API key authentication requires 'api_key' in auth_config")
+
+        # Add Bearer prefix if requested (e.g., for Fireflies API)
+        value = f"Bearer {api_key}" if use_bearer_prefix else api_key
+        return {header_name: value}
+
+
+class MCPConnectionError(Exception):
+    """MCP connection related errors."""
+    pass

parrot/mcp/config.py

@@ -0,0 +1,75 @@
+from dataclasses import dataclass, field
+from typing import List, Optional, Any
+from enum import Enum
+
+
+class AuthMethod(str, Enum):
+    """Authentication method for MCP server."""
+    NONE = "none"
+    API_KEY = "api_key"  # Header-based API key validation
+    OAUTH2_INTERNAL = "oauth2_internal"  # In-memory OAuthAuthorizationServer
+    OAUTH2_EXTERNAL = "oauth2_external"  # External OAuth2 (Azure, Keycloak)
+    BEARER = "bearer"  # navigator-auth session-based
+
+
+@dataclass
+class MCPServerConfig:
+    """Configuration for MCP server."""
+    name: str = "ai-parrot-mcp-server"
+    version: str = "1.0.0"
+    description: str = "AI-Parrot Tools via MCP Protocol"
+
+    # Server settings
+    transport: str = "stdio"  # "stdio" or "http" or "unix"
+    host: str = "localhost"
+    port: int = 8080
+    socket_path: Optional[str] = None  # For UNIX socket transport
+
+    # Tool filtering
+    allowed_tools: Optional[List[str]] = None
+    blocked_tools: Optional[List[str]] = None
+
+    # Logging
+    log_level: str = "INFO"
+
+    # Authentication method (replaces enable_oauth for new code)
+    auth_method: AuthMethod = AuthMethod.NONE
+
+    # API Key settings
+    api_key_header: str = "X-API-Key"
+    api_key_store: Optional[Any] = None  # APIKeyStore instance
+
+    # External OAuth2 settings (for OAUTH2_EXTERNAL)
+    oauth2_issuer_url: Optional[str] = None
+    oauth2_introspection_endpoint: Optional[str] = None
+    oauth2_client_id: Optional[str] = None
+    oauth2_client_secret: Optional[str] = None
+    oauth2_resource_server_url: Optional[str] = None
+
+    # OAuth / Authorization (for OAUTH2_INTERNAL, backward compatible)
+    enable_oauth: bool = False  # Deprecated: use auth_method instead
+    oauth_scopes: Optional[List[str]] = None
+    oauth_token_ttl: int = 3600
+    oauth_code_ttl: int = 600
+    oauth_allow_dynamic_registration: bool = True
+
+    # base path for HTTP transport
+    base_path: str = "/mcp"
+    # custom events path for SSE (optional)
+    events_path: Optional[str] = None
+    
+    # For Future gRPC implementation (expected)
+    grpc_host: Optional[str] = None
+    grpc_port: Optional[int] = None
+    grpc_use_tls: bool = True
+    grpc_cert_path: Optional[str] = None
+    grpc_use_protobuf: bool = False  # Use native protobuf vs JSON-RPC wrapper
+
+    # QUIC transport settings
+    quic_cert_path: Optional[str] = None
+    quic_key_path: Optional[str] = None
+    quic_serialization: str = "msgpack"  # "json" or "msgpack"
+    quic_enable_0rtt: bool = True
+    quic_max_datagram_size: int = 65536
+    quic_idle_timeout: float = 60.0
+    quic_webtransport_path: str = "/mcp"