Declarative.Avalonia.AgentTools 12.1.1

Declarative.Avalonia.AgentTools

In-process MCP (Model Context Protocol) inspector for AI agents that build UI with Avalonia.Markup.Declarative.

In a debug build it exposes the running app to an agent over loopback so the agent can close the feedback loop while iterating on a view:

• get_app_info — windows, focus, popups, theme, versions, hot-reload/interaction state (call first)
• get_visual_tree — text visual tree with names, local bounds and absolute abs=/center= client-DIP coords (the frame click_at/tap/drag/hit_test share); maxDepth/filter to trim; open popups included
• get_layout — detailed layout for one control: bounds, window-relative position, requested vs actual size, alignment, margin/padding, visibility, off-screen/clipped flags, and the ancestor chain
• get_properties — effective state + every locally-set styled property
• get_property_sources — where each value came from (local / style / template / animation / inherited)
• get_data_context — the control's view-model rendered as text (debug bindings)
• get_source — the ViewBase component that built a control (which class to edit); optional file:line
• find_text / hit_test — locate controls by visible text or by pixel coordinate (hit_test also reports how the control can be driven: automation-invokable / focusable / raw-pointer-only)
• layout_audit — automated layout lint (zero-size, off-screen, overlap, out-of-parent, text-clipped)
• list_components — active declarative views
• screenshot_window (with annotate) / screenshot_control / screenshot_region — PNG screenshots (image content blocks); scale enlarges with nearest-neighbour so pixel art stays crisp, maxWidth caps the payload, and screenshot_region crops an arbitrary rectangle — the way to look inside a custom canvas that the visual tree sees as one opaque control
• compare_screenshots / list_screenshots — before/after pixel diff (red diff image + % changed)
• highlight — draw a frame around a control (or all of a type) and screenshot it; action='clear' clears
• wait_for / wait_idle — sync after an interaction or hot reload
• get_errors — recent build / binding / converter / runtime errors (incl. exceptions in handlers)
• get_logs — the app's raw log output (Avalonia's Logger and stdout/stderr) from an in-process ring buffer, so you can read what the app printed even when the developer, not you, started the process
• get_render_stats — measured fps, last layout pass count/duration, visual count, size and scaling: catch a performance regression without a profiler
• tap, drag, pointer_press/pointer_move/pointer_release, pointer_wheel, touch_press/touch_move/touch_release, pinch — (optional, off by default) real synthesized input through Avalonia's input pipeline: works on custom controls with hand-written pointer handlers and no automation peer (scrub a Border slider, move a thumb, draw). Includes genuine double clicks (tap count=2 really produces ClickCount == 2), wheel/touchpad deltas in notches, pen pressure and the inverted eraser end, and multi-finger gestures
• invoke, set_window_size, set_theme, click_at, open_popup, list_bindable, set_view_model, invoke_command — (optional, off by default) remote control: invoke / select / select_item / toggle / set / expand / collapse / focus / scroll / scroll_by / context_menu / key / type (key/type send real input), plus resize, theme switch, pointer-first click-by-coordinate, open a closed popup, list a DataContext's bindable surface, and an escape hatch to set a view-model property or run an ICommand/method directly (structured, actionable errors; reach awkward states without restarting)
• your own tools — register app-specific tools so the agent can reach what the generic ones cannot (see below)

Usage

var appBuilder = AppBuilder.Configure<App>()
    .UsePlatformDetect()
#if DEBUG
    .UseAgentInspector() // loopback MCP server on 127.0.0.1:5599
#endif
    .SetupWithLifetime(lifetime);

Your own tools

To the inspector, a custom drawing surface is one opaque Control filling the window — the scene, layers and pixels inside it are reachable only through tools your app writes. Register them with WithTools<T>(); instance methods run on a single instance built from your IServiceProvider, so a tool can take the app's real services in its constructor:

[McpServerToolType]
public sealed class SpriteTools(AppState state)
{
    [McpServerTool(Name = "get_sprite_info", ReadOnly = true), Description(
        "Returns the open sprite's size, frame count and the selected layer.")]
    public string GetSpriteInfo() => $"{state.Sprite.Size}, {state.Sprite.Frames.Count} frame(s)";
}

.UseAgentInspector(o =>
{
    o.EnableInteraction = true;
    o.Services = serviceProvider;
    o.WithTools<SpriteTools>();
})

Mark a state-changing tool type [AgentInteractionTools] and it is registered only when EnableInteraction is set, leaving your read-only tools available either way.

Enable the MCP in your agent

The server speaks streamable HTTP on loopback, so any MCP client points at the same endpoint — http://127.0.0.1:5599. Run the app under dotnet watch so the agent's edits hot-reload into the live process it is inspecting.

Claude Code — one command (or a project-scoped .mcp.json):

claude mcp add --transport http avalonia-agent-inspector http://127.0.0.1:5599

// .mcp.json  (project root)
{
  "mcpServers": {
    "avalonia-agent-inspector": {
      "type": "http",
      "url": "http://127.0.0.1:5599"
    }
  }
}

opencode — add it under mcp in opencode.json with type: "remote":

// opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "avalonia-agent-inspector": {
      "type": "remote",
      "url": "http://127.0.0.1:5599",
      "enabled": true
    }
  }
}

Codex — add an [mcp_servers.*] table to ~/.codex/config.toml (or the project's .codex/config.toml):

# ~/.codex/config.toml
[mcp_servers.avalonia-agent-inspector]
url = "http://127.0.0.1:5599"

# First time you use a streamable-HTTP MCP with Codex, enable the RMCP client once:
[features]
experimental_use_rmcp_client = true

Show a live "agent connected" status in your UI (like Chrome DevTools) by subscribing to AgentConnectionMonitor — events are raised on the UI thread:

#if DEBUG
AgentConnectionMonitor.StatusChanged += (_, e) =>
    window.Title = e.IsConnected ? "🟢 Agent connected — My App" : "My App";
#endif

Dev only. Keep the call under #if DEBUG. This package pulls in the ASP.NET Core web stack and a remote-control surface; it must not ship in Release. The server binds to loopback only, and the tier-2 tools (invoke, set_window_size, set_theme, click_at, the pointer/wheel/touch synthesis tools, set_view_model, invoke_command) stay disabled unless you set EnableInteraction = true.

See the repository's docs/agent-tools.md for the full guide.