Execute a command safely with timeout and output limits.

This tool executes commands without shell injection vulnerabilities. Commands are parsed into argument lists and executed directly via subprocess without shell=True.

Args: command: Command to execute (e.g., "python --version", "npm test") working_directory: Working directory for execution (default: current) timeout_ms: Timeout in milliseconds (default: 30000, max: 300000) capture_output: Whether to capture stdout/stderr (default: True) ctx: MCP context for logging (optional)

Returns: ExecuteCommandOutput with stdout, stderr, exit code, and timing

Raises: ValueError: If input validation fails SanitizedError: If command execution fails

Security: - No shell=True (prevents shell injection) - Command parsed with shlex.split (safe parsing) - Mandatory timeout enforcement - Output size limits (prevents memory exhaustion) - Path validation for working directory - Sanitized error messages (no information leakage)

Examples: >>> result = await execute_command("python --version") >>> print(result.stdout) # "Python 3.11.5" >>> print(result.exit_code) # 0

>>> result = await execute_command(
...     "npm test",
...     working_directory="./myproject",
...     timeout_ms=60000
... )

Search for patterns in file contents across a directory or file.

This tool uses ripgrep to efficiently search for regex patterns in files. It returns matches with line numbers and surrounding context lines.

Args: pattern: Regular expression pattern to search for path: File or directory path to search in case_sensitive: Whether search should be case-sensitive (default: True) file_types: File type filters (e.g., ['py', 'js']). None = all files exclude_patterns: Glob patterns to exclude (e.g., ['node_modules']) max_results: Maximum number of results to return (1-10000) context_lines: Lines of context before/after match (0-10) ctx: MCP context for logging (optional)

Returns: SearchFileContentsOutput with matches and metadata

Raises: ValueError: If input validation fails SanitizedError: If search execution fails

Examples: >>> result = search_file_contents("TODO", "./src", case_sensitive=False) >>> print(f"Found {len(result.matches)} TODO comments")

List running processes with optional filtering and sorting.

This tool retrieves information about running processes on the system, including PID, name, CPU usage, memory usage, command line, and status. Results can be filtered by name, sorted by various criteria, and limited to a maximum number of results.

Args: name_filter: Filter processes by name (case-insensitive substring match). If None, return all processes. sort_by: Sort processes by: cpu (descending), memory (descending), pid (ascending), or name (ascending). Default: cpu. limit: Maximum number of processes to return. Default: 100, max: 1000. ctx: MCP context for logging (optional)

Returns: ListProcessesOutput with process list, total count, truncation flag, and retrieval time

Raises: SanitizedError: If process iteration fails

Security: - Handles permission errors gracefully (skips inaccessible processes) - No sensitive system information leaked in errors - Command lines are included but may be empty if access denied - Zombie and terminated processes handled without errors

Performance: - Uses psutil.process_iter() for efficient iteration - oneshot() context for batch info retrieval per process - Target: <2s for process list retrieval

Examples: >>> result = await list_processes() >>> print(result.total_count, "processes found") 245 processes found

>>> result = await list_processes(
...     name_filter="python",
...     sort_by=ProcessSortBy.MEMORY,
...     limit=50
... )
>>> for proc in result.processes:
...     print(f"{proc.name}: {proc.memory_mb}MB")

Terminate a process by PID with graceful or forced termination.

This tool allows terminating stuck or hung processes to clean up system resources. It supports both graceful termination (SIGTERM/WM_CLOSE) with a timeout, and forced termination (SIGKILL/TerminateProcess) for unresponsive processes.

Args: pid: Process ID to terminate (must be >= 1) force: If True, forcefully kill the process. If False, attempt graceful termination with timeout. Default: False timeout_seconds: Timeout in seconds to wait for graceful termination. Ignored if force=True. Range: 0.1-30.0s. Default: 5.0s ctx: MCP context for logging (optional)

Returns: KillProcessOutput with success status, PID, message, timing, and whether forced termination was used

Raises: SanitizedError: If process termination fails or is not enabled

Security: - Requires PROCEXEC_ENABLE_KILL=true environment variable to function - Handles permission errors gracefully (no crashes) - Cannot terminate system-critical processes (OS protection) - Error messages are sanitized (no sensitive info)

Examples: >>> # Graceful termination >>> result = await kill_process(pid=1234, force=False, timeout_seconds=5.0) >>> print(result.success, result.message) True 'Process terminated gracefully'

>>> # Forced termination
>>> result = await kill_process(pid=5678, force=True)
>>> print(result.success, result.forced)
True True