@mgcrea/mcp-ios-simulator 0.2.2 → 0.3.1

package/README.md

@@ -26,9 +26,17 @@ unlock. And **screenshots work with nothing installed at all**.
 - **Push without APNs.** Deliver a real remote notification with no certificate
   and no server.
 - **Manage the app.** Install a build, launch it with fixture arguments,
-  terminate it, open a deep link. An app's data container is an ordinary path on
-  this Mac, so its database or logs are read directly — there is nothing to copy
-  off a device.
+  terminate it, uninstall it, open a deep link. An app's data container is an
+  ordinary path on this Mac, so its database or logs are read directly — there
+  is nothing to copy off a device.
+- **Read its logs.** `launch` with `capture_logs: true` writes the app's stdout,
+  stderr and every `Logger`/`os_log` message into one file, and `read_logs`
+  follows it with a cursor, a regex filter and Xcode's thirty-character line
+  prefix cut down to the time.
+- **Read its crashes.** Simulator crash reports land among this Mac's own in
+  `~/Library/Logs/DiagnosticReports`; `list_crash_logs` keeps only the
+  simulators', says which simulator each came from, and `get_crash_log` returns
+  the exception and the faulting thread with library names resolved.
 
 ## Security
 
@@ -42,9 +50,13 @@ What that still costs you, stated honestly:
 - `install` and `launch` run code on your Mac. A simulated process is a host
   process.
 - The app's data container is a plain host path, readable by anything.
-- `erase` is irreversible — it is the only tool behind an explicit `confirm`.
+- `erase` and `uninstall` are irreversible — they are the two tools behind an
+  explicit `confirm`.
+- `list_crash_logs` reads this Mac's DiagnosticReports folder. It keeps only
+  simulator reports and `get_crash_log` refuses a Mac app's, but the folder is
+  yours and the server reads it as you.
 - `IOS_SIMULATOR_ALLOW_WRITES=0` restores the device server's posture in one
-  variable, and then the fourteen driving tools are **absent** from `tools/list`
+  variable, and then the seventeen driving tools are **absent** from `tools/list`
   rather than refused, because a refusal still lets a model try, retry and reason
   about a way around it.
 
@@ -67,8 +79,9 @@ image library nor a plist parser has to be installed.
 The asymmetry with `mcp-ios-device` is worth stating plainly: there, _every_
 pixel comes through WebDriverAgent, so nothing about the screen works until a
 signed runner is installed and trusted on the phone. Here `simctl` captures the
-screen itself, so **fourteen of the nineteen tools work with no runner at all**
-— only `ios_simulator_ui_tree` and the five input tools need one, and building it
+screen itself, so **eighteen of the twenty-five tools work with no runner at all**
+— only `ios_simulator_ui_tree`, `ios_simulator_wait_for_element` and the five
+input tools need one, and building it
 takes about two minutes with no Apple account.
 
 `ios_simulator_diagnostics` reports both lanes separately, so "the simulator is
@@ -77,18 +90,19 @@ failure.
 
 ## Configure
 
