@mgcrea/mcp-ios-simulator 0.4.0 → 0.4.2

package/dist/index.d.ts

@@ -48,6 +48,18 @@ declare class LaunchCaptures {
    */
   running(capture: Capture): boolean;
 }
+/**
+ * One TCP listener in the runner port range, and the simulator it runs inside
+ * when it runs inside one.
+ *
+ * `udid` is absent for anything on the host — a dev server that happens to sit
+ * on 8100 is still worth knowing about, because a runner cannot bind there.
+ */
+type RunnerListener = {
+  pid: number;
+  port: number;
+  udid?: string;
+};
 /**
  * `xcrun simctl` — Apple's own simulator tool, and the half of this server that
  * needs nothing installed and nothing signed.
@@ -247,6 +259,17 @@ export declare class Simctl {
    *
    * A successful capture also writes a `Note: No display specified…` line to
    * stderr, so non-empty stderr is not a failure here.
+   *
+   * A device with two displays — the iPhone Duo, iOS 27.1 runtime — makes the
+   * bare call fail outright: exit 22, "Cannot choose between 2 displays.
+   * Specify one with --display". Only then is it retried on `--display=primary`,
+   * so a single-display simulator and Xcode 26 never see the flag. Primary
+   * rather than whichever is lit, because it is the display WebDriverAgent
+   * addresses when no `currentDisplayId` is set: a capture of the other one
+   * would put every tap read off it in the wrong coordinate space. On an open
+   * Duo that display is black (appium/appium-xcuitest-driver#3012); driving
+   * the inner one means selecting it in WDA too, which nothing here does yet.
+   * The `internal` alias the help text offers fails on the Duo with exit 22.
    */
   screenshotPng(udid: string): Promise<string>;
   /**
@@ -361,6 +384,7 @@ export declare class SimulatorClient implements ScreenHost<SimulatorSummary> {
   private readonly wdaClients;
   /** `simctl list` is ~80ms and most tools want it twice; 2s collapses that. */
   private cache;
