linux-mcp-server 0.1.0a2__py3-none-any.whl

linux_mcp_server/tools/system_info.py

@@ -0,0 +1,524 @@
+"""System information tools."""
+
+import os
+import platform
+
+from datetime import datetime
+
+import psutil
+
+from mcp.types import ToolAnnotations
+
+from linux_mcp_server.audit import log_tool_call
+from linux_mcp_server.connection.ssh import execute_command
+from linux_mcp_server.server import mcp
+from linux_mcp_server.utils import format_bytes
+from linux_mcp_server.utils.types import Host
+from linux_mcp_server.utils.types import Username
+
+
+@mcp.tool(
+    title="Get system information",
+    description="Get basic system information such as operating system, distribution, kernel version, uptime, and last boot time.",
+    annotations=ToolAnnotations(readOnlyHint=True),
+)
+@log_tool_call
+async def get_system_information(  # noqa: C901
+    host: Host | None = None,
+    username: Username | None = None,
+) -> str:
+    """
+    Get basic system information.
+    """
+    info = []
+
+    try:
+        if host:
+            # Remote execution - use Linux commands
+            # Hostname
+            returncode, stdout, _ = await execute_command(
+                ["hostname"],
+                host=host,
+                username=username,
+            )
+            if returncode == 0 and stdout:
+                info.append(f"Hostname: {stdout.strip()}")
+
+            # OS Information from /etc/os-release
+            returncode, stdout, _ = await execute_command(
+                ["cat", "/etc/os-release"],
+                host=host,
+                username=username,
+            )
+            if returncode == 0 and stdout:
+                os_info = {}
+                for line in stdout.split("\n"):
+                    line = line.strip()
+                    if "=" in line:
+                        key, value = line.split("=", 1)
+                        os_info[key] = value.strip('"')
+
+                info.append(f"Operating System: {os_info.get('PRETTY_NAME', 'Unknown')}")
+                if "VERSION_ID" in os_info:
+                    info.append(f"OS Version: {os_info['VERSION_ID']}")
+
+            # Kernel version
+            returncode, stdout, _ = await execute_command(
+                ["uname", "-r"],
+                host=host,
+                username=username,
+            )
+            if returncode == 0 and stdout:
+                info.append(f"Kernel Version: {stdout.strip()}")
+
+            # Architecture
+            returncode, stdout, _ = await execute_command(
+                ["uname", "-m"],
+                host=host,
+                username=username,
+            )
+            if returncode == 0 and stdout:
+                info.append(f"Architecture: {stdout.strip()}")
+
+            # Uptime
+            returncode, stdout, _ = await execute_command(
+                ["uptime", "-p"],
+                host=host,
+                username=username,
+            )
+            if returncode == 0 and stdout:
+                info.append(f"Uptime: {stdout.strip()}")
+
+            # Boot time
+            returncode, stdout, _ = await execute_command(
+                ["uptime", "-s"],
+                host=host,
+                username=username,
+            )
+            if returncode == 0 and stdout:
+                info.append(f"Boot Time: {stdout.strip()}")
+        else:
+            # Local execution - use psutil and platform
+            # Hostname
+            hostname = platform.node()
+            info.append(f"Hostname: {hostname}")
+
+            # OS Information
+            if os.path.exists("/etc/os-release"):
+                os_info = {}
+                with open("/etc/os-release") as f:
+                    for line in f:
+                        line = line.strip()
+                        if "=" in line:
+                            key, value = line.split("=", 1)
+                            os_info[key] = value.strip('"')
+
+                info.append(f"Operating System: {os_info.get('PRETTY_NAME', 'Unknown')}")
+                if "VERSION_ID" in os_info:
+                    info.append(f"OS Version: {os_info['VERSION_ID']}")
+            else:
+                info.append(f"Operating System: {platform.system()} {platform.release()}")
+
+            # Kernel version
+            kernel = platform.release()
+            info.append(f"Kernel Version: {kernel}")
+
+            # Architecture
+            arch = platform.machine()
+            info.append(f"Architecture: {arch}")
+
+            # Uptime
+            boot_time = datetime.fromtimestamp(psutil.boot_time())
+            uptime = datetime.now() - boot_time
+            days = uptime.days
+            hours, remainder = divmod(uptime.seconds, 3600)
+            minutes, seconds = divmod(remainder, 60)
+            info.append(f"Uptime: {days}d {hours}h {minutes}m {seconds}s")
+            info.append(f"Boot Time: {boot_time.strftime('%Y-%m-%d %H:%M:%S')}")
+
+        return "\n".join(info)
+    except Exception as e:
+        return f"Error gathering system information: {str(e)}"
+
+
+@mcp.tool(
+    title="Get CPU information",
+    description="Get CPU information.",
+    annotations=ToolAnnotations(readOnlyHint=True),
+)
+@log_tool_call
+async def get_cpu_information(  # noqa: C901
+    host: Host | None = None,
+    username: Username | None = None,
+) -> str:
+    """
+    Get CPU information.
+    """
+    info = []
+
+    try:
+        if host:
+            # Remote execution - use Linux commands
+            # Get CPU model from /proc/cpuinfo
+            returncode, stdout, _ = await execute_command(
+                ["grep", "-m", "1", "model name", "/proc/cpuinfo"],
+                host=host,
+                username=username,
+            )
+            if returncode == 0 and stdout:
+                cpu_model = stdout.split(":", 1)[1].strip() if ":" in stdout else stdout.strip()
+                info.append(f"CPU Model: {cpu_model}")
+
+            # Get CPU core counts from /proc/cpuinfo
+            returncode, stdout, _ = await execute_command(
+                ["grep", "-c", "^processor", "/proc/cpuinfo"],
+                host=host,
+                username=username,
+            )
+            if returncode == 0 and stdout:
+                logical_cores = int(stdout.strip())
+                info.append(f"CPU Logical Cores (threads): {logical_cores}")
+
+            # Get physical cores (using core id uniqueness)
+            returncode, stdout, _ = await execute_command(
+                ["grep", "^core id", "/proc/cpuinfo"],
+                host=host,
+                username=username,
+            )
+            if returncode == 0 and stdout:
+                core_ids = {line.split(":", 1)[1].strip() for line in stdout.strip().split("\n") if ":" in line}
+                physical_cores = len(core_ids)
+                info.append(f"CPU Physical Cores: {physical_cores}")
+
+            # Get CPU frequency from /proc/cpuinfo
+            returncode, stdout, _ = await execute_command(
+                ["grep", "-m", "1", "cpu MHz", "/proc/cpuinfo"],
+                host=host,
+                username=username,
+            )
+            if returncode == 0 and stdout and ":" in stdout:
+                cpu_mhz = stdout.split(":", 1)[1].strip()
+                info.append(f"CPU Frequency: Current={cpu_mhz}MHz")
+
+            # Get load average
+            returncode, stdout, _ = await execute_command(
+                ["cat", "/proc/loadavg"],
+                host=host,
+                username=username,
+            )
+            if returncode == 0 and stdout:
+                load_parts = stdout.strip().split()
+                if len(load_parts) >= 3:
+                    info.append(f"\nLoad Average (1m, 5m, 15m): {load_parts[0]}, {load_parts[1]}, {load_parts[2]}")
+
+            # Get CPU usage using top (one iteration)
+            returncode, stdout, _ = await execute_command(
+                ["top", "-bn1"],
+                host=host,
+                username=username,
+            )
+            if returncode == 0 and stdout:
+                for line in stdout.split("\n"):
+                    if "Cpu(s):" in line or "%Cpu" in line:
+                        info.append(f"\n{line.strip()}")
+                        break
+        else:
+            # Local execution - use psutil
+            # CPU count
+            physical_cores = psutil.cpu_count(logical=False)
+            logical_cores = psutil.cpu_count(logical=True)
+            info.append(f"CPU Physical Cores: {physical_cores}")
+            info.append(f"CPU Logical Cores (threads): {logical_cores}")
+
+            # CPU frequency
+            try:
+                cpu_freq = psutil.cpu_freq()
+                if cpu_freq:
+                    info.append(
+                        f"CPU Frequency: Current={cpu_freq.current:.2f}MHz, Min={cpu_freq.min:.2f}MHz, Max={cpu_freq.max:.2f}MHz"
+                    )
+            except Exception:
+                pass  # CPU frequency might not be available
+
+            # CPU usage per core
+            cpu_percent = psutil.cpu_percent(interval=0.1, percpu=True)
+            info.append("\nCPU Usage per Core:")
+            for i, percent in enumerate(cpu_percent):
+                info.append(f"  Core {i}: {percent}%")
+
+            # Overall CPU usage
+            overall_cpu = psutil.cpu_percent(interval=0.1)
+            info.append(f"\nOverall CPU Usage: {overall_cpu}%")
+
+            # Load average
+            load_avg = os.getloadavg()
+            info.append(f"\nLoad Average (1m, 5m, 15m): {load_avg[0]:.2f}, {load_avg[1]:.2f}, {load_avg[2]:.2f}")
+
+            # Try to get CPU model info from /proc/cpuinfo
+            try:
+                with open("/proc/cpuinfo") as f:
+                    for line in f:
+                        if line.startswith("model name"):
+                            cpu_model = line.split(":")[1].strip()
+                            info.insert(0, f"CPU Model: {cpu_model}")
+                            break
+            except Exception:
+                pass
+
+        return "\n".join(info)
+    except Exception as e:
+        return f"Error gathering CPU information: {str(e)}"
+
+
+@mcp.tool(
+    title="Get memory information",
+    description="Get detailed memory including physical and swap.",
+    annotations=ToolAnnotations(readOnlyHint=True),
+)
+@log_tool_call
+async def get_memory_information(
+    host: Host | None = None,
+    username: Username | None = None,
+) -> str:
+    """
+    Get memory information.
+    """
+    info = []
+
+    try:
+        if host:
+            # Remote execution - use free command
+            returncode, stdout, _ = await execute_command(
+                ["free", "-b"],
+                host=host,
+                username=username,
+            )
+
+            if returncode == 0 and stdout:
+                lines = stdout.strip().split("\n")
+
+                # Parse memory line
+                for line in lines:
+                    if line.startswith("Mem:"):
+                        parts = line.split()
+                        if len(parts) >= 7:
+                            total = int(parts[1])
+                            used = int(parts[2])
+                            free = int(parts[3])
+                            available = int(parts[6]) if len(parts) > 6 else free
+                            percent = (used / total * 100) if total > 0 else 0
+
+                            info.append("=== RAM Information ===")
+                            info.append(f"Total: {format_bytes(total)}")
+                            info.append(f"Available: {format_bytes(available)}")
+                            info.append(f"Used: {format_bytes(used)} ({percent:.1f}%)")
+                            info.append(f"Free: {format_bytes(free)}")
+
+                    elif line.startswith("Swap:"):
+                        parts = line.split()
+                        if len(parts) >= 4:
+                            total = int(parts[1])
+                            used = int(parts[2])
+                            free = int(parts[3])
+                            percent = (used / total * 100) if total > 0 else 0
+
+                            info.append("\n=== Swap Information ===")
+                            info.append(f"Total: {format_bytes(total)}")
+                            info.append(f"Used: {format_bytes(used)} ({percent:.1f}%)")
+                            info.append(f"Free: {format_bytes(free)}")
+        else:
+            # Local execution - use psutil
+            # Virtual memory (RAM)
+            mem = psutil.virtual_memory()
+            info.append("=== RAM Information ===")
+            info.append(f"Total: {format_bytes(mem.total)}")
+            info.append(f"Available: {format_bytes(mem.available)}")
+            info.append(f"Used: {format_bytes(mem.used)} ({mem.percent}%)")
+            info.append(f"Free: {format_bytes(mem.free)}")
+
+            if buffers := getattr(mem, "buffers", None):
+                info.append(f"Buffers: {format_bytes(buffers)}")
+
+            if cached := getattr(mem, "cached", None):
+                info.append(f"Cached: {format_bytes(cached)}")
+
+            # Swap memory
+            swap = psutil.swap_memory()
+            info.append("\n=== Swap Information ===")
+            info.append(f"Total: {format_bytes(swap.total)}")
+            info.append(f"Used: {format_bytes(swap.used)} ({swap.percent}%)")
+            info.append(f"Free: {format_bytes(swap.free)}")
+
+        return "\n".join(info)
+    except Exception as e:
+        return f"Error gathering memory information: {str(e)}"
+
+
+@mcp.tool(
+    title="Get disk usage",
+    description="Get detailed disk space information including size, mount points, and utilization..",
+    annotations=ToolAnnotations(readOnlyHint=True),
+)
+@log_tool_call
+async def get_disk_usage(
+    host: Host | None = None,
+    username: Username | None = None,
+) -> str:
+    """
+    Get disk usage information.
+    """
+    info = []
+
+    try:
+        if host:
+            # Remote execution - use df command
+            returncode, stdout, _ = await execute_command(
+                ["df", "-h", "--output=source,size,used,avail,pcent,target"],
+                host=host,
+                username=username,
+            )
+
+            if returncode == 0 and stdout:
+                info.append("=== Filesystem Usage ===\n")
+                info.append(stdout)
+            else:
+                # Fallback to basic df command
+                returncode, stdout, _ = await execute_command(
+                    ["df", "-h"],
+                    host=host,
+                    username=username,
+                )
+                if returncode == 0 and stdout:
+                    info.append("=== Filesystem Usage ===\n")
+                    info.append(stdout)
+        else:
+            # Local execution - use psutil
+            info.append("=== Filesystem Usage ===\n")
+            info.append(f"{'Filesystem':<30} {'Size':<10} {'Used':<10} {'Avail':<10} {'Use%':<6} {'Mounted on'}")
+            info.append("-" * 90)
+
+            # Get all disk partitions
+            partitions = psutil.disk_partitions(all=False)
+
+            for partition in partitions:
+                try:
+                    usage = psutil.disk_usage(partition.mountpoint)
+                    info.append(
+                        f"{partition.device:<30} "
+                        f"{format_bytes(usage.total):<10} "
+                        f"{format_bytes(usage.used):<10} "
+                        f"{format_bytes(usage.free):<10} "
+                        f"{usage.percent:<6.1f} "
+                        f"{partition.mountpoint}"
+                    )
+                except PermissionError:
+                    # Skip partitions we can't access
+                    continue
+                except Exception as e:
+                    info.append(f"{partition.device:<30} Error: {str(e)}")
+
+            # Disk I/O statistics
+            try:
+                disk_io = psutil.disk_io_counters()
+                if disk_io:
+                    info.append("\n=== Disk I/O Statistics (since boot) ===")
+                    info.append(f"Read: {format_bytes(disk_io.read_bytes)}")
+                    info.append(f"Write: {format_bytes(disk_io.write_bytes)}")
+                    info.append(f"Read Count: {disk_io.read_count}")
+                    info.append(f"Write Count: {disk_io.write_count}")
+            except Exception:
+                pass  # Disk I/O might not be available
+
+        return "\n".join(info)
+    except Exception as e:
+        return f"Error gathering disk usage information: {str(e)}"
+
+
+@mcp.tool(
+    title="Get hardware information",
+    description="Get hardware information such as CPU details, PCI devices, USB devices, and hardware information from DMI.",
+    annotations=ToolAnnotations(readOnlyHint=True),
+)
+@log_tool_call
+async def get_hardware_information(  # noqa: C901
+    host: Host | None = None,
+    username: Username | None = None,
+) -> str:
+    """
+    Get hardware information.
+    """
+    try:
+        info = []
+        info.append("=== Hardware Information ===\n")
+
+        # Try lscpu for CPU info
+        try:
+            returncode, stdout, stderr = await execute_command(
+                ["lscpu"],
+                host=host,
+                username=username,
+            )
+
+            if returncode == 0:
+                info.append("=== CPU Architecture (lscpu) ===")
+                info.append(stdout)
+        except FileNotFoundError:
+            info.append("CPU info: lscpu command not available")
+
+        # Try lspci for PCI devices
+        try:
+            returncode, stdout, stderr = await execute_command(
+                ["lspci"],
+                host=host,
+                username=username,
+            )
+
+            if returncode == 0:
+                pci_lines = stdout.strip().split("\n")
+
+                info.append("\n=== PCI Devices ===")
+                # Show first 50 devices to avoid overwhelming output
+                for line in pci_lines[:50]:
+                    info.append(line)
+
+                if len(pci_lines) > 50:
+                    info.append(f"\n... and {len(pci_lines) - 50} more PCI devices")
+        except FileNotFoundError:
+            info.append("\nPCI devices: lspci command not available")
+
+        # Try lsusb for USB devices
+        try:
+            returncode, stdout, stderr = await execute_command(
+                ["lsusb"],
+                host=host,
+                username=username,
+            )
+
+            if returncode == 0:
+                info.append("\n\n=== USB Devices ===")
+                info.append(stdout)
+        except FileNotFoundError:
+            info.append("\nUSB devices: lsusb command not available")
+
+        # Memory hardware info from dmidecode (requires root)
+        try:
+            returncode, stdout, stderr = await execute_command(
+                ["dmidecode", "-t", "memory"],
+                host=host,
+                username=username,
+            )
+
+            if returncode == 0:
+                info.append("\n\n=== Memory Hardware (dmidecode) ===")
+                info.append(stdout)
+            elif "Permission denied" in stderr:
+                info.append("\n\nMemory hardware info: Requires root privileges (dmidecode)")
+        except FileNotFoundError:
+            info.append("\nMemory hardware info: dmidecode command not available")
+
+        if len(info) == 1:  # Only the header
+            info.append("No hardware information tools available.")
+
+        return "\n".join(info)
+    except Exception as e:
+        return f"Error getting hardware information: {str(e)}"

