# WinWright

[![GitHub Release](https://img.shields.io/github/v/release/civyk-official/civyk-winwright?label=Release)](https://github.com/civyk-official/civyk-winwright/releases)
[![License](https://img.shields.io/badge/License-Freeware-blue)](LICENSE)
[![Platform](https://img.shields.io/badge/Platform-Windows%2010%2F11-0078D4)](https://github.com/civyk-official/civyk-winwright)
[![MCP](https://img.shields.io/badge/MCP-52%20tools-0D9488)](https://modelcontextprotocol.io/)

Windows automation server for the [Model Context Protocol](https://modelcontextprotocol.io/).
52 consolidated tools for desktop (WPF, WinForms, Win32), browser (Chrome/Edge via CDP),
and system management — accessible to AI agents over MCP, **or driven directly from the
command line (`winwright call …`) when MCP is blocked**.

## Describe tests in plain English — the AI agent does the rest

![WinWright Demo](assets/demo.gif)

You write test cases in plain English. The AI agent uses WinWright's MCP tools to
discover UI controls, perform actions, and record everything as a portable JSON script.

## Replay recorded scripts — no AI agent needed

![Run Script Demo](assets/demo-run-script.gif)

Once recorded, scripts run deterministically with `winwright run` — no AI agent,
no LLM calls, no token costs. Results are the same every time.

If the UI layout changes, WinWright can **self-heal** broken selectors automatically
(`winwright heal`). For larger UI redesigns, ask the AI agent to update the script —
still faster than rewriting tests from scratch.

Why this matters:

- **Save AI costs** — the agent records once, scripts replay for free
- **Deterministic results** — every run produces identical, reproducible outcomes
- **Easy maintenance** — self-healing selectors and AI-assisted script repair

## Contents

- [Quick Start](#quick-start)
- [Install](#install)
- [MCP Client Configuration](#mcp-client-configuration)
- [CLI Mode (when MCP is blocked)](#cli-mode-when-mcp-is-blocked)
- [Use Cases](#use-cases)
- [Tools](#tools)
- [Configuration](#configuration)
- [Who Is This For](#who-is-this-for)
- [How It Compares](#how-it-compares)
- [Support](#support)
- [License](#license)

## Quick Start

Install, configure your MCP client, then ask the agent to do something:

> "Launch Notepad, type 'Hello from WinWright', then read back what you typed."

The agent calls WinWright tools and returns results:

```text
ww_launch    → { "processId": 12840, "mainWindowTitle": "Untitled - Notepad" }
ww_type      → { "success": true }
ww_get_value → { "value": "Hello from WinWright" }
```

Every tool returns structured JSON. The agent decides which tools to call and in what order —
you describe the goal in plain language.

## Install

Download from [GitHub Releases](https://github.com/civyk-official/civyk-winwright/releases):

| Asset | Architecture |
|-------|-------------|
| `winwright-*-win-x64.zip` | Intel/AMD 64-bit |
| `winwright-*-win-arm64.zip` | ARM64 (Surface Pro, etc.) |

## MCP Client Configuration

### Claude Code / VSCode (stdio)

```json
{
  "servers": {
    "winwright": {
      "type": "stdio",
      "command": "C:/path/to/Civyk.WinWright.Mcp.exe",
      "args": ["mcp"]
    }
  }
}
```

### Claude Code / VSCode (HTTP)

Start the server first: `Civyk.WinWright.Mcp.exe serve --port 8765`

```json
{
  "servers": {
    "winwright": {
      "type": "http",
      "url": "http://localhost:8765/mcp"
    }
  }
}
```

### Claude Desktop

```json
{
  "mcpServers": {
    "winwright": {
      "command": "C:/path/to/Civyk.WinWright.Mcp.exe",
      "args": ["mcp"]
    }
  }
}
```

## CLI Mode (when MCP is blocked)

Many corporate environments block MCP. WinWright can be driven **entirely from the command line**
instead — the same tools, the same automation, with **no MCP client** between the agent and the
tool. A background daemon (a loopback `serve` instance) owns the live sessions, so the `appId`
returned by `ww_launch` stays valid across separate commands.

```bash
winwright tools                          # discover the tool surface (replaces MCP advertisement)
winwright call ww_launch --exePath "C:\Apps\MyApp.exe"   # -> {"appId":"app-1", ...}
winwright call ww_click  --appId app-1 --selector "#submit"
winwright call ww_get_value --appId app-1 --selector "#status"
winwright call ww_close  --appId app-1
```

JSON results go to stdout (safe to pipe to `jq`); diagnostics go to stderr. The daemon auto-starts
on the first `call`, binds to loopback only, and self-exits when idle.

Because the CLI doesn't advertise its capabilities the way MCP does, install the bundled **Claude
Code skill** so an agent knows how to use it — embedded in the binary, so it installs **offline**:

```bash
winwright skills install --scope user      # -> %USERPROFILE%\.claude\skills\winwright\
winwright skills install --scope project   # -> <cwd>\.claude\skills\winwright\
```

## Use Cases

> Each card links to a detailed walkthrough with real prompts, tool call parameters,
> and example output. Browse all guides in [docs/use-cases/](docs/use-cases/).

### [Scripted UI Test Automation for CI](docs/use-cases/01-scripted-ci.md)

Record an AI session once — the agent discovers the UI, performs actions, embeds assertions —
then export a portable JSON script that replays in CI without an AI agent. Describe your app
or paste your existing manual test suite; the agent scripts it automatically.

### [Autonomous Desktop Automation](docs/use-cases/02-desktop-automation.md)

Give an AI agent access to your desktop. It launches apps, moves data between them,
fills forms, and takes screenshots for verification — no scripts to write or maintain.

### [Legacy App Data Extraction](docs/use-cases/03-data-extraction.md)

Many enterprise apps have no API. If Windows UI Automation can see a control,
WinWright can read its value. Extract data from apps that were never built for integration.

### [Scripted Desktop Automation for Repeated Tasks](docs/use-cases/04-scripted-desktop-rpa.md)

Record a repetitive daily workflow once. Export as an RPA script and replay on demand —
no AI agent required after the recording. Ideal for report exports, data imports,
and any multi-step task that runs the same way every time.

### [AI-Powered UI Testing](docs/use-cases/05-ui-testing.md)

An AI agent explores your WinForms or WPF app, finds elements, and asserts state.
No brittle XPath selectors to maintain — the agent adapts when UI changes.

### [Bulk Data Validation](docs/use-cases/06-bulk-data-validation.md)

Drive an app through 50+ records automatically. Compare each displayed value against
a reference table and get a structured pass/fail report with discrepancy details.

### [Cross-App Workflows](docs/use-cases/07-cross-app-workflows.md)

Automate workflows that span desktop apps and browser — read from an accounting app,
submit to a web portal, screenshot the confirmation.

### [Application Health Monitoring](docs/use-cases/08-app-health-monitoring.md)

Verify a running app is alive and responsive — process running, connection status showing
'Connected', service healthy. Pair with Windows Task Scheduler for scheduled checks.

### [Remote Administration](docs/use-cases/09-remote-administration.md)

Manage processes, services, registry, and scheduled tasks on remote machines over HTTP.
Five-layer security: IP allowlist, Windows Negotiate auth, AD group authorization,
rate limiting, and per-user session limits.

### [Accessibility Auditing](docs/use-cases/10-accessibility-auditing.md)

Traverse the full UIA element tree. Check that controls have names, buttons have labels,
and keyboard paths exist. The AI agent generates a compliance report.

### [Dialog and Modal Handling](docs/use-cases/11-dialog-handling.md)

Detect unexpected confirmation dialogs, file-save prompts, and Win32 MessageBox popups
after every click. Handle or dismiss them without breaking the automation flow.

## Tools

52 consolidated tools across four categories, plus a cross-cutting security layer
(merged from 110+ via action/mode parameters):

| Category | Tools | What it does |
|----------|-------|-------------|
| **Desktop Automation** | 33 | Launch/attach/close apps, click, type, read values, screenshots, tree navigation and queries, waits, grids (`ww_grid`), dialogs (`ww_dialog`), windows (`ww_window`), clipboard, session handles (UIA3) |
| **System** | 8 | Processes, registry, environment variables, file system, network, services, scheduled tasks, machine control |
| **AI Agent** | 7 | Semantic snapshots & state diffing (`ww_snapshot`), element inspection (`ww_inspect`), event watching, test case recording, selector healing (`ww_heal_script`), `ww_get_schema` for tool discovery |
| **Browser** | 4 | Chrome/Edge via CDP — sessions, pages, elements, advanced (eval/forms/dialogs). No Selenium dependency |
| **Security** | — | Cross-cutting: runtime permission guards with AD group overrides, JSONL audit logging |

Each tool supports multiple actions via an `action` parameter (e.g., `ww_service(action="list")`, `ww_snapshot(action="get")`), reducing the total tool count while maintaining full functionality. Discover the live surface anytime with `winwright tools`.

## Configuration

Create `winwright.json` next to the binary (or `%APPDATA%\WinWright\winwright.json`).
All settings live under a top-level `WinWright` section:

```json
{
  "WinWright": {
    "Permissions": {
      "AllowShell": false,
      "AllowProcessKill": false,
      "AllowRegistryWrite": false,
      "AllowFileWrite": false,
      "AllowServiceControl": false,
      "AllowTaskScheduler": false,
      "AllowPower": false,
      "AllowLockScreen": false,
      "AllowMachineEnv": false,
      "AllowBrowserEval": false,
      "AllowNetworkProbe": true,
      "AllowFileRead": true
    },
    "Audit": {
      "Enabled": true,
      "RetentionDays": 30
    }
  }
}
```

All destructive operations are disabled by default — enable only what you need.
`AllowNetworkProbe` (ping/DNS) and `AllowFileRead` (`ww_file` read/list) are the only
default-`true` permissions; both are read-only, and worth setting to `false` when serving
over HTTP to remote clients. Gated calls are audit-logged to daily-rotated
`audit-YYYY-MM-DD.jsonl` files.

## CLI

```text
winwright mcp                                    Start MCP server (stdio)
winwright serve --port N                         Start MCP server (HTTP, default 8765)
winwright tools [--json|<name>]                  List the tool surface (CLI discovery; no MCP client needed)
winwright call <tool> [--param value …]          Invoke one tool via the local daemon (CLI automation)
winwright daemon <start|stop|status>             Control the background host that owns CLI sessions
winwright skills <install|list|uninstall>        Install the bundled Claude Code skill (offline)
winwright run <script.json> [--format text|junit] [--output <file>] [--screenshots [--screenshots-dir <dir>]]
                                                 Replay a recorded automation script
winwright heal <script.json> [--output <file>] [--min-confidence <0-1>]
                                                 Probe broken selectors against a live UI and repair them
                                                 (launches/attaches using the script's own metadata)
winwright inspect <pid>                          Dump UIA element tree for a process
winwright doctor                                 Verify environment prerequisites
```

## Requirements

- Windows 10 or 11 (x64 or ARM64)
- No .NET runtime needed for the binary download — it's self-contained

## Who Is This For

**Good fit:**

- QA engineers testing WinForms, WPF, or Win32 apps who want AI-assisted test creation
- Developers building AI agents that need to interact with the Windows desktop
- Teams extracting data from legacy enterprise apps that have no API
- Anyone automating repetitive multi-app workflows on Windows

**Not a good fit:**

- Linux or macOS automation — WinWright is Windows-only (UIA is a Windows API)
- Web-only testing — use [Playwright](https://playwright.dev/) instead; WinWright's browser tools are for mixed desktop+browser workflows
- High-throughput data pipelines — UIA reads controls one at a time; if you need bulk data transfer, a proper API or database connection is better

## How It Compares

| | WinWright | UiPath | Power Automate Desktop | Playwright |
| - | --------- | ------ | ---------------------- | ---------- |
| **What it automates** | Desktop + browser + system | Desktop + browser + system | Desktop + browser + cloud | Browser only |
| **How you use it** | AI agent via MCP (natural language) | Visual workflow designer | Visual workflow designer | Code (JS/Python/C#) |
| **Desktop support** | WPF, WinForms, Win32 (UIA3) | WPF, WinForms, Win32, Java, SAP | WPF, WinForms, Win32 | None |
| **Browser support** | Chrome/Edge via CDP | Chrome, Edge, Firefox | Chrome, Edge, Firefox | Chrome, Edge, Firefox, Safari |
| **Selector model** | AI picks elements by name/type | Visual selector recorder | Visual selector recorder | CSS/XPath selectors |
| **Cost** | Free | Licensed (per-user/bot) | Free (desktop), licensed (cloud) | Free |
| **Setup** | Single binary, no runtime | Full install + studio | Windows store app | npm install |
| **Designed for** | AI agents and MCP clients | Enterprise RPA | Business user automation | Developer testing |

WinWright is not an RPA platform. It's a tool server that gives AI agents access to Windows.
If you need a visual workflow builder or enterprise orchestration, UiPath or Power Automate
are better choices. If you need browser-only testing, Playwright is more mature.

WinWright fits where those tools don't — when an AI agent needs to see and operate
the Windows desktop, or when you need desktop + browser in one MCP session.

## Support

**Help keep this project alive and growing!**

If WinWright has helped your development workflow, consider supporting its continued development. Your contribution helps with:

- Ongoing maintenance and bug fixes
- New feature development
- Infrastructure costs

**50% of all donations go directly to children's charities** helping those in need. The remaining funds support project maintenance and feature upgrades.

[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Support-orange.svg)](https://buymeacoffee.com/civyk)
[![Ko-fi](https://img.shields.io/badge/Ko--fi-Support-blue.svg)](https://ko-fi.com/civyk)

> Every contribution, no matter the size, makes a difference.

- **Issues:** [GitHub Issues](https://github.com/civyk-official/civyk-winwright/issues)
- **Changelog:** [GitHub Releases](https://github.com/civyk-official/civyk-winwright/releases)

## License

Free to use for any purpose — personal, academic, commercial.
See [LICENSE](LICENSE) for full terms. Attribution required when redistributing.

---

**Built on Trust, Driven by Value** — [Civyk](https://civyk.com)