◉ClassyGitshadowzzh

terminal.py

terminal.py
"""
Terminal MCP Server

This module provides MCP server functionality for executing terminal commands safely.
It supports command execution with timeout controls and returns LLM-friendly formatted results.

Key features:
- Execute terminal commands with configurable timeouts
- Cross-platform command execution support
- Command history tracking and retrieval
- Safety checks for dangerous commands
- LLM-optimized output formatting

Main functions:
- mcp_execute_command: Execute terminal commands with safety checks
- mcp_get_command_history: Retrieve recent command execution history
- mcp_get_terminal_capabilities: Get terminal service capabilities
"""

import asyncio
import json
import os
import platform
import time
import traceback
from datetime import datetime

from dotenv import load_dotenv
from pydantic import BaseModel, Field
from pydantic.fields import FieldInfo

from aworld.logs.util import Color
from examples.gaia.mcp_collections.base import ActionArguments, ActionCollection, ActionResponse

# pylint: disable=C0301


class CommandResult(BaseModel):
    """Individual command execution result with structured data."""

    command: str
    success: bool
    stdout: str
    stderr: str
    return_code: int
    duration: str
    timestamp: str


class TerminalMetadata(BaseModel):
    """Metadata for terminal operation results."""

    command: str
    platform: str
    working_directory: str
    timeout_seconds: int
    execution_time: float | None = None
    return_code: int | None = None
    safety_check_passed: bool = True
    error_type: str | None = None
    history_count: int | None = None


