MCP reference

screenwright-mcp reference

Overview

The agent face of ScreenWright. An MCP server over stdio that reads and writes an iPhone or iPad home-screen layout over USB or Wi-Fi, through the same verified pipeline the Mac app uses.

• Transport: stdio, newline-delimited JSON-RPC 2.0.
• MCP protocol version 2025-06-18; the server echoes the client's version in initialize.
• Server name screenwright, version 0.1.3.
• Tools only: no resources, no prompts.
• Logs go to stderr only; stdout is the protocol.
• Works with the ScreenWright app closed. Same HomeScreenKit core.

Server instructions sent in initialize · verbatim

ScreenWright edits an iPhone/iPad home screen layout over USB or Wi-Fi. Workflow: list_devices → get_layout (structure, widget UUIDs, grid metrics) → get_installed_apps (for planning) → preview_layout (dry-run: compile + validate + exact diff, device untouched) → apply_layout (snapshot → write → settle → read back → verify). Every write is snapshotted first; list_snapshots → preview_restore_snapshot → restore_snapshot roll back. Hard limits: wallpaper and icon appearance are out of reach; apps cannot be removed from the home screen (SpringBoard re-inserts them); widgets cannot be created, only moved/resized/removed. Preview before you apply.

Shared arguments

Every device-touching tool accepts:

• udid (string, optional): target device UDID from list_devices. Omit it and the server takes the first USB listing; when no USB device is listed it takes the first listing of any transport, so a Wi-Fi-only device is picked silently and the session runs over Wi-Fi (the result says so: transport: "Wi-Fi"). Pass udid when more than one device is around.
• network (boolean, optional): connect over Wi-Fi instead of USB. Connection establishment retries for about 30 seconds because a locked phone's Wi-Fi entry comes and goes. Any write over Wi-Fi is flagged wireless: true.

get_layout, preview_layout, apply_layout, preview_restore_snapshot and restore_snapshot report transport ("USB" or "Wi-Fi"); every write additionally carries wireless.

Install and register

The server ships inside the app, at ScreenWright.app/Contents/MacOS/screenwright-mcp, and is signed and notarized with it. There is no second download and no install step: register that path with your client. The examples assume the app is in Applications; if it lives somewhere else, choose Help, then Set Up MCP Server in ScreenWright and copy either form below with the real path filled in.

Claude Code: project .mcp.json

{
  "mcpServers": {
    "screenwright": { "command": "/Applications/ScreenWright.app/Contents/MacOS/screenwright-mcp", "args": [] }
  }
}

or from the shell:

claude mcp add screenwright -- /Applications/ScreenWright.app/Contents/MacOS/screenwright-mcp

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json, same shape; the path must be absolute. Any MCP client that speaks stdio can register it the same way; Claude Code is where it has been exercised.

Smoke test by hand

Two newline-delimited requests on stdin:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_devices","arguments":{}}}' \
  | /Applications/ScreenWright.app/Contents/MacOS/screenwright-mcp

You should see an initialize result followed by a devices list. A phone with Wi-Fi visibility on appears twice: same UDID, a "USB" row and a "Wi-Fi" row.

With no device attached, list_devices returns {"count": 0, "devices": []} and any device tool returns:

{ "error": "device_unavailable", "message": "no devices visible to usbmuxd. Is the device attached (or paired with Wi-Fi visibility on)?" }

Pairing is the same as for the app: one USB attach with Trust This Computer; for Wi-Fi, enable “Show this iPhone when on Wi-Fi” in Finder once.

Building from a checkout instead? swift build -c release --product screenwright-mcp produces the same server under .build/release, and ./install.sh --mcp copies it to /usr/local/bin. Register whichever copy you mean to run; the two are built from the same sources.

Workflow

