Windows自动化

Requirements

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

Install

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:

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.

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/.

[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.

MCP Client Configuration

Configuration

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

{
  "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 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.

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:

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

Claude Code Plugin

From inside Claude Code, add the marketplace and install:

/plugin marketplace add civyk-official/civyk-winwright
/plugin install winwright@civyk-winwright

The plugin's install script downloads the latest binary automatically.

Note: WinWright has been submitted to the official Claude Code plugin directory and is pending review. Until approved, use the marketplace commands above to install.

How It Compares

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.