@mgcrea/mcp-ios-simulator 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Olivier Louvignes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,218 @@
+# @mgcrea/mcp-ios-simulator
+
+Model Context Protocol server for driving an **iOS Simulator** from a model:
+screenshot the screen, read its accessibility tree, tap, swipe, type, manage the
+app under test — and stage the device itself, which is the part no physical
+device can do.
+
+No Apple Developer team. No code signing. No device trust. No tunnel. Nothing to
+unlock. And **screenshots work with nothing installed at all**.
+
+## Features
+
+- **See the screen, with zero setup.** `simctl` captures it directly, scaled to
+  exactly the device's point size, so a position read off the image is a tap
+  coordinate with no conversion. No WebDriverAgent needed for this.
+- **Read the screen.** A flattened, pruned accessibility tree — type, label,
+  identifier and the precomputed tap point per element — instead of the tens of
+  KB of nested JSON WebDriverAgent actually returns.
+- **Drive the screen.** Tap by coordinate or by accessibility label, swipe, type,
+  press Home. Every action returns the resulting screen by default, so a
+  mis-aimed tap is visible on the call that made it.
+- **Stage the device.** Dark mode, Dynamic Type size, increased contrast, a
+  frozen 9:41 status bar, a simulated location, and app permissions granted or
+  denied without a prompt anyone has to tap. **None of this is possible on real
+  hardware.**
+- **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.
+
+## Security
+
+**Writes are on by default**, and that is deliberate. The rest of the fleet is
+read-only until a flag is set because a mutating tool acts on someone's real
+account or someone's real phone. A simulator is neither: it holds no person's
+data, and `ios_simulator_erase` puts it back to factory in seconds.
+
+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`.
+- `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`
+  rather than refused, because a refusal still lets a model try, retry and reason
+  about a way around it.
+
+**Your credentials.** There are none. The server holds no tokens and talks to no
+vendor API. Everything goes through `xcrun simctl` and a loopback HTTP server.
+
+**Supply chain.** Three runtime dependencies: `@modelcontextprotocol/server`,
+`zod`, and [`@mgcrea/mcp-ios-core`](../mcp-ios-core) — our own, and itself
+dependent on only the first two. Scaling images uses `sips` and reading property
+lists uses `plutil`, both of which ship with macOS, specifically so neither an
+image library nor a plist parser has to be installed.
+
+## How it reaches the simulator
+
+| Lane                     | Carries                                                                                                                                     | Needs                                       |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
+| `xcrun simctl`           | simulators, apps, install, launch, deep links, **the screenshot**, appearance, status bar, location, permissions, push, boot/shutdown/erase | Xcode. Nothing else.                        |
+| WebDriverAgent over HTTP | the accessibility tree, tap, swipe, type, buttons                                                                                           | a runner started once with `scripts/wda.sh` |
+
+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
+takes about two minutes with no Apple account.
+
+`ios_simulator_diagnostics` reports both lanes separately, so "the simulator is
+fine but the runner is not up" is a distinguishable answer rather than a generic
+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.                         |
+
+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
+one-off `IOS_SIMULATOR_ALLOW_WRITES=0` beats a file that says `true`. Unknown keys
+in the file are an error rather than silently ignored — a typo that looks like
+"that setting had no effect" is the worst way to learn where your configuration
+came from.
+
+See [.env.example](.env.example) for the annotated version.
+
+## Quick start
+
+Requires macOS with Xcode and a booted simulator.
+
+### A. Everything except the tree and the taps, with no setup
+
+```bash
+npx -y @mgcrea/mcp-ios-simulator
+```
+
+`list`, `list_apps`, `screenshot`, `diagnostics`, `power`, `install`, `launch`,
+`open_url`, `set_environment`, `push` and `erase` all work immediately.
+
+### B. The input lane
+
+`ui_tree`, `tap`, `tap_element`, `swipe`, `type` and `press_button` need a
+WebDriverAgent runner. Build and start it — no team id, no signing, no prompt:
+
+```bash
+scripts/wda.sh setup   # ~2 minutes
+scripts/wda.sh run     # leave this running
+scripts/wda.sh status  # is it answering?
+```
+
+Installed from npm, the same script is the `ios-simulator-wda` binary:
+
+```bash
+npx -p @mgcrea/mcp-ios-simulator ios-simulator-wda setup
+npx -p @mgcrea/mcp-ios-simulator ios-simulator-wda run
+```
+
+### C. Wired into a client
+
+See [.mcp.json.example](.mcp.json.example).
+
+## Tools
+
+Nineteen. Five are read-only; the other fourteen disappear with
+`IOS_SIMULATOR_ALLOW_WRITES=0`.
+
+| Tool                            | Writes?       | What it does                                                             |
+| ------------------------------- | ------------- | ------------------------------------------------------------------------ |
+| `ios_simulator_list`            |               | Every simulator, with state and whether its runtime is installed         |
+| `ios_simulator_diagnostics`     |               | Both lanes, the resolved target, the geometry, and who owns the WDA port |
+| `ios_simulator_list_apps`       |               | Installed apps, with bundle id and host-path data container              |
+| `ios_simulator_screenshot`      |               | The screen, in point space — **no runner needed**                        |
+| `ios_simulator_ui_tree`         |               | Addressable elements with precomputed tap points                         |
+| `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_install`         | ✓             | Install a simulator `.app`                                               |
+| `ios_simulator_launch`          | ✓             | Launch, with fixture arguments and captured output                       |
+| `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    |
+| `ios_simulator_push`            | ✓             | A remote notification, with no APNs certificate                          |
+| `ios_simulator_restart_wda`     | ✓             | Start or restart the runner, detached                                    |
+
+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); `addmedia`,
+`keychain`, `pbcopy`, `spawn`, `diagnose` and `recordVideo` (real capabilities
+that an agent would use approximately never, and every tool costs listing bytes
+on every connect).
+
+## Traps worth knowing
+
+All measured on Xcode 26.6 (17F113).
+
+- **`simctl io … screenshot -` does not write to stdout.** The help text says it
+  does. It creates a file literally named `-` in the current working directory
+  and prints `Wrote screenshot to: …` to stderr, exit 0. This server always
+  passes a real path.
+- **`simctl io` on a simulator whose runtime is missing aborts** — SIGABRT, exit
+  134, an uncaught `NSInternalInconsistencyException` and a thirty-line stack
+  trace, not an error message. Availability is checked in the resolver, before
+  the call. On a typical machine a large fraction of simulators are in this
+  state.
+- **`erase`, `delete` and `shutdown` all accept the literal `all`.** A target of
+  `"all"` reaching `simctl erase` wipes every simulator on the machine. Refused
+  in the resolver and again in the adapter.
+- **`booted` is a coin flip.** simctl's own help: "If multiple devices are booted
+  … simctl will choose one of them." Resolved to a concrete UDID here first.
+- **WebDriverAgent scans ports 8100-8199 when `USE_PORT` is unset.** With two
+  booted simulators, the second runner comes up healthy on 8101 and a server
+  pointed at 8100 drives the _first_ one while every call reports success.
+  `scripts/wda.sh` always pins `USE_PORT`, and `diagnostics` reports the port's
+  real owner via `SIMULATOR_UDID` from `ps -Eww`.
+- **`listapps` returns an old-style NeXTSTEP plist, not JSON.** `--json` is a flag
+  on `list` and nothing else.
+- **A status bar override survives a reboot.** Clear it or it quietly pollutes
+  every later screenshot.
+- **`simctl launch` environment variables need a `SIMCTL_CHILD_` prefix** on the
+  calling process, not a flag.
+- **`simctl install` wants a `.app` bundle directory** built for the simulator —
+  an `.ipa` or a device build fails with "No such file or directory", which reads
+  like a path typo.
+- **`simctl boot` gives you no window.** It runs headless, which is what an agent
+  wants and confusing the first time; `power` opens Simulator.app by default.
+- **Two runtimes can share one identifier**, so the key of `list devices` is not
+  a primary key.
+
+## Develop
+
+```bash
+pnpm install
+pnpm lint && pnpm format:check && pnpm typecheck && pnpm test && pnpm build
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/cli.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import { a as createServer, j as BUILD_INFO, n as loadConfig, t as defaultConfigPath } from "./config-C1TH-p-c.js";
+import { ZodError } from "zod";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+//#region src/cli.ts
+const stderrLogger = {
+	debug: (...args) => {
+		if (process.env.IOS_SIMULATOR_DEBUG) console.error("[ios-simulator-mcp]", ...args);
+	},
+	warn: (...args) => console.error("[ios-simulator-mcp]", ...args),
+	error: (...args) => console.error("[ios-simulator-mcp]", ...args)
+};
+/** Show a config mistake as its field messages, not 40 frames of zod internals. */
+const describeFatal = (err) => {
+	if (err instanceof ZodError) return err.issues.map((issue) => {
+		const path = issue.path.join(".");
+		return path ? `${path}: ${issue.message}` : issue.message;
+	}).join("\n");
+	return err instanceof Error ? err.message : String(err);
+};
+const main = async () => {
+	stderrLogger.warn(`${BUILD_INFO.name}@${BUILD_INFO.version} (git ${BUILD_INFO.gitCommit} ${BUILD_INFO.gitCommitDate}, node ${process.version})`);
+	const configPath = defaultConfigPath();
+	const config = loadConfig(process.env, configPath);
+	const { server } = createServer({
+		config,
+		logger: stderrLogger
+	});
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	stderrLogger.warn(`ios-simulator-mcp connected (simulator=${config.simulatorId ?? "auto"}, wda=${config.wdaUrl ?? `127.0.0.1:${config.wdaPort}`}, writes=${config.allowWrites ? "enabled" : "DISABLED"})`);
+	if (config.allowWrites && config.launchArgs.length > 0) stderrLogger.warn(`default launch arguments: ${config.launchArgs.join(" ")}`);
+	const shutdown = (signal) => {
+		stderrLogger.warn(`received ${signal}, shutting down`);
+		process.exit(0);
+	};
+	process.on("SIGINT", () => shutdown("SIGINT"));
+	process.on("SIGTERM", () => shutdown("SIGTERM"));
+};
+main().catch((err) => {
+	console.error(`[ios-simulator-mcp] fatal: ${describeFatal(err)}`);
+	process.exit(1);
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { StdioServerTransport } from \"@modelcontextprotocol/server/stdio\";\nimport { ZodError } from \"zod\";\n\nimport { BUILD_INFO } from \"#/build-info\";\nimport { defaultConfigPath, loadConfig } from \"#/config\";\nimport { createServer } from \"#/server\";\n\n// Everything goes to stderr: stdout is the MCP protocol channel, and a stray\n// log line there corrupts the stream.\nconst stderrLogger = {\n  debug: (...args: unknown[]) => {\n    if (process.env.IOS_SIMULATOR_DEBUG) console.error(\"[ios-simulator-mcp]\", ...args);\n  },\n  warn: (...args: unknown[]) => console.error(\"[ios-simulator-mcp]\", ...args),\n  error: (...args: unknown[]) => console.error(\"[ios-simulator-mcp]\", ...args),\n};\n\n/** Show a config mistake as its field messages, not 40 frames of zod internals. */\nconst describeFatal = (err: unknown): string => {\n  if (err instanceof ZodError) {\n    return err.issues\n      .map((issue) => {\n        const path = issue.path.join(\".\");\n        return path ? `${path}: ${issue.message}` : issue.message;\n      })\n      .join(\"\\n\");\n  }\n  return err instanceof Error ? err.message : String(err);\n};\n\nconst main = async (): Promise<void> => {\n  stderrLogger.warn(\n    `${BUILD_INFO.name}@${BUILD_INFO.version} (git ${BUILD_INFO.gitCommit} ${BUILD_INFO.gitCommitDate}, node ${process.version})`,\n  );\n  const configPath = defaultConfigPath();\n  const config = loadConfig(process.env, configPath);\n  const { server } = createServer({ config, logger: stderrLogger });\n  const transport = new StdioServerTransport();\n  await server.connect(transport);\n  // The banner is not decoration. It prints before anything can fail, and it is\n  // the only place the resolved capability state is visible. Here the *unusual*\n  // state is writes being off — they default on, because a simulator is\n  // disposable — so `writes=DISABLED` is the one worth shouting: it is what\n  // explains a tool being missing from tools/list.\n  stderrLogger.warn(\n    `ios-simulator-mcp connected (simulator=${config.simulatorId ?? \"auto\"}, ` +\n      `wda=${config.wdaUrl ?? `127.0.0.1:${config.wdaPort}`}, ` +\n      `writes=${config.allowWrites ? \"enabled\" : \"DISABLED\"})`,\n  );\n  if (config.allowWrites && config.launchArgs.length > 0) {\n    stderrLogger.warn(`default launch arguments: ${config.launchArgs.join(\" \")}`);\n  }\n\n  const shutdown = (signal: string): void => {\n    stderrLogger.warn(`received ${signal}, shutting down`);\n    process.exit(0);\n  };\n  process.on(\"SIGINT\", () => shutdown(\"SIGINT\"));\n  process.on(\"SIGTERM\", () => shutdown(\"SIGTERM\"));\n};\n\nmain().catch((err: unknown) => {\n  console.error(`[ios-simulator-mcp] fatal: ${describeFatal(err)}`);\n  process.exit(1);\n});\n"],"mappings":";;;;;AAUA,MAAM,eAAe;CACnB,QAAQ,GAAG,SAAoB;EAC7B,IAAI,QAAQ,IAAI,qBAAqB,QAAQ,MAAM,uBAAuB,GAAG,IAAI;CACnF;CACA,OAAO,GAAG,SAAoB,QAAQ,MAAM,uBAAuB,GAAG,IAAI;CAC1E,QAAQ,GAAG,SAAoB,QAAQ,MAAM,uBAAuB,GAAG,IAAI;AAC7E;;AAGA,MAAM,iBAAiB,QAAyB;CAC9C,IAAI,eAAe,UACjB,OAAO,IAAI,OACR,KAAK,UAAU;EACd,MAAM,OAAO,MAAM,KAAK,KAAK,GAAG;EAChC,OAAO,OAAO,GAAG,KAAK,IAAI,MAAM,YAAY,MAAM;CACpD,CAAC,CAAC,CACD,KAAK,IAAI;CAEd,OAAO,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AACxD;AAEA,MAAM,OAAO,YAA2B;CACtC,aAAa,KACX,GAAG,WAAW,KAAK,GAAG,WAAW,QAAQ,QAAQ,WAAW,UAAU,GAAG,WAAW,cAAc,SAAS,QAAQ,QAAQ,EAC7H;CACA,MAAM,aAAa,kBAAkB;CACrC,MAAM,SAAS,WAAW,QAAQ,KAAK,UAAU;CACjD,MAAM,EAAE,WAAW,aAAa;EAAE;EAAQ,QAAQ;CAAa,CAAC;CAChE,MAAM,YAAY,IAAI,qBAAqB;CAC3C,MAAM,OAAO,QAAQ,SAAS;CAM9B,aAAa,KACX,0CAA0C,OAAO,eAAe,OAAO,QAC9D,OAAO,UAAU,aAAa,OAAO,UAAU,WAC5C,OAAO,cAAc,YAAY,WAAW,EAC1D;CACA,IAAI,OAAO,eAAe,OAAO,WAAW,SAAS,GACnD,aAAa,KAAK,6BAA6B,OAAO,WAAW,KAAK,GAAG,GAAG;CAG9E,MAAM,YAAY,WAAyB;EACzC,aAAa,KAAK,YAAY,OAAO,gBAAgB;EACrD,QAAQ,KAAK,CAAC;CAChB;CACA,QAAQ,GAAG,gBAAgB,SAAS,QAAQ,CAAC;CAC7C,QAAQ,GAAG,iBAAiB,SAAS,SAAS,CAAC;AACjD;AAEA,KAAK,CAAC,CAAC,OAAO,QAAiB;CAC7B,QAAQ,MAAM,8BAA8B,cAAc,GAAG,GAAG;CAChE,QAAQ,KAAK,CAAC;AAChB,CAAC"}