WinProbe

General-purpose WPF/UIA automation engine for Windows desktop applications with MCP Server integration.

Connects to any WPF (or Win32/UIA-compatible) application and provides programmatic element discovery, interaction, assertion, background-safe operation, test script recording/replay, and AI-driven testing via the Model Context Protocol (MCP).

Features

• 44 MCP tools for complete UI automation coverage
• Background-safe — most operations work without foreground focus (no mouse movement, no focus stealing)
• Record/Replay — capture test scripts during AI sessions, replay deterministically at zero token cost
• Layered architecture — each layer can be consumed independently (Core, Wpf, Recording, Mcp)
• Production quality — TreatWarningsAsErrors, sealed classes, ProbeResult<T> pattern, XML documentation

Quick Start

Prerequisites

• .NET SDK 10.0.201+
• Windows 10/11 (required for UI Automation)

Build

dotnet build WinProbe.slnx

Run MCP Server

dotnet run --project src/WinProbe.Mcp/WinProbe.Mcp.csproj --no-launch-profile

Run Tests

# Unit tests only (no running application needed)
dotnet test WinProbe.slnx --nologo --filter "Category!=LiveApp&Category!=E2E"

The LiveApp and E2E suites drive a real application — see Test Baseline.

Configure an MCP client

Add to .mcp.json at the root of your project:

{
  "mcpServers": {
    "wpf-automation": {
      "type": "stdio",
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "/path/to/WinProbe/src/WinProbe.Mcp/WinProbe.Mcp.csproj",
        "--no-launch-profile"
      ]
    }
  }
}

Usage Flow

connect (processName: "MyApp")
  -> get_visual_tree
  -> click (automationId: "loginBtn")
  -> fill_field (automationId: "username", text: "admin")
  -> screenshot
  -> assert_state ({"username": {"value": "admin"}, "loginBtn": {"enabled": true}})

Tool Categories

Category	Tools	Description
Connection (6)	connect, disconnect, get_status, get_windows, focus_window, set_window_state	App lifecycle management
Inspection (4)	get_visual_tree, find_elements, get_page_summary, get_element_info	UI tree discovery
Interaction (12)	click, fill_field, select_item, toggle, right_click, double_click, focus, expand_collapse, scroll, fill_form, navigate_to, hover	Element manipulation
Keyboard (2)	send_keys, send_shortcut	Background-safe keyboard input
Reading (7)	read_value, read_all_fields, get_focused_element, read_table, read_list_items, assert_state, read_validation_errors	Value extraction and assertions
Wait (5)	wait_for_element, wait_until_gone, click_and_wait, wait_for_enabled, wait_for_value	Async polling
Screenshot (3)	screenshot, screenshot_element, screenshot_and_inspect	Visual capture
Recording (5)	record_start, record_step, record_stop, replay, list_recordings	Test script management

Architecture

Mcp (entry point, 44 tools, MCP stdio transport)
 |
 +-- Wpf (FlaUI/UIA3 + Win32 P/Invoke implementations)
 |    +-- Core (interfaces, models, result types)
 |
 +-- Recording (record/replay engine)
      +-- Core

Project Structure

src/
  WinProbe.Core/        # Interfaces, models, ProbeResult<T>, utilities
  WinProbe.Wpf/         # FlaUI/UIA3 + Win32 implementations
  WinProbe.Recording/   # Record/replay engine (JSON persistence)
  WinProbe.Mcp/         # MCP Server entry point + tool definitions
tests/
  WinProbe.Core.Tests/        # 12 unit tests
  WinProbe.Recording.Tests/   # 17 unit tests
  WinProbe.Wpf.Tests/         # 1 unit + 17 live-app tests
docs/
  architecture.md          # Solution architecture and design principles
  api-reference.md         # Complete 44-tool API reference
  getting-started.md       # Setup, configuration, first steps
  development.md           # Contributing, conventions, testing
  test-scenarios.md        # Reusable AI-driven testing patterns

Documentation

Document	Description
Architecture	Layers, dependency rules, design patterns, cross-cutting concerns
API Reference	All 44 tools with parameters, examples, and response formats
Getting Started	Prerequisites, setup, configuration, first automation session
Development Guide	Conventions, testing, adding new tools, project structure
Test Scenarios	Reusable AI-driven testing patterns to adapt to your app
Contributing	Standards, architecture rules, running the live tests
Security	Reporting vulnerabilities, and what WinProbe can access

Background-Safe Operations

Most operations work without the application being in the foreground:

Operation	Method	Foreground Required?
Click, toggle, select	UIA patterns (Invoke, Toggle, SelectionItem)	No
Text input	UIA ValuePattern / Win32 PostMessage	No
Keyboard shortcuts	Win32 PostMessage (WM_KEYDOWN/WM_KEYUP)	No
Screenshots	Test Agent → WGC → BitBlt cascade	No (last-resort BitBlt needs the window uncovered)
Read values, inspect tree	UIA tree traversal	No
Hover	Mouse.MoveTo	Yes
Right-click	Physical click	Yes

Test Baseline

• 30 unit tests — run anywhere, no application required
  • Core: ProbeResult, ElementQuery validation
  • Recording: RecordingService lifecycle, ParameterExtensions type coercion
• 17 live-app tests — excluded by the filter above; they attach to a real running application. Set WINPROBE_TARGET_PROCESS to its process name (defaults to Notepad), and for the E2E login flow also set WINPROBE_E2E_TENANT / _USERNAME / _PASSWORD.
  • Category=LiveApp (10) — connect, tree, windows, capture backends
  • Category=E2E (7) — ordered login-to-navigation walkthrough
• 0 warnings with TreatWarningsAsErrors=true

License

MIT © 2025 Wosoolsoft