XamlMcp

# XamlMcp

<!-- mcp-name: io.github.trrahul/xamlmcp -->

[XamlMcp](https://www.rahultr.dev/xamlmcp/) is an open-source XAML MCP server and AI inspection
toolkit for Avalonia, WPF, WinUI 3, and .NET MAUI. It lets Claude Code, Codex, GitHub Copilot, and
other MCP clients inspect and drive a running application: walk the visual or logical tree, read
and write properties, inspect styles and resources, capture screenshots, send input, invoke
commands and automation patterns, and observe changes over an authenticated local transport.

See the [XamlMcp installation and configuration guide](https://www.rahultr.dev/xamlmcp/) for a
focused setup path across supported frameworks and AI clients.

The current release is `1.0.0-preview.2`. It supports Avalonia, modern .NET WPF,
self-contained unpackaged WinUI 3, and .NET MAUI on Windows and Android. Protocol version 1 is
stable. Native MAUI nodes, iOS, and Mac Catalyst are unsupported.

See the [framework feature and tool matrix](docs/framework-feature-matrix.md) for per-tool support
and capability limits. The [preview release guide](docs/preview-release.md) explains the package
roles, installation options, and verification commands.

## Packages

| Package | What it is |
|---|---|
| `XamlMcp.Avalonia` | In-process agent for Avalonia apps (net8.0, Avalonia 11.3.18+ and 12.x) |
| `XamlMcp.Wpf` | In-process agent for modern .NET WPF apps (net8.0-windows) |
| `XamlMcp.WinUI` | In-process agent for unpackaged WinUI 3 apps (Windows App SDK 2.3.1) |
| `XamlMcp.Maui` | Logical agent for .NET MAUI 10.0.80 (`net10.0`, Windows, and Android API 24+; screenshots require API 26+) |
| `XamlMcp.Windows.Input` | Shared guarded Win32 raw-input core used by Windows framework agents |
| `XamlMcp.Agent.Hosting` | Framework-neutral desktop discovery, authentication, and named-pipe host |
| `XamlMcp.Protocol` | Shared JSON-RPC contract — DTOs and framing; no UI-framework dependency |
| `XamlMcp.Server` | Stdio MCP server: a `dotnet tool` named `xamlmcp` that connects AI clients to running agents |

## Install

Prerequisite: the app you inspect can target .NET 8 or later, but the `xamlmcp` tool (and
building this repo or the sample from source) needs the **.NET 10 SDK/runtime**.

Add the agent package for your UI framework:

```
dotnet add package XamlMcp.Avalonia --version 1.0.0-preview.2
dotnet add package XamlMcp.Wpf --version 1.0.0-preview.2
dotnet add package XamlMcp.WinUI --version 1.0.0-preview.2
dotnet add package XamlMcp.Maui --version 1.0.0-preview.2
```

The agent's floor is **Avalonia 11.3.18**. If your project pins older references (the
current `avalonia.app` template pins 11.3.0) restore fails with a NU1605 package-downgrade
error — bump your `Avalonia.*` package references to at least 11.3.18.

Install the MCP server tool:

```
dotnet tool install --global XamlMcp.Server --version 1.0.0-preview.2
```

You can also run the server without a global installation:

```
dnx XamlMcp.Server@1.0.0-preview.2
```

## Attach the Avalonia agent

Two entry points provide explicit diagnostic opt-in. Nothing listens unless you enable the agent
per build (option B) or per launch (option A):

```csharp
using XamlMcp.Avalonia;

// Option A - fluent, in BuildAvaloniaApp. Compiled in, but INERT unless the
// XAML_MCP=1 environment variable is set when the app launches.
public static AppBuilder BuildAvaloniaApp()
    => AppBuilder.Configure<App>()
        .UsePlatformDetect()
        .AttachXamlMcp();

// Option B - on the Application instance (e.g. in OnFrameworkInitializationCompleted).
// Marked [Conditional("DEBUG")]: the CALL SITE disappears from YOUR Release builds.
public override void OnFrameworkInitializationCompleted()
{
    this.AttachXamlMcp();
    base.OnFrameworkInitializationCompleted();
}
```

Why two shapes? `[Conditional]` requires a `void` method, so the fluent `AppBuilder`
overload can't use it and gates on the environment variable instead. And why not a plain
`#if DEBUG` inside the package? That would gate on how *this package* was compiled at pack
time and could never see *your* app's configuration at all. Both overloads instead gate
on your build configuration or your launch environment.

Know the difference: option B's call is **gone** from your Release binaries; option A's
code ships in Release but stays inert unless `XAML_MCP=1` is present at launch — anyone
who controls the launch environment can enable it. If you need hard exclusion with the
fluent shape, wrap the `.AttachXamlMcp()` line in your own `#if DEBUG`.

## Attach the WPF agent

Call the extension on the WPF `Application` in `OnStartup`:

```csharp
using System.Windows;
using XamlMcp.Wpf;

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

The WPF method is `[Conditional("DEBUG")]`, so the call site disappears from the consuming app's
Release build. There is no environment-enabled WPF overload. The agent uses the
`Application.Dispatcher` that performs attachment. Windows and controls owned by secondary WPF UI
threads are excluded.

## Attach the WinUI agent

Attach on the WinUI UI thread, explicitly register each `Window`, and keep the calls inside the
application's diagnostic build gate:

```csharp
using Microsoft.UI.Xaml;
using XamlMcp.WinUI;

public partial class App : Application
{
    private WinUiXamlMcpSession? _xamlMcp;
    private IDisposable? _windowRegistration;

    protected override void OnLaunched(LaunchActivatedEventArgs args)
    {
        var window = new MainWindow();
#if DEBUG
        var session = WinUiXamlMcp.Attach();
        _xamlMcp = session;
        _windowRegistration = session.RegisterWindow(window);
        window.Closed += async (_, _) =>
        {
            _windowRegistration?.Dispose();
            await session.DisposeAsync();
        };
#endif
        window.Activate();
    }
}
```

`Attach()` is not conditionally compiled: the caller owns the `#if DEBUG` or equivalent diagnostic
gate. One session supports one `DispatcherQueue` and explicitly registered windows on that queue.
The supported floor is Windows App SDK 2.3.1, target framework
`net8.0-windows10.0.19041.0`, Windows 10 1809 (`10.0.17763.0`), and `win-x64`.

WinUI support is unpackaged. Use `WindowsPackageType=None`,
`WindowsAppSDKSelfContained=true`, and publish to a fresh directory:

```powershell
dotnet publish MyWinUiApp.csproj -c Release -r win-x64 --self-contained true -o artifacts/winui
```

The publish output must retain the generated `.xbf` and `.pri` resources. MSIX/package identity,
certificates, Store distribution, XAML Islands, and multiple UI threads are unsupported.

## Attach the .NET MAUI agent

Call `UseXamlMcp()` while building the MAUI app, inside the application's diagnostic build gate:

```csharp
using XamlMcp.Maui;

public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder()
        .UseMauiApp<App>();

#if DEBUG
    builder.UseXamlMcp();
#endif

    return builder.Build();
}
```

The same package and `UseXamlMcp()` call work in unpackaged Windows applications and debuggable
Android applications on MAUI 10.0.80. The package does not inspect the consumer's configuration,
so the caller must own the `#if DEBUG` or equivalent diagnostic gate. Android projects must set
`SupportedOSPlatformVersion` to `24.0` or later. Screenshots require API 26 or later.

On Windows, the agent writes a discovery file under `%LOCALAPPDATA%/XamlMcp/instances/`
(override the directory with `XAML_MCP_DIR`) and serves JSON-RPC 2.0 on a current-user named pipe.
On Android, it listens only on device loopback and stores a per-launch descriptor in app-private
storage. The server reads that descriptor through debuggable `run-as` access and creates an owned
`adb forward` only while connecting. Both transports require the per-launch token before any
inspection call.

To discover an Android app, pass its application ID to the MCP server. Select a device explicitly
when more than one authorized device is online:

```powershell
claude mcp add xamlmcp -- xamlmcp --android-package dev.example.app --android-device emulator-5554
```

The Windows build prerequisites are the .NET 10 SDK and MAUI Windows workload. Android also
requires the .NET Android workload and Android SDK platform tools (`adb`). iOS and Mac Catalyst
are unsupported.

## Connect an AI client

XamlMcp is a local stdio MCP server. Claude Code or Codex starts it when the client session needs
it; you do not run a persistent server process.

This repository includes portable project configuration for both clients:

- [`.mcp.json`](.mcp.json) configures Claude Code.
- [`.codex/config.toml`](.codex/config.toml) configures Codex in a trusted checkout.

Both configurations run the pinned preview directly from NuGet with `dnx`, so they require the
.NET 10 SDK but no global tool installation. After cloning the repository, open a new client
session and verify the registration:

```powershell
claude mcp get xamlmcp
codex mcp get xamlmcp
```

To register the pinned preview for your user account or from another project, run:

```powershell
claude mcp add --scope user xamlmcp -- dnx XamlMcp.Server@1.0.0-preview.2
codex mcp add xamlmcp -- dnx XamlMcp.Server@1.0.0-preview.2
```

Alternatively, install the tool globally and register its `xamlmcp` command:

```powershell
dotnet tool install --global XamlMcp.Server --version 1.0.0-preview.2
claude mcp add --scope user xamlmcp -- xamlmcp
codex mcp add xamlmcp -- xamlmcp
```

If a client already has a server named `xamlmcp`, remove or update that entry before adding the
new one. Use `claude mcp remove xamlmcp --scope <local|user|project>` or
`codex mcp remove xamlmcp` as appropriate.

Launch an instrumented application next. Set `XAML_MCP=1` when using Avalonia's fluent attachment
form. Then ask the client to call **`list-apps`** → **`attach(instanceId)`** → any tool below.
Integer PID attach remains