linux_mcp_server/utils/__init__.py

@@ -0,0 +1,2 @@
+from linux_mcp_server.utils.enum import StrEnum as StrEnum
+from linux_mcp_server.utils.format import format_bytes as format_bytes

linux_mcp_server/utils/enum.py

@@ -0,0 +1,16 @@
+from enum import Enum
+
+
+try:
+    from enum import StrEnum  # pyright: ignore[reportAttributeAccessIssue]
+except ImportError:
+    StrEnum = None
+
+
+class StringEnum(str, Enum):
+    def __str__(self):
+        return self.value
+
+
+if StrEnum is None:
+    StrEnum = StringEnum

linux_mcp_server/utils/format.py

@@ -0,0 +1,26 @@
+def format_bytes(bytes_value: int | float) -> str:
+    """
+    Format bytes into human-readable format.
+
+    Args:
+        bytes_value: Number of bytes to format
+
+    Returns:
+        Human-readable string representation (e.g., "1.5GB", "256.0MB")
+
+    Examples:
+        >>> format_bytes(1024)
+        '1.0KB'
+        >>> format_bytes(1536)
+        '1.5KB'
+        >>> format_bytes(1073741824)
+        '1.0GB'
+    """
+    value = float(bytes_value)
+    for unit in ["B", "KB", "MB", "GB", "TB"]:
+        if value < 1024.0:
+            return f"{value:.1f}{unit}"
+
+        value /= 1024.0
+
+    return f"{value:.1f}PB"

