Skip to content

api-reference.md

Latest commit

 

History

History
369 lines (265 loc) · 11.3 KB

api-reference.md

File metadata and controls

369 lines (265 loc) · 11.3 KB
Raw

API Reference — 44 MCP Tools

Connection Tools (6)

connect

Connect to a running WPF application by process name, PID, or launch a new instance.

Parameter Type Default Description
processName string? null Process name (without .exe)
pid int? null Process ID
exePath string? null Path to executable to launch
arguments string? null Arguments when launching
timeoutSeconds int 15 Timeout for main window to appear

Returns: ConnectionInfo JSON (processName, processId, windowTitle, dimensions)

disconnect

Disconnect from the currently attached application without closing it.

Returns: "Disconnected from 'AppName'."

get_status

Check the current connection status.

Returns: "Connected to: AppName (PID: 12345)" or "Not connected to any application."

get_windows

List all top-level windows of the connected application.

Returns: JSON array of WindowInfo (title, automationId, dimensions, isEnabled)

focus_window

Switch focus to a specific window by title (partial match).

Parameter Type Default Description
title string? null Partial window title; omit for main window

set_window_state

Change a window's state. Restores the window before activating it.

Parameter Type Default Description
state string — restore, normal, maximize, minimize, hide, show
title string? null Partial window title; omit for main window

Useful before screenshot, whose BitBlt fallback needs a non-minimized window.

Inspection Tools (4)

get_visual_tree

Get UI Automation visual tree in hierarchical text format.

Parameter Type Default Description
maxDepth int 4 Max depth to traverse
rootAutomationId string? null AutomationId of root element to scope the dump

Output format:

Window [id=mainWindow] "Title"
  Button [id=btn1] "Click Me" <button>
  Edit [id=nameField] "Name" <text-box> = "John"
  CheckBox [id=chk1] "Active" = On
  Text "Status" (disabled)

Annotations: (disabled), (offscreen), <helpText>, {itemStatus}, = "value"

find_elements

Search for UI elements matching criteria.

Parameter Type Default Description
controlType string? null Control type filter (Button, Edit, etc.)
nameContains string? null Name substring filter (case-insensitive)
interactableOnly bool false Only return enabled, visible elements

Returns: JSON array of ElementInfo (max 100 results)

get_page_summary

Quick summary of active page: window title, tabs, elements by type, validation errors.

Parameter Type Default Description
scopeAutomationId string? null Scope to container AutomationId

get_element_info

Get detailed information about a specific element including bounds and supported patterns.

Parameter Type Default Description
automationId string required AutomationId of the element

Interaction Tools (12)

click

Click a UI element using UIA Invoke pattern (background-safe).

Parameter Type Default Description
automationId string? null AutomationId
name string? null Element name
controlType string? null Control type filter

Fallback chain: InvokePattern -> TogglePattern -> ExpandCollapsePattern -> SelectionItemPattern -> Focus+Enter

fill_field

Enter text into a text field, clearing existing content.

Parameter Type Default Description
text string required Text to enter
automationId string? null AutomationId
name string? null Element name

select_item

Select an item in ComboBox or ListBox by text or index.

Parameter Type Default Description
automationId string? null AutomationId
name string? null Element name
itemText string? null Item text to select
index int? null Item index to select

toggle

Toggle CheckBox or ToggleButton.

Parameter Type Default Description
automationId string? null AutomationId
name string? null Element name
setChecked bool? null Specific state; null = toggle

right_click

Right-click element to open context menu (foreground operation).

double_click

Double-click element.

focus

Set keyboard focus to element without clicking.

expand_collapse

Expand or collapse element supporting ExpandCollapse pattern.

Parameter Type Default Description
automationId string? null AutomationId
name string? null Element name
action string "expand" "expand" or "collapse"

scroll

Scroll within scrollable container.

Parameter Type Default Description
automationId string? null AutomationId
name string? null Element name
horizontal string "none" "left", "right", or "none"
vertical string "down" "up", "down", or "none"

fill_form

Fill multiple form fields in one call.

Parameter Type Default Description
fields string required JSON: {"automationId": "value", ...}

Example: fill_form(fields: '{"firstName": "Ahmed", "email": "ahmed@test.com"}')