1. list_devices: find the UDID and the transport you want.
2. get_layout: the current structure, every widget's UUID, and the real grid metrics (columns, rows, slot capacities). Never assume 4×6.
3. get_installed_apps: the list app references resolve against. A superset of what's on the home screen; hidden and system apps included.
4. preview_layout: compile, validate, and diff your spec against the device. No write. diff is the change you asked for, with a readable summary beside it; predicted is what the phone will do with it, and normalizations names each app SpringBoard will put back or drop. Pass baselineFingerprint on as expectedBaseline.
5. apply_layout write: snapshot → validate → write → settle ~3 s → read back → verify.

Preview before you apply, and before you restore. Read diff; it is what you asked for. Read predicted; it is what you will get.

Tools

Sixteen tools. Three of them write.

{ "version": 1, "otherPages": "replace", "pages": [{ "items": ["com.apple.mobilesafari"] }] }

{
  "diff": [
    { "message": "length 2 -> 1",
      "path": "state[1]" }
  ],
  "summary": [
    "Com.apple.Music is removed from page 1 slot 2."
  ]
}

{
  "predicted": {
    "diff": [],
    "layout": {
      "dock": [{ "app": "com.apple.mobilephone" }],
      "pages": [{ "page": 1, "items": [
        { "app": "com.apple.mobilesafari" },
        { "app": "com.apple.Music" }
      ] }]
    }
  },
  "normalizations": [{
    "bundleID": "com.apple.Music",
    "action": "reinsert",
    "reason": "omittedApp",
    "message": "SpringBoard is predicted to re-insert com.apple.Music because it is on the current home screen but omitted from the requested layout."
  }]
}

Layout spec

The grammar below is embedded verbatim in the validate_layout, preview_layout and apply_layout descriptions; an agent needs nothing outside tools/list.

{
  "version": 1,
  "dock": ["com.apple.mobilephone", "Safari"],   // optional; 1-4 apps only. Omit to keep the current dock.
  "pages": [
    {"page": 3, "items": [                        // "page": 1-based page number (patch mode only; one past the end appends)
      "com.apple.freeform",                       // bare string = app ref: exact bundle ID, else case-insensitive display name
      {"folder": "Studio", "items": ["com.adobe.fresco", "Linea"]},   // or "pages": [[...],[...]] for explicit interior pages
      {"widget": "<UUID from get_layout>", "size": "medium"}          // existing widgets only, by UUID; "size" optionally resizes
    ]}
  ],
  "otherPages": "keep",       // "keep" = patch mode (default): only the named pages change, everything else is carried verbatim.
                              // "replace" = full mode: the pages array IS the whole home screen, in order ("page" numbers forbidden).
  "unplacedWidgets": "keep"   // "keep" | "error" | "drop". Default "keep" in patch mode, "error" in full mode. Never silent.
}

Wide lines scroll sideways inside the block; the scrollbar stays visible.

App references

A bare string is an app. Exact bundle ID first; otherwise a case-insensitive display name. A miss is unknown_bundle_id or unknown_name with did_you_mean; two matches is ambiguous_name with candidates.

Folders

{ "folder": name, "items": [refs] } packs items into interior pages using the device's folder page capacity; { "folder": name, "pages": [[refs], [refs]] } sets interior pages explicitly. Folders need a name and non-empty pages. Folders cannot nest.

Widgets

{ "widget": UUID, "size"?: "small" | "medium" | "large" | "extraLarge" }. The UUID must come from get_layout. size resizes; contents are carried verbatim. widgetSlotCosts from get_layout lists a cost for all four sizes on every device, so its presence there says nothing about fit. What governs extraLarge is page capacity: the kit counts it as 4×8, 32 slots, and an iPhone page holds 24 (pageSlotCapacity), so validation rejects it there as pageCapacity. It fits only where pageSlotCapacity is at least 32. The 4×8 footprint is the kit's assumption; it has not been confirmed against an iPad.

unplacedWidgets

"keep" carries an unmentioned widget where it is; "error" refuses; "drop" removes it. Never silent.

Rules an agent must know

