Architecture

Architecture

A Python FastMCP server (stdio by default, optional streamable-HTTP). It performs real OS actions through a set of platform backends.

Modules

File	Responsibility
src/lowlevel_computer_use_mcp/server.py	All 53 MCP tool definitions; platform dispatch (IS_WINDOWS/IS_LINUX); CLI (--http, --admin, install-startup, …)
winio.py	Windows backend (ctypes Win32): background PostMessage input, PrintWindow capture, off-screen desktop, show/hide, admin/elevation helpers
linuxio.py	Linux backend: window mgmt + background input + per-window capture via xdotool/wmctrl/ImageMagick; Xvfb virtual displays
ahk.py	AutoHotkey detection + run_script/control_send/control_click
wslio.py	Ephemeral WSL provisioning (Alpine minirootfs download / clone / import; run; destroy)
installer_gui.py	Tkinter auto-installer (uv bootstrap, register clients, YOLO, startup, AHK)

Dependencies

mcp (FastMCP), pydantic, pyautogui, pygetwindow, psutil, mss, pillow, numpy, imageio + imageio-ffmpeg. Windows extras come via pywin32/ctypes; Linux uses system CLI tools. Managed with uv (pyproject.toml, uv.lock).

Transports

• stdio (default) — spawned per client (Claude Code, Codex).
• streamable-HTTP (--http --host --port) — an always-on service, e.g. the boot-startup task; clients connect to http://host:port/mcp.

Tool conventions

• Tools validate input with Pydantic models and return a JSON string {"ok": true, ...} / {"ok": false, "error": "..."}.
• Annotations mark readOnlyHint / destructiveHint / idempotentHint / openWorldHint.
• Cross-platform tools dispatch to winio/linuxio based on the host OS; Windows-only (wsl_*, ahk_*, admin/boot, headless desktop) and Linux-only (*_virtual_display, linux_status) tools report unavailability gracefully off-platform.

Server instructions & skill

The server ships condensed instructions (enumerating all tools and patterns) sent to clients on connect, plus a full Macros (skills/lowlevel-computer-use/) with exhaustive references.