navigate_to

Navigate to sidebar page: focus nav item, press Enter, wait for tab, return summary.

Parameter Type Default Description
sidebarKey string required Sidebar key (e.g., "approvals/inbox")
timeoutMs int 10000 Timeout for tab to appear

hover

Move mouse cursor over element (foreground operation).

Keyboard Tools (2)

send_keys

Send keyboard input: text or special key.

Parameter Type Default Description
keys string required Text or special key name
automationId string? null Target element (optional)
name string? null Target name (optional)

Special keys: ENTER, TAB, ESCAPE, BACKSPACE, DELETE, SPACE, UP, DOWN, LEFT, RIGHT, HOME, END, PAGEUP, PAGEDOWN, F1-F12

send_shortcut

Send keyboard shortcut (e.g., "Ctrl+S").

Parameter Type Default Description
shortcut string required "+" separated keys (e.g., "Ctrl+Shift+N")
automationId string? null Target element (optional)
name string? null Target name (optional)

Reading Tools (7)

read_value

Read current value of a UI element.

read_all_fields

Read all input fields (Edit, ComboBox, CheckBox, RadioButton) on current page.

Parameter Type Default Description
scopeAutomationId string? null Scope to container

get_focused_element

Get information about the currently focused element.

read_table

Read DataGrid/Table as structured data with headers and rows.

Parameter Type Default Description
automationId string required AutomationId of the DataGrid
maxRows int 20 Maximum rows to read

read_list_items

Read all items from List or ComboBox with selection state.

assert_state

Assert state of multiple elements in one call.

Parameter Type Default Description
assertions string required JSON object (see below)

Format:

{
  "loginBtn": {"enabled": true},
  "nameField": {"value": "admin"},
  "oldDialog": {"exists": false},
  "activeChk": {"checked": true},
  "statusText": {"contains": "Ready"}
}

Available checks: exists (bool), enabled (bool), value (exact match), checked (bool), contains (substring)

Returns: Pass/fail report with counts.

read_validation_errors

Scan fields for validation errors (ItemStatus = "error: ...").

Wait Tools (5)

wait_for_element

Wait for a UI element to appear and become visible.

Parameter Type Default Description
automationId string? null AutomationId
name string? null Element name
controlType string? null Control type
timeoutMs int 10000 Timeout
pollIntervalMs int 250 Poll interval

wait_until_gone

Wait for a UI element to disappear.

click_and_wait

Atomic click + wait for another element (for navigation flows).

Parameter Type Default Description
clickAutomationId string? null Element to click
clickName string? null Name of element to click
waitAutomationId string? null Element to wait for
waitName string? null Name to wait for
waitControlType string? null Control type to wait for
timeoutMs int 10000 Timeout

wait_for_enabled

Wait for an element to become enabled (e.g., submit button after form fill).

wait_for_value

Wait for an element's value to match expected string (e.g., cascading dropdown update).

Screenshot Tools (3)

screenshot

Capture the connected application window to PNG file.

Parameter Type Default Description
outputPath string? null Output path (auto-generated if omitted)

screenshot_element

Capture a specific element to PNG file.

Parameter Type Default Description
automationId string required Element to capture
outputPath string? null Output path

screenshot_and_inspect

Take screenshot and return visual tree dump together.

Recording Tools (5)

record_start

Begin recording a test script.

Parameter Type Default Description
name string required Script name (used as filename)
description string? null Optional description

record_step

Manually record a tool invocation step.

Parameter Type Default Description
toolName string required Tool name
parameters string? null Parameters as JSON
result string? null Result string

record_stop

Stop recording and save the script to disk as JSON.

replay

Replay a recorded test script with pass/fail reporting.

Parameter Type Default Description
name string required Script name
stopOnFailure bool true Stop on first failure

list_recordings

List all available recording scripts with metadata.

Error Format

All tools return errors in this format:

Error: Human-readable error message.
Suggestion: Optional recovery hint.

Error categories: NotConnected, ProcessNotFound, WindowTimeout, ElementNotFound, PatternNotSupported, Timeout, InvalidArgument, WindowMinimized, and more (see ProbeErrorCode enum).