linux_mcp_server/utils/types.py

@@ -0,0 +1,5 @@
+import typing as t
+
+
+Host = t.Annotated[str, "Remote host to connect to"]
+Username = t.Annotated[str, "SSH username (if not provided, the current user account is used)"]

linux_mcp_server/utils/validation.py

@@ -0,0 +1,57 @@
+"""Input validation utilities for MCP tools.
+
+Provides validation functions for handling numeric parameters where LLMs often
+pass floats instead of integers.
+"""
+
+
+def validate_positive_int(
+    value: int | float,
+    param_name: str = "parameter",
+    min_value: int = 1,
+    max_value: int | None = None,
+) -> tuple[int | None, str | None]:
+    """
+    Validate and normalize a numeric value to a positive integer.
+
+    Accepts both int and float (LLMs often pass floats) and truncates to int.
+    Validates bounds and caps at max_value if specified.
+
+    Returns:
+        (validated_int, error_message) tuple. On success: (int_value, None).
+        On failure: (None, error_msg).
+    """
+    if not isinstance(value, (int, float)):
+        return None, f"Error: {param_name} must be a number"
+
+    int_value = int(value)
+
+    if int_value < min_value:
+        return None, f"Error: {param_name} must be at least {min_value}"
+
+    if max_value is not None and int_value > max_value:
+        int_value = max_value
+
+    return int_value, None
+
+
+def validate_pid(pid: int | float) -> tuple[int | None, str | None]:
+    """Validate a process ID (PID). Accepts floats from LLMs and truncates to int."""
+    return validate_positive_int(pid, param_name="PID", min_value=1)
+
+
+def validate_line_count(
+    lines: int | float,
+    default: int = 100,
+    max_lines: int = 10000,
+) -> tuple[int, str | None]:
+    """
+    Validate line count for log reading functions.
+
+    Accepts floats from LLMs, truncates to int, caps at max_lines.
+    Returns default value if validation fails.
+    """
+    validated, error = validate_positive_int(lines, "lines", 1, max_lines)
+    if error or validated is None:
+        return (default, error)
+    return (validated, None)