# autoit-mcp (portable)

Windows GUI-automation **MCP server** for Claude Code — drive any desktop app
deterministically (launch, wait for windows, click controls/menus/coords, type
keys, read text, search pixels) and **prove results on disk** (a saved/exported
file appearing = proof), instead of relying on screenshots.

Backed by the official **AutoItX3 DLL** (via PyAutoIt, loaded directly — no COM
registration). A bundled copy of full **AutoIt v3** also enables the `.au3`
escape hatch (UDFs, `_ScreenCapture`, registry, complex macros) and `Aut2Exe`
compile. **32 tools**, all prefixed `au_`.

---

## What's in this folder
```
autoit-mcp/
  server.py            the MCP server (single file)
  requirements.txt     mcp + PyAutoIt
  install.ps1          one-shot setup (venv + deps + skill + .mcp.json snippet)
  autoit3/             bundled full AutoIt (AutoIt3_x64.exe, AutoItX, Aut2Exe, Include)
  skill/autoit-gui/    bundled Claude Code SKILL (standalone run+verify+screenshot)
  README.md            this file
  .gitignore
  (.venv/  logs/  mcp.snippet.json   created by install.ps1 at runtime)
```
~12 MB. Self-contained except for Python (see prerequisites).

## The bundled skill (`autoit-gui`)
This package ships its own Claude Code **skill** so a fresh machine is fully
self-sufficient — it does NOT rely on the `run` / `verify` / `screen-capture`
skills (which won't exist there). The skill teaches the model to launch an app,
drive menus/controls, **take a screenshot via the bundled `_ScreenCapture` UDF**,
and **prove a save/export by checking the file on disk**. `install.ps1` copies it
to `%USERPROFILE%\.claude\skills\autoit-gui\` automatically; restart Claude Code to
load it. (To install manually, copy `skill\autoit-gui\` there yourself.)

## Prerequisites on the new machine
- **Windows** (uses Win32 + AutoItX).
- **Python 3.9+** on PATH (python.org — tick *Add Python to PATH*). That's the
  only thing not bundled.
- **Claude Code** (the host that loads MCP servers).

## Install (3 steps)
1. Copy this whole `autoit-mcp/` folder anywhere on the new machine
   (e.g. `C:\tools\autoit-mcp`).
2. Open PowerShell in the folder and run:
   ```powershell
   powershell -ExecutionPolicy Bypass -File .\install.ps1
   ```
   It creates a local `.venv`, installs deps, smoke-tests (`TOOLS 32`), and writes
   **`mcp.snippet.json`** with the correct absolute paths for *this* machine.
3. Merge that snippet into your project's `.mcp.json` (under `mcpServers`), e.g.:
   ```json
   {
     "mcpServers": {
       "autoit": {
         "command": "C:\\tools\\autoit-mcp\\.venv\\Scripts\\python.exe",
         "args": ["C:\\tools\\autoit-mcp\\server.py"]
       }
     }
   }
   ```
   Then **restart Claude Code** and **approve** the `autoit` server in `/mcp`.

> No global install, no admin rights, no AutoItX COM registration needed.

## Verify it loaded
In Claude Code after restart, the `autoit` server should expose 32 `au_*` tools.
Quick check from the model: call `au_autoit_info` → should report
`run_au3_available: true` and point at `…\autoit3\AutoIt3_x64.exe` (bundled).

---

## Tools (32, prefix `au_`)
| Group | Tools |
|---|---|
| Process | `au_run`, `au_process_close`, `au_process_exists`, `au_process_wait_close` |
| Window  | `au_win_wait`, `au_win_exists`, `au_win_activate`, `au_win_get_pos`, `au_win_get_text`, `au_win_get_state`, `au_win_set_state`, `au_win_close`, `au_list_windows` |
| Input   | `au_send(keys, raw)`, `au_mouse_click(x,y,…)`, `au_mouse_move(x,y)` |
| Menu/Control | `au_win_menu_select`, `au_control_click`, `au_control_send`, `au_control_set_text`, `au_control_get_text`, `au_statusbar_get_text`, `au_set_option` |
| Clipboard | `au_clip_get`, `au_clip_put` |
| Pixels (chromeless UIs) | `au_pixel_get_color`, `au_pixel_search` |
| Disk proof | `au_file_exists`, `au_wait_file` |
| Full AutoIt | `au_run_au3(script,timeout)`, `au_compile_au3(script_path,out_exe)`, `au_autoit_info()` |

Defaults: DPI-aware (coords = physical pixels), `WinTitleMatchMode=2` (window
title matched as a substring anywhere). Every tool returns structured JSON
(`{ok:true,…}` / `{ok:false,error}`) and never crashes the call. Calls are logged
to `logs/YYYY-MM-DD.log`.

## Design choices (vs. a generic "generate .au3" MCP)
- Direct **AutoItX DLL** calls, not COM `Dispatch("AutoItX3.Control")` (COM needs
  `regsvr32`; the DLL doesn't).
- **No temp `.au3` for ordinary actions** — direct calls are faster + sturdier.
  `.au3` is the escape hatch only (`au_run_au3`), for what AutoItX lacks.

## Gotchas learned on real targets
- **`au_win_menu_select` only works on native Win32/MFC menus.** Many modern apps
  (Qt / WPF / Electron / CEF) use owner-drawn menus that `WinMenuSelectItem` can't
  see → it no-ops. For those use accelerators: `au_send("{ALTDOWN}{ALTUP}")` then
  `"f"` then `"a"` = Save As. Keep `au_win_menu_select` for classic Win32 apps.
- CEF/Qt welcome/home screens have no native controls and reflow on resize →
  coordinate clicks are fragile. Prefer launching with a **document argument**, or
  use `au_pixel_search` to find a button.
- The Win11 file dialog ignores classic `Edit1`/`Button1`; instead activate it,
  `au_send("^a")`, `au_send(path, raw=True)`, `au_send("{ENTER}")`.
- Prove success with `au_wait_file(out_path)` rather than a screenshot.

## Full AutoIt notes
- The bundled `autoit3/` makes `au_run_au3` + `au_compile_au3` work out of the box.
  The server auto-detects it (no env var needed); you can override with
  `AUTOIT3_EXE` or `AUTOIT3_DIR`.
- **ImageSearch** is a 3rd-party UDF (not part of standard AutoIt). To enable it,
  drop `ImageSearch.au3` + its DLL into `autoit3/Include/`, then call it via
  `au_run_au3`.
- If you'd rather not bundle AutoIt, delete `autoit3/`: the 31 DLL-based tools
  still work; only `au_run_au3`/`au_compile_au3` become unavailable.

## Uninstall
Delete the folder. (Nothing is written outside it; no registry, no PATH changes.)
Remove the `autoit` block from your `.mcp.json`.

## Troubleshooting
- *`Python 3 not found`* during install → install Python, reopen PowerShell, retry.
- *Server doesn't appear in `/mcp`* → ensure the `.mcp.json` paths match the
  snippet exactly (absolute, double backslashes) and that you restarted Claude Code.
- *`au_run_au3` returns "AutoIt3.exe not found"* → keep `autoit3/` next to
  `server.py`, or set `AUTOIT3_EXE` to a full `AutoIt3_x64.exe`.
- *Coordinates land in the wrong place* → the host app may be per-monitor DPI
  scaled; the server is system-DPI-aware. Use `au_win_get_pos` to anchor clicks
  relative to the window, or use `au_pixel_search`.