Interaction, Event, Layout, and Performance Tools

Interaction

  • click_element
  • drag_and_drop
  • scroll_to_element
  • simulate_keyboard
  • element_screenshot
  • get_focus_state
  • focus_element

get_focus_state and focus_element matter whenever keyboard input, default buttons, tab navigation, or multiple windows are involved.

For focus_element and simulate_keyboard, pick a visible, enabled, focusable control from the active rendered visual tree. If one real-project target returns ElementNotLoaded or cannot receive keyboard focus, use get_interaction_readiness or get_element_snapshot(elementId) after a concrete elementId is known and retry another loaded focusable candidate before calling the workflow limited.

element_screenshot defaults to outputMode: "metadata" and also supports "file" or "base64". Metadata responses include dimensions, format, rendered: false, byteLength: 0, and a nextSteps entry that repeats the call with outputMode: "file" when pixel evidence is required, without rendering PNG bytes. metadata mode does not return screenshotId, resourceUri, or a wpf://screenshots/{screenshotId} handle.

File and base64 responses render pixels, include rendered: true, dimensions, format, and byteLength. File mode returns screenshotId, resourceUri, an exact resourceRead request, fileName, expiresAtUtc, localPathRedacted: true, and sha256; base64 mode returns base64Image only for small inline PNG payloads. Use file mode for larger captures so clients receive a session-scoped resource handle instead of inline pixels. Do not pass outputPath; first call resourceRead.method with resourceRead.params once in the same MCP server session. resourceRead.chunking.fallbackOnly is true: only if the complete blob is unavailable or truncated, use sequential offsets from resourceRead.chunking.uriTemplate, keep each read within maxChunkBytes, concatenate the decoded byte ranges, and verify the result against byteLength and sha256.

Every successful response also identifies sourceWidth, sourceHeight, scaleFactor, and downscaled. Width limits are useful for compact evidence, but a response with downscaled: true is not authoritative typography or pixel evidence. Omit both limits and verify downscaled: false when judging text rendering or final visual fidelity.

For screenshot-resource lifecycle validation, use outputMode: "file" and then resources/read; metadata mode is intentionally a non-rendering shape/availability probe. File mode is an MCP server-owned retained screenshot resource. SessionManager supplies a per-process server-issued lease root, expires it after 24 hours, caps each MCP server session at 100 resources, deletes evicted or expired PNG files, and purges them when the target disconnects or the server session manager is disposed. This lifecycle is managed by SessionManager, not by the Inspector default screenshot cache.

State snapshot and sequential mutations

  • capture_state_snapshot
  • batch_mutate
  • restore_state_snapshot

These tools are registered under the State/Mutation category (see src/WpfDevTools.Mcp.Server/McpTools/StateMcpTools.cs and MutationBatchMcpTools.cs). They are listed together with interaction here because they are the preferred guard rails around destructive UI interactions.

capture_state_snapshot and restore_state_snapshot are the preferred guard rails before trying UI mutations that may need rollback.

Mutation success responses may include restoreRequired: true, restoreStatus: "notRestored", and restoreSuggestedAction. These fields mean the tool changed runtime state and the server has not restored it for you. If the app must be left unchanged, use get_state_diff when a snapshot is active, then call restore_state_snapshot after verification.

Use batch_mutate when you need an ordered sequence of live mutations inside one tool call. It is safer than improvising multiple destructive calls in a single agent turn because the server validates and executes the operations sequentially.

Interaction tool responses now also carry nextSteps and navigation. When the tool already recommends the follow-up, prefer that guidance over a fixed manual verification checklist.

Routed events

  • trace_routed_events
  • get_event_handlers
  • fire_routed_event
  • drain_events

fire_routed_event is useful for route analysis. It is not a universal substitute for real user input.

If you start a trace session with trace_routed_events(mode: "start") before the interaction, the usual next step is drain_events to read back the buffered event records explicitly. trace_routed_events(mode: "get") remains available for trace-session retrieval, but drain_events is the preferred shared-buffer read path when the session may also contain binding, dependency property, or validation events.

