What 'MCP Server' Actually Means: A Receipt-Pointer Contract, Not A Tool Return Value

It means six tools registered in one Server object at main.swift:1408 (open, click, type, press_key, scroll, refresh), a stdio transport that carries JSON-RPC, and a strict return-value shape: every tool call writes two files to /tmp/macos-use/ (a flat-text response and a PNG screenshot, both prefixed with the same millisecond timestamp) and returns a compact summary pointing at them. main.swift:1825-1842 is the whole contract. The MCP client never receives the full traversal in its conversation context; it receives a file path and a grep hint, and decides for itself what to pull back in.

Because the accessibility tree for a real macOS app is huge. Opening Safari and traversing its window can produce 1500+ elements across tabs, toolbar buttons, bookmark bars, and sheet overlays. Inlining that into every tool response blows a 200k-context model out of the water after a handful of calls. main.swift:1821-1830 takes the flat-text rendering from buildFlatTextResponse (main.swift:992) and puts it on disk at /tmp/macos-use/{ms_epoch}_{safeName}.txt. The MCP summary that does go over the wire is usually under 500 bytes. The client can grep that file for a role or a text label before pulling anything back into context.

One element per line, verbatim from buildFlatTextResponse at Sources/MCPServer/main.swift:992. Each line is a role plus an optional text plus coordinates plus viewport status: '[AXButton (button)] "Open" x:680 y:520 w:80 h:30 visible'. For click/type/press/scroll the file holds a diff instead, with + added, - removed, ~ modified prefixes. For open/refresh it holds the whole tree. Diff files also include counts at the top and up to 3 notable text changes; open files include app_name, total element count, and processing time. No JSON, no escaping, no parsing. The file is readable by a model with a single Read tool call.

A CGWindowListCreateImage capture of the target app's chosen window, saved as PNG by the subprocess at Sources/ScreenshotHelper/main.swift, and, if the tool call was a click, a red crosshair plus a ring drawn at the click point so you can visually confirm where the event landed. The screenshot shares the same {ms_epoch}_{toolname} prefix as the .txt, so `ls -1 /tmp/macos-use/1744996800123_click_and_traverse.*` returns the pair. The screenshot-helper is a separate executableTarget declared at Package.swift:25-28; the main server never calls the capture API directly. That isolation has its own story (see the macos-use guide), but from the caller's point of view the .png just appears next to the .txt.

The compact summary includes `hint: grep -n 'AXButton' /tmp/macos-use/{file}.txt # search by role or text` at main.swift:761. The intended flow is: the model reads the summary, decides it wants to click 'Open', runs grep 'Open' against the file path, reads the two or three matching lines, pulls out the x/y/width/height of the best match, and passes those back in the next click_and_traverse tool call. The PNG is the tiebreaker when grep's best match is ambiguous or when an action produces an unexpected diff. Most of a productive session never loads the full .txt into model context.

Nine short lines built by buildCompactSummary at main.swift:731-830. Status, pid, app name, optional 'dialog: AXSheet detected' line, the file path, file_size in bytes with element count in parentheses, the grep hint, the screenshot path, and a tool-specific one-liner (e.g. 'Clicked at (412,598). +3 added, -1 removed, ~0 modified'). For a typical click_and_traverse that summary is around 400 bytes. The full file on disk for the same call is often 60-80kB. The compression ratio is roughly 200:1, and the model decides what it actually pulls into context.

Because a single tool call can write both files within the same second. main.swift:1825 sets `timestamp = Int(Date().timeIntervalSince1970 * 1000)` and both filenames at main.swift:1827 and main.swift:1834 interpolate that same integer, so the .txt and .png of one call always share a filename prefix. Second precision would work for a human running one tool at a time; millisecond precision is cheap and it prevents collisions during rapid-fire composed calls (click→type→press, which lands at main.swift:1709-1750 and writes its final file after the last traversal).

Nothing automatic. The directory is created with FileManager.default.createDirectory at main.swift:1823 if missing, but files are not cleaned up on server start or shutdown. macOS will reap them on reboot because /tmp is cleared on each launch of the system; until then they accumulate. In practice that is the behavior you want during debugging: you can scroll back through a session and see exactly which tool call produced which on-screen state, correlated by timestamp. If you are running hour-long sessions the directory grows. Add `find /tmp/macos-use -mmin +60 -delete` to a cron if that matters.

No. The MCP spec lets a tool return any text content it wants. Returning a pointer instead of the payload is idiomatic when the payload is large and the payload is also accessible to the model via another MCP tool (here, the filesystem via Read/Grep, which Claude Code exposes natively). It would be an anti-pattern if the file were on a remote resource the model could not reach, or if the summary hid information the model needed to make a decision. Neither is the case. The summary carries the decision-critical fields (status, diff counts, pid); the bulk details live on disk where grep is the right tool, not natural language.

Six, declared together at main.swift:1408 as `let allTools = [openAppTool, clickTool, typeTool, pressKeyTool, scrollTool, refreshTool]`. Each has a schema object (main.swift:1293-1405) and a handler branch in the server's CallTool dispatcher (main.swift:1525-1662). Five of the six are 'disruptive' at main.swift:1667 (`isDisruptive = params.name != refreshTool.name`), meaning they engage the InputGuard overlay and restore cursor/frontmost-app state on exit. refresh_traversal is the only read-only tool; it never touches input, never engages the guard, and still writes the same .txt + .png pair so its response is indistinguishable on disk from the others.

Every macOS MCP I checked returns the traversal inline. steipete/macos-automator-mcp returns AppleScript output; CursorTouch/MacOS-MCP returns a JSON accessibility tree; ashwwwin/automation-mcp and mb-dev/macos-ui-automation-mcp return elements verbatim in the tool response. None of them put the payload on disk and return a pointer. As a consequence, long sessions with those servers force the model to re-read the same traversal from context on each step or to agree to truncation. The receipt-pointer contract at main.swift:1821-1842 is the uncopyable structural detail of this server, and it is a consequence of the platform: macOS accessibility trees are big because macOS apps are deeply nested (toolbars inside splitters inside tab groups inside windows inside sheets).

Not from the client side today. The file write at main.swift:1829 is unconditional (it only has `try?` for I/O error swallowing, not a feature flag). If you fork the server you can gate it behind an environment variable, but the compact summary intentionally does not carry the full traversal string; removing the file write would leave the model with a reference to a non-existent path. The cleaner modification is to point outputDir somewhere other than /tmp, e.g. a per-session directory under ~/Library/Caches. The timestamp scheme does not care about the path.