<!-- mcp-name: io.github.chrispulman/uiinspect-mcp -->

UIInspect MCP Server

UIInspect.MCP.Server is a consent-gated NuGet MCP server that gives AI agents semantic access to Windows applications through UI Automation 3 (UIA3). It discovers accessible application windows, returns bounded control trees, and performs deterministic actions against opaque element references instead of relying on screenshots or pixel coordinates.

The package runs as a local stdio server on .NET 10. WPF, WinForms, WinUI 3, Avalonia, and .NET MAUI Windows are directly tested against deterministic UI Automation fixtures.

Quick Install

Once the package is available on NuGet.org, click to install it in your preferred environment:

Note:

• These install links use the NuGet package identity UIInspect.MCP.Server and select the latest 0.* prerelease.
• The selected package must be available on NuGet.org. For an unpublished local build, expose the package directory as a NuGet feed and add --source <feed-path> to the dnx arguments.
• UIInspect is Windows-only and requires an interactive desktop.

Manual MCP configuration using NuGet:

{
  "mcpServers": {
    "uiinspect-mcp": {
      "type": "stdio",
      "command": "dnx",
      "args": [
        "UIInspect.MCP.Server@0.2.1-alpha.0.1",
        "--prerelease",
        "--yes"
      ]
    }
  }
}

Some clients use servers instead of mcpServers; only the outer property name changes.

The NUKE build stamps every literal UIInspect.MCP.Server package coordinate in this README with the MinVer package version before packaging:

dnx UIInspect.MCP.Server@0.2.1-alpha.0.1 --yes

Codex Skill

The package includes the uiinspect Codex skill and its MCP dependency metadata. When the packaged server starts, it installs missing skill files into an existing Codex home: CODEX_HOME when it is set and exists, otherwise %USERPROFILE%\.codex when that directory exists. Automatic installation never overwrites existing skill files.

Install the skill explicitly and create the Codex home when needed. This command installs the skill and exits without starting the MCP server:

dnx UIInspect.MCP.Server@0.2.1-alpha.0.1 --yes -- --install-codex-skill

To deliberately replace an existing installed copy with the packaged version:

dnx UIInspect.MCP.Server@0.2.1-alpha.0.1 --yes -- --install-codex-skill --force

Set CODEX_HOME before either command when Codex uses a non-default location. The skill is installed at <Codex home>\skills\uiinspect.

Invoke the installed skill with a request such as:

Use $uiinspect to inspect and safely operate the target Windows application.

Requirements

• Windows 10 or Windows 11 with an interactive desktop.
• A .NET 10 SDK that provides dnx.
• UIInspect must run in the same Windows logon session as the target application.
• UIInspect must run at a sufficient integrity level for the target. A non-elevated server cannot automate an elevated application.

The MCP protocol owns stdout; server diagnostics are written to stderr.

What the package provides

• Top-level window discovery with process-instance identity and native window handles.
• A trusted, server-owned Windows approval dialog shown at most once per client and exact target process instance during one server session, with a bounded timeout that closes stale prompts.
• Optional 1, 2, 5, 8, 12, or 24 hour unattended approval shared safely by concurrent UIInspect server processes in the current Windows user/session.
• Attach by process ID with an optional native window handle.
• Bounded, flattened UI Automation control-tree snapshots.
• Opaque, generation-scoped element references with explanatory semantic paths.
• Invoke, resolved click, ValuePattern set, SelectionItemPattern select, expand/collapse, and allowlisted logical-key actions.
• Password-element redaction and no control-value collection during inspection.
• Consent bound to the local stdio server instance or a trusted Windows-session approval broker, with expiry and PID-reuse checks, rate limits, application-level append-only redacted JSONL auditing, and deterministic session cleanup.

The current package deliberately does not provide XAML source or visual trees, dependency properties, bindings, validation, DataContext or command diagnostics, hot reload, screenshots, OCR, overlays, recording/replay, arbitrary reflection, shell execution, generic property writes, or TCP transport.

Consent and security

UIInspect never treats an agent name or ordinary MCP request as user approval. Stdio client metadata is self-asserted and cannot prove that the caller is Codex, Claude Code, or another trusted agent, so UIInspect does not provide an agent-name bypass. In normal mode, the local user approves the exact process instance and requested capabilities in a trusted Windows dialog before the server attaches. Repeated and concurrent requests reuse that server-session decision without opening another dialog. A denial is terminal for that client and process instance until the server restarts, and later capability expansion is denied rather than silently approved or prompted again.

