WinWright

WinWright

Model Context Protocol 用の Windows 自動化サーバーです。 デスクトップ（WPF、WinForms、Win32）、ブラウザー（CDP 経由の Chrome/Edge）、 システム管理に対応する 52 の統合ツールを備え、MCP 経由で AI エージェントから利用できます。または、MCP がブロックされている場合は、コマンドライン（winwright call …）から直接操作できます。

テスト内容を平易な英語で記述すれば、あとは AI エージェントにおまかせ

テストケースを平易な英語で記述します。AI エージェントは WinWright の MCP ツールを使って UI コントロールを検出し、操作を実行し、そのすべてをポータブルな JSON スクリプトとして記録します。

記録したスクリプトを再生 — AI エージェントは不要

記録したスクリプトは winwright run で毎回同じように実行できます。AI エージェントも LLM 呼び出しもトークンコストも不要です。実行するたびに同じ結果が得られます。

UI レイアウトが変わった場合、WinWright は壊れたセレクターを自動的に自己修復できます （winwright heal）。大規模な UI の再設計の場合は、AI エージェントにスクリプトの更新を依頼してください。 テストを最初から書き直すよりも、すばやく対応できます。

これが重要な理由：

• AI コストを節約 — エージェントが一度記録すれば、スクリプトは無料で再生できます
• 決定的な結果 — 実行のたびに、同一で再現可能な結果が得られます
• メンテナンスが簡単 — セレクターの自己修復と、AI によるスクリプト修復

目次

• クイックスタート
• インストール
• MCP クライアントの設定
• CLI モード（MCP がブロックされている場合）
• ユースケース
• ツール
• 設定
• 対象ユーザー
• 他製品との比較
• サポート
• ライセンス

クイックスタート

インストールして MCP クライアントを設定したら、エージェントに操作を依頼します。

「メモ帳を起動して、『Hello from WinWright』と入力し、入力した内容を読み上げてください。」

エージェントは WinWright のツールを呼び出し、結果を返します。

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

すべてのツールは構造化された JSON を返します。どのツールをどの順番で呼び出すかはエージェントが判断します。 目標を自然な言葉で説明してください。

インストール

GitHub Releases からダウンロードします。

アセット	アーキテクチャ
winwright-*-win-x64.zip	Intel/AMD 64 ビット
winwright-*-win-arm64.zip	ARM64（Surface Pro など）

MCP クライアントの設定

Claude Code / VSCode（stdio）

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

Claude Code / VSCode（HTTP）

先にサーバーを起動します：Civyk.WinWright.Mcp.exe serve --port 8765

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

Claude Desktop

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

CLI モード（MCP がブロックされている場合）

多くの企業環境では MCP がブロックされています。その場合、WinWright はコマンドラインから完全に操作できます。エージェントとツールの間にMCP クライアントを介さず、同じツールで同じ自動化を利用できます。バックグラウンドデーモン（ループバックの serve インスタンス）が実行中のセッションを管理するため、ww_launch が返す appId は別々のコマンド間でも有効です。

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 の結果は stdout に出力されるため、jq に安全に渡せます。診断情報は stderr に出力されます。デーモンは最初の call で自動起動し、ループバックのみにバインドされ、アイドル状態になると自動終了します。

CLI は MCP のように機能を提示しないため、エージェントが使い方を把握できるよう、同梱のClaude Code スキルをインストールしてください。バイナリに組み込まれているため、オフラインでインストールできます。

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

ユースケース

各カードから、実際のプロンプト、ツール呼び出しのパラメーター、出力例を含む詳しい手順を確認できます。 すべてのガイドは docs/use-cases/ からご覧ください。

CI 向けスクリプト UI テスト自動化

AI セッションを一度記録すると、エージェントが UI を検出して操作を実行し、アサーションを埋め込みます。 その後、AI エージェントなしで CI 上で再生できる、ポータブルな JSON スクリプトとしてエクスポートできます。アプリについて説明するか、既存の手動テストスイートを貼り付けると、エージェントが自動でスクリプトを作成します。

自律型デスクトップ自動化

