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

linux_mcp_server/__init__.py

@@ -0,0 +1 @@
+"""Linux MCP Server - Read-only diagnostics and troubleshooting for RHEL systems."""

linux_mcp_server/__main__.py

@@ -0,0 +1,30 @@
+"""Main entry point for the Linux MCP Server."""
+
+import logging
+import sys
+
+from .logging_config import setup_logging
+from .server import main
+
+
+def cli():
+    """Console script entry point for the Linux MCP Server."""
+    # Initialize logging first, before any other operations
+    setup_logging()
+
+    logger = logging.getLogger(__name__)
+    logger.info("Starting Linux MCP Server")
+
+    try:
+        # FastMCP.run() creates its own event loop, don't use asyncio.run()
+        main()
+    except KeyboardInterrupt:
+        logger.info("Linux MCP Server stopped by user")
+        sys.exit(0)
+    except Exception as e:
+        logger.critical(f"Fatal error in Linux MCP Server: {e}", exc_info=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    cli()

linux_mcp_server/audit.py

@@ -0,0 +1,290 @@
+"""Audit logging utilities for Linux MCP Server.
+
+This module provides helper functions for consistent audit logging across
+the entire MCP server. All functions add structured context to log records
+that can be output in both human-readable and JSON formats.
+"""
+
+import logging
+import typing as t
+
+from contextlib import contextmanager
+
+
+# Sensitive field names that should be redacted in logs
+SENSITIVE_FIELDS = {
+    "password",
+    "passwd",
+    "pwd",
+    "secret",
+    "api_key",
+    "apikey",
+    "token",
+    "auth",
+    "authorization",
+    "private_key",
+    "privatekey",
+}
+
+
+def sanitize_parameters(params: dict[str, t.Any]) -> dict[str, t.Any]:
+    """
+    Sanitize parameters by redacting sensitive fields.
+
+    Args:
+        params: Dictionary of parameters to sanitize
+
+    Returns:
+        Dictionary with sensitive fields redacted
+    """
+    if not params:
+        return params
+
+    sanitized = {}
+    for key, value in params.items():
+        # Check if key is sensitive
+        key_lower = key.lower().replace("_", "").replace("-", "")
+        is_sensitive = any(sensitive in key_lower for sensitive in [s.replace("_", "") for s in SENSITIVE_FIELDS])
+
+        if is_sensitive:
+            sanitized[key] = "***REDACTED***"
+        elif isinstance(value, dict):
+            # Recursively sanitize nested dicts
+            sanitized[key] = sanitize_parameters(value)
+        else:
+            sanitized[key] = value
+
+    return sanitized
+
+
+@contextmanager
+def AuditContext(**extra_fields):
+    """
+    Context manager for adding extra fields to all log records.
+
+    Usage:
+        with AuditContext(tool="list_services", host="server1.com") as logger:
+            logger.info("Starting operation")
+
+    Args:
+        **extra_fields: Additional fields to add to log records
+
+    Yields:
+        Logger with extra fields
+    """
+    logger = logging.getLogger()
+
+    # Create adapter with extra fields
+    class ContextAdapter(logging.LoggerAdapter):
+        def process(self, msg, kwargs):
+            # Add extra fields to the record
+            if "extra" not in kwargs:
+                kwargs["extra"] = {}
+
+            if isinstance(self.extra, t.Iterable):
+                kwargs["extra"].update(self.extra)
+
+            return msg, kwargs
+
+    adapter = ContextAdapter(logger, extra_fields)
+    yield adapter
+
+
+def log_tool_call(tool_name: str, parameters: dict[str, t.Any]):
+    """
+    Log a tool invocation.
+
+    Args:
+        tool_name: Name of the tool being called
+        parameters: Tool parameters (will be sanitized)
+    """
+    logger = logging.getLogger(__name__)
+
+    # Determine if local or remote execution
+    execution_mode = "remote" if parameters.get("host") else "local"
+
+    # Sanitize parameters
+    safe_params = sanitize_parameters(parameters)
+
+    # Build log record with extra fields
+    extra = {
+        "event": "TOOL_CALL",
+        "tool": tool_name,
+        "execution_mode": execution_mode,
+    }
+
+    # Add host and username if present
+    if "host" in parameters:
+        extra["host"] = parameters["host"]
+    if "username" in parameters:
+        extra["username"] = parameters["username"]
+
+    # Add sanitized parameters as string
+    params_str = ", ".join(f"{k}={v}" for k, v in safe_params.items() if k not in ["host", "username"])
+
+    message = f"TOOL_CALL: {tool_name}"
+    if params_str:
+        message += f" | {params_str}"
+
+    logger.info(message, extra=extra)
+
+
+def log_tool_complete(
+    tool_name: str,
+    status: str,
+    duration: float,
+    error: str | None = None,
+):
+    """
+    Log tool completion.
+
+    Args:
+        tool_name: Name of the tool
+        status: Completion status ("success" or "error")
+        duration: Execution time in seconds
+        error: Optional error message
+    """
+    logger = logging.getLogger(__name__)
+
+    extra = {
+        "event": "TOOL_COMPLETE",
+        "tool": tool_name,
+        "status": status,
+        "duration": f"{duration:.3f}s",
+    }
+
+    message = f"TOOL_COMPLETE: {tool_name}"
+
+    if status == "error":
+        if error:
+            extra["error"] = error
+            message += f" | error: {error}"
+        logger.error(message, extra=extra)
+    else:
+        logger.info(message, extra=extra)
+
+
+def log_ssh_connect(
+    host: str,
+    username: str,
+    status: str,
+    reused: bool = False,
+    key_path: str | None = None,
+    error: str | None = None,
+):
+    """
+    Log SSH connection event.
+
+    Verbosity is tiered based on log level:
+    - INFO: Basic connection success/failure
+    - DEBUG: Detailed information including key path, reuse status
+
+    Args:
+        host: Remote host
+        username: SSH username
+        status: Connection status ("success" or "failed")
+        reused: Whether connection was reused (shown at DEBUG level)
+        key_path: Path to SSH key used (shown at DEBUG level)
+        error: Optional error message
+    """
+    logger = logging.getLogger(__name__)
+
+    user_host = f"{username}@{host}"
+
+    if status == "success":
+        extra = {
+            "event": "SSH_CONNECT",
+            "host": host,
+            "username": username,
+            "status": status,
+        }
+
+        # At INFO level, just log basic success
+        message = f"SSH_CONNECT: {user_host}"
+
+        # At DEBUG level, add more details
+        if logger.isEnabledFor(logging.DEBUG):
+            if reused is not None:
+                extra["reused"] = str(reused)
+            if key_path:
+                extra["key"] = key_path
+
+        logger.info(message, extra=extra)
+
+    else:
+        # Connection failed
+        extra = {
+            "event": "SSH_CONNECT_FAILED",
+            "host": host,
+            "username": username,
+            "status": "failed",
+        }
+
+        if error:
+            extra["reason"] = error
+
+        message = f"SSH_AUTH_FAILED: {user_host}"
+        if error:
+            message += f" | reason: {error}"
+
+        logger.warning(message, extra=extra)
+
+
+def log_ssh_command(
+    command: str,
+    host: str,
+    exit_code: int,
+    duration: float | None = None,
+):
+    """
+    Log SSH command execution.
+
+    Verbosity is tiered based on log level:
+    - INFO: Command and exit code
+    - DEBUG: Also includes execution duration
+
+    Args:
+        command: Command that was executed
+        host: Remote host
+        exit_code: Command exit code
+        duration: Optional execution duration in seconds (shown at DEBUG level)
+    """
+    logger = logging.getLogger(__name__)
+
+    extra = {
+        "event": "REMOTE_EXEC",
+        "command": command,
+        "host": host,
+        "exit_code": exit_code,
+    }
+
+    message = f"REMOTE_EXEC: {command} | host={host} | exit_code={exit_code}"
+
+    # At DEBUG level, include duration
+    if duration is not None and logger.isEnabledFor(logging.DEBUG):
+        extra["duration"] = f"{duration:.3f}s"
+        message += f" | duration={duration:.3f}s"
+
+    logger.info(message, extra=extra)
+
+
+def log_operation(operation: str, message: str, level: int = logging.INFO, **context):
+    """
+    Log a general operation with context.
+
+    This is a generic logging function for operations that don't fit
+    other specific logging functions.
+
+    Args:
+        operation: Name of the operation
+        message: Log message
+        level: Log level (default: INFO)
+        **context: Additional context fields
+    """
+    logger = logging.getLogger(__name__)
+
+    extra = {"operation": operation, **context}
+
+    full_message = f"{operation}: {message}"
+
+    logger.log(level, full_message, extra=extra)

linux_mcp_server/logging_config.py

@@ -0,0 +1,176 @@
+"""Centralized logging configuration for Linux MCP Server.
+
+Simplified logging setup with standard Python logging infrastructure.
+Supports structured logging with extra fields for audit and diagnostic purposes.
+"""
+
+import json
+import logging
+import logging.handlers
+import os
+
+from pathlib import Path
+
+
+def get_log_directory() -> Path:
+    """Get the log directory path, creating it if necessary."""
+    env_log_dir = os.getenv("LINUX_MCP_LOG_DIR")
+    log_dir = Path(env_log_dir) if env_log_dir else Path.home() / ".local" / "share" / "linux-mcp-server" / "logs"
+    log_dir.mkdir(parents=True, exist_ok=True)
+    return log_dir
+
+
+def get_log_level() -> int:
+    """Get the log level from environment variable (defaults to INFO)."""
+    level_name = os.getenv("LINUX_MCP_LOG_LEVEL", "INFO").upper()
+    return getattr(logging, level_name, logging.INFO)
+
+
+def get_retention_days() -> int:
+    """Get the log retention days from environment variable (defaults to 10)."""
+    try:
+        return int(os.getenv("LINUX_MCP_LOG_RETENTION_DAYS", "10"))
+    except ValueError:
+        return 10
+
+
+class StructuredFormatter(logging.Formatter):
+    """
+    Structured log formatter supporting extra fields.
+
+    Format: TIMESTAMP | LEVEL | MODULE | MESSAGE | key=value ...
+    Extra fields added to LogRecord are appended as key=value pairs.
+    """
+
+    STANDARD_FIELDS = {
+        "name",
+        "msg",
+        "args",
+        "created",
+        "filename",
+        "funcName",
+        "levelname",
+        "levelno",
+        "lineno",
+        "module",
+        "msecs",
+        "message",
+        "pathname",
+        "process",
+        "processName",
+        "relativeCreated",
+        "thread",
+        "threadName",
+        "exc_info",
+        "exc_text",
+        "stack_info",
+        "asctime",
+        "taskName",
+    }
+
+    def format(self, record: logging.LogRecord) -> str:
+        """Format a log record with extra fields."""
+        # Base message
+        base_msg = super().format(record)
+
+        # Append extra fields as key=value pairs
+        extra_fields = [f"{k}={v}" for k, v in record.__dict__.items() if k not in self.STANDARD_FIELDS]
+
+        return f"{base_msg} | {' | '.join(extra_fields)}" if extra_fields else base_msg
+
+
+class JSONFormatter(logging.Formatter):
+    """JSON log formatter for machine-readable logs."""
+
+    EXCLUDE_FIELDS = {
+        "args",
+        "exc_text",
+        "exc_info",
+        "stack_info",
+        "filename",
+        "funcName",
+        "lineno",
+        "module",
+        "msecs",
+        "pathname",
+        "process",
+        "processName",
+        "relativeCreated",
+        "thread",
+        "threadName",
+        "taskName",
+    }
+
+    def format(self, record: logging.LogRecord) -> str:
+        """Format a log record as JSON."""
+        log_data = {
+            "timestamp": self.formatTime(record, self.datefmt),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+        }
+
+        # Add exception info if present
+        if record.exc_info:
+            log_data["exception"] = self.formatException(record.exc_info)
+
+        # Add extra fields
+        for key, value in record.__dict__.items():
+            if (
+                key not in self.EXCLUDE_FIELDS
+                and key not in log_data
+                and key not in {"name", "msg", "levelname", "levelno", "created"}
+            ):
+                log_data[key] = value
+
+        return json.dumps(log_data)
+
+
+def setup_logging():
+    """Set up logging with structured formatters and rotation."""
+    log_dir = get_log_directory()
+    log_level = get_log_level()
+    retention_days = get_retention_days()
+
+    # Configure root logger
+    root_logger = logging.getLogger()
+    root_logger.setLevel(log_level)
+    root_logger.handlers.clear()  # Remove existing handlers
+
+    # Human-readable text log
+    text_handler = logging.handlers.TimedRotatingFileHandler(
+        filename=log_dir / "server.log",
+        when="midnight",
+        interval=1,
+        backupCount=retention_days,
+        encoding="utf-8",
+    )
+    text_handler.setLevel(log_level)
+    text_handler.setFormatter(
+        StructuredFormatter("%(asctime)s | %(levelname)s | %(name)s | %(message)s", datefmt="%Y-%m-%d %H:%M:%S")
+    )
+    text_handler.suffix = "%Y-%m-%d"
+    root_logger.addHandler(text_handler)
+
+    # JSON log
+    json_handler = logging.handlers.TimedRotatingFileHandler(
+        filename=log_dir / "server.json",
+        when="midnight",
+        interval=1,
+        backupCount=retention_days,
+        encoding="utf-8",
+    )
+    json_handler.setLevel(log_level)
+    json_handler.setFormatter(JSONFormatter(datefmt="%Y-%m-%dT%H:%M:%S"))
+    json_handler.suffix = "%Y-%m-%d"
+    root_logger.addHandler(json_handler)
+
+    # Console handler for development
+    console_handler = logging.StreamHandler()
+    console_handler.setLevel(log_level)
+    console_handler.setFormatter(
+        StructuredFormatter("%(asctime)s | %(levelname)s | %(name)s | %(message)s", datefmt="%Y-%m-%d %H:%M:%S")
+    )
+    root_logger.addHandler(console_handler)
+
+    logging.getLogger(__name__).info(f"Logging initialized: {log_dir}")