The MCP agent dry run plan nobody else talks about: one tool, zero events, one grep.

No, and you do not want one. The server ships six tools (open_application_and_traverse, click_and_traverse, type_and_traverse, press_key_and_traverse, scroll_and_traverse, refresh_traversal). Five of them are mutating. One of them, refresh_traversal, is pure read. The dry-run primitive is not a flag on the mutating tools; it is a separate tool. You call refresh_traversal to plan, and you call one of the other five to commit. That is the whole contract. See Sources/MCPServer/main.swift:1408 for the tool list.

main.swift:1667 declares `let isDisruptive = params.name != refreshTool.name`. Every input-guard install, cursor save, frontmost-app save, CGEventTap, and post-action cursor restore is gated on `if isDisruptive` (main.swift:1670, 1754, 1767-1781). refresh_traversal takes the non-disruptive branch: no CGEventTap is installed, no cursor is saved, no app focus is saved, and the InputGuard.shared.engage() call at main.swift:1696 is never reached. The action path runs `primaryAction = .traverseOnly` (main.swift:1656), which only reads AX attributes. You can verify by stracing the process or just tailing stderr: the 'InputGuard: engaging' log line never appears for refresh_traversal.

Every tool call writes a flat-text file to /tmp/macos-use/<millisecond-timestamp>_<toolname-without-prefix>.txt. For a dry run the file is named like /tmp/macos-use/1713610245731_refresh_traversal.txt. Each line is one AX element: `[AXButton (button)] "Send" x:1240 y:720 w:56 h:32 visible`. Roles are prefixed with AX so you can grep for the kind you want. Coordinates are top-left plus width and height, already in CGEvent-compatible point space (1pt == 1px, no backingScaleFactor math required, see CLAUDE.md Coordinate System note). The write happens at main.swift:1829.

Three steps. 1) refresh_traversal with pid=X. 2) Grep the resulting .txt file for the role and label you want (`grep -n 'AXButton.*"Send"' /tmp/macos-use/<file>.txt`). 3) click_and_traverse with the x, y, w, h values from that line. The click tool auto-centers at (x+w/2, y+h/2), so you pass the values from the grep output verbatim. There is no mapping layer, no screenshot-to-coordinate math, no fuzzy element resolver sitting in the middle. The grep match is the plan.

Three reasons. 1) LLMs handle line-oriented grep output more reliably than nested JSON when you only want 3 of 800 elements. 2) The agent can run actual `grep -n` in a sub-tool instead of loading the full tree into context. 3) Each line is independently meaningful, so you can build the click sequence with a few grep invocations and keep the rest of the tree out of your context window. main.swift:1002-1004 writes one element per line and that is the whole trick.

The mutating tool runs its own traversal immediately before the action (traverseBefore = true), so even a stale plan is checked against the live tree on commit. If the target element moved, the AX tree at commit time reflects that. If the tool fails to find the element at the requested coordinates, the returned diff will be empty or reflect the wrong click, and you re-plan from the post-action .txt file. Nothing gets committed to an invisible element silently. The diff tells you what actually changed.

Yes, because it skips several real-time operations. It does not CFRunLoopAddSource the CGEventTap (InputGuard.swift:148-152), does not schedule the 30-second watchdog timer (InputGuard.swift:172-180), does not render the translucent overlay window (InputGuard.swift:202-277), does not wait the 100ms inter-action sleep in composed mode (main.swift:1727), and does not wait the 200ms post-action grace period (main.swift:1757). Net: a dry run is typically hundreds of milliseconds cheaper than a mutating call that does the same traversal internally. If your agent only needs the AX tree, refresh_traversal is the cheapest way to get it.

Do not. The server already compresses click + type + pressKey into one tool call via click_and_traverse's optional `text` and `pressKey` params (main.swift:1329-1348). The dry-run plan only needs to resolve the FIRST click target, because the rest of the chain is declarative (the text to type, the key to press) and does not require separate element lookup. For genuinely multi-step flows (click A, wait for sheet, click B), alternate: refresh_traversal → click, refresh_traversal → click. Each dry run is one cheap read; each commit is one chained call.

It is orthogonal. LangGraph's planner/executor decomposition is a prompt-level pattern: one LLM call writes a plan, another LLM call executes. What mcp-server-macos-use gives you is the *physical* substrate that makes that pattern safe on a real desktop: a read-only tool that returns the exact coordinates your plan needs, and a diff on every mutating call so the executor can detect plan drift. You can run LangGraph planner/executor over macos-use and the two layers stack cleanly.

You cannot, and that limitation is honest. A GUI dry run is only valid against the live tree. Simulating the intermediate states (what the Save sheet will look like after Cmd+S, what the confirmation dialog will say) requires running the action. The server does not fake this. The realistic pattern is: dry-run the current state, commit one step, dry-run the new state, commit the next step. Each commit produces a diff you use to verify that step landed before planning the next. There is no speculative multi-step dry run because the UI cannot be symbolically evaluated.

The pattern generalizes; the APIs do not. Terminator (the Windows-side MCP sibling) reads UI Automation's UIA tree instead of macOS's AX tree. Element IDs, role names (ControlType.Button vs AXButton), and coordinate conventions differ. The discipline is the same: one read-only tool returns the tree, one mutating tool commits. This article is specifically about the macOS side because `isDisruptive = params.name != refreshTool.name` is a macos-use-specific line of code, and `/tmp/macos-use/` is a macos-use-specific file path.

Clone the repo, run `xcrun --toolchain com.apple.dt.toolchain.XcodeDefault swift build`, point any MCP client at `.build/debug/MCPServer`, call open_application_and_traverse with identifier='Safari' to get a PID, then call refresh_traversal with that PID. Open the file at the path in the summary. That is your dry-run plan: every interactive element of Safari's frontmost window, one per line, with coordinates. Grep it for whatever you want to click next. No events have been sent yet; the only side effect so far was opening the app.