Start mode keeps a safe 30-second minimum by default. If effectiveDuration is higher than requestedDuration, the response nextSteps includes an exact trace_routed_events retry that preserves the original public durationMs and sets allowShortStartDuration=true. Use that retry only when the shorter window is intentional; otherwise keep the safer effective duration.

Use maxEvents on trace_routed_events(mode: "get") or capture-mode retrieval when you need to cap trace payload size. Trace responses include returnedEventCount, totalEventCount, eventsTruncated, and maxEvents so agents can detect that the events array is intentionally partial and retry with a larger cap only when needed.

Trace responses also surface cleanup state when trace teardown is delayed or recovered. Use cleanupState, cleanupFailed, and cleanupIncomplete together: deferredCompleted means an earlier cleanup problem recovered and the handlers were removed, while deferredPending, deferredFailed, or failed need more caution before starting another trace.

Some interaction and diagnostic responses may piggyback a compact pendingEvents array when buffered events are already available. Use drain_events when you need the complete explicit event read step instead of opportunistic piggyback data.

Layout

  • get_layout_info
  • highlight_element
  • get_clipping_info
  • invalidate_layout

get_clipping_info analyzes one concrete target and its visual ancestors, or up to 100 explicit targets through elementIds. It detects explicit Clip, ClipToBounds, WPF-generated layout clips, and Window client viewport overflow. The implicit Window boundary reports clippingSource="window-client-viewport"; results also include directional overflowAmount, the responsible clippingAncestors, and a generic suggestedFix. Batch results retain elementId correlation.

visibleContentImpact="not-determined" means the structural clip or overflow does not by itself prove visible pixel loss. Confirm affected content with focused descendant checks or a screenshot before changing layout.

geometricClippingSeverity reports none, partial, or full, and visibleRatio reports the remaining geometric area from 0 to 1. These fields prioritize viewport-facing checks; they do not identify whether meaningful pixels were lost. When the target is inside a ScrollViewer, nearestScrollContainer reports its extentWidth/viewportWidth, height equivalents, offsets, requested and computed scrollbar visibility, and hasVisibleScrollBarChrome. isTargetClippedByViewport=true means that viewer's content presenter is the target's primary clip and the viewer itself is visible; canBringTargetIntoView=true additionally proves every clipped axis is scrollable. Use this context to distinguish an intentional carousel peek from an accidental sliver or exposed scrollbar before editing the blueprint.

The tool does not implicitly aggregate every descendant of a container. When a caption or control looks cut off but has no name, use find_elements(query: "visible text") first and pass the returned IDs to get_clipping_info. diagnose_visibility uses the same effective clipping boundaries for partial and full visibility classification.

MVVM

  • get_viewmodel
  • get_commands
  • execute_command
  • modify_viewmodel
  • get_validation_errors

Performance

  • get_render_stats
  • find_binding_leaks
  • measure_element_render_time
  • get_visual_count

Render statistics bound the internal visual-count walk to 1000 nodes by default. Use visualCountLimit and visualCountTruncated to tell whether the reported render-stat visual count is complete or intentionally capped.

Safe usage pattern

  1. Inspect first.
  2. Call capture_state_snapshot before changing UI state.
  3. Use get_focus_state and focus_element before keyboard-sensitive actions.
  4. Interact once, or use batch_mutate for an ordered mutation sequence.
  5. Verify by following navigation.recommended or nextSteps from the interaction result.
  6. If the session has an active snapshot, get_state_diff is usually the first follow-up.
  7. If the session has buffered runtime events, drain_events is usually the first explicit follow-up.
  8. Use restore_state_snapshot if the workflow requires rollback or if you need to leave the app unchanged.
  9. Avoid stacking many independent mutations into one agent step unless batch_mutate is the intentional orchestration tool.