AI エージェントにデスクトップへのアクセス権を付与します。エージェントはアプリを起動し、アプリ間でデータを移動し、フォームに入力し、確認用のスクリーンショットを撮影します。スクリプトの作成や保守は不要です。

レガシーアプリのデータ抽出

多くのエンタープライズアプリには API がありません。Windows UI Automation からコントロールを認識できれば、WinWright はその値を読み取れます。連携を想定して作られていないアプリからデータを抽出できます。

繰り返し作業向けのスクリプトによるデスクトップ自動化

毎日の反復的なワークフローを一度記録します。RPA スクリプトとしてエクスポートし、必要に応じて再生できます。記録後に AI エージェントは不要です。レポートのエクスポート、データのインポート、毎回同じ手順で実行される複数ステップのタスクに最適です。

AI を活用した UI テスト

AI エージェントが WinForms または WPF アプリを調査し、要素を見つけて状態をアサートします。保守が難しい XPath セレクターは不要です。UI が変わってもエージェントが適応します。

一括データ検証

アプリを自動で 50 件以上のレコードに対して操作します。表示される各値を参照テーブルと照合し、不一致の詳細を含む構造化された合格／不合格レポートを取得できます。

アプリ間ワークフロー

デスクトップアプリとブラウザーにまたがるワークフローを自動化します。会計アプリから読み取り、Web ポータルに送信し、確認画面のスクリーンショットを撮影します。

アプリの稼働状況の監視

実行中のアプリが稼働していて応答可能であることを確認します。プロセスが実行中であること、接続ステータスに「Connected」と表示されること、サービスが正常であることを確認できます。定期的なチェックには Windows タスク スケジューラと組み合わせてください。

リモート管理

HTTP 経由で、リモートマシン上のプロセス、サービス、レジストリ、スケジュールされたタスクを管理します。5 層のセキュリティを備えています。IP 許可リスト、Windows Negotiate 認証、AD グループ認可、レート制限、ユーザーごとのセッション数制限です。

アクセシビリティ監査

UIA 要素ツリー全体をたどります。コントロールに名前があること、ボタンにラベルがあること、キーボード操作の経路が存在することを確認します。AI エージェントがコンプライアンスレポートを生成します。

ダイアログとモーダルの処理

クリックのたびに、予期しない確認ダイアログ、ファイル保存プロンプト、Win32 MessageBox ポップアップを検出します。自動化のフローを中断せずに処理または閉じることができます。

ツール

4 つのカテゴリにわたる統合済みツール 52 個に加え、全カテゴリに適用されるセキュリティレイヤー （アクション／モードのパラメーターによって 110 個以上から統合）：

カテゴリ	ツール	機能
デスクトップ自動化	33	アプリの起動／接続／終了、クリック、入力、値の読み取り、スクリーンショット、ツリーのナビゲーションとクエリ、待機、グリッド（ww_grid）、ダイアログ（ww_dialog）、ウィンドウ（ww_window）、クリップボード、セッションハンドル（UIA3）
システム	8	プロセス、レジストリ、環境変数、ファイルシステム、ネットワーク、サービス、スケジュールされたタスク、マシン制御
AI エージェント	7	セマンティックスナップショットと状態差分（ww_snapshot）、要素の検査（ww_inspect）、イベント監視、テストケースの記録、セレクターの修復（ww_heal_script）、ツール検出用の ww_get_schema
ブラウザー	4	CDP 経由の Chrome／Edge — セッション、ページ、要素、高度な操作（eval／フォーム／ダイアログ）。Selenium への依存なし
セキュリティ	—	全カテゴリに適用：AD グループによる上書きに対応した実行時の権限ガード、JSONL 監査ログ

各ツールは action パラメーターを介して複数のアクションに対応します（例：ww_service(action="list")、ww_snapshot(action="get")）。これにより、すべての機能を維持しながらツールの総数を抑えています。winwright tools を実行すれば、いつでも最新のツール一覧を確認できます。

設定

バイナリと同じ場所（または %APPDATA%\WinWright\winwright.json）に winwright.json を作成します。 すべての設定はトップレベルの WinWright セクションに記述します：

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

