alita-sdk 0.3.257__py3-none-any.whl → 0.3.562__py3-none-any.whl

alita_sdk/cli/mcp_loader.py

@@ -0,0 +1,315 @@
+"""
+MCP (Model Context Protocol) server integration.
+
+Handles loading MCP server configurations and connecting to MCP servers
+using langchain-mcp-adapters to load tools with persistent sessions.
+
+Requires: pip install langchain-mcp-adapters
+Documentation: https://docs.langchain.com/oss/python/langchain/mcp
+Issue Reference: https://github.com/langchain-ai/langchain-mcp-adapters/issues/178
+"""
+
+import json
+import logging
+from pathlib import Path
+from typing import Dict, Any, List, Optional
+from rich.console import Console
+
+from .config import substitute_env_vars
+
+console = Console()
+logger = logging.getLogger(__name__)
+
+
+def load_mcp_config(file_path: str) -> Dict[str, Any]:
+    """Load MCP configuration from JSON file (VSCode/Copilot format).
+    
+    Args:
+        file_path: Path to mcp.json configuration file
+        
+    Returns:
+        Dictionary with mcpServers configuration, or empty dict if file doesn't exist
+    """
+    path = Path(file_path)
+    
+    if not path.exists():
+        # Gracefully handle missing file - MCP is optional
+        return {}
+    
+    try:
+        with open(path) as f:
+            content = f.read()
+        
+        # Apply environment variable substitution
+        content = substitute_env_vars(content)
+        config = json.loads(content)
+        
+        # Validate structure
+        if 'mcpServers' not in config:
+            console.print(f"[yellow]Warning: {file_path} missing 'mcpServers' key[/yellow]")
+            return {}
+            
+        return config
+    except json.JSONDecodeError as e:
+        console.print(f"[red]Error parsing {file_path}:[/red] {e}")
+        return {}
+    except Exception as e:
+        console.print(f"[red]Error loading {file_path}:[/red] {e}")
+        return {}
+
+
+def load_mcp_tools(agent_def: Dict[str, Any], mcp_config_path: str) -> List[Dict[str, Any]]:
+    """Load MCP tools from agent definition with tool-level filtering.
+    
+    This function creates MCP server configuration objects that will be processed
+    by the runtime layer using langchain-mcp-adapters to connect to MCP servers
+    and load their tools.
+    
+    The actual connection happens in create_mcp_client() which uses:
+    - langchain_mcp_adapters.client.MultiServerMCPClient for connection
+    - langchain_mcp_adapters.tools.load_mcp_tools for tool loading
+    
+    Args:
+        agent_def: Agent definition dictionary containing mcps list
+        mcp_config_path: Path to mcp.json configuration file (workspace-level)
+        
+    Returns:
+        List of MCP server configurations that will be used by MultiServerMCPClient
+        to connect to servers and load tools with filtering applied.
+    """
+    import fnmatch
+    
+    toolkit_configs = []
+    
+    # Get MCP configuration
+    mcps = agent_def.get('mcps', [])
+    if not mcps:
+        return toolkit_configs
+    
+    # Load mcp.json config file from workspace
+    mcp_config = load_mcp_config(mcp_config_path)
+    mcp_servers = mcp_config.get('mcpServers', {})
+    
+    # Process each MCP entry
+    for mcp_entry in mcps:
+        # Handle both string and object formats
+        if isinstance(mcp_entry, str):
+            server_name = mcp_entry
+            agent_selected_tools = None
+            agent_excluded_tools = None
+        elif isinstance(mcp_entry, dict):
+            server_name = mcp_entry.get('name')
+            agent_selected_tools = mcp_entry.get('selected_tools')
+            agent_excluded_tools = mcp_entry.get('excluded_tools')
+        else:
+            console.print(f"[yellow]Warning: Invalid MCP entry format: {mcp_entry}[/yellow]")
+            continue
+        
+        if not server_name:
+            console.print(f"[yellow]Warning: MCP entry missing 'name': {mcp_entry}[/yellow]")
+            continue
+        
+        # Get server configuration
+        server_config = mcp_servers.get(server_name)
+        if not server_config:
+            console.print(f"[yellow]Warning: MCP server '{server_name}' not found in MCP configuration[/yellow]")
+            continue
+        
+        # Determine tool selection (agent overrides server defaults)
+        server_selected_tools = server_config.get('selected_tools')
+        server_excluded_tools = server_config.get('excluded_tools')
+        
+        # Agent overrides take precedence
+        final_selected_tools = agent_selected_tools if agent_selected_tools is not None else server_selected_tools
+        final_excluded_tools = agent_excluded_tools if agent_excluded_tools is not None else server_excluded_tools
+        
+        # Get connection details
+        server_type = server_config.get('type')  # VSCode format: "stdio" or "streamable_http"
+        server_url = server_config.get('url')
+        server_command = server_config.get('command')
+        server_args = server_config.get('args', [])
+        server_env = server_config.get('env', {})
+        stateful = server_config.get('stateful', False)
+        
+        # Build MCP server config for langchain-mcp-adapters
+        # Support both VSCode format (type: "stdio") and our format (command: "...")
+        if server_type == 'stdio' or server_command:
+            # stdio transport (subprocess)
+            if not server_command:
+                console.print(f"[red]Error: MCP server '{server_name}' has type 'stdio' but no 'command'[/red]")
+                continue
+            
+            console.print(f"[yellow]Note: MCP server '{server_name}' uses command/stdio connection[/yellow]")
+            mcp_server_config = {
+                'transport': 'stdio',
+                'command': server_command,
+                'args': server_args or []
+            }
+        elif server_type == 'streamable_http' or server_url:
+            # HTTP-based transport
+            if not server_url:
+                console.print(f"[red]Error: MCP server '{server_name}' has type 'streamable_http' but no 'url'[/red]")
+                continue
+            
+            mcp_server_config = {
+                'transport': 'streamable_http',
+                'url': server_url
+            }
+        else:
+            console.print(f"[red]Error: MCP server '{server_name}' has neither 'type'/'url' nor 'command'[/red]")
+            continue
+        
+        # Add environment variables if specified
+        if server_env:
+            mcp_server_config['env'] = server_env
+        
+        # Wrap in toolkit config format
+        toolkit_config = {
+            'toolkit_type': 'mcp',
+            'name': server_name,
+            'mcp_server_config': mcp_server_config,
+        }
+        
+        # Add tool filtering if specified
+        if final_selected_tools is not None:
+            toolkit_config['selected_tools'] = final_selected_tools
+        if final_excluded_tools is not None:
+            toolkit_config['excluded_tools'] = final_excluded_tools
+        
+        toolkit_configs.append(toolkit_config)
+        
+        # Display loaded tools info
+        if final_selected_tools:
+            tools_display = ', '.join(final_selected_tools)
+            console.print(f"✓ Loaded MCP server: [cyan]{server_name}[/cyan] (selected: {tools_display})")
+        elif final_excluded_tools:
+            console.print(f"✓ Loaded MCP server: [cyan]{server_name}[/cyan] (excluded: {', '.join(final_excluded_tools)})")
+        else:
+            console.print(f"✓ Loaded MCP server: [cyan]{server_name}[/cyan] (all tools)")
+    
+    return toolkit_configs
+
+
+class MCPSessionManager:
+    """Manages persistent MCP sessions for stateful tools like Playwright.
+    
+    Holds MCP client and session context managers alive for the entire agent lifetime.
+    This is critical for stateful MCP servers that maintain state across tool calls
+    (e.g., Playwright browser sessions).
+    
+    See: https://github.com/langchain-ai/langchain-mcp-adapters/issues/178
+    """
+    def __init__(self):
+        self.client = None
+        self.sessions = {}
+        self._session_contexts = {}
+    
+    def __del__(self):
+        """Cleanup sessions when manager is garbage collected."""
+        # Best effort cleanup - sessions will be closed when process exits anyway
+        pass
+
+
+async def load_mcp_tools_async(mcp_toolkit_configs: List[Dict[str, Any]]):
+    """
+    Load actual MCP tools from servers with persistent sessions.
+    
+    IMPORTANT: This function returns an MCPSessionManager that MUST be kept alive
+    for the entire agent session to maintain stateful MCP server state (e.g., browser).
+    
+    Args:
+        mcp_toolkit_configs: List of MCP toolkit configurations with transport details
+        
+    Returns:
+        Tuple of (session_manager, list_of_tools) where:
+        - session_manager: MCPSessionManager that holds client and persistent sessions
+        - list_of_tools: LangChain async tools from MCP that use persistent sessions
+    """
+    if not mcp_toolkit_configs:
+        return None, []
+    
+    try:
+        from langchain_mcp_adapters.client import MultiServerMCPClient
+        from langchain_mcp_adapters.tools import load_mcp_tools
+    except ImportError:
+        console.print("[yellow]Warning: langchain-mcp-adapters not installed. MCP tools will not be available.[/yellow]")
+        console.print("[yellow]Install with: pip install langchain-mcp-adapters[/yellow]")
+        return None, []
+    
+    # Build server configs for MultiServerMCPClient
+    server_configs = {}
+    for config in mcp_toolkit_configs:
+        server_name = config.get('name', 'unknown')
+        mcp_server_config = config.get('mcp_server_config', {})
+        transport = mcp_server_config.get('transport', 'stdio')
+        
+        if transport == 'stdio':
+            command = mcp_server_config.get('command')
+            args = mcp_server_config.get('args', [])
+            env = mcp_server_config.get('env')
+            
+            # Ensure command is a string
+            if isinstance(command, list):
+                command = command[0] if command else None
+            
+            # Build config dict - only include env if it's set
+            config_dict = {
+                'transport': 'stdio',
+                'command': command,
+                'args': args
+            }
+            if env:
+                config_dict['env'] = env
+            
+            server_configs[server_name] = config_dict
+            console.print(f"[dim]MCP server {server_name}: {command} {' '.join(args)}[/dim]")
+            
+        elif transport == 'streamable_http':
+            server_configs[server_name] = {
+                'transport': 'streamable_http',
+                'url': mcp_server_config.get('url'),
+                'headers': mcp_server_config.get('headers')
+            }
+    
+    if not server_configs:
+        return None, []
+    
+    try:
+        # Create session manager to hold everything alive
+        manager = MCPSessionManager()
+        manager.client = MultiServerMCPClient(server_configs)
+        
+        # Create PERSISTENT sessions for each server
+        # This keeps the MCP server subprocess and state alive for stateful tools
+        all_tools = []
+        
+        for server_name in server_configs.keys():
+            # Enter the session context and keep it alive for entire agent lifetime
+            session_context = manager.client.session(server_name)
+            session = await session_context.__aenter__()
+            
+            # Store both for cleanup and reference
+            manager.sessions[server_name] = session
+            manager._session_contexts[server_name] = session_context
+            
+            # Load tools using the persistent session
+            tools = await load_mcp_tools(
+                session,
+                connection=manager.client.connections[server_name],
+                server_name=server_name
+            )
+            all_tools.extend(tools)
+            
+            console.print(f"[dim]Created persistent session for {server_name}: {len(tools)} tools[/dim]")
+        
+        console.print(f"✓ Loaded {len(all_tools)} MCP tools total from {len(mcp_toolkit_configs)} servers with persistent sessions")
+        
+        return manager, all_tools
+            
+    except ImportError:
+        # Already handled above
+        raise
+    except Exception as e:
+        logger.exception(f"Failed to create MCP client and sessions")
+        console.print(f"[red]Error: Failed to load MCP tools: {e}[/red]")
+        return None, []

