# WPFVisualTreeMcp

> MCP server for inspecting WPF application Visual Trees - enables AI agents to debug and analyze WPF UI hierarchies in real-time

- **Type:** MCP server
- **Install:** `agentstack add mcp-faze79-wpfvisualtreemcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [faze79](https://agentstack.voostack.com/s/faze79)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [faze79](https://github.com/faze79)
- **Source:** https://github.com/faze79/WPFVisualTreeMcp

## Install

```sh
agentstack add mcp-faze79-wpfvisualtreemcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# WpfVisualTreeMcp

[](https://github.com/faze79/WpfVisualTreeMcp/actions/workflows/build.yml)
[](https://github.com/faze79/WpfVisualTreeMcp/releases)
[](https://dotnet.microsoft.com/)
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io/)

> MCP server for inspecting WPF application Visual Trees - enables AI agents to debug and analyze WPF UI hierarchies in real-time

> **📢 Latest Updates:** See [RELEASE_NOTES.md](RELEASE_NOTES.md) for recent improvements including screenshot capture, DLL auto-injection, AdornerLayer/Popup traversal, and IPC deadlock fixes.

## 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
- **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.

## Quick Start

### 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: Download Release (Recommended)

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 at `server\WpfVisualTreeMcp.Server.exe`

#### Option 2: Build from Source

```bash
git clone https://github.com/faze79/WpfVisualTreeMcp.git
cd WpfVisualTreeMcp
dotnet build -c Release
```

#### Option 3: .NET Tool (Coming Soon)

```bash
dotnet tool install -g WpfVisualTreeMcp
```

### Configuration

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

#### Claude Code

**Option 1: Command Line (Recommended)**

Use the `claude mcp add` command to add the server directly:

```bash
# Add to current project only
claude mcp add wpf-visual-tree -- C:/path/to/WpfVisualTreeMcp/publish/WpfVisualTreeMcp.Server.exe

# Add globally (available in all projects)
claude mcp add --scope user wpf-visual-tree -- C:/path/to/WpfVisualTreeMcp/publish/WpfVisualTreeMcp.Server.exe
```

You can verify the server was added:
```bash
claude mcp list
```

**Option 2: Project-level JSON Configuration**

Create or edit `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "wpf-visual-tree": {
      "command": "C:/path/to/WpfVisualTreeMcp/publish/WpfVisualTreeMcp.Server.exe",
      "args": []
    }
  }
}
```

**Option 3: Global JSON Configuration**

Add to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "wpf-visual-tree": {
      "command": "C:/path/to/WpfVisualTreeMcp/publish/WpfVisualTreeMcp.Server.exe",
      "args": []
    }
  }
}
```

**Important Notes:**
- Use absolute paths to the built `.exe` file
- Use forward slashes (`/`) in paths on Windows
- Build in Release mode for production: `dotnet build -c Release`
- Restart Claude Code after configuration changes

#### Cursor

Add to your Cursor settings (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "wpf-visual-tree": {
      "command": "C:/path/to/WpfVisualTreeMcp/publish/WpfVisualTreeMcp.Server.exe",
      "args": []
    }
  }
}
```

### Self-Hosted Mode (Recommended)

For your WPF application to be inspectable, add a reference to the Inspector DLL and initialize it on startup:

1. Add a project reference to `WpfVisualTreeMcp.Inspector`

2. In your `App.xaml.cs`:

```csharp
using System.Diagnostics;
using System.Windows;
using WpfVisualTreeMcp.Inspector;

public partial class App : Application
{
    protected override void OnStartup(StartupEventArgs e)
    {
        base.OnStartup(e);

        // Initialize the WPF Visual Tree Inspector
        InspectorService.Initialize(Process.GetCurrentProcess().Id);
    }

    protected override void OnExit(ExitEventArgs e)
    {
        InspectorService.Instance?.Dispose();
        base.OnExit(e);
    }
}
```

This enables the MCP server to connect to your application via named pipes for real-time inspection.

## Usage Examples

### List Running WPF Applications

```
Use the wpf_list_processes tool to show all running WPF applications.
```

### Attach and Inspect Visual Tree

```
Attach to the MyApp.exe WPF application and show me the visual tree of the main window.
```

### Find Binding Errors

```
Check the attached WPF application for any binding errors and explain what's causing them.
```

### Search for Elements