1. App refs resolve against the installed list; a miss or ambiguity is a structured error (did_you_mean / candidates), never a guess.
2. Placing an app removes it from everywhere else: duplicates are unrepresentable.
3. Apps CANNOT be removed from the home screen (SpringBoard re-inserts anything omitted; the validator warns with omittedApp). Widgets CAN be removed, by omission with "unplacedWidgets": "drop".
4. Widgets are referenced by UUID from get_layout, never invented; a synthesized widget renders as a dead blank tile.
5. Slot budget per page comes from get_layout's metrics (e.g. 24 on an iPhone: app/folder = 1 slot, small widget = 4, medium = 8, large = 16). Dock 1–4 apps only. Page count within the device's maxPages (15).
6. Emptied folders and pages are dropped with warnings (folder_dropped, page_dropped).

get_layout entry shapes

The read mirrors the spec's keys so an agent can copy identifiers straight from a read into a spec.

{ "app": "com.apple.facetime", "name": "FaceTime" }

{ "folder": "Utilities", "pages": [[{ "app": "…", "name": "…" }, …]] }

{ "widget": "4B5D8634-…", "size": "small", "contents": "small Smart Stack: com.apple.weather / …" }

{ "unknown": true, "note": "unrecognized entry shape: preserved verbatim on untouched pages, not expressible in a layout spec" }

Device-owned metadata (iconModDate, bundleVersion) never appears and is never part of a diff.

Errors

Every issue is an object, never a bare string:

{ "error" | "warning": code, "message", "path"?, "value"?, "did_you_mean"?: [], "candidates"?: [] }

All issues are collected in one pass. Codes are stable.

stale_plan

write_unverified

What a refusal looks like

Two apps on the test phone are named “Connect”: App Store Connect and Garmin Connect. Ask for “Connect” by name and typo a policy key, and validate_layout returns this. Nothing was written.

{
  "ok": false,
  "errors": [
    {
      "error": "ambiguous_name",
      "path": "$.pages[0].items[0]",
      "value": "Connect",
      "candidates": ["com.apple.AppStoreConnect", "com.garmin.connect.mobile"],
      "message": "\"Connect\" names 2 installed apps (com.apple.AppStoreConnect, com.garmin.connect.mobile). Use a bundle ID; the compiler reports ambiguity rather than guessing"
    }
  ],
  "warnings": [
    {
      "warning": "unknown_key",
      "path": "$.otherPagez",
      "value": "otherPagez",
      "did_you_mean": ["otherPages"],
      "message": "unrecognized key \"otherPagez\" is ignored; a typo here silently takes the default"
    }
  ]
}

1. Candidates, not a choice. The agent picks a bundle ID; the compiler won't.
2. A path into your spec. $.pages[0].items[0]. Every issue says where.
3. Typos in keys come back as warnings. A misspelled otherPages would otherwise silently take the default.
4. Every issue in one pass. Fix them all, validate again, then preview.

Message strings are the compiler's own; the two Connect apps are real, from the test phone's installed list. And exact bundle IDs are exact: com.zwift.Zwift is the Zwift Companion app; the game is com.zwift.ZwiftGame.

Warnings

An app you omitted is a warning (omittedApp), not an error: it can't be removed, and SpringBoard will put it back. The verifier expects that re-insertion and counts it as clean, and preview_layout shows it before you write, as a reinsert in normalizations and in predicted.layout. An app deleted from the phone since a snapshot is the other case: uninstalledApp on a restore, a drop in the prediction.

Write report

One shape for anything that went through the verified writer, apply_layout and restore_snapshot:

{
  "applied": true,
  "verifiedClean": boolean,          // the only success signal that means anything
  "transport": "USB" | "Wi-Fi",
  "wireless": boolean,
  "snapshot": "<filename>",           // yyyyMMdd-HHmmss.SSS[-label].plist, e.g. 20260901-011349.680-mcp-apply.plist
  "snapshotPath": "<absolute path>",  // under ~/Library/Application Support/ScreenWright/Snapshots/<udid>/
  "changesPlanned": number,           // the number of diff lines the preview showed
  "summary": [string],                // one readable sentence per change, ripple collapsed; [] when nothing changed
  "expectedNormalizations": [{ "path", "message" }],
  "unexpectedDifferences": [{ "path", "message" }],
  "recoveryAdvice": string            // only when verifiedClean is false
}

