docs: rewrite use cases section with real developer workflows#67
docs: rewrite use cases section with real developer workflows#67saen-ai wants to merge 11 commits into
Conversation
…dep CVEs - record_video: was hardcoded to "booted", ignoring the udid param — now uses getBootedDeviceId() consistently with all other tools; also adds udid to the tool schema so callers can target a specific simulator - ui_view: JSON.parse on idb output had no error handling — server would crash on malformed output; wrapped in try/catch with a clear error message; also validates frame dimensions are positive numbers before use - ui_view: temp PNG/JPEG files now deleted immediately after reading instead of accumulating until server exit; file names include a random suffix to prevent collisions on rapid successive calls - record_video: improved start detection — now rejects properly if the process exits early, increased timeout from 3s to 5s, tracks resolved state to avoid double-settling the promise - deps: updated @modelcontextprotocol/sdk to latest (fixes CVE ReDoS, cross-client data leak, DNS rebinding — all high severity); ran npm audit fix for 6 additional moderate/low vulns in ajv, body-parser, minimatch, path-to-regexp, qs, diff Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
idb ui text only supports ASCII keycodes and throws 'No keycode found' for any emoji or non-ASCII character. This adds a new ui_paste tool that works around the limitation using the macOS pasteboard: 1. Copies text to the Mac clipboard via pbcopy 2. Syncs it to the simulator pasteboard via xcrun simctl pbsync 3. Long-presses at the given coordinates to trigger the paste menu 4. Finds the Paste button in the accessibility tree and taps it This enables typing emoji, Arabic, Chinese, and any Unicode text into simulator inputs — essential for testing apps with international users or emoji-heavy content. ui_type is unchanged and remains the right tool for ASCII text.
1.5s was triggering iOS system gestures (app switcher / home screen), dismissing the app before the paste menu appeared. 0.8s is long enough to trigger the contextual paste menu without conflicting with system gestures.
idb ui tap requires integer x/y values — passing floats like 55.166... causes 'invalid int value' error. Round the calculated center coordinates.
terminate_app: kills a running app by bundle ID without having to relaunch it — useful for testing cold-start flows and crash recovery open_url: opens any URL or deep link in the simulator — essential for testing universal links, custom URL schemes, and OAuth redirect flows list_apps: lists all installed apps with their bundle IDs and display names, sorted alphabetically — removes the need to manually look up bundle IDs before calling launch_app or terminate_app
- max_size: resizes screenshot proportionally using sips when the image exceeds the given pixel dimension (width or height). Solves the Claude 2000px API limit issue (joshuayoes#42). - force: prevents silent overwrites by erroring when the output file already exists. Defaults to false (joshuayoes#19). Fixes joshuayoes#42, Fixes joshuayoes#19
Instead of pkill-ing all simctl recordVideo processes, we now store each recording's ChildProcess in a Map keyed by UDID. stop_recording sends SIGINT to that specific PID, leaving any other simulators or concurrent idb operations untouched. Falls back to pkill if no tracked process is found (e.g. server restarted mid-recording) so behaviour is never worse than before. Also adds an optional udid param to stop_recording for multi-simulator setups. Fixes joshuayoes#20
Adds an optional timeout (1–3600 seconds) to record_video. When set, a setTimeout fires after the given duration and sends SIGINT to the tracked recording process — same targeted kill used by stop_recording. If omitted, behaviour is unchanged: recording runs until stop_recording is called. Fixes joshuayoes#5
Adds a rotate_device tool that rotates the iOS Simulator left (counter-clockwise) or right (clockwise) using the Simulator app's built-in keyboard shortcuts via osascript. Supports an optional `times` param (1–3) for multi-increment rotations without multiple tool calls. A 500ms delay between increments lets the simulator animate each step. Contributes to joshuayoes#49
Replaces the generic prompt list with five concrete end-to-end flows that reflect how the tool is actually used: bug reproduction recording, post-implementation feature validation, React Native Redbox debugging, Unicode/emoji text input testing, and rotation-based layout checks. Also adds missing tool entries to the Tools section for ui_paste, rotate_device, terminate_app, open_url, and list_apps. Fixes joshuayoes#40
|
Thanks — the use-cases rewrite addresses #40 and reads well. But this PR mixes two kinds of content that should live in different places:
My preference: go with (a) — split and ship each tool's docs with its tool PR, and this PR becomes a smaller, focused use-cases rewrite that only demonstrates tools currently on |
2 participants
Summary
Rewrites the use cases section of the README as requested in #40, replacing the generic prompt list with five concrete end-to-end workflows that reflect how developers actually use this tool.
Fixes #40
New workflows added
ui_pastefor non-ASCII textAlso
Added missing tool entries to the Tools section for
ui_paste,rotate_device,terminate_app,open_url, andlist_apps— these were added in recent PRs but the README wasn't updated.