-| Variable                       | Default                     | What it does                                                                  |
-| ------------------------------ | --------------------------- | ----------------------------------------------------------------------------- |
-| `IOS_SIMULATOR_ID`             | the only booted simulator   | UDID, name, or `booted`. Two booted and no value is an error that names them. |
-| `IOS_SIMULATOR_ALLOW_WRITES`   | **on**                      | `0` drops the fourteen driving tools from `tools/list`.                       |
-| `IOS_SIMULATOR_LAUNCH_ARGS`    | none                        | Launch arguments applied when `launch` passes none of its own.                |
-| `IOS_SIMULATOR_WDA_PORT`       | `8100`                      | Must match the runner's `USE_PORT`. One port per simulator.                   |
-| `IOS_SIMULATOR_WDA_URL`        | `http://127.0.0.1:<port>`   | Explicit override; rarely needed.                                             |
-| `IOS_SIMULATOR_MAX_TREE_BYTES` | `24000`                     | Byte cap on a `ui_tree` payload.                                              |
-| `IOS_SIMULATOR_TIMEOUT_MS`     | `120000`                    | Budget for one `simctl` call; a boot is slow.                                 |
-| `IOS_SIMULATOR_WDA_TIMEOUT_MS` | `30000`                     | Budget for one WebDriverAgent call.                                           |
-| `IOS_SIMULATOR_OUTPUT_DIR`     | `$TMPDIR/mcp-ios-simulator` | Screenshots, launch logs, the runner log.                                     |
-| `IOS_SIMULATOR_DEBUG`          | off                         | Log every `simctl` and WebDriverAgent call to stderr.                         |
+| Variable                          | Default                            | What it does                                                                  |
+| --------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------- |
+| `IOS_SIMULATOR_ID`                | the only booted simulator          | UDID, name, or `booted`. Two booted and no value is an error that names them. |
+| `IOS_SIMULATOR_ALLOW_WRITES`      | **on**                             | `0` drops the seventeen driving tools from `tools/list`.                      |
+| `IOS_SIMULATOR_LAUNCH_ARGS`       | none                               | Launch arguments applied when `launch` passes none of its own.                |
+| `IOS_SIMULATOR_WDA_PORT`          | `8100`                             | Must match the runner's `USE_PORT`. One port per simulator.                   |
+| `IOS_SIMULATOR_WDA_URL`           | `http://127.0.0.1:<port>`          | Explicit override; rarely needed.                                             |
+| `IOS_SIMULATOR_MAX_TREE_BYTES`    | `24000`                            | Byte cap on a `ui_tree` payload.                                              |
+| `IOS_SIMULATOR_TIMEOUT_MS`        | `120000`                           | Budget for one `simctl` call; a boot is slow.                                 |
+| `IOS_SIMULATOR_WDA_TIMEOUT_MS`    | `30000`                            | Budget for one WebDriverAgent call.                                           |
+| `IOS_SIMULATOR_OUTPUT_DIR`        | `$TMPDIR/mcp-ios-simulator`        | Screenshots, launch logs, the runner log.                                     |
+| `IOS_SIMULATOR_CRASH_REPORTS_DIR` | `~/Library/Logs/DiagnosticReports` | Where `list_crash_logs` looks.                                                |
+| `IOS_SIMULATOR_DEBUG`             | off                                | Log every `simctl` and WebDriverAgent call to stderr.                         |
 
 The same keys in camelCase can go in `~/.config/ios-simulator-mcp/config.json`
 (`IOS_SIMULATOR_CONFIG` to move it). The environment wins **per field**, so a
@@ -136,8 +150,10 @@ See [.mcp.json.example](.mcp.json.example).
 
 ## Tools
 
-Twenty-one. Six are read-only; the other fifteen disappear with
-`IOS_SIMULATOR_ALLOW_WRITES=0`.
+Twenty-five. Eight are read-only; the other seventeen disappear with
+`IOS_SIMULATOR_ALLOW_WRITES=0`. `read_logs` is among those seventeen although it
+changes nothing: it only reads what `launch` started capturing, so it goes where
+`launch` goes.
 
 | Tool                             | Writes?       | What it does                                                             |
 | -------------------------------- | ------------- | ------------------------------------------------------------------------ |
@@ -147,15 +163,19 @@ Twenty-one. Six are read-only; the other fifteen disappear with
 | `ios_simulator_screenshot`       |               | The screen, in point space — **no runner needed**                        |
 | `ios_simulator_ui_tree`          |               | Addressable elements with precomputed tap points                         |
 | `ios_simulator_wait_for_element` |               | Poll until something appears, or goes away                               |
+| `ios_simulator_list_crash_logs`  |               | Simulator crash reports, newest first, by simulator and process          |
+| `ios_simulator_get_crash_log`    |               | One report: exception, termination, faulting thread                      |
 | `ios_simulator_tap`              | ✓             | Tap a point                                                              |
 | `ios_simulator_tap_element`      | ✓             | Tap by identifier, label or predicate                                    |
 | `ios_simulator_swipe`            | ✓             | Drag between two points                                                  |
 | `ios_simulator_type`             | ✓             | Type into the focused field, or a named one                              |
 | `ios_simulator_press_button`     | ✓             | Home                                                                     |
 | `ios_simulator_power`            | ✓             | Boot or shut down; never implicit                                        |
-| `ios_simulator_erase`            | ✓ **confirm** | Wipe to factory — the only irreversible tool                             |
+| `ios_simulator_erase`            | ✓ **confirm** | Wipe to factory                                                          |
 | `ios_simulator_install`          | ✓             | Install a simulator `.app`                                               |
 | `ios_simulator_launch`           | ✓             | Launch, with fixture arguments and captured output                       |
+| `ios_simulator_read_logs`        | ✓ (gate only) | Follow a `capture_logs` launch: stdout, stderr and os_log, with a cursor |
+| `ios_simulator_uninstall`        | ✓ **confirm** | Remove one app and its data                                              |
 | `ios_simulator_terminate`        | ✓             | Kill a running app                                                       |
 | `ios_simulator_open_url`         | ✓             | Deep links and universal links                                           |
 | `ios_simulator_set_environment`  | ✓             | Appearance, Dynamic Type, contrast, status bar, location, permissions    |