```
Find all Button elements in the visual tree that have IsEnabled set to false.
```

### Export Visual Tree

```
Export the visual tree of the current window to JSON format so I can analyze the structure.
```

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    AI Agent (Claude Code)                    │
└─────────────────────────┬───────────────────────────────────┘
                          │ MCP Protocol (stdio)
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                 WpfVisualTreeMcp Server                      │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐  │
│  │   MCP Handler   │  │  Tree Navigator │  │   Injector  │  │
│  │  (Tools/Res.)   │  │   & Inspector   │  │   Manager   │  │
│  └────────┬────────┘  └────────┬────────┘  └──────┬──────┘  │
└───────────┼────────────────────┼───────────────────┼────────┘
            │                    │                   │
            └────────────────────┼───────────────────┘
                                 │ Named Pipes / IPC
                                 ▼
┌─────────────────────────────────────────────────────────────┐
│                   Target WPF Application                     │
│  ┌─────────────────────────────────────────────────────────┐│
│  │              Injected Inspector DLL                      ││
│  │  • VisualTreeHelper access                              ││
│  │  • LogicalTreeHelper access                             ││
│  │  • Property/Binding inspection                          ││
│  │  • Resource dictionary enumeration                      ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
```

For detailed architecture documentation, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).

## Available Tools

| Tool | Description |
|------|-------------|
| `wpf_list_processes` | List all running WPF applications |
| `wpf_attach` | Attach to a WPF application (supports `auto_inject` for DLL injection) |
| `wpf_get_visual_tree` | Get the visual tree hierarchy (default depth: 25, max: 100) |
| `wpf_get_element_properties` | Get all dependency properties of an element |
| `wpf_find_elements` | Search for elements by type or name (partial matching) |
| `wpf_find_elements_deep` | Deep search across all windows including adorners/popups |
| `wpf_capture_screenshot` | Capture a screenshot of the window or element (returns image) |
| `wpf_get_bindings` | Get data bindings for an element (includes MultiBinding, converter, StringFormat) |
| `wpf_get_binding_errors` | List all captured binding errors |
| `wpf_clear_binding_errors` | Clear the captured binding errors list |
| `wpf_get_data_context` | Get DataContext type, properties, INPC status, and inheritance chain |
| `wpf_get_resources` | Enumerate resource dictionaries |
| `wpf_get_styles` | Get applied styles and templates |
| `wpf_watch_property` | Monitor a property for changes |
| `wpf_highlight_element` | Visually highlight an element |
| `wpf_click_element` | **Click a control** — UI Automation invoke (`Invoke`/`Toggle`/`Select`/`ExpandCollapse`) by default, `physical=true` for a real OS mouse click. *State-changing.* |
| `wpf_set_text` | **Set text/value** of a TextBox/ComboBox/PasswordBox — UI Automation `IValueProvider.SetValue` by default, `physical=true` to type via OS keyboard input. *State-changing.* |
| `wpf_send_keys` | **Send a keyboard shortcut** (`Ctrl+S`, `Alt+F4`, `F5`, `Enter`, ...) to an element or the focused window. *State-changing.* |
| `wpf_get_layout_info` | Get layout information |
| `wpf_export_tree` | Export visual tree to XAML or JSON |

For complete tool documentation, see [docs/TOOLS_REFERENCE.md](docs/TOOLS_REFERENCE.md).

## Roadmap

### Phase 1: Core Inspection ✅
- [x] Project structure and architecture
- [x] Process discovery and enumeration
- [x] Basic process attachment
- [x] Visual tree navigation
- [x] Property inspection
- [x] Element search

### Phase 2: Advanced Features ✅
- [x] IPC communication via named pipes
- [x] Binding analysis and error detection
- [x] Resource dictionary enumeration
- [x] Style and template inspection
- [x] Property change monitoring (with notifications)

### Phase 3: Interaction & Diagnostics ✅
- [x] Element highlighting overlay
- [x] XAML/JSON export
- [x] Screenshot capture (returns MCP `ImageContentBlock`)
- [x] DLL auto-injection into running WPF processes (x64/x86)
- [x] AdornerLayer and Popup visual tree traversal

### Phase 4: CLI + Driving the App ✅ *(v0.4.0 / v0.5.0)*
- [x] Dual-mode executable (MCP stdio + one-shot CLI) *(v0.4.0)*
- [x] Control click via UI Automation patterns *(v0.4.0)*
- [x] Physical OS mouse click as opt-in fallback *(v0.4.0)*
- [x] User-level Claude Code skill bundling the CLI *(v0.4.0)*
- [x] Set text/value via UI Automation `IValueProvider` + fallbacks *(v0.5.0)*
- [x] Physical keyboard typing with Unicode BMP support *(v0.5.0)*
- [x] Keyboard shortcuts (`Ctrl+S`, `Alt+F4`, `F5`, ...) via OS input *(v0.5.0)*

### Phase 5: Multi-architecture ✅ *(v0.6.0)*
- [x] Cross-bitness auto-injection (64-bit server → 32-bit target)
- [x] Architecture-matching `WpfInjectorHelper.exe` (32-bit .NET 8)
- [x] Removes v0.5.0 known limitation; both x86 and x64 WPF apps drivable

### Future Considerations
- [ ] Symmetric x64 helper for x86-server-to-x64-target injection
- [ ] Visual tree diff/comparison
- [ ] Performance diagnostics
- [ ] Visual tree modification capabilities

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

### Development Setup

1. Clone the repository:
   ```bash
   git clone https://github.com/faze79/WpfVisualTreeMcp.git
   cd WpfVisualTreeMcp
   ```

2. Open in Visual Studio 2022 or VS Code:
   ```bash
   code .
   # or
   start WpfVisualTreeMcp.sln
   ```

3. Build and run tests:
   ```bash
   dotnet build
   dotnet test
   ```

4. Run the sample WPF app for testing:
   ```bash
   dotnet run --project samples/SampleWpfApp
   ```

### Project Structure

```
WpfVisualTreeMcp/
├── src/
│   ├── WpfVisualTreeMcp.Server/        # MCP Server (.NET 8) - Uses official MCP SDK
│   │   ├── Program.cs                  # Server initialization with MCP SDK
│   │   ├── WpfTools.cs                 # 20 WPF tools (17 inspection + click/set-text/send-keys)
│   │   ├── Cli/CliRunner.cs            # One-shot CLI front-end (v0.4.0)
│   │   └── Services/                   # Process & IPC management
│   ├── WpfVisualTreeMcp.Inspector/     # Injected DLL (.NET Framework 4.8)
│   ├── WpfVisualTreeMcp.Injector/      # Managed injection logic (CreateRemoteThread; net48 + net8.0)
│   ├── WpfVisualTreeMcp.InjectorHelper/# x86 .NET 8 helper exe for cross-arch injection (v0.6.0)
│   ├── WpfVisualTreeMcp.Bootstrapper/  # Native C++ DLL for CLR hosting
│   └── WpfVisualTreeMcp.Shared/        # Shared models & IPC contracts
├── samples/
│   └── SampleWpfApp/                   # Test application
├── tests/
│   └── WpfVisualTreeMcp.Tests/         # Unit tests (48 tests)
├── publish/                            # Published server + native DLLs
│   └── native/{x64,x86}/              # Architecture-specific bootstrapper
└── docs/                               # Documentation
```

### Technical Details

- **MCP SDK**: Built with the [official C# MCP SDK](https://github.com/modelcontextprotocol/csharp-sdk) from Microsoft/Anthropic
- **Protocol**: JSON-RPC 2.0 over stdio transport
- **Target Framework**: .NET 8.0 (Server) / .NET Framework 4.8 + .NET 8.0-windows (Inspector, dual-target)
- **IPC**: Named Pipes for server-to-application communication
- **Tools**: 20 tools auto-discovered via `[McpServerTool]` attributes (17 read-only inspection + 3 state-changing: `wpf_click_element`, `wpf_set_text`, `wpf_send_keys`)
- **CLI**: same executable runs as one-shot CLI when given a subcommand (`Program.cs` routes via `CliRunner.IsCliCommand`)

## Acknowledgments

- Inspired by [Snoop WPF](https://github.com/snoopwpf/snoopwpf) - the original WPF spy utility
- Built on the [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic
- Thanks to the .NET and WPF community

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [faze79](https://github.com/faze79)
- **Source:** [faze79/WPFVisualTreeMcp](https://github.com/faze79/WPFVisualTreeMcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-faze79-wpfvisualtreemcp
- Seller: https://agentstack.voostack.com/s/faze79
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.