+  private runnerCache;
   private profiles;
   constructor(opts: SimulatorClientOptions);
   listSimulators(opts?: {
@@ -429,21 +453,54 @@ export declare class SimulatorClient implements ScreenHost<SimulatorSummary> {
   /** The capture lane that needs no runner — the whole reason this server is cheap to start. */
   screenshotPng(target: SimulatorSummary): Promise<string>;
   /**
-   * Where WebDriverAgent is.
-   *
-   * Unlike the device lane there is no tunnel address to derive: a simulator
-   * shares the host's network stack, so the runner's port *is* a host loopback
-   * port. That is also the trap — several booted simulators contend for the
-   * same one, and WebDriverAgent scans 8100-8199 when `USE_PORT` is unset, so a
-   * second runner comes up healthy on 8101 and a server pointed at 8100 drives
-   * the first simulator while reporting success. `ios_simulator_diagnostics`
-   * reports which simulator actually owns the port.
+   * Where WebDriverAgent is *configured* to be: IOS_SIMULATOR_WDA_URL, or the
+   * base port on loopback. Which runner a call actually reaches is decided per
+   * simulator by `runnerUrl`; this is only the fallback when nothing better is
+   * known.
    */
   wdaUrl(): string;
   /** The simulator `resolveTarget` falls back to when no hint is given. */
   get defaultSimulatorId(): string | undefined;
+  /** Where runner ports are allocated from, and the fallback when no owner is known. */
   get wdaPort(): number;
-  wda(_target: SimulatorSummary): WdaClient;
+  /**
+   * Every listener in the runner ranges, attributed to its simulator. Cached
+   * for 2s: every UI call asks, and lsof plus ps costs tens of milliseconds.
+   */
+  listRunners(opts?: {
+    fresh?: boolean;
+  }): Promise<RunnerListener[]>;
+  /** Called once a runner is started, so the next call looks again. */
+  forgetRunners(): void;
+  /** The first port nothing listens on, from the base port up. */
+  freeRunnerPort(): Promise<number>;
+  /** The port of this simulator's own runner, when it has one. */
+  ownRunnerPort(target: SimulatorSummary): Promise<number | undefined>;
+  /**
+   * Which runner a call for this simulator goes to.
+   *
+   * A simulator shares the host's network stack, so every runner is a host
+   * loopback port, and one server process — Bastion runs one for every session
+   * on the Mac — sees all of them. A fixed port therefore meant one simulator
+   * per process, and worse, a second simulator's calls went to the first one's
+   * runner while every tool reported success.
+   *
+   * So the owner is looked up rather than assumed: the simulator's own runner
+   * wherever it listens; failing that the configured URL, *unless* that is
+   * known to be another simulator's, which is refused. Not knowing the owner
+   * (lsof saw nothing) keeps the configured URL, which is the behaviour from
+   * before ownership was checked.
+   */
+  runnerUrl(target: SimulatorSummary): Promise<string>;
+  /**
+   * The WebDriverAgent client for one simulator, one per UDID so each keeps its
+   * own session. The URL is resolved on every request, so a runner restarted on
+   * another port is followed without a server restart.
+   */
+  wda(target: SimulatorSummary): WdaClient;
+  /** The configured URL, unchecked — for diagnostics with no single target. */
+  wdaConfigured(): WdaClient;
+  private wdaClient;
 }
 /**
  * There are no credentials here, and unlike the device server there is barely
@@ -578,6 +635,28 @@ export declare const START_RUNNER_TOOL_REMEDY: string;
 export declare const startRunnerRemedy: (allowWrites: boolean) => string;
 /** What to do when WebDriverAgent does not answer at all. */
 export declare const wdaUnavailableRemedy: (allowWrites: boolean) => string;
+/**
+ * The target has no runner of its own, and the port this server would fall
+ * back to is another simulator's.
+ *
+ * Refused rather than forwarded, because the failure it prevents does not look
+ * like one: the other runner answers healthily, a tap lands on someone else's
+ * screen, and the UI tree that comes back describes an app the caller never
+ * launched.
+ */
+export declare class RunnerBelongsElsewhereError extends IosError$1 {
+  readonly name = "RunnerBelongsElsewhereError";
+  constructor(opts: {
+    target: {
+      name: string;
+      id: string;
+    };
+    owner: string;
+    port: number;
+    freePort: number;
+    allowWrites: boolean;
+  });
+}
 /** No simulator matched, or several did and none was named. */
 export declare class SimulatorNotFoundError extends IosError$1 {
   readonly name = "SimulatorNotFoundError";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":["IosError"],"sources":["../src/client/logs.ts","../src/client/simctl.ts","../src/client/shape.ts","../src/client/simulator.ts","../src/config.ts","../src/tools/runner.ts","../src/server.ts","../src/client/display.ts","../src/client/errors.ts","../src/build-info.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.ts","names":["IosError"],"sources":["../src/client/logs.ts","../src/client/runners.ts","../src/client/simctl.ts","../src/client/shape.ts","../src/client/simulator.ts","../src/config.ts","../src/tools/runner.ts","../src/server.ts","../src/client/display.ts","../src/client/errors.ts","../src/build-info.ts"],"mappings":"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"}

package/dist/index.js

@@ -1 +1 @@
-export { N as BUILD_INFO, g as CommandError, _ as CommandTimeoutError, v as EMPTY_SCREENSHOT_REMEDY, y as IosError, b as RuntimeUnavailableError, r as SERVER_NAME, i as SERVER_VERSION, x as START_RUNNER_SCRIPT_REMEDY, S as START_RUNNER_TOOL_REMEDY, s as Simctl, o as SimulatorClient, C as SimulatorNotBootedError, w as SimulatorNotFoundError, T as TIMEOUT_REMEDY, E as TOOLCHAIN_REMEDY, D as ToolchainError, O as WdaError, k as WdaUnavailableError, A as WritesDisabledError, c as assertNotBulkTarget, a as createServer, t as defaultConfigPath, n as loadConfig, l as parseSimctlError, p as pngDimensions, m as readScreenProfile, j as startRunnerRemedy, u as summarizeApps, d as summarizeDevices, h as toDisplayInfo, f as toListRow, M as wdaUnavailableRemedy } from "./config-HmqayUrt.js";
+export { P as BUILD_INFO, g as CommandError, _ as CommandTimeoutError, v as EMPTY_SCREENSHOT_REMEDY, y as IosError, b as RunnerBelongsElsewhereError, x as RuntimeUnavailableError, r as SERVER_NAME, i as SERVER_VERSION, S as START_RUNNER_SCRIPT_REMEDY, C as START_RUNNER_TOOL_REMEDY, s as Simctl, o as SimulatorClient, w as SimulatorNotBootedError, T as SimulatorNotFoundError, E as TIMEOUT_REMEDY, D as TOOLCHAIN_REMEDY, O as ToolchainError, k as WdaError, A as WdaUnavailableError, j as WritesDisabledError, c as assertNotBulkTarget, a as createServer, t as defaultConfigPath, n as loadConfig, l as parseSimctlError, p as pngDimensions, m as readScreenProfile, M as startRunnerRemedy, u as summarizeApps, d as summarizeDevices, h as toDisplayInfo, f as toListRow, N as wdaUnavailableRemedy } from "./config-BA3aCrX9.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mgcrea/mcp-ios-simulator",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Model Context Protocol server for driving iOS Simulators: screenshots, UI tree, taps, app lifecycle and device staging",
   "keywords": [
     "ios",
@@ -66,10 +66,10 @@
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "^2.4.0",
-    "@types/node": "^26.6.5",
+    "@types/node": "^26.6.6",
     "oxfmt": "^0.75.0",
     "oxlint": "^1.90.0",
-    "tsdown": "^0.23.3",
+    "tsdown": "^0.23.4",
     "tsx": "^4.23.15",
     "typescript": "^7.0.2",
     "vite": "^8.3.5",
@@ -78,5 +78,5 @@
   "engines": {
     "node": ">=22"
   },
-  "packageManager": "pnpm@12.10.1"
+  "packageManager": "pnpm@12.16.1"
 }

package/scripts/wda.sh

@@ -20,11 +20,11 @@
 #   USE_PORT                 same thing, for people driving xcodebuild by hand
 #   NODE                     node binary         (default: node off PATH)
 #   WDA_DIR                  checkout location   (default: ~/.cache/mcp-ios-simulator/WebDriverAgent)
-#   WDA_REF                  git tag to pin      (default: v16.12.3)
+#   WDA_REF                  git tag to pin      (default: v16.15.3)
 set -euo pipefail
 
 WDA_DIR="${WDA_DIR:-$HOME/.cache/mcp-ios-simulator/WebDriverAgent}"
-WDA_REF="${WDA_REF:-v16.12.3}"
+WDA_REF="${WDA_REF:-v16.15.3}"
 DERIVED="${WDA_DIR}/.build"
 PORT="${USE_PORT:-${IOS_SIMULATOR_WDA_PORT:-8100}}"
 # Not always on PATH: a host that embeds its own runtime leaves nothing called