@@ -165,8 +185,7 @@ Twenty-one. Six are read-only; the other fifteen disappear with
 
 Deliberately absent: `create`, `clone`, `delete`, `rename`, `upgrade` and `pair`
 (fleet management, not driving, and `delete all` is a footgun with no upside);
-`get_app_container` (`list_apps` already returns the path); `uninstall`
-(`install` overwrites, and `erase` covers first-run properly); `keychain`,
+`get_app_container` (`list_apps` already returns the path); `keychain`,
 `pbcopy`, `spawn`, `diagnose` and `recordVideo` (real capabilities that an agent
 would use approximately never, and every tool costs listing bytes on every
 connect).
@@ -177,6 +196,11 @@ only way an app whose first step is "choose a photo" can be driven here at all.
 Anyone hitting that had to drop out to a shell, which is exactly what these
 tools exist to avoid.
 
+`uninstall` was on it too, on the grounds that `install` overwrites and `erase`
+covers a first run. But `erase` takes every other app's data and a reboot with
+it, and "this app's first launch, everything else as it was" is the ordinary
+case. It sits behind `confirm` like `erase`.
+
 ## Traps worth knowing
 
 Measured on Xcode 26.6 (17F113) unless marked Xcode 27, which was checked on
@@ -207,6 +231,37 @@ Xcode 27.0 (27A266a) with an iOS 27.0 runtime.
   every later screenshot.
 - **`simctl launch` environment variables need a `SIMCTL_CHILD_` prefix** on the
   calling process, not a flag.
+- **An app's `Logger` output reaches no file unless `OS_ACTIVITY_DT_MODE` is
+  set** (Xcode 27). Settings launched plainly wrote 8 lines to stderr; launched
+  with `SIMCTL_CHILD_OS_ACTIVITY_DT_MODE=YES` it wrote 77 in the same eight
+  seconds, the unified log mirrored with Xcode's prefix. `capture_logs` sets it.
+- **`--stdout` and `--stderr` may be the same file** (Xcode 27). A probe app
+  alternating `print`, stderr and `Logger` produced one file with all fifteen
+  lines in order and nothing overwritten. The redirect **appends**, so a
+  relaunch into the same path keeps the previous run's lines — every
+  `capture_logs` launch gets a fresh file.
+- **A launch log under `/tmp` or `$TMPDIR` is not where you asked** (Xcode 27).
+  The simulator opens the redirect itself, and it has its own `/tmp` and
+  `/var/folders`: `--stdout=/tmp/x/a.out` created
+  `<device>/data/tmp/x/a.out`, and the path given never existed — which is
+  where this server's default output directory is. `launch` now looks in both
+  places and returns the real one. A path under `/Users` is written as given.
+- **A simulator crash report says it is one in `platform`, not
+  `is_simulated`** (Xcode 27). Of 593 reports on one Mac, the 464 from
+  simulators all had header `platform: 7` (`PLATFORM_IOSSIMULATOR`), the Mac's
+  all had 1, and `is_simulated: 1` was on 13 _Mac_ reports — Safari, Mail and two
+  helpers. `procPath` is anonymised, so the simulator's UDID comes from the
+  body's `coalitionName` (`com.apple.CoreSimulator.SimDevice.<UDID>`), which sat
+  in the first 1.8 KB of every one.
+- **A Swift `fatalError` message is in the log, not the crash report**
+  (Xcode 27). The probe's report had the `_assertionFailure` frame and no
+  application-specific text; the message was on stderr. `get_crash_log` says so
+  when it happens.
+- **`simctl uninstall` of an app that is not installed succeeds** (Xcode 27),
+  silently, exit 0. Success does not prove it was there.
+- **Launching an app that is not installed fails as "The request to open …
+  failed"** (Xcode 27), `FBSOpenApplicationServiceErrorDomain` code 4, with nothing about installation.
+  The error now carries that remedy.
 - **A label belongs to the control _and_ to every container around it.**
   WebDriverAgent answers depth-first, so an unqualified label match lands on the
   navigation bar as readily as on the button — and a tap on a container does

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { N as BUILD_INFO, a as createServer, n as loadConfig, t as defaultConfigPath } from "./config-qc0zwYZr.js";
+import { N as BUILD_INFO, a as createServer, n as loadConfig, t as defaultConfigPath } from "./config-D0JgmT_U.js";
 import { ZodError } from "zod";
 import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 //#region src/cli.ts