Inspection, interaction, and keyboard access are separate capabilities. Request only the minimum needed for the task. Grants are short-lived and bound to the local stdio server principal, exact process identity, Windows session, and approved capabilities. Tool parameters cannot supply or override that principal.

For unattended tests and multiple agent sessions, activate one fixed-duration approval from a trusted interactive terminal:

uiinspect-mcp --authorize-unattended 8
uiinspect-mcp --unattended-status
uiinspect-mcp --revoke-unattended

Replace 8 with exactly 1, 2, 5, 8, 12, or 24. When invoking the NuGet package directly, append manager arguments to the existing dnx command after --, for example -- --authorize-unattended 8.

The trusted dialog clearly approves all local UIInspect clients in the current Windows user and interactive session for Inspect, Interact, and Keyboard. The broker keeps the lease only in memory, serves concurrent agent sessions through current-user-only named pipes, and stops at expiry, revocation, process exit, logoff, or reboot. Each agent calls uiinspect_get_unattended_approval, then follows the normal consent and attach workflow; uiinspect_request_consent exchanges the broker lease for an exact-process grant without another dialog. Activation and extension are deliberately not MCP tools.

Successful actions invalidate all current element references. Re-inspect before the next action so the server can semantically resolve the current UI rather than act on stale coordinates.

The default audit file is:

%LOCALAPPDATA%\UIInspect.MCP\audit\actions.jsonl

Set UIINSPECT_AUDIT_PATH for the MCP server process to use another location. Audit records exclude entered values, password content, clipboard data, screenshots, raw provider exceptions, and all keystrokes except the allowlisted logical key name. Appends are enforced at the application level; protect the audit directory with an ACL that grants access only to the server account and administrators.

See the complete security model for consent scopes, rate limits, audit contents, integrity boundaries, and the threat model.

MCP tools

| Tool | Purpose | Required access | |---|---|---| | uiinspect_discover_windows | List top-level UI Automation windows | Discovery | | uiinspect_get_unattended_approval | Report the current user/session approval window | Discovery | | uiinspect_request_consent | Show the trusted local approval dialog once per exact target and server session | Local user decision | | uiinspect_attach | Open an opaque session for a PID and optional HWND | Inspect | | uiinspect_inspect_tree | Return a bounded semantic snapshot | Inspect | | uiinspect_invoke | Use InvokePattern | Interact | | uiinspect_click | Click a semantically resolved element | Interact | | uiinspect_set_value | Set a value through ValuePattern | Interact | | uiinspect_set_text | Set text through ValuePattern | Interact | | uiinspect_select_item | Use SelectionItemPattern | Interact | | uiinspect_expand_collapse | Use ExpandCollapsePattern | Interact | | uiinspect_send_key | Send one allowlisted logical key after focus | Keyboard | | uiinspect_close_session | Dispose an attached session | Session owner |

Recommended workflow

1. Call uiinspect_get_unattended_approval when an unattended window is expected, then call uiinspect_discover_windows.
2. Identify the intended process and window using independently known application context.
3. Call uiinspect_request_consent once with every capability required for the session. An active broker lease avoids a per-target dialog; otherwise the local user must approve the exact process instance. Repeats reuse the decision and cannot expand it.
4. Call uiinspect_attach.
5. Call uiinspect_inspect_tree with the smallest useful depth and node budget.
6. Select an element using its automation ID, control type, accessible name, patterns, and semantic path.
7. Prefer uiinspect_invoke, uiinspect_set_value (or its uiinspect_set_text alias), uiinspect_select_item, or uiinspect_expand_collapse. Use uiinspect_click only when the provider does not expose InvokePattern, and use uiinspect_send_key only when keyboard consent was granted.
8. Re-inspect after every successful action to obtain fresh element references.
9. Call uiinspect_close_session.

Recovery behavior

• On stale_element, inspect again and use a newly returned element reference.
• On unattended_approval_inactive, ask the user to activate a window from a trusted terminal or continue with the ordinary per-target prompt. Do not loop on the status tool.
• On consent_expired, call uiinspect_get_unattended_approval when unattended operation is expected, then call uiinspect_request_consent, uiinspect_attach, and uiinspect_inspect_tree. A still-active broker lease or retained explicit decision renews the exact-process grant without another dialog.
• On session_not_found, attach again when consent remains active; otherwise request consent, attach, and inspect.
• On target_changed or target_unavailable, rediscover the target; a new exact process identity requires its own consent decision.
• On rate_limited, wait for retryAfterMilliseconds before retrying.
• Treat consent_denied as terminal for that client, target, and server process. Do not retry in a loop.
• Treat