class TerminalActionCollection(ActionCollection):
    """MCP service for terminal command execution with safety controls.

    Provides secure terminal command execution capabilities including:
    - Cross-platform command execution
    - Configurable timeout controls
    - Command history tracking
    - Safety checks for dangerous operations
    - LLM-friendly result formatting
    - Error handling and logging
    """

    def __init__(self, arguments: ActionArguments) -> None:
        super().__init__(arguments)

        # Initialize command history
        self.command_history: list[dict] = []
        self.max_history_size = 50

        # Define dangerous commands for safety
        self.dangerous_commands = [
            "rm -rf /",
            "mkfs",
            "dd if=",
            ":(){ :|:& };:",  # Unix
            "del /f /s /q",
            "format",
            "diskpart",  # Windows
            "sudo rm",
            "sudo dd",
            "sudo mkfs",  # Sudo variants
        ]

        # Get current platform info
        self.platform_info = {
            "system": platform.system(),
            "platform": platform.platform(),
            "architecture": platform.architecture()[0],
        }

        self._color_log("Terminal service initialized", Color.green, "debug")
        self._color_log(f"Platform: {self.platform_info['system']}", Color.blue, "debug")

    def _check_command_safety(self, command: str) -> tuple[bool, str | None]:
        """Check if command is safe to execute.

        Args:
            command: Command string to check

        Returns:
            Tuple of (is_safe, reason_if_unsafe)
        """
        command_lower = command.lower().strip()

        for dangerous_cmd in self.dangerous_commands:
            if dangerous_cmd.lower() in command_lower:
                return False, f"Command contains dangerous pattern: {dangerous_cmd}"

        return True, None

    def _format_command_output(self, result: CommandResult, output_format: str = "markdown") -> str:
        """Format command execution results for LLM consumption.

        Args:
            result: Command execution result
            output_format: Format type ('markdown', 'json', 'text')

        Returns:
            Formatted string suitable for LLM consumption
        """
        if output_format == "json":
            return json.dumps(result.model_dump(), indent=2)

        elif output_format == "text":
            output_parts = [
                f"Command: {result.command}",
                f"Status: {'SUCCESS' if result.success else 'FAILED'}",
                f"Duration: {result.duration}",
                f"Return Code: {result.return_code}",
            ]

            if result.stdout:
                output_parts.extend(["\nOutput:", result.stdout])

            if result.stderr:
                output_parts.extend(["\nErrors/Warnings:", result.stderr])

            return "\n".join(output_parts)

        else:  # markdown (default)
            status_emoji = "✅" if result.success else "❌"

            output_parts = [
                f"# Terminal Command Execution {status_emoji}",
                f"**Command:** `{result.command}`",
                f"**Status:** {'SUCCESS' if result.success else 'FAILED'}",
                f"**Duration:** {result.duration}",
                f"**Return Code:** {result.return_code}",
                f"**Timestamp:** {result.timestamp}",
            ]

            if result.stdout:
                output_parts.extend(["\n## Output", "```", result.stdout.strip(), "```"])

            if result.stderr:
                output_parts.extend(["\n## Errors/Warnings", "```", result.stderr.strip(), "```"])

            return "\n".join(output_parts)

    async def _execute_command_async(self, command: str, timeout: int) -> CommandResult:
        """Execute command asynchronously with timeout.

        Args:
            command: Command to execute
            timeout: Timeout in seconds

        Returns:
            CommandResult with execution details
        """
        start_time = datetime.now()

        try:
            # Create appropriate subprocess for platform
            if self.platform_info["system"] == "Windows":
                process = await asyncio.create_subprocess_shell(
                    command, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE, shell=True
                )
            else:
                process = await asyncio.create_subprocess_shell(
                    command,
                    stdout=asyncio.subprocess.PIPE,
                    stderr=asyncio.subprocess.PIPE,
                    shell=True,
                    executable="/bin/bash",
                )

            try:
                stdout, stderr = await asyncio.wait_for(process.communicate(), timeout)
                stdout = stdout.decode("utf-8", errors="replace")
                stderr = stderr.decode("utf-8", errors="replace")
                return_code = process.returncode

            except asyncio.TimeoutError:
                try:
                    process.kill()
                except Exception:
                    pass

                duration = str(datetime.now() - start_time)
                return CommandResult(
                    command=command,
                    success=False,
                    stdout="",
                    stderr=f"Command timed out after {timeout} seconds",
                    return_code=-1,
                    duration=duration,
                    timestamp=start_time.isoformat(),
                )

            duration = str(datetime.now() - start_time)
            result = CommandResult(
                command=command,
                success=return_code == 0,
                stdout=stdout,
                stderr=stderr,
                return_code=return_code,
                duration=duration,
                timestamp=start_time.isoformat(),
            )

            # Add to history
            self.command_history.append(
                {
                    "timestamp": start_time.isoformat(),
                    "command": command,
                    "success": return_code == 0,
                    "duration": duration,
                }
            )

            # Maintain history size limit
            if len(self.command_history) > self.max_history_size:
                self.command_history.pop(0)

            return result

        except Exception as e:
            duration = str(datetime.now() - start_time)
            return CommandResult(
                command=command,
                success=False,
                stdout="",
                stderr=f"Error executing command: {str(e)}",
                return_code=-1,
                duration=duration,
                timestamp=start_time.isoformat(),
            )

    async def mcp_execute_command(
        self,
        command: str = Field(description="Terminal command to execute"),
        timeout: int = Field(default=30, description="Command timeout in seconds (default: 30)"),
        output_format: str = Field(default="markdown", description="Output format: 'markdown', 'json', or 'text'"),
    ) -> ActionResponse:
        """Execute a terminal command with safety checks and timeout controls.

        This tool provides secure command execution with:
        - Cross-platform compatibility (Windows, macOS, Linux)
        - Configurable timeout controls
        - Safety checks for dangerous commands
        - LLM-optimized result formatting
        - Command history tracking

        Specialized Feature:
        - Execute Python code and output the result to stdout
            - Example (Directly execute simple Python code): `python -c "nums = [1, 2, 3, 4]\nsum_of_nums = sum(nums)\nprint(f'{sum_of_nums=}')"`
            - Example (Execute code from a file): `python my_script.py`

        Args:
            command: The terminal command to execute
            timeout: Maximum execution time in seconds
            output_format: Format for the response output

        Returns:
            ActionResponse with command execution results and metadata
        """
        # Handle FieldInfo objects
        if isinstance(command, FieldInfo):
            command = command.default
        if isinstance(timeout, FieldInfo):
            timeout = timeout.default
        if isinstance(output_format, FieldInfo):
            output_format = output_format.default

        try:
            # Safety check
            is_safe, safety_reason = self._check_command_safety(command)
            if not is_safe:
                return ActionResponse(
                    success=False,
                    message=f"Command rejected for security reasons: {safety_reason}",
                    metadata=TerminalMetadata(
                        command=command,
                        platform=self.platform_info["system"],
                        working_directory=str(self.workspace),
                        timeout_seconds=timeout,
                        safety_check_passed=False,
                        error_type="security_violation",
                    ).model_dump(),
                )

            self._color_log(f"🔧 Executing command: {command}", Color.cyan)

            # Execute command
            start_time = time.time()
            result = await self._execute_command_async(command, timeout)
            execution_time = time.time() - start_time

            # Format output
            formatted_output = self._format_command_output(result, output_format)

            # Create metadata
            metadata = TerminalMetadata(
                command=command,
                platform=self.platform_info["system"],
                working_directory=str(self.workspace),
                timeout_seconds=timeout,
                execution_time=execution_time,
                return_code=result.return_code,
                safety_check_passed=True,
            )

            if result.success:
                self._color_log("✅ Command completed successfully", Color.green)
            else:
                self._color_log(f"❌ Command failed with return code {result.return_code}", Color.red)
                metadata.error_type = "execution_failure"

            return ActionResponse(success=result.success, message=formatted_output, metadata=metadata.model_dump())

        except Exception as e:
            error_msg = f"Failed to execute command: {str(e)}"
            self.logger.error(f"Command execution error: {traceback.format_exc()}")

            return ActionResponse(
                success=False,
                message=error_msg,
                metadata=TerminalMetadata(
                    command=command,
                    platform=self.platform_info["system"],
                    working_directory=str(self.workspace),
                    timeout_seconds=timeout,
                    safety_check_passed=True,
                    error_type="internal_error",
                ).model_dump(),
            )

    def mcp_get_command_history(
        self,
        count: int = Field(default=10, description="Number of recent commands to return (default: 10)"),
        output_format: str = Field(default="markdown", description="Output format: 'markdown', 'json', or 'text'"),
    ) -> ActionResponse:
        """Retrieve recent command execution history.

        Args:
            count: Number of recent commands to return
            output_format: Format for the response output

        Returns:
            ActionResponse with command history and metadata
        """
        # Handle FieldInfo objects
        if isinstance(count, FieldInfo):
            count = count.default
        if isinstance(output_format, FieldInfo):
            output_format = output_format.default

        try:
            # Get recent history
            recent_history = self.command_history[-count:] if self.command_history else []

            if not recent_history:
                message = "No command history available."
            else:
                if output_format == "json":
                    message = json.dumps(recent_history, indent=2)
                elif output_format == "text":
                    history_lines = []
                    for i, entry in enumerate(recent_history, 1):
                        status = "SUCCESS" if entry["success"] else "FAILED"
                        history_lines.append(
                            f"{i}. [{entry['timestamp']}] {entry['command']} - {status}"
                            f" ({entry.get('duration', 'N/A')})"
                        )
                    message = "\n".join(history_lines)
                else:  # markdown
                    history_lines = ["# Command History", f"Showing {len(recent_history)} recent commands:\n"]

                    for i, entry in enumerate(recent_history, 1):
                        status_emoji = "✅" if entry["success"] else "❌"
                        history_lines.extend(
                            [
                                f"## {i}. {status_emoji} `{entry['command']}`",
                                f"- **Timestamp:** {entry['timestamp']}",
                                f"- **Duration:** {entry.get('duration', 'N/A')}",
                                "",
                            ]
                        )

                    message = "\n".join(history_lines)

            metadata = TerminalMetadata(
                command="get_command_history",
                platform=self.platform_info["system"],
                working_directory=str(self.workspace),
                timeout_seconds=0,
                history_count=len(recent_history),
            )

            return ActionResponse(success=True, message=message, metadata=metadata.model_dump())

        except Exception as e:
            error_msg = f"Failed to retrieve command history: {str(e)}"
            self.logger.error(f"History retrieval error: {traceback.format_exc()}")

            return ActionResponse(
                success=False,
                message=error_msg,
                metadata=TerminalMetadata(
                    command="get_command_history",
                    platform=self.platform_info["system"],
                    working_directory=str(self.workspace),
                    timeout_seconds=0,
                    error_type="internal_error",
                ).model_dump(),
            )

    def mcp_get_terminal_capabilities(self) -> ActionResponse:
        """Get information about terminal service capabilities and configuration.

        Returns:
            ActionResponse with terminal service capabilities and current configuration
        """
        capabilities = {
            "platform_info": self.platform_info,
            "supported_features": [
                "Cross-platform command execution",
                "Configurable timeout controls",
                "Command history tracking",
                "Safety checks for dangerous commands",
                "Multiple output formats (markdown, json, text)",
                "LLM-optimized result formatting",
                "Async command execution",
            ],
            "supported_formats": ["markdown", "json", "text"],
            "configuration": {
                "max_history_size": self.max_history_size,
                "current_history_count": len(self.command_history),
                "working_directory": str(self.workspace),
                "dangerous_commands_count": len(self.dangerous_commands),
            },
            "safety_features": [
                "Dangerous command detection",
                "Timeout controls",
                "Error handling and logging",
                "Command validation",
            ],
        }

        formatted_info = f"""# Terminal Service Capabilities
        
        ## Platform Information
        - **System:** {self.platform_info["system"]}
        - **Platform:** {self.platform_info["platform"]}
        - **Architecture:** {self.platform_info["architecture"]}

        ## Features
        {chr(10).join(f"- {feature}" for feature in capabilities["supported_features"])}

        ## Supported Output Formats
        {chr(10).join(f"- {fmt}" for fmt in capabilities["supported_formats"])}

        ## Current Configuration
        - **Max History Size:** {capabilities["configuration"]["max_history_size"]}
        - **Current History Count:** {capabilities["configuration"]["current_history_count"]}
        - **Working Directory:** {capabilities["configuration"]["working_directory"]}
        - **Dangerous Commands Monitored:** {capabilities["configuration"]["dangerous_commands_count"]}

        ## Safety Features
        {chr(10).join(f"- {feature}" for feature in capabilities["safety_features"])}
        """

        return ActionResponse(success=True, message=formatted_info, metadata=capabilities)


# Default arguments for testing
if __name__ == "__main__":
    load_dotenv()

    arguments = ActionArguments(
        name="terminal",
        transport="stdio",
        workspace=os.getenv("AWORLD_WORKSPACE", "~"),
    )
    try:
        service = TerminalActionCollection(arguments)
        service.run()
    except Exception as e:
        print(f"An error occurred: {e}: {traceback.format_exc()}")