apply_layout adds compileWarnings; restore_snapshot adds restored. Diffs ignore iconModDate and bundleVersion. Settle time is ~3 s.

What a clean write returns

The dock swap from the worked example, as logged: 6 diff lines, two sentences, that snapshot, USB, verified clean. Field names are the server's; the object is assembled from the session record.

{
  "applied": true,
  "verifiedClean": true,
  "transport": "USB",
  "wireless": false,
  "snapshot": "20260901-011349.680-mcp-apply.plist",
  "snapshotPath": "/Users/you/Library/Application Support/ScreenWright/Snapshots/<udid>/20260901-011349.680-mcp-apply.plist",
  "changesPlanned": 6,
  "summary": [
    "Zwift moves from page 11 slot 23 to dock slot 4.",
    "Music moves from dock slot 4 to page 11 slot 23."
  ],
  "expectedNormalizations": [],
  "unexpectedDifferences": [],
  "compileWarnings": []
}

Snapshots and rollback

Every apply_layout and restore_snapshot writes a snapshot first, under ~/Library/Application Support/ScreenWright/Snapshots/<udid>/, named yyyyMMdd-HHmmss.SSS[-label].plist. At least the last 20 are kept per device. The app's Snapshots sheet and list_snapshots read the same folder; an agent's snapshots show up in the app, and vice versa.

list_snapshots returns them newest first. preview_restore_snapshot plans the rollback without writing or snapshotting: the diff and summary the restore would make, the uninstalledApp warnings it would raise, the filename it chose, and a baselineFingerprint. restore_snapshot pushes that snapshot back through the full verified pipeline, and takes a fresh pre-restore snapshot first, so rolling back is itself reversible. Omit snapshot on either to use the most recent; pass the previewed filename and fingerprint to restore exactly what you looked at.

The app reads the same folder as a write history (Help, then Write History, or ⌘Y; also the History button in the editor). Each snapshot is one write, labelled by who took it: mcp-apply and pre-restore show as AGENT, gui-apply as APP, with the same summary sentences for what the layout had become by the next snapshot. An agent's writes are visible to the person who owns the phone even if the app was closed at the time. Write History, and what it cannot tell →

If a restore verifies unclean, the on-device reset is the last resort:

Connectivity and hard limits

Connectivity

• USB: one-time “Trust This Computer” pairing. Works with the phone locked.
• Wi-Fi: enable “Show this iPhone when on Wi-Fi” in Finder over USB once; then same network, no cable. network: true selects the link; connection attempts retry for ~30 s because a locked phone's entry comes and goes; writes are flagged wireless: true.
• If Wi-Fi discovery stops working after it worked once, check that the phone's Private Wi-Fi Address is off for that network.
• Grid metrics are read from the device: an iPad's grid is read as an iPad's grid.

Hard limits

The first four are stated to agents in the server's instructions rather than attempted; the rest follow from the wire format and the device's own metrics.

• Wallpaper: cannot be set. On iOS 27, reading it drops the service channel, so it is never read either.
• Icon appearance (dark, tinted, large): cannot be set.
• Apps cannot be removed from the home screen; SpringBoard re-inserts anything omitted. Omission is a warning.
• Widgets cannot be created; only moved, resized, or removed, by UUID.
• Blank slots, free placement, hidden apps, Today View widgets, App Library order: not in the wire format.
• Page ceiling is a device metric (15 on current iOS). Slot capacities are device metrics too.
• Apple can change the service in any iOS release. Tested on iOS 27.0, iPhone 16 Pro, and an iPad.

The full table, with reasons, is on the How it works page.

Worked example: a real session

From Claude Code, over USB, on an iPhone 16 Pro running iOS 27.0.

What the Mac app's Review sheet makes of those two patches, pinned by a fixture test: seven entries: a dock swap, one widget moved, and four apps moved to make room.

fixture · compile only  On a fixture, the same compiler reorganized a real 265-app baseline into 17 folders with zero errors and zero warnings, every app placed exactly once. A compile, not a device write.