alita_sdk/cli/toolkit.py

@@ -0,0 +1,327 @@
+"""
+Toolkit testing commands for Alita CLI.
+
+Provides commands to list, inspect, and test toolkits directly from the command line.
+"""
+
+import click
+import json
+import logging
+from typing import Optional, Dict, Any
+
+from .cli import get_client
+from .toolkit_loader import load_toolkit_config
+
+logger = logging.getLogger(__name__)
+
+
+@click.group()
+def toolkit():
+    """Toolkit testing commands."""
+    pass
+
+
+@toolkit.command('list')
+@click.option('--failed', is_flag=True, help='Show failed imports')
+@click.pass_context
+def toolkit_list(ctx, failed: bool):
+    """List all available toolkits."""
+    formatter = ctx.obj['formatter']
+    
+    try:
+        # Import toolkit registry
+        from alita_sdk.tools import AVAILABLE_TOOLS, AVAILABLE_TOOLKITS, FAILED_IMPORTS
+        
+        if failed:
+            # Show failed imports
+            if FAILED_IMPORTS:
+                click.echo("\nFailed toolkit imports:\n")
+                for name, error in FAILED_IMPORTS.items():
+                    click.echo(f"  - {name}: {error}")
+                click.echo(f"\nTotal failed: {len(FAILED_IMPORTS)}")
+            else:
+                click.echo("\nNo failed imports")
+            return
+        
+        # Build toolkit list
+        toolkits = []
+        for name, toolkit_dict in AVAILABLE_TOOLS.items():
+            toolkit_class_name = None
+            if 'toolkit_class' in toolkit_dict:
+                toolkit_class_name = toolkit_dict['toolkit_class'].__name__
+            
+            toolkits.append({
+                'name': name,
+                'class_name': toolkit_class_name,
+                'has_get_tools': 'get_tools' in toolkit_dict
+            })
+        
+        # Format and display
+        output = formatter.format_toolkit_list(toolkits)
+        click.echo(output)
+        
+    except Exception as e:
+        logger.exception("Failed to list toolkits")
+        click.echo(formatter.format_error(str(e)), err=True)
+        raise click.Abort()
+
+
+@toolkit.command('schema')
+@click.argument('toolkit_name')
+@click.pass_context
+def toolkit_schema(ctx, toolkit_name: str):
+    """
+    Show configuration schema for a toolkit.
+    
+    TOOLKIT_NAME: Name of the toolkit (e.g., 'jira', 'github', 'confluence')
+    """
+    formatter = ctx.obj['formatter']
+    
+    try:
+        # Import toolkit registry
+        from alita_sdk.tools import AVAILABLE_TOOLKITS
+        
+        # Find toolkit class
+        toolkit_class = None
+        for name, cls in AVAILABLE_TOOLKITS.items():
+            if name.lower().replace('toolkit', '').replace('alita', '').strip() == toolkit_name.lower():
+                toolkit_class = cls
+                break
+        
+        if not toolkit_class:
+            # Try direct match
+            for name, cls in AVAILABLE_TOOLKITS.items():
+                if toolkit_name.lower() in name.lower():
+                    toolkit_class = cls
+                    break
+        
+        if not toolkit_class:
+            available = [name.lower().replace('toolkit', '').replace('alita', '').strip() 
+                        for name in AVAILABLE_TOOLKITS.keys()]
+            raise click.ClickException(
+                f"Toolkit '{toolkit_name}' not found.\n"
+                f"Available toolkits: {', '.join(sorted(set(available)))}"
+            )
+        
+        # Get schema
+        schema_model = toolkit_class.toolkit_config_schema()
+        schema = schema_model.model_json_schema()
+        
+        # Format and display
+        if formatter.__class__.__name__ == 'JSONFormatter':
+            output = formatter.format_toolkit_schema(toolkit_name, schema)
+        else:
+            output = formatter.format_toolkit_schema(toolkit_name, schema)
+        
+        click.echo(output)
+        
+    except click.ClickException:
+        raise
+    except Exception as e:
+        logger.exception(f"Failed to get schema for toolkit '{toolkit_name}'")
+        click.echo(formatter.format_error(str(e)), err=True)
+        raise click.Abort()
+
+
+@toolkit.command('test')
+@click.argument('toolkit_type')
+@click.option('--tool', required=True, help='Tool name to execute')
+@click.option('--config', 'config_file', type=click.File('r'), 
+              help='Toolkit configuration JSON file')
+@click.option('--params', type=click.File('r'), 
+              help='Tool parameters JSON file')
+@click.option('--param', multiple=True, 
+              help='Tool parameter as key=value (can be used multiple times)')
+@click.option('--llm-model', default='gpt-4o-mini', 
+              help='LLM model to use (default: gpt-4o-mini)')
+@click.option('--temperature', default=0.1, type=float,
+              help='LLM temperature (default: 0.1)')
+@click.option('--max-tokens', default=1000, type=int,
+              help='LLM max tokens (default: 1000)')
+@click.pass_context
+def toolkit_test(ctx, toolkit_type: str, tool: str, config_file, params, 
+                param, llm_model: str, temperature: float, max_tokens: int):
+    """Test a specific tool from a toolkit.
+    
+    TOOLKIT_TYPE: Type of toolkit (e.g., 'jira', 'github', 'confluence')
+    
+    \b
+    Examples:
+      alita toolkit test jira --tool get_issue --config jira.json --params params.json
+      alita toolkit test jira --tool get_issue --config jira.json --param issue_key=PROJ-123
+      alita -o json toolkit test github --tool get_issue --config github.json
+    """
+    formatter = ctx.obj['formatter']
+    client = get_client(ctx)
+    
+    try:
+        # Load toolkit configuration
+        toolkit_config = {}
+        if config_file:
+            toolkit_config = load_toolkit_config(config_file.name)
+            logger.debug(f"Loaded toolkit config from {config_file.name}")
+        
+        # Add the tool to selected_tools in the config
+        if 'selected_tools' not in toolkit_config:
+            toolkit_config['selected_tools'] = []
+        if tool not in toolkit_config['selected_tools']:
+            toolkit_config['selected_tools'].append(tool)
+        
+        # Load tool parameters
+        tool_params = {}
+        if params:
+            tool_params = json.load(params)
+            logger.debug(f"Loaded tool params from {params.name}")
+        
+        # Parse inline parameters
+        if param:
+            for param_pair in param:
+                if '=' not in param_pair:
+                    raise click.ClickException(
+                        f"Invalid parameter format: '{param_pair}'. "
+                        "Use --param key=value"
+                    )
+                key, value = param_pair.split('=', 1)
+                
+                # Try to parse as JSON for complex values
+                try:
+                    tool_params[key] = json.loads(value)
+                except json.JSONDecodeError:
+                    tool_params[key] = value
+            
+            logger.debug(f"Parsed {len(param)} inline parameters")
+        
+        # Prepare full toolkit configuration
+        full_config = {
+            'toolkit_name': toolkit_type,
+            'type': toolkit_type,
+            'settings': toolkit_config
+        }
+        
+        # LLM configuration
+        llm_config = {
+            'temperature': temperature,
+            'max_tokens': max_tokens,
+        }
+        
+        # Execute test
+        logger.info(f"Testing tool '{tool}' from toolkit '{toolkit_type}'")
+        result = client.test_toolkit_tool(
+            toolkit_config=full_config,
+            tool_name=tool,
+            tool_params=tool_params,
+            llm_model=llm_model,
+            llm_config=llm_config
+        )
+        
+        # Format and display result
+        output = formatter.format_toolkit_result(result)
+        click.echo(output)
+        
+        # Exit with error code if test failed
+        if not result.get('success', False):
+            raise click.Abort()
+        
+    except click.ClickException:
+        raise
+    except Exception as e:
+        logger.exception("Failed to execute toolkit test")
+        click.echo(formatter.format_error(str(e)), err=True)
+        raise click.Abort()
+
+
+@toolkit.command('tools')
+@click.argument('toolkit_type')
+@click.option('--config', 'config_file', type=click.File('r'),
+              help='Toolkit configuration JSON file (required for some toolkits)')
+@click.pass_context
+def toolkit_tools(ctx, toolkit_type: str, config_file):
+    """
+    List available tools for a specific toolkit.
+    
+    TOOLKIT_TYPE: Type of toolkit (e.g., 'jira', 'github', 'confluence')
+    
+    Some toolkits require configuration to determine available tools.
+    Use --config to provide configuration if needed.
+    """
+    formatter = ctx.obj['formatter']
+    client = get_client(ctx)
+    
+    try:
+        # Load toolkit configuration if provided
+        toolkit_config = {}
+        if config_file:
+            toolkit_config = load_toolkit_config(config_file.name)
+        
+        # Import and instantiate toolkit
+        from alita_sdk.tools import AVAILABLE_TOOLS
+        
+        if toolkit_type not in AVAILABLE_TOOLS:
+            raise click.ClickException(
+                f"Toolkit '{toolkit_type}' not found. "
+                f"Use 'alita-cli toolkit list' to see available toolkits."
+            )
+        
+        toolkit_entry = AVAILABLE_TOOLS[toolkit_type]
+        
+        if 'toolkit_class' not in toolkit_entry:
+            raise click.ClickException(
+                f"Toolkit '{toolkit_type}' does not support tool listing"
+            )
+        
+        # Get toolkit class and instantiate
+        toolkit_class = toolkit_entry['toolkit_class']
+        
+        # Create minimal configuration
+        full_config = {
+            'toolkit_name': toolkit_type,
+            'type': toolkit_type,
+            'settings': toolkit_config
+        }
+        
+        # Try to get available tools via API wrapper
+        try:
+            # Instantiate API wrapper if possible
+            api_wrapper_class = None
+            
+            # Find API wrapper class by inspecting toolkit
+            import inspect
+            for name, obj in inspect.getmembers(toolkit_class):
+                if inspect.isclass(obj) and 'ApiWrapper' in obj.__name__:
+                    api_wrapper_class = obj
+                    break
+            
+            if api_wrapper_class:
+                try:
+                    api_wrapper = api_wrapper_class(**toolkit_config)
+                    available_tools = api_wrapper.get_available_tools()
+                    
+                    # Format tools list
+                    click.echo(f"\nAvailable tools for {toolkit_type}:\n")
+                    for tool_info in available_tools:
+                        tool_name = tool_info.get('name', 'unknown')
+                        description = tool_info.get('description', '')
+                        click.echo(f"  - {tool_name}")
+                        if description:
+                            click.echo(f"      {description}")
+                    
+                    click.echo(f"\nTotal: {len(available_tools)} tools")
+                    return
+                    
+                except Exception as e:
+                    logger.debug(f"Could not instantiate API wrapper: {e}")
+            
+            # Fallback: show general info
+            click.echo(f"\n{toolkit_type} toolkit is available")
+            click.echo("Use 'alita-cli toolkit schema {toolkit_type}' to see configuration options")
+            
+        except Exception as e:
+            logger.exception("Failed to list tools")
+            raise click.ClickException(str(e))
+        
+    except click.ClickException:
+        raise
+    except Exception as e:
+        logger.exception("Failed to list toolkit tools")
+        click.echo(formatter.format_error(str(e)), err=True)
+        raise click.Abort()