WPFVisualTreeMcp

# WpfVisualTreeMcp

<!-- mcp-name: io.github.faze79/wpf-visual-tree -->

[![Build](https://github.com/faze79/WpfVisualTreeMcp/actions/workflows/build.yml/badge.svg)](https://github.com/faze79/WpfVisualTreeMcp/actions/workflows/build.yml)
[![Release](https://img.shields.io/github/v/release/faze79/WpfVisualTreeMcp)](https://github.com/faze79/WpfVisualTreeMcp/releases)
[![.NET](https://img.shields.io/badge/.NET-8.0-512BD4)](https://dotnet.microsoft.com/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green)](https://modelcontextprotocol.io/)

> **Let AI agents see, debug and drive running WPF apps.** Snoop + Playwright for AI, exposed over the Model Context Protocol — visual tree, bindings, screenshots, mouse dragging, touch gestures, text input and keyboard. Inspect running apps without source changes; touch behavior depends on the application's input support.

![Demo: an AI agent drives a WPF app and finds a binding bug](docs/assets/demo.gif)

*An AI agent queries controls by visible text, fills the form, selects a list item, clicks Submit — then explains why the Status box stayed empty by pulling the app's binding errors. Every step is one MCP tool call (or CLI command).*

## Quickstart (60 seconds)

1. Download and extract the [latest release](https://github.com/faze79/WPFVisualTreeMcp/releases) zip (requires the [.NET 8 Desktop Runtime](https://dotnet.microsoft.com/download/dotnet/8.0)).
2. Register it in your MCP client — for Claude Code, add to `.mcp.json`:
   ```json
   {
     "mcpServers": {
       "wpf-visual-tree": {
         "command": "C:/path/to/WpfVisualTreeMcp.Server.exe",
         "args": []
       }
     }
   }
   ```
3. Ask your agent: *"Look at my running WPF app and tell me why the Save button is disabled."*

Prefer the terminal? The same exe is a full CLI: `WpfVisualTreeMcp.Server.exe help`.

## Overview

**WpfVisualTreeMcp** is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that allows AI coding agents (Claude Code, Cursor, GitHub Copilot) to inspect and interact with running WPF applications. Think of it as giving your AI assistant the same capabilities as tools like [Snoop WPF](https://github.com/snoopwpf/snoopwpf) or Visual Studio's Live Visual Tree.

### Why This Matters

Debugging WPF UI issues traditionally requires manual inspection with specialized tools. This project bridges that gap by exposing WPF inspection capabilities through MCP, enabling AI agents to:

- **Understand UI structure** during code reviews
- **Diagnose binding errors** automatically
- **Suggest fixes** for layout issues
- **Assist with UI refactoring** tasks
- **Analyze visual tree hierarchies** in real-time

## Features

### Core Inspection
- **Process Discovery** - List all running WPF applications available for inspection
- **Visual Tree Navigation** - Traverse the complete visual tree hierarchy
- **Logical Tree Access** - Navigate the logical tree structure
- **Property Inspection** - Read all dependency properties of any UI element

### Binding & Resources
- **Binding Analysis** - Inspect bindings with converter, StringFormat, FallbackValue, MultiBinding support
- **DataContext Inspection** - View DataContext type, properties, INPC status, and inheritance chain
- **Binding Error Detection** - Automatically capture and report binding errors with classification
- **Resource Enumeration** - Browse resource dictionaries at any scope
- **Style Inspection** - View applied styles and templates

### Search & Monitoring
- **Element Search** - Find elements by type, name, or property values
- **Deep Search** - Search entire tree including AdornerLayer and Popup elements
- **Property Watching** - Monitor property changes in real-time

### Interaction & Export
- **Touch Gestures** *(v0.13.0)* - `wpf_touch_gesture` / CLI `touch`: native tap, long press, swipe, pinch and rotation with one or two contacts. Includes an interactive demo and [WPF compatibility guidance](docs/TOOLS_REFERENCE.md#touch-compatibility-and-verification).
- **Mouse Drag** - `wpf_drag` / CLI `drag`: drag between visual-tree elements or by a local displacement, with left/right/middle buttons, configurable duration and local start/end points. Supports slider thumbs, splitters and drag-and-drop. See the [parameters and examples](docs/TOOLS_REFERENCE.md#wpf_drag).
- **Screenshot Capture** - Capture window/element screenshots visible to AI agents
- **Element Highlighting** - Visually highlight elements in the running app
- **Control Click** *(v0.4.0)* - Click elements via UI Automation (`Invoke`/`Toggle`/`Select`/`ExpandCollapse`) or a real OS mouse click
- **Set Text** *(new in v0.5.0)* - Fill a TextBox/ComboBox/PasswordBox via UI Automation `IValueProvider.SetValue`, with a `TextBox.Text` / `PasswordBox.Password` / reflected-`Text` fallback, or `physical=true` to type via OS keyboard input (full Unicode BMP)
- **Send Keys** *(new in v0.5.0)* - Send keyboard shortcuts (`Ctrl+S`, `Alt+F4`, `F5`, `Enter`, `Ctrl+Shift+F`, ...) to an element or the focused window via OS keyboard input
- **Layout Information** - Get detailed layout metrics
- **Tree Export** - Export visual tree to XAML or JSON format
- **Auto-Injection** - Inject Inspector into running WPF processes (no source changes needed); **multi-architecture** since v0.6.0 — a 64-bit server can inject into 32-bit WPF apps via a bundled `WpfInjectorHelper.exe`

### Dual-Mode CLI *(new in v0.4.0)*
The same `WpfVisualTreeMcp.Server.exe` runs as either an MCP stdio server
(no arguments, default) or as a **one-shot CLI** (any recognised subcommand).
Useful when the MCP server isn't connected, for scripting, and for verifying
the pipeline manually. Run `WpfVisualTreeMcp.Server.exe help` for the full
command list. Output is JSON on stdout; diagnostics go to stderr.

## How it compares

**vs. the general tool categories:**

| | **WpfVisualTreeMcp** | [Snoop](https://github.com/snoopwpf/snoopwpf) | [FlaUI](https://github.com/FlaUI/FlaUI) / WinAppDriver | Generic computer-use (screenshot + mouse) |
|---|---|---|---|---|
| Consumer | **AI agents (MCP) + humans (CLI)** | Humans (GUI) | Test code (C#) | AI agents |
| Visual tree, dependency properties | ✅ | ✅ | ❌ (UIA view only) | ❌ |
| Data bindings, binding errors, DataContext | ✅ | ✅ | ❌ | ❌ |
| Find controls by visible text / properties | ✅ | manual | partial (UIA) | pixel guessing |
| Click / type / select / shortcuts | ✅ | ❌ | ✅ | ✅ (blind) |
| Wait for UI conditions (no sleep loops) | ✅ | ❌ | ✅ | ❌ |
| Element screenshots + popup-aware screen capture | ✅ | ❌ | partial | full screen only |
| Works without target source changes | ✅ (auto-injection) | ✅ | ✅ | ✅ |

**vs. other WPF MCP servers.** Most WPF MCP servers are built on **UI Automation** (FlaUI): they read the *accessibility* tree, and can only reach WPF internals — bindings, DataContext, ViewModel state — if you **install their in-process probe into the app you want to inspect**. This server takes the Snoop route instead: it **injects at runtime**, so it reads the *real* visual tree and diagnoses binding errors and DataContext **with zero changes to the target app** — nothing to add to your build, nothing to ship into production.

| | **WpfVisualTreeMcp** | UIA-based servers (FlaUI) | Other injection-based servers |
|---|---|---|---|
| Sees the real visual tree (not just the UIA view) | ✅ injection | ❌ accessibility tree | ✅ |
| Binding errors + DataContext **without a probe in the target** | ✅ | ❌ (needs in-process probe) | partial |
| Interaction surface | click (UIA + physical, double/right), set-text w/ read-back, send-keys, **select-item (virtualized)** | click / type / select | usually invoke-only |
| Wait for element conditions | ✅ `wpf_wait_for` | ✅ | ❌ |
| Popup / dropdown / context-menu screenshots | ✅ screen mode | partial | screenshot only |
| Cross-architecture injection (x64 ⇄ x86) | ✅ | n/a | ❌ |
| Dual-mode: MCP server **and** one-shot CLI | ✅ | ❌ | ❌ |
| Distribution | NuGet (`dnx`/tool) + official MCP registry | varies | varies |

In short: UIA-based tools see what accessibility exposes, and computer-use agents see pixels. This project gives the agent **the same insider view a WPF developer has in Snoop — with no probe to install in the target app** — plus the widest set of hands to act on it, over a protocol every AI coding tool speaks.

## Installation

### Prerequisites

- Windows 10/11
- [.NET 8.0 SDK](https://dotnet.microsoft.com/download/dotnet/8.0) or later
- A WPF application to inspect

### Installation

#### Option 1: .NET tool / NuGet (Recommended)

```bash
dotnet tool install -g WpfVisualTreeMcp     # installs the `wpfinspect` command
```

The package is also published as an **MCP server package** (`PackageType: McpServer`),
so MCP clients that support NuGet-hosted servers can launch it directly:

```bash
dnx WpfVisualTreeMcp                        # runs the MCP stdio server
```

#### Option 2: Download Release

Download the latest release from [GitHub Releases](https://github.com/faze79/WpfVisualTreeMcp/releases):

1. Download `WpfVisualTreeMcp-vX.X.X-win-x64.zip`
2. Extract to a folder (e.g., `C:\Tools\WpfVisualTreeMcp`)
3. The MCP server executable is `WpfVisualTreeMcp.Server.exe`

#### Option 3: Build from Source

```bash
git clone https://github.com/faze79/WpfVisualTreeMcp.git
cd WpfVisualTreeMcp
# Visual Studio Developer PowerShell (C++ v143 toolset + Windows SDK)
./scripts/Build-NativeBootstrapper.ps1
dotnet build -c Release
```

For injection build requirements, package layout, and troubleshooting, see the
[Injector README](src/WpfVisualTreeMcp.Injector/README.md). Injecting into x86 apps
requires the x86 .NET 8 runtime for the helper.

### Configuration

The server uses the **official Microsoft/Anthropic MCP SDK for .NET**, providing guaranteed compatibility with Claude Code and other MCP clients.

#### Claude Code