Skip to main content
Glama
win-cua-guard

win-cua-guard

by JakeBilu

win-cua-guard

A Per-Monitor v2 DPI-aware Windows Computer Use (CUA) CLI and FastMCP server with fail-closed safety guardrails.

Why?

Raw GUI automation scripts routinely misclick across scaled multi-monitor setups, break inside isolated Windows sandbox desktops (WinSta0\exebox-*), or accidentally interact with sensitive messaging apps, password managers, CAPTCHAs, and #32770 OS file upload dialogs.

win-cua-guard solves both problems cleanly:

  • Per-Monitor v2 DPI Awareness initialized before importing PyAutoGUI.

  • 50px / 100px Coordinate-Grid Overlay Screenshots (--grid) + offline --synthetic-selftest calibration canvas.

  • .NET UI Automation Lookup (uia-find) returning exact element bounding rectangles and center coordinates.

  • Unicode-safe Win32 SendInput (KEYEVENTF_UNICODE) without clipboard clobbering.

  • Fail-Closed Safety Guardrails (SafetyBlockedError, exit code 2) enforced across both CLI and MCP tools, with user-extensible --blocklist YAML/JSON policies.

Related MCP server: ORVEX

Baseline & Custom Guardrails

Baseline protections (always enforced):

  • Messaging / chat surfaces (WhatsApp)

  • Anti-bot / CAPTCHA gates (reCAPTCHA, Turnstile, cf-turnstile, captcha)

  • #32770 OS file chooser / upload dialogs (Open, File Upload, Choose File to Upload, Select File)

  • Non-Default Win32 sandbox desktops (WinSta0\exebox-*)

Extend with --blocklist blocklist.example.yaml (or WIN_CUA_BLOCKLIST env var).

Quickstart

pip install -e .

# Inspect monitors, DPI awareness mode, and Win32 desktop station
win-cua screen-info

# Capture a coordinate-grid screenshot of a target window
win-cua screenshot --title "SketchUp" --grid --out screen_grid.png

# Generate an offline synthetic calibration grid (works inside sandboxes)
win-cua screenshot --synthetic-selftest --grid --out selftest.png

# Apply custom blocklist rules
win-cua --blocklist blocklist.example.yaml click --x 400 --y 300 --dry-run

MCP Server Configuration

{
  "mcpServers": {
    "win-cua-guard": {
      "command": "win-cua-mcp",
      "args": ["--blocklist", "C:\\path\\to\\blocklist.example.yaml"]
    }
  }
}

License

MIT — see LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to inspect and drive native Windows desktop applications (WinForms, WPF, WinUI 3, and WebView2 hybrids) through Microsoft UI Automation by capturing interactive control snapshots, then clicking, filling, and asserting on elements via ephemeral refs or semantic screen-map targets. Mutating actions are dry-run by default and gated behind explicit arming, allow-lists, and a kill switch for lawful, assisted QA testing.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to drive Windows desktop automation — opening and interacting with applications, native UI controls, keyboard/mouse input, files, processes, clipboard, and Chrome/Edge browsing via UI Automation and CDP. All actions pass through a safety policy with human approval, emergency stop, and deterministic verification.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI clients to inspect and control allowlisted Windows applications using screenshots, mouse actions, Unicode keyboard input, UI Automation, and an Esc/F12 emergency stop.
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP-capable AI agents to control Windows desktops through UI Automation element trees, native screenshots, app launching, batched action sequences, smart waits, and safety gates using normalized coordinates.
      MIT