破壊的な操作はすべてデフォルトで無効になっています。必要なものだけを有効にしてください。 AllowNetworkProbe（ping／DNS）と AllowFileRead（ww_file の読み取り／一覧表示）は、デフォルトで true に設定されている唯一の権限です。どちらも読み取り専用であり、リモートクライアントに HTTP 経由で提供する場合は false に設定することをおすすめします。制限対象の呼び出しは、日次ローテーションされる audit-YYYY-MM-DD.jsonl ファイルに監査ログとして記録されます。

CLI

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

要件

• Windows 10 または 11（x64 または ARM64）
• バイナリのダウンロード版は自己完結型のため、.NET ランタイムは不要です

対象ユーザー

適しているユーザー：

• AI 支援によるテスト作成を希望する、WinForms、WPF、Win32 アプリのテストを行う QA エンジニア
• Windows デスクトップを操作する必要がある AI エージェントを開発する開発者
• API のないレガシーなエンタープライズアプリからデータを抽出するチーム
• Windows 上で複数アプリにまたがる反復的なワークフローを自動化するすべての方

適していないユーザー：

• Linux または macOS の自動化 — WinWright は Windows 専用です（UIA は Windows API です）
• Web のみのテスト — 代わりに Playwright を使用してください。WinWright のブラウザーツールは、デスクトップとブラウザーを組み合わせたワークフロー向けです
• 高スループットのデータパイプライン — UIA はコントロールを 1 つずつ読み取ります。データを一括転送する必要がある場合は、適切な API またはデータベース接続のほうが適しています

比較

	WinWright	UiPath	Power Automate Desktop	Playwright
自動化の対象	デスクトップ＋ブラウザー＋システム	デスクトップ＋ブラウザー＋システム	デスクトップ＋ブラウザー＋クラウド	ブラウザーのみ
使用方法	MCP 経由の AI エージェント（自然言語）	ビジュアルワークフローデザイナー	ビジュアルワークフローデザイナー	コード（JS/Python/C#）
デスクトップ対応	WPF、WinForms、Win32（UIA3）	WPF、WinForms、Win32、Java、SAP	WPF、WinForms、Win32	なし
ブラウザー対応	CDP 経由の Chrome/Edge	Chrome、Edge、Firefox	Chrome、Edge、Firefox	Chrome、Edge、Firefox、Safari
セレクターモデル	AI が名前／種類で要素を選択	ビジュアルセレクターレコーダー	ビジュアルセレクターレコーダー	CSS/XPath セレクター
費用	無料	ライセンス制（ユーザー／ボット単位）	無料（デスクトップ）、ライセンス制（クラウド）	無料
セットアップ	単一バイナリ、ランタイム不要	完全なインストール＋Studio	Windows ストアアプリ	npm install
対象	AI エージェントと MCP クライアント	エンタープライズ RPA	ビジネスユーザー向け自動化	開発者向けテスト

WinWright は RPA プラットフォームではありません。AI エージェントに Windows へのアクセスを提供するツールサーバーです。 ビジュアルワークフロービルダーやエンタープライズオーケストレーションが必要な場合は、UiPath または Power Automate のほうが適しています。ブラウザーのみのテストが必要な場合は、Playwright のほうが成熟しています。

WinWright は、ほかのツールでは対応できない用途に適しています。AI エージェントが Windows デスクトップを認識して操作する必要がある場合や、1 つの MCP セッションでデスクトップとブラウザーの両方を扱う必要がある場合です。

サポート

このプロジェクトの継続と成長を支援してください！

WinWright が開発ワークフローに役立っている場合は、継続的な開発へのご支援をご検討ください。ご寄付は、以下の取り組みに役立てられます。

• 継続的なメンテナンスとバグ修正
• 新機能の開発
• インフラストラクチャの費用

寄付金の50％は、支援を必要とする子どもたちを支える慈善団体に直接寄付されます。 残りの資金は、プロジェクトのメンテナンスと機能強化に充てられます。

ご支援の大小にかかわらず、すべてが力になります。

• 課題： GitHub Issues
• 変更履歴： GitHub Releases

ライセンス

個人、学術、商用を問わず、あらゆる目的で無料で使用できます。 詳細な条件については、LICENSE をご覧ください。再配布する場合は帰属表示が必要です。

---

信頼を礎に、価値を原動力に — Civyk