Model Context Protocol (MCP)를 위한 Windows 자동화 서버입니다.
데스크톱 (WPF, WinForms, Win32), 브라우저 (CDP를 통한 Chrome/Edge), 그리고 시스템 관리를 위한 약 52개의 통합 도구를 제공합니다. 이는 MCP를 통해 AI 에이전트가 접근할 수 있으며, MCP가 차단된 경우 명령줄(command line)에서 직접 실행(winwright call …)할 수도 있습니다.

사용자는 평이한 영어로 테스트 케이스를 작성합니다. AI 에이전트는 WinWright의 MCP 도구를 사용하여 UI 컨트롤을 탐색하고, 동작을 수행하며, 모든 과정을 휴대 가능한 JSON 스크립트로 기록합니다.

한 번 기록된 스크립트는 winwright run을 통해 결정론적(deterministic)으로 실행됩니다.

— AI 에이전트 불필요,
— LLM 호출 불필요,
— 토큰 비용 발생 없음. 결과는 매번 동일합니다.

UI 레이아웃이 변경되면, WinWright는 손상된 셀렉터(selector)를 자동으로 **자가 치유(self-heal)**할 수 있습니다 (winwright heal). 대규모 UI 재설계의 경우, AI 에이전트에게 스크립트 업데이트를 요청하십시오. 이 역시 처음부터 테스트를 다시 작성하는 것보다 빠릅니다.

이것이 중요한 이유:

AI 비용 절감— 에이전트가 한 번 기록하면, 스크립트는 무료로 재생됩니다.
결정론적 결과— 모든 실행이 동일하고 재현 가능한 결과를 생성합니다.
쉬운 유지보수— 자가 치유 셀렉터 및 AI 지원 스크립트 수리

• 빠른 시작 (Quick Start)
• 설치 (Install)
• MCP 클라이언트 설정 (MCP Client Configuration)
• CLI 모드 (MCP가 차단된 경우)
• 사용 사례 (Use Cases)
• 도구 (Tools)
• 설정 (Configuration)
• 대상 사용자 (Who Is This For)
• 비교 (How It Compares)
• 지원 (Support)
• 라이선스 (License)

설치하고 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에서 다운로드하십시오:

자산 (Asset)	아키텍처 (Architecture)
winwright-*-win-x64.zip	Intel/AMD 64-bit
winwright-*-win-arm64.zip	ARM64 (Surface Pro 등)

{
"servers": {
"winwright": {
...

먼저 서버를 시작하세요: Civyk.WinWright.Mcp.exe serve --port 8765

{
"servers": {
"winwright": {
...

{
"mcpServers": {
"winwright": {
...

많은 기업 환경에서는 MCP를 차단합니다. 대신 WinWright는 **전적으로 명령줄 (command line)**을 통해 구동될 수 있습니다. 에이전트와 도구 사이에 MCP 클라이언트 (MCP client) 없이도 동일한 도구와 동일한 자동화를 사용할 수 있습니다. 백그라운드 데몬 (루프백 serve 인스턴스)이 라이브 세션을 소유하므로, ww_launch에 의해 반환된 appId는 별도의 명령 간에도 유효하게 유지됩니다.

winwright call ww_launch --exePath "C:\Apps\MyApp.exe" # -> {"appId":"app-1", ...}
winwright call ww_click --appId app-1 --selector "#submit"
...

JSON 결과는 stdout으로 전송되며 (jq로 파이프 연결 가능), 진단 정보는 stderr로 전송됩니다. 데몬은 첫 번째 call 시 자동으로 시작되며, 루프백에만 바인딩되고, 유휴 상태가 되면 스스로 종료됩니다.

CLI는 MCP와 같은 방식으로 자신의 기능을 광고하지 않기 때문에, 에이전트가 이를 사용하는 방법을 알 수 있도록 번들로 제공되는 Claude Code skill을 설치하세요. 바이너리에 내장되어 있어 오프라인에서도 설치됩니다:

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

각 카드는 실제 프롬프트, 도구 호출 파라미터(tool call parameters), 예시 출력이 포함된 상세 가이드로 연결됩니다. 모든 가이드는 docs/use-cases/에서 찾아볼 수 있습니다.

AI 세션을 한 번만 기록하세요. 에이전트가 UI를 탐색하고, 동작을 수행하며, 어설션 (assertion)을 임베딩합니다. 그 후 AI 에이전트 없이도 CI에서 재현할 수 있는 휴대 가능한 JSON 스크립트로 내보내세요. 앱을 설명하거나 기존의 수동 테스트 스위트를 붙여넣기만 하면 에이전트가 자동으로 스크립트를 작성합니다.

AI 에이전트에게 데스크톱 접근 권한을 부여하세요. 에이전트는 앱을 실행하고, 앱 간에 데이터를 이동하며, 양식을 채우고, 검증을 위해 스크린샷을 찍습니다. 작성하거나 유지 관리해야 할 스크립트가 필요 없습니다.

많은 엔터프라이즈 앱에는 API가 없습니다. Windows UI Automation이 컨트롤을 볼 수 있다면, WinWright는 그 값을 읽을 수 있습니다. 통합을 위해 만들어지지 않은 앱으로부터 데이터를 추출하세요.

반복적인 일상 업무 워크플로우를 한 번만 기록하세요. RPA 스크립트로 내보낸 뒤 필요할 때마다 재생할 수 있습니다 — 기록 후에는 AI 에이전트가 필요하지 않습니다. 보고서 내보내기, 데이터 가져오기, 그리고 매번 동일한 방식으로 실행되는 모든 다단계 작업에 이상적입니다.

AI 에이전트가 WinForms 또는 WPF 앱을 탐색하여 요소를 찾고 상태를 단언(assert)합니다. 유지 관리해야 할 취약한 XPath 선택자(selector)가 없습니다 — UI가 변경되어도 에이전트가 적응합니다.

50개 이상의 레코드를 통해 앱을 자동으로 구동합니다. 표시되는 각 값을 참조 테이블과 비교하여 불일치 세부 정보가 포함된 구조화된 통과/실패(pass/fail) 보고서를 받으세요.

데스크톱 앱과 브라우저에 걸친 워크플로우를 자동화합니다 — 회계 앱에서 데이터를 읽고, 웹 포털에 제출하며, 확인 화면을 스크린샷으로 찍습니다.

실행 중인 앱이 살아있고 응답하는지 확인합니다 — 프로세스가 실행 중인지, 연결 상태가 'Connected'로 표시되는지, 서비스가 정상인지 확인합니다. Windows 작업 스케줄러(Task Scheduler)와 결합하여 정기적인 점검을 수행할 수 있습니다.

HTTP를 통해 원격 머신의 프로세스, 서비스, 레지스트리 및 예약된 작업을 관리합니다. 5계층 보안을 제공합니다: IP 허용 목록(allowlist), Windows Negotiate 인증, AD 그룹 권한 부여, 속도 제한(rate limiting), 사용자별 세션 제한.

전체 UIA 요소 트리(element tree)를 탐색합니다. 컨트롤에 이름이 있는지, 버튼에 레이블이 있는지, 키보드 경로가 존재하는지 확인합니다. AI 에이전트가 준수 보고서(compliance report)를 생성합니다.

매 클릭 후 발생하는 예기치 않은 확인 대화 상자, 파일 저장 프롬프트, Win32 MessageBox 팝업을 감지합니다. 자동화 흐름을 끊지 않고 이를 처리하거나 닫습니다.

5개 카테고리에 걸쳐 통합된 약 52개의 도구 (action/mode 파라미터를 통해 110개 이상에서 병합됨):

카테고리	도구 수	기능
데스크톱 자동화 (Desktop Automation)	~26	앱 실행, 클릭, 타이핑, 값 읽기, 스크린샷, 트리 탐색, 그리드 (ww_grid), 다이얼로그 (ww_dialog), 윈도우 (ww_window), 테스트 케이스 녹화, CI 스크립트 내보내기 (UIA3)
시스템 (System)	~12	프로세스, 레지스트리, 환경 변수, 파일 시스템, 네트워크, 서비스, 예약된 작업
브라우저 (Browser)	4	CDP를 통한 Chrome/Edge — 세션, 페이지, 요소, 고급 기능 (eval/양식/다이얼로그). Selenium 의존성 없음
AI 에이전트 (AI Agent)	~8	시맨틱 스냅샷 및 상태 차이 분석 (ww_snapshot), 요소 검사 (ww_inspect), 이벤트 감시, 액션 녹화, 도구 발견을 위한 ww_get_schema
보안 (Security)	—	AD 그룹 오버라이드를 포함한 런타임 권한 가드, JSONL 감사 로그 기록

각 도구는 action 파라미터를 통해 여러 액션을 지원하여 (예: ww_service(action="list"), ww_snapshot(action="get")), 전체 기능을 유지하면서도 총 도구 수를 줄입니다. 언제든지 winwright tools를 통해 활성화된 인터페이스를 확인할 수 있습니다.

바이너리 옆에 winwright.json 파일을 생성하세요 (또는 %APPDATA%\WinWright\winwright.json).
모든 설정은 최상위 WinWright 섹션 아래에 위치합니다:

{
"WinWright": {
"Permissions": {
...

모든 파괴적인 작업은 기본적으로 비활성화되어 있습니다 — 필요한 것만 활성화하세요.
AllowNetworkProbe (ping/DNS) 및 AllowFileRead (ww_file 읽기/목록)가 유일하게 default-true인 권한입니다. 두 권한 모두 읽기 전용이며, 원격 클라이언트에 HTTP로 서비스를 제공할 때는 false로 설정하는 것이 좋습니다. 제한된 호출은 일별로 로테이션되는 audit-YYYY-MM-DD.jsonl 파일에 감사 로그로 기록됩니다.

winwright mcp MCP 서버 시작 (stdio)
winwright serve --port N MCP 서버 시작 (HTTP, 기본값 8765)
winwright tools [--json|<name>] 도구 인터페이스 목록 표시 (CLI 발견; MCP 클라이언트 불필요)
...

• Windows 10 또는 11 (x64 또는 ARM64)
• 바이너리 다운로드 시 .NET 런타임이 필요하지 않음 — 자체 포함(self-contained) 방식임

적합한 사례:

• AI 보조 테스트 생성을 원하는 WinForms, WPF 또는 Win32 앱 테스트 QA 엔지니어
• Windows 데스크톱과 상호작용해야 하는 AI 에이전트(AI agents)를 구축하는 개발자
• API가 없는 레거시 엔터프라이즈 앱(legacy enterprise apps)에서 데이터를 추출하는 팀
• Windows에서 반복적인 멀티 앱 워크플로(multi-app workflows)를 자동화하려는 모든 사용자

적합하지 않은 사례:

• Linux 또는 macOS 자동화 — WinWright는 Windows 전용입니다 (UIA는 Windows API임)
• 웹 전용 테스트 — 대신 Playwright를 사용하세요; WinWright의 브라우저 도구는 데스크톱과 브라우저가 혼합된 워크플로를 위한 것입니다
• 고처리량 데이터 파이프라인 (High-throughput data pipelines) — UIA는 컨트롤을 한 번에 하나씩 읽습니다; 대량의 데이터 전송이 필요한 경우 적절한 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
셀렉터 모델 (Selector model)	AI가 이름/유형별로 요소 선택	시각적 셀렉터 레코더	시각적 셀렉터 레코더	CSS/XPath 셀렉터
비용	무료	라이선스 필요 (사용자/봇당)	무료 (데스크톱), 라이선스 필요 (클라우드)	무료
설정	단일 바이너리, 런타임 불필요	전체 설치 + 스튜디오	Windows 스토어 앱	npm install
설계 목적	AI 에이전트 및 MCP 클라이언트	엔터프라이즈 RPA	비즈니스 사용자 자동화	개발자 테스트

WinWright는 RPA 플랫폼이 아닙니다. 이는 AI 에이전트에게 Windows 접근 권한을 부여하는 도구 서버(tool server)입니다. 시각적 워크플로 빌더나 엔터프라이즈 오케스트레이션(enterprise orchestration)이 필요한 경우 UiPath 또는 Power Automate가 더 나은 선택입니다. 브라우저 전용 테스트가 필요한 경우 Playwright가 더 성숙한 도구입니다.

WinWright는 해당 도구들이 대응하지 못하는 영역, 즉 AI 에이전트가 Windows 데스크톱을 보고 조작해야 하거나, 하나의 MCP 세션에서 데스크톱과 브라우저를 모두 사용해야 할 때 적합합니다.

이 프로젝트가 계속 유지되고 성장할 수 있도록 도와주세요!

WinWright가 귀하의 개발 워크플로(workflow)에 도움이 되었다면, 지속적인 개발을 지원하는 것을 고려해 주세요. 귀하의 기여는 다음 사항에 도움이 됩니다:

• 지속적인 유지보수 및 버그 수정
• 새로운 기능 개발
• 인프라 비용

모든 기부금의 50%는 도움이 필요한 아이들을 돕는 아동 자선 단체에 직접 전달됩니다. 나머지 자금은 프로젝트 유지보수 및 기능 업그레이드를 지원합니다.

금액에 상관없이 모든 기여는 큰 차이를 만듭니다.

이슈(Issues): GitHub Issues
변경 이력(Changelog): GitHub Releases

개인적, 학술적, 상업적 용도를 포함하여 어떤 목적으로든 자유롭게 사용할 수 있습니다. 전체 약관은 LICENSE를 참조하세요. 재배포 시에는 출처 표기가 필요합니다.

신뢰를 바탕으로 구축되고, 가치로 움직입니다 — Civyk