@mmerterden/multi-agent-toolkit-mcp 3.0.0

package/index.js

@@ -0,0 +1,1725 @@
+#!/usr/bin/env node
+
+/**
+ * multi-agent-toolkit-mcp - iOS Simulator & Android Emulator MCP Server
+ *
+ * Tools for mobile device control: screenshot, tap, swipe, type, UI tree,
+ * dark mode, accessibility testing, push notifications, location simulation,
+ * screen recording, crash logs, mock-mode vs Figma design audit (design-check
+ * family), and more. The advertised count is ALL_TOOLS.length; README and
+ * package.json carry the number and the gates hold them to it.
+ *
+ * Works with: Claude Code, Claude Desktop, Cursor, Windsurf, Copilot CLI, Cline, Zed
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { execSync, exec, spawn } from "child_process";
+import { writeFileSync, readFileSync, mkdirSync, existsSync, readdirSync, statSync } from "fs";
+import { join, dirname, basename, isAbsolute, resolve, sep } from "path";
+import { homedir } from "os";
+import { fileURLToPath } from "url";
+import { runAudit as runAppStoreAudit } from "./tools/ios-app-store-audit/index.js";
+import {
+  exportIpa,
+  listProviders,
+  resolveAuth,
+  validateApp,
+} from "./tools/ios-testflight/index.js";
+import { DESIGN_TOOLS, handleDesign } from "./tools/design-check/index.js";
+import { interactiveElements } from "./tools/ui-inspect/index.js";
+import { selectCrashReports } from "./tools/crash-logs/index.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SCREENSHOT_DIR = join(process.env.TMPDIR || "/tmp", "mobile-dev-mcp");
+if (!existsSync(SCREENSHOT_DIR)) mkdirSync(SCREENSHOT_DIR, { recursive: true });
+
+// ── Helpers ──
+
+// Marker prefix for command failures. The CallTool dispatch turns any result
+// carrying it into an MCP error result (isError: true), so a host -  and the
+// pipeline gates reading these results -  can tell failure from success.
+const ERROR_PREFIX = "ERROR: ";
+
+// A failing CLI often dumps its entire usage text (simctl's is ~3 KB). Inlining
+// that spends the caller's context on a help page, so keep only the actionable
+// head of the message.
+const ERROR_MAX_CHARS = 600;
+
+function truncateError(msg) {
+  const flat = String(msg).trim();
+  if (flat.length <= ERROR_MAX_CHARS) return flat;
+  return `${flat.slice(0, ERROR_MAX_CHARS)}\n... [${flat.length - ERROR_MAX_CHARS} more chars truncated]`;
+}
+
+function isFailure(value) {
+  return typeof value === "string" && value.startsWith(ERROR_PREFIX);
+}
+
+function run(cmd, opts = {}) {
+  try {
+    return execSync(cmd, { encoding: "utf-8", timeout: 30000, ...opts }).trim();
+  } catch (e) {
+    return `${ERROR_PREFIX}${truncateError(e.message)}`;
+  }
+}
+
+// Async twin of run() for tools that hold the child for minutes: execSync would
+// block the event loop, leaving the server unable to answer any other request
+// (or a cancellation) for the whole build. Same contract: trimmed stdout on
+// success, ERROR_PREFIX marker on failure.
+function runAsync(cmd, opts = {}) {
+  return new Promise((resolve) => {
+    exec(cmd, { encoding: "utf-8", timeout: 30000, maxBuffer: 16 * 1024 * 1024, ...opts }, (err, stdout, stderr) => {
+      if (err) resolve(`${ERROR_PREFIX}${truncateError(`${err.message}\n${stdout || ""}\n${stderr || ""}`)}`);
+      else resolve(String(stdout).trim());
+    });
+  });
+}
+
+// spawn-based collector for the long-runners that also want incremental output
+// (progress heartbeats read the last line). Interleaves stdout+stderr the way a
+// terminal would, honors an AbortSignal, and never rejects.
+//
+// Output is capped at the 64MB the execSync it replaced enforced via maxBuffer:
+// unbounded `output += chunk` on a verbose xcodebuild can exceed V8's max
+// string length, and that throw fires inside a stream 'data' handler - outside
+// the CallTool try/catch - killing the whole stdio server. The oldest chunks
+// are dropped; errors and test verdicts land at the tail of a build log.
+const SPAWN_OUTPUT_CAP = 64 * 1024 * 1024;
+
+function spawnCollect(cmd, { timeout = 600000, signal, env, onLine } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn("/bin/sh", ["-c", cmd], { env });
+    const chunks = [];
+    let size = 0;
+    let truncated = false;
+    let timedOut = false;
+    let aborted = false;
+    const timer = setTimeout(() => { timedOut = true; child.kill("SIGTERM"); }, timeout);
+    const onAbort = () => { aborted = true; child.kill("SIGTERM"); };
+    if (signal) {
+      if (signal.aborted) onAbort();
+      else signal.addEventListener("abort", onAbort, { once: true });
+    }
+    const collect = (chunk) => {
+      const s = String(chunk);
+      chunks.push(s);
+      size += s.length;
+      while (size > SPAWN_OUTPUT_CAP && chunks.length > 1) {
+        size -= chunks[0].length;
+        chunks.shift();
+        truncated = true;
+      }
+      if (size > SPAWN_OUTPUT_CAP) {
+        chunks[0] = chunks[0].slice(size - SPAWN_OUTPUT_CAP);
+        size = SPAWN_OUTPUT_CAP;
+        truncated = true;
+      }
+      if (onLine) {
+        const lines = s.split("\n");
+        for (let i = lines.length - 1; i >= 0; i--) {
+          const line = lines[i].trim();
+          if (line) { onLine(line); break; }
+        }
+      }
+    };
+    child.stdout.on("data", collect);
+    child.stderr.on("data", collect);
+    child.on("error", (e) => {
+      clearTimeout(timer);
+      resolve({ code: 127, output: `${chunks.join("")}\n${e.message}`, truncated, timedOut, aborted });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (signal) signal.removeEventListener("abort", onAbort);
+      resolve({ code: code ?? 1, output: chunks.join(""), truncated, timedOut, aborted });
+    });
+  });
+}
+
+function startHeartbeat(ctx, label, detail) {
+  if (!ctx?.progress) return () => {};
+  const started = Date.now();
+  ctx.progress(`${label}: started`);
+  const timer = setInterval(() => {
+    const d = detail ? detail() : "";
+    ctx.progress(`${label}: ${Math.round((Date.now() - started) / 1000)}s${d ? ` - ${d}` : ""}`);
+  }, 10000);
+  timer.unref?.();
+  return () => clearInterval(timer);
+}
+
+// Confine a caller-supplied RELATIVE output name to a base directory: a value
+// like "../../../.zshrc" otherwise escapes SCREENSHOT_DIR via join() and
+// overwrites a dotfile. An absolute path is treated as the caller's explicit
+// choice (a local tool writing where the user's own agent asked), but a relative
+// one must resolve inside the base.
+function safeRelOutput(name, baseDir) {
+  const raw = String(name ?? "");
+  if (isAbsolute(raw)) return raw;
+  const full = resolve(baseDir, raw);
+  if (full !== baseDir && !full.startsWith(baseDir + sep)) {
+    throw new Error(`output path escapes ${baseDir}: ${raw}`);
+  }
+  return full;
+}
+
+function sanitizeId(id) {
+  // Bundle IDs / package names: only allow alphanumeric, dots, underscores, hyphens
+  if (!id) return id;
+  if (!/^[a-zA-Z0-9._\-/]+$/.test(id)) throw new Error(`Invalid identifier: ${id}`);
+  return id;
+}
+
+// Single-quote a value for POSIX sh. Every command here is built as a string and
+// handed to execSync, i.e. to a shell -  and $( ) expands inside DOUBLE quotes,
+// so double-quoting a caller-supplied value does not contain it. Single quotes
+// suppress all expansion; an embedded single quote is closed, escaped, reopened.
+function shq(value) {
+  return `'${String(value ?? "").replace(/'/g, "'\\''")}'`;
+}
+
+// Numeric coordinates / scales: reject anything that is not a plain number so it
+// can be interpolated bare.
+function num(value, label) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) throw new Error(`Invalid numeric value for ${label}: ${value}`);
+  return n;
+}
+
+// Enum-shaped values (permission names, privacy services, keycodes) that are
+// interpolated bare: allow only the shell-inert identifier charset.
+function token(value, label) {
+  const s = String(value ?? "");
+  if (!/^[A-Za-z0-9._-]+$/.test(s)) throw new Error(`Invalid ${label}: ${value}`);
+  return s;
+}
+
+// Device serials are interpolated bare into shell command strings, so they get
+// the same treatment as token() - but adb serials for TCP endpoints carry a
+// colon (ip:port), which token() refuses. Colon is shell-inert, so the widened
+// charset stays injection-proof.
+function deviceSerial(value) {
+  const s = String(value ?? "");
+  if (!/^[A-Za-z0-9._:-]+$/.test(s)) throw new Error(`Invalid device_id: ${value}`);
+  return s;
+}
+
+function hasCommand(cmd) {
+  try {
+    execSync(`which ${cmd}`, { encoding: "utf-8", timeout: 5000 });
+    return true;
+  } catch { return false; }
+}
+
+const HAS_XCRUN = hasCommand("xcrun");
+
+// idb (Facebook) is the real iOS Simulator UI driver - `simctl io` has NO tap/swipe/type
+// operation, so tap/swipe/type/geometry route through idb. Resolve its binary + set a PATH
+// that includes idb_companion (Homebrew) so the CLI can spawn the companion.
+function resolveIdb() {
+  try { const p = execSync("command -v idb 2>/dev/null", { encoding: "utf-8" }).trim(); if (p) return p; } catch {}
+  try { const g = execSync("ls -d \"$HOME\"/Library/Python/*/bin/idb 2>/dev/null | head -1", { encoding: "utf-8", shell: "/bin/bash" }).trim(); if (g) return g; } catch {}
+  return null;
+}
+// Every user-base bin directory pip could have installed idb into, newest
+// first. resolveIdb globs any Python version, so pinning the companion PATH to
+// one was wrong: on a machine where fb-idb landed under 3.11 the binary
+// resolved fine while this PATH pointed at a 3.9 directory that need not
+// exist, leaving idb_companion findable only if it happened to be on the
+// inherited PATH.
+function pythonUserBins() {
+  try {
+    const out = execSync('ls -d "$HOME"/Library/Python/*/bin 2>/dev/null', {
+      encoding: "utf-8",
+      shell: "/bin/bash",
+    }).trim();
+    return out ? out.split("\n").filter(Boolean).sort().reverse() : [];
+  } catch { return []; }
+}
+
+const IDB_BIN = resolveIdb();
+const HAS_IDB = !!IDB_BIN;
+// The resolved binary's own directory leads, so whichever install actually won
+// is the one whose siblings (idb_companion) are reachable.
+const IDB_PATH = [...new Set([
+  ...(IDB_BIN ? [dirname(IDB_BIN)] : []),
+  "/opt/homebrew/bin",
+  ...pythonUserBins(),
+  ...(process.env.PATH || "").split(":"),
+].filter(Boolean))].join(":");
+function idb(args, opts = {}) {
+  if (!IDB_BIN) return "ERROR: idb not installed. Install: brew install facebook/fb/idb-companion && pip3 install --user fb-idb";
+  return run(`${shq(IDB_BIN)} ${args}`, { env: { ...process.env, PATH: IDB_PATH }, ...opts });
+}
+const HAS_ADB = hasCommand("adb");
+
+// Active screen recordings, keyed "ios:<udid>" / "android:<serial|default>".
+// The start call spawns the recorder and returns; the stop call looks the
+// child up here, ends it, and hands back the file. One recording per device:
+// two simctl recorders on one simulator fight over the io channel.
+const RECORDINGS = new Map();
+
+function fileResult(text, ...paths) {
+  return {
+    type: "file",
+    text,
+    files: paths.filter(Boolean).map((p) => ({ path: p, name: basename(p) })),
+  };
+}
+
+// ── iOS Tools ──
+
+function iosDevice(id) {
+  // Same exposure as adbFlag: the returned value is interpolated bare into
+  // simctl/idb shell strings. UDIDs and "booted" fit the serial charset; a
+  // device name with spaces never worked here unquoted, so refusing it trades
+  // a broken command for a clear error.
+  if (id) return deviceSerial(id);
+  const out = run("xcrun simctl list devices booted -j");
+  try {
+    const data = JSON.parse(out);
+    for (const devs of Object.values(data.devices || {})) {
+      for (const d of devs) { if (d.state === "Booted") return d.udid; }
+    }
+  } catch {}
+  throw new Error("No booted iOS Simulator. Use ios_list_devices and ios_boot_device first.");
+}
+
+const IOS_TOOLS = [
+  { name: "ios_list_devices", description: "List all available iOS simulators and their state", inputSchema: { type: "object", properties: {} } },
+  { name: "ios_boot_device", description: "Boot an iOS simulator by UDID or name", inputSchema: { type: "object", properties: { device: { type: "string", description: "Device UDID or name" } }, required: ["device"] } },
+  { name: "ios_screenshot", description: "Capture an iOS simulator screenshot. Returns a base64 PNG by default; pass `path` to write the file and return only its location, which is what a run taking many captures needs - a base64 image per capture exhausts the caller's context. Use when you need to see the screen, or to collect captures for a later comparison.", inputSchema: { type: "object", properties: { device_id: { type: "string" }, path: { type: "string", description: "Absolute file path to write the PNG to. The parent directory must already exist. Returns the path instead of the image." } } } },
+  { name: "ios_tap", description: "Tap at coordinates on iOS simulator", inputSchema: { type: "object", properties: { x: { type: "number" }, y: { type: "number" }, device_id: { type: "string" } }, required: ["x", "y"] } },
+  { name: "ios_swipe", description: "Swipe on iOS simulator", inputSchema: { type: "object", properties: { x1: { type: "number" }, y1: { type: "number" }, x2: { type: "number" }, y2: { type: "number" }, device_id: { type: "string" } }, required: ["x1", "y1", "x2", "y2"] } },
+  { name: "ios_type_text", description: "Type text on iOS simulator", inputSchema: { type: "object", properties: { text: { type: "string" }, device_id: { type: "string" } }, required: ["text"] } },
+  { name: "ios_launch_app", description: "Launch iOS app by bundle ID", inputSchema: { type: "object", properties: { bundle_id: { type: "string" }, device_id: { type: "string" } }, required: ["bundle_id"] } },
+  { name: "ios_terminate_app", description: "Terminate iOS app", inputSchema: { type: "object", properties: { bundle_id: { type: "string" }, device_id: { type: "string" } }, required: ["bundle_id"] } },
+  { name: "ios_list_apps", description: "List installed iOS apps", inputSchema: { type: "object", properties: { device_id: { type: "string" } } } },
+  { name: "ios_go_home", description: "Press iOS home button", inputSchema: { type: "object", properties: { device_id: { type: "string" } } } },
+  { name: "ios_set_appearance", description: "Set iOS light/dark mode", inputSchema: { type: "object", properties: { mode: { type: "string", enum: ["light", "dark"] }, device_id: { type: "string" } }, required: ["mode"] } },
+  { name: "ios_set_content_size", description: "Set iOS Dynamic Type size for accessibility testing", inputSchema: { type: "object", properties: { size: { type: "string", enum: ["extra-small", "small", "medium", "large", "extra-large", "extra-extra-large", "extra-extra-extra-large", "accessibility-medium", "accessibility-large", "accessibility-extra-large", "accessibility-extra-extra-large", "accessibility-extra-extra-extra-large"] }, device_id: { type: "string" } }, required: ["size"] } },
+  { name: "ios_set_locale", description: "Change iOS app language (requires restart)", inputSchema: { type: "object", properties: { language: { type: "string", description: "Language code (e.g. tr, en, de, ar)" }, bundle_id: { type: "string" }, device_id: { type: "string" } }, required: ["language", "bundle_id"] } },
+  { name: "ios_open_url", description: "Open URL or deep link on iOS", inputSchema: { type: "object", properties: { url: { type: "string" }, device_id: { type: "string" } }, required: ["url"] } },
+  { name: "ios_status_bar", description: "Override iOS status bar. Use 'preset' for App Store screenshot defaults (clean=9:41/100%, testing=11:11/50%, low-battery=20%, airplane=offline) or 'clear' to revert. Manual time/battery_level override the preset.", inputSchema: { type: "object", properties: { preset: { type: "string", enum: ["clean", "testing", "low-battery", "airplane", "clear"], description: "Predefined status bar preset" }, time: { type: "string" }, battery_level: { type: "number" }, device_id: { type: "string" } } } },
+  { name: "ios_push_notification", description: "Send simulated iOS push notification", inputSchema: { type: "object", properties: { bundle_id: { type: "string" }, title: { type: "string" }, body: { type: "string" }, device_id: { type: "string" } }, required: ["bundle_id", "title", "body"] } },
+  { name: "ios_grant_permission", description: "Grant iOS privacy permission", inputSchema: { type: "object", properties: { bundle_id: { type: "string" }, service: { type: "string", enum: ["all", "calendar", "contacts-limited", "contacts", "location", "location-always", "photos-add", "photos", "media-library", "microphone", "motion", "reminders", "siri"] }, device_id: { type: "string" } }, required: ["bundle_id", "service"] } },
+  { name: "ios_revoke_permission", description: "Revoke iOS privacy permission", inputSchema: { type: "object", properties: { bundle_id: { type: "string" }, service: { type: "string" }, device_id: { type: "string" } }, required: ["bundle_id", "service"] } },
+  { name: "ios_reset_permissions", description: "Reset all iOS permissions for an app", inputSchema: { type: "object", properties: { bundle_id: { type: "string" }, device_id: { type: "string" } }, required: ["bundle_id"] } },
+  { name: "ios_set_location", description: "Set simulated iOS GPS location", inputSchema: { type: "object", properties: { latitude: { type: "number" }, longitude: { type: "number" }, device_id: { type: "string" } }, required: ["latitude", "longitude"] } },
+  { name: "ios_clear_location", description: "Clear simulated iOS location", inputSchema: { type: "object", properties: { device_id: { type: "string" } } } },
+  { name: "ios_set_increase_contrast", description: "Enable/disable iOS Increase Contrast", inputSchema: { type: "object", properties: { enabled: { type: "boolean" }, device_id: { type: "string" } }, required: ["enabled"] } },
+  { name: "ios_record_video", description: "Record the iOS simulator screen. action:\"start\" (default) spawns `simctl io recordVideo` in the background and returns immediately; action:\"stop\" ends the recording and returns the video file path. One recording per device.", inputSchema: { type: "object", properties: { action: { type: "string", enum: ["start", "stop"], description: "Default start" }, filename: { type: "string", description: "Output file name or absolute path (start only). Default rec_<timestamp>.mp4 in the tool's temp dir." }, codec: { type: "string", enum: ["h264", "hevc"] }, device_id: { type: "string" } } } },
+  { name: "ios_add_media", description: "Add photo/video to iOS photo library", inputSchema: { type: "object", properties: { file_path: { type: "string" }, device_id: { type: "string" } }, required: ["file_path"] } },
+  { name: "ios_keychain_reset", description: "Reset iOS simulator keychain", inputSchema: { type: "object", properties: { device_id: { type: "string" } } } },
+  { name: "ios_get_app_container", description: "Get iOS app container path", inputSchema: { type: "object", properties: { bundle_id: { type: "string" }, container: { type: "string", enum: ["app", "data", "groups"] }, device_id: { type: "string" } }, required: ["bundle_id"] } },
+  { name: "ios_erase_device", description: "Factory reset iOS simulator", inputSchema: { type: "object", properties: { device_id: { type: "string" } } } },
+  { name: "ios_get_ui_tree", description: "Get iOS accessibility UI tree via macOS AX APIs. Pass `path` to write the raw dump to a file and return only its location - the full tree can be tens of KB.", inputSchema: { type: "object", properties: { max_depth: { type: "number" }, path: { type: "string", description: "Absolute file path to write the raw tree JSON to. The parent directory must already exist." } } } },
+  { name: "ios_accessibility_audit", description: "Audit iOS app accessibility: missing labels, small tap targets (<44pt), missing identifiers. Use scope to filter by identifier prefix (e.g. 'login_' only checks login screen elements).", inputSchema: { type: "object", properties: { max_depth: { type: "number" }, scope: { type: "string", description: "Filter: only audit elements whose identifier starts with this prefix (e.g. 'login_', 'settings_'). Omit to audit all." } } } },
+  { name: "ios_biometric", description: "Simulate Face ID / Touch ID on iOS simulator (match or nomatch)", inputSchema: { type: "object", properties: { match: { type: "boolean", description: "true=success, false=failure" }, device_id: { type: "string" } }, required: ["match"] } },
+  { name: "ios_archive_audit", description: "DEPRECATED - use ios_app_store_audit (18-rule deep scan). Lighter 6-check audit kept for backward compatibility; will be removed in the next major.", inputSchema: { type: "object", properties: { archive_path: { type: "string", description: "Path to .xcarchive" } }, required: ["archive_path"] } },
+  { name: "ios_export_ipa", description: "Export a .xcarchive to a signed .ipa via xcodebuild -exportArchive. Generates the exportOptions.plist from the arguments (method defaults to app-store-connect), so callers do not have to hand-maintain one. Returns the .ipa path plus parsed errors; a run that exits 0 without producing an .ipa is reported as a failure. Pair with ios_testflight_validate for the pre-submission gate.", inputSchema: { type: "object", properties: { archive_path: { type: "string", description: "Absolute path to the .xcarchive" }, output_dir: { type: "string", description: "Directory to write the .ipa into" }, method: { type: "string", description: "Export method: app-store-connect (default) | release-testing | enterprise | development" }, team_id: { type: "string", description: "Apple Developer team ID" }, provisioning_profiles: { type: "object", description: "Map of bundleId -> provisioning profile name (manual signing)" }, signing_style: { type: "string", description: "automatic | manual" }, upload_symbols: { type: "boolean", description: "Include symbols (default true)" }, allow_provisioning_updates: { type: "boolean", description: "Off by default. Lets xcodebuild register devices and create/modify provisioning profiles in the developer account - a change on Apple's side, so it is opt-in" }, timeout_sec: { type: "number", description: "Default 900" } }, required: ["archive_path", "output_dir"] } },
+  { name: "ios_testflight_validate", description: "Run Apple's own pre-submission validation on an .ipa via `xcrun altool --validate-app`, then map returned ITMS error codes onto the App Store rule each one implies. This is the authoritative gate: unlike the static ios_app_store_audit it can catch an unregistered bundle ID, a profile that does not match the App Store Connect app record, a version+build pair already used, and entitlements not provisioned for the app ID. Auth is a 3-tier chain: ASC API key (api_key_id + api_issuer_id), else Apple ID + app-specific password referenced indirectly through a keychain item or env var (never passed by value), else the gate returns verdict SKIPPED with a reason. SKIPPED is not a pass - it means Apple was never asked. Set list_providers=true for a pre-flight that reports which teams the credentials can deliver for (needed when a corporate Apple ID belongs to several).", inputSchema: { type: "object", properties: { ipa_path: { type: "string", description: "Absolute path to the .ipa" }, platform: { type: "string", description: "ios (default) | appletvos | visionos | macos" }, api_key_id: { type: "string", description: "App Store Connect API key ID (tier 1)" }, api_issuer_id: { type: "string", description: "App Store Connect issuer ID (tier 1)" }, p8_path: { type: "string", description: "Explicit path to AuthKey_<id>.p8; otherwise altool's search dirs are used" }, apple_id: { type: "string", description: "Apple ID (tier 2)" }, keychain_item: { type: "string", description: "Keychain item holding the app-specific password (tier 2, preferred)" }, password_env_var: { type: "string", description: "Env var holding the app-specific password (tier 2 fallback)" }, provider_public_id: { type: "string", description: "Required when the account belongs to multiple providers" }, list_providers: { type: "boolean", description: "Pre-flight only: list deliverable providers and return" }, timeout_sec: { type: "number", description: "Default 900" } }, required: [] } },
+  { name: "ios_app_store_audit", description: "Deep App Store Review compliance audit for .xcarchive bundles. 18-rule catalog covering privacy manifest, code signing, embedded SDKs, entitlements, asset hygiene, IPv6 compliance, debug-tool leak detection, Swift ABI compatibility, SDK floor (ITMS-90725), and more. Returns structured JSON with severity-ranked violations and ITMS error code mappings. Replaces ios_archive_audit (deprecated). Pass rules='core' for the 6 baseline checks (code-signing, entitlements, info-plist, privacy-manifest, binary-size, sdk-floor); 'all'|'deep' for the full 18-rule scan; CSV like 'binary-size,ipv6-compliance' for an explicit subset.", inputSchema: { type: "object", properties: { archive_path: { type: "string", description: "Absolute path to the .xcarchive bundle" }, rules: { type: "string", description: "'all' (default) | 'core' | 'deep' | comma-separated ruleIDs" } }, required: ["archive_path"] } },
+  { name: "ios_xcodebuild", description: "Build / test / clean an Xcode project with progressive disclosure. Returns one-line summary plus xcresult ID; drill in via ios_xcresult. Token-efficient - full log stays out of context unless requested.", inputSchema: { type: "object", properties: { project: { type: "string", description: "Path to .xcodeproj (mutually exclusive with workspace)" }, workspace: { type: "string", description: "Path to .xcworkspace (mutually exclusive with project)" }, scheme: { type: "string" }, configuration: { type: "string", description: "Debug / Release (default: Release)" }, destination: { type: "string", description: "Xcode destination string. Default: generic iOS Simulator" }, action: { type: "string", enum: ["build", "test", "clean", "archive", "clean-build"], description: "Default: build" }, derived_data_path: { type: "string" }, extra_args: { type: "string", description: "Additional raw xcodebuild args appended verbatim" }, timeout_sec: { type: "number", description: "Build timeout in seconds (default 600)" } }, required: ["scheme"] } },
+  { name: "ios_xcresult", description: "Drill into a previous ios_xcodebuild result by xcresult ID. Modes: summary (counts), errors (file:line + message), warnings, log (last N lines), tests (failed). Use this instead of dumping the whole build log into context.", inputSchema: { type: "object", properties: { id: { type: "string", description: "xcresult ID returned by ios_xcodebuild" }, mode: { type: "string", enum: ["summary", "errors", "warnings", "log", "tests"], description: "Default: summary" }, log_lines: { type: "number", description: "Lines of raw log to return when mode=log (default 200)" } }, required: ["id"] } },
+  { name: "ios_visual_diff", description: "Compare two PNG screenshots. Returns JSON with diff_pct, pass/fail vs threshold, and an optional diff image. Use for snapshot regression checks across light/dark, locale, dynamic type variants.", inputSchema: { type: "object", properties: { baseline: { type: "string", description: "Path to baseline PNG" }, current: { type: "string", description: "Path to current PNG" }, threshold: { type: "number", description: "Per-pixel color threshold 0..1 (default 0.1, lower = stricter)" }, max_diff_pct: { type: "number", description: "Fail if diff exceeds this percent (default 1.0)" }, output: { type: "string", description: "Path to write diff PNG (optional)" } }, required: ["baseline", "current"] } },
+  { name: "ios_list_crashes", description: "List recent crash reports from the host's ~/Library/Logs/DiagnosticReports - where simulator app crashes land. Filter by process name, bound by age and count.", inputSchema: { type: "object", properties: { app: { type: "string", description: "Only reports whose file name (the crashed process) contains this substring" }, since_min: { type: "number", description: "Only reports newer than this many minutes" }, limit: { type: "number", description: "Max reports returned, newest first (default 20)" } } } },
+];
+
+async function handleIOS(name, args, ctx = {}) {
+  if (!HAS_XCRUN) return `${ERROR_PREFIX}Xcode not installed - iOS tools unavailable. Install Xcode and run: xcode-select --install`;
+  const did = (n) => { try { return iosDevice(n); } catch (e) { return null; } };
+
+  switch (name) {
+    case "ios_list_devices": {
+      const out = run("xcrun simctl list devices available -j");
+      try {
+        const data = JSON.parse(out);
+        const result = [];
+        for (const [rt, devs] of Object.entries(data.devices || {}))
+          for (const d of devs) result.push({ name: d.name, udid: d.udid, state: d.state, runtime: rt.split(".").pop() });
+        return JSON.stringify(result.filter(d => d.name.includes("iPhone") || d.name.includes("iPad")), null, 2);
+      } catch { return out; }
+    }
+    case "ios_boot_device": return run(`xcrun simctl boot ${shq(args.device)}`);
+    // `path` returns the file location instead of the image. A design audit takes
+    // 100+ captures, and a base64 PNG per capture exhausts the caller's context
+    // long before the audit finishes - the run that motivated this shelled out to
+    // `xcrun simctl io ... screenshot <path>` directly to avoid it. With `path`
+    // the caller keeps the tool and decides which captures to actually look at.
+    case "ios_screenshot": {
+      const d = iosDevice(args.device_id);
+      const f = args.path ? String(args.path) : join(SCREENSHOT_DIR, `ios_${Date.now()}.png`);
+      if (args.path) {
+        const parent = dirname(f);
+        if (!existsSync(parent)) return `ERROR: directory does not exist: ${parent}`;
+      }
+      run(`xcrun simctl io ${d} screenshot ${shq(f)}`);
+      if (!existsSync(f)) return "ERROR: Screenshot failed";
+      if (args.path) return fileResult(`Screenshot written: ${f}`, f);
+      const buf = readFileSync(f);
+      return { type: "image", data: buf.toString("base64"), mimeType: "image/png", path: f };
+    }
+    case "ios_tap": { const d = iosDevice(args.device_id); const r = idb(`ui tap --udid ${d} ${num(args.x, "x")} ${num(args.y, "y")}`); return (typeof r === "string" && r.startsWith("ERROR")) ? r : `Tapped (${args.x}, ${args.y})`; }
+    case "ios_swipe": { const d = iosDevice(args.device_id); const dur = args.duration_ms ? ` --duration ${(args.duration_ms / 1000).toFixed(2)}` : ""; const r = idb(`ui swipe --udid ${d} ${num(args.x1, "x1")} ${num(args.y1, "y1")} ${num(args.x2, "x2")} ${num(args.y2, "y2")}${dur}`); return isFailure(r) ? r : "Swiped"; }
+    case "ios_type_text": { const d = iosDevice(args.device_id); const r = idb(`ui text --udid ${d} ${shq(args.text)}`); return (typeof r === "string" && r.startsWith("ERROR")) ? r : `Typed: ${args.text}`; }
+    case "ios_launch_app": { const d = iosDevice(args.device_id); return run(`xcrun simctl launch ${d} ${sanitizeId(args.bundle_id)}`) || `Launched ${args.bundle_id}`; }
+    case "ios_terminate_app": { const d = iosDevice(args.device_id); return run(`xcrun simctl terminate ${d} ${sanitizeId(args.bundle_id)}`) || `Terminated`; }
+    case "ios_list_apps": { const d = iosDevice(args.device_id); return run(`xcrun simctl listapps ${d} 2>/dev/null | grep -E "CFBundleIdentifier|CFBundleDisplayName" | paste - - | sort`); }
+    // `simctl io <device> pressButton` does not exist -  `io` supports only
+    // enumerate/poll/recordVideo/screenshot/screenConfig. The home button is an
+    // idb UI operation, same as tap/swipe/type.
+    case "ios_go_home": {
+      const d = iosDevice(args.device_id);
+      if (!HAS_IDB) return `${ERROR_PREFIX}ios_go_home needs idb. Install: brew install facebook/fb/idb-companion && pip3 install --user fb-idb`;
+      const out = idb(`ui button --udid ${d} HOME`);
+      return isFailure(out) ? out : "Home";
+    }
+    case "ios_set_appearance": { const d = iosDevice(args.device_id); return run(`xcrun simctl ui ${d} appearance ${token(args.mode, "appearance mode")}`) || `Appearance: ${args.mode}`; }
+    case "ios_set_content_size": { const d = iosDevice(args.device_id); return run(`xcrun simctl ui ${d} content_size ${token(args.size, "content size")}`) || `Content size: ${args.size}`; }
+    case "ios_set_locale": { const d = iosDevice(args.device_id); const bid = sanitizeId(args.bundle_id); run(`xcrun simctl spawn ${d} defaults write ${bid} AppleLanguages -array ${shq(args.language)}`); run(`xcrun simctl terminate ${d} ${bid}`); run(`xcrun simctl launch ${d} ${bid}`); return `Locale: ${args.language}`; }
+    case "ios_open_url": { const d = iosDevice(args.device_id); return run(`xcrun simctl openurl ${d} ${shq(args.url)}`) || `Opened: ${args.url}`; }
+    case "ios_status_bar": {
+      const d = iosDevice(args.device_id);
+      if (args.preset === "clear") return run(`xcrun simctl status_bar ${d} clear`) || "Status bar cleared";
+      const PRESETS = {
+        clean:        { time: "9:41", battery: 100, dataNetwork: "wifi",     wifiBars: 3, cellBars: 4, mode: "charged" },
+        testing:      { time: "11:11", battery: 50, dataNetwork: "wifi",     wifiBars: 3, cellBars: 4, mode: "discharging" },
+        "low-battery":{ time: "9:41", battery: 20,  dataNetwork: "wifi",     wifiBars: 3, cellBars: 4, mode: "discharging" },
+        airplane:     { time: "9:41", battery: 100, dataNetwork: "hide",     wifiBars: 0, cellBars: 0, mode: "charged" }
+      };
+      const p = args.preset ? PRESETS[args.preset] : null;
+      const time = args.time || p?.time;
+      const battery = args.battery_level !== undefined ? args.battery_level : p?.battery;
+      let cmd = `xcrun simctl status_bar ${d} override`;
+      // time is caller-supplied and was double-quoted, so $( ) expanded; single-quote it.
+      if (time) cmd += ` --time ${shq(time)}`;
+      // battery_level is declared numeric but never validated, so a string reached
+      // the bare interpolation. num() rejects anything non-numeric.
+      if (battery !== undefined) cmd += ` --batteryLevel ${num(battery, "battery_level")} --batteryState ${token(p?.mode || "charged", "battery mode")}`;
+      if (p) {
+        cmd += ` --dataNetwork ${p.dataNetwork} --wifiMode active --wifiBars ${p.wifiBars} --cellularMode ${p.cellBars > 0 ? "active" : "notSupported"} --cellularBars ${p.cellBars} --operatorName ""`;
+      }
+      return run(cmd) || `Status bar set${args.preset ? ` (preset: ${args.preset})` : ""}`;
+    }
+    case "ios_push_notification": { const d = iosDevice(args.device_id); const payload = { aps: { alert: { title: args.title, body: args.body }, sound: "default" } }; const f = join(SCREENSHOT_DIR, `push_${Date.now()}.json`); writeFileSync(f, JSON.stringify(payload)); return run(`xcrun simctl push ${d} ${sanitizeId(args.bundle_id)} ${shq(f)}`) || `Push sent: ${args.title}`; }
+    case "ios_grant_permission": { const d = iosDevice(args.device_id); return run(`xcrun simctl privacy ${d} grant ${token(args.service, "privacy service")} ${sanitizeId(args.bundle_id)}`) || `Granted ${args.service}`; }
+    case "ios_revoke_permission": { const d = iosDevice(args.device_id); return run(`xcrun simctl privacy ${d} revoke ${token(args.service, "privacy service")} ${sanitizeId(args.bundle_id)}`) || `Revoked ${args.service}`; }
+    case "ios_reset_permissions": { const d = iosDevice(args.device_id); return run(`xcrun simctl privacy ${d} reset all ${sanitizeId(args.bundle_id)}`) || `Reset permissions`; }
+    case "ios_set_location": { const d = iosDevice(args.device_id); return run(`xcrun simctl location ${d} set ${num(args.latitude, "latitude")},${num(args.longitude, "longitude")}`) || `Location: ${args.latitude},${args.longitude}`; }
+    case "ios_clear_location": { const d = iosDevice(args.device_id); return run(`xcrun simctl location ${d} clear`) || "Location cleared"; }
+    case "ios_set_increase_contrast": { const d = iosDevice(args.device_id); return run(`xcrun simctl ui ${d} increase_contrast ${args.enabled ? "enabled" : "disabled"}`) || `Contrast: ${args.enabled}`; }
+    case "ios_record_video": {
+      const d = iosDevice(args.device_id);
+      const key = `ios:${d}`;
+      if ((args.action || "start") === "stop") {
+        const rec = RECORDINGS.get(key);
+        if (!rec) return `${ERROR_PREFIX}no active iOS recording on ${d}. Start one with action:"start".`;
+        RECORDINGS.delete(key);
+        const exited = new Promise((resolve) => rec.child.once("close", () => resolve(true)));
+        // SIGINT, not SIGTERM: simctl finalizes the mp4 container on interrupt
+        // and a harder kill leaves the file unplayable.
+        rec.child.kill("SIGINT");
+        const closed = await Promise.race([exited, new Promise((resolve) => setTimeout(resolve, 8000, false))]);
+        if (!existsSync(rec.path)) return `${ERROR_PREFIX}recording stopped but no file at ${rec.path}`;
+        // The file exists from the moment recording began, so existence alone
+        // does not prove simctl finished writing it - only a clean exit does.
+        if (!closed) return fileResult(`Recording stopping: simctl did not exit within 8s, so the file at ${rec.path} may still be finalizing. Wait for its size to stabilize before using it.`, rec.path);
+        return fileResult(`Recording saved: ${rec.path}`, rec.path);
+      }
+      if (RECORDINGS.has(key)) return `${ERROR_PREFIX}a recording is already running on ${d}. Stop it first with action:"stop".`;
+      const f = args.filename
+        ? safeRelOutput(args.filename, SCREENSHOT_DIR)
+        : join(SCREENSHOT_DIR, `rec_${Date.now()}.mp4`);
+      // Validated before spawning, like every other path-accepting tool: a bad
+      // directory otherwise surfaces only at stop time, as a confusing failure.
+      const recParent = dirname(f);
+      if (!existsSync(recParent)) return `${ERROR_PREFIX}directory does not exist: ${recParent}`;
+      const child = spawn("xcrun", ["simctl", "io", d, "recordVideo", `--codec=${args.codec || "hevc"}`, "--force", f], { stdio: "ignore" });
+      child.once("close", () => { if (RECORDINGS.get(key)?.child === child) RECORDINGS.delete(key); });
+      RECORDINGS.set(key, { child, path: f });
+      return `Recording started on ${d} (pid ${child.pid}) -> ${f}\nCall ios_record_video with action:"stop" to finish.`;
+    }
+    case "ios_add_media": { const d = iosDevice(args.device_id); return run(`xcrun simctl addmedia ${d} ${shq(args.file_path)}`) || "Media added"; }
+    case "ios_keychain_reset": { const d = iosDevice(args.device_id); return run(`xcrun simctl keychain ${d} reset`) || "Keychain reset"; }
+    case "ios_get_app_container": { const d = iosDevice(args.device_id); return run(`xcrun simctl get_app_container ${d} ${sanitizeId(args.bundle_id)} ${args.container || "app"}`); }
+    case "ios_erase_device": { const d = iosDevice(args.device_id); return run(`xcrun simctl erase ${d}`) || "Device erased"; }
+    case "ios_get_ui_tree": {
+      const script = join(__dirname, "ui-tree-dumper.swift");
+      if (!existsSync(script)) return "ui-tree-dumper.swift not found";
+      // Path check first, matching the Android sibling: the AX dump takes up to
+      // 15s, too expensive to spend before rejecting a bad destination.
+      if (args.path) {
+        const parent = dirname(String(args.path));
+        if (!existsSync(parent)) return `${ERROR_PREFIX}directory does not exist: ${parent}`;
+      }
+      const depth = num(args.max_depth ?? 10, "max_depth");
+      const tree = run(`swift ${shq(script)} ${depth}`, { timeout: 15000 });
+      if (!args.path || isFailure(tree)) return tree;
+      writeFileSync(String(args.path), tree);
+      return fileResult(`UI tree written: ${args.path}`, String(args.path));
+    }
+    case "ios_accessibility_audit": {
+      const script = join(__dirname, "ui-tree-dumper.swift");
+      if (!existsSync(script)) return "ui-tree-dumper.swift not found";
+      const depth = num(args.max_depth ?? 10, "max_depth");
+      const scope = args.scope || null;
+      const treeJson = run(`swift ${shq(script)} ${depth}`, { timeout: 15000 });
+      try {
+        const issues = [];
+        let totalScanned = 0, totalSkipped = 0;
+        function auditNode(node, path = "") {
+          const loc = path ? `${path} > ${node.role}` : node.role;
+          const w = node.frame?.w || 0, h = node.frame?.h || 0;
+          const isInteractive = ["AXButton", "AXLink", "AXTextField", "AXTextArea", "AXCheckBox", "AXRadioButton", "AXSlider", "AXSwitch", "AXTab"].includes(node.role);
+          if (isInteractive) {
+            // Scope filter: skip elements outside scope
+            if (scope && node.identifier && !node.identifier.startsWith(scope)) { totalSkipped++; if (node.children) node.children.forEach(c => auditNode(c, loc)); return; }
+            if (scope && !node.identifier) { /* no identifier = can't scope, still audit */ }
+            totalScanned++;
+            if (!node.title && !node.description && !node.value) issues.push({ severity: "critical", issue: "Missing accessibility label", element: loc, identifier: node.identifier, frame: node.frame });
+            if (!node.identifier) issues.push({ severity: "warning", issue: "Missing accessibility identifier (UI testing)", element: loc });
+            if (w > 0 && h > 0 && (w < 44 || h < 44)) issues.push({ severity: "important", issue: `Tap target too small: ${w.toFixed(0)}x${h.toFixed(0)}pt (min 44x44)`, element: loc, identifier: node.identifier, frame: node.frame });
+          }
+          if (node.children) node.children.forEach(c => auditNode(c, loc));
+        }
+        const tree = JSON.parse(treeJson);
+        auditNode(tree);
+        return JSON.stringify({ scope: scope || "all", elements_scanned: totalScanned, elements_skipped: totalSkipped, total_issues: issues.length, critical: issues.filter(i => i.severity === "critical").length, important: issues.filter(i => i.severity === "important").length, warning: issues.filter(i => i.severity === "warning").length, issues }, null, 2);
+      } catch (e) { return `ERROR parsing UI tree: ${e.message}\n\nRaw output:\n${treeJson?.substring(0, 500)}`; }
+    }
+    // `simctl keychain <device> biometric-enroll` / `biometric-match` do not
+    // exist -  `keychain` supports only add-root-cert/add-cert/reset. The only
+    // available lever is the (undocumented) BiometricKit notification, which is
+    // posted via notifyutil inside the simulator. notifyutil exits 0 even when
+    // it cannot set or post the name, so its output has to be inspected: a
+    // "Failed with code N" line means the notification did not land, and that
+    // must be reported as a failure rather than as a simulated success.
+    case "ios_biometric": {
+      const d = iosDevice(args.device_id);
+      const action = args.match ? "match" : "nomatch";
+      const NOTIFYUTIL = "/usr/bin/notifyutil"; // simctl spawn does not resolve PATH
+      const enroll = run(`xcrun simctl spawn ${d} ${NOTIFYUTIL} -s com.apple.BiometricKit.enrollmentChanged 1`);
+      const post = run(`xcrun simctl spawn ${d} ${NOTIFYUTIL} -p com.apple.BiometricKit_Sim.pearl.${action}`);
+      const combined = `${enroll}\n${post}`;
+      if (isFailure(enroll) || isFailure(post)) return combined.trim();
+      if (/Failed with code \d+/.test(combined)) {
+        return `${ERROR_PREFIX}biometric notification not delivered on this simulator/Xcode. ` +
+          `notifyutil reported: ${combined.replace(/\s+/g, " ").trim()}. ` +
+          `BiometricKit simulation is undocumented by Apple and requires a foreground app ` +
+          `registered for these notifications; verify Face ID enrollment in the Simulator ` +
+          `Features menu before relying on this tool.`;
+      }
+      return `Biometric ${action} posted (enrollment set, ${action} delivered)`;
+    }
+    case "ios_archive_audit": {
+      const p = args.archive_path;
+      if (!existsSync(p)) return `ERROR: Archive not found at ${p}`;
+      const findings = [];
+      // 1. Find .app inside archive
+      const appDir = run(`find ${shq(p + "/Products/Applications")} -name "*.app" -maxdepth 1 2>/dev/null | head -1`);
+      if (!appDir) return "ERROR: No .app found inside archive";
+      const appName = appDir.split("/").pop();
+      const binaryName = appName.replace(".app", "");
+      const binaryPath = `${appDir}/${binaryName}`;
+      // 2. Binary size
+      const sizeOut = run(`stat -f "%z" ${shq(binaryPath)} 2>/dev/null`);
+      if (sizeOut) { const sizeMB = parseInt(sizeOut) / 1048576; findings.push({ check: "binary_size", value: `${sizeMB.toFixed(1)} MB`, status: sizeMB > 500 ? "warning" : "pass", detail: sizeMB > 500 ? "Binary exceeds 500MB - may hit App Store limits" : "OK" }); }
+      // 3. Debug tool leak check
+      const debugSymbols = run(`nm ${shq(binaryPath)} 2>/dev/null | grep -iE "FLEX|Reveal|Stetho|Flipper|CocoaDebug|Pulse" | head -10`);
+      findings.push({ check: "debug_tools", status: debugSymbols ? "critical" : "pass", detail: debugSymbols ? `Debug tools found in binary: ${debugSymbols}` : "No debug tools detected" });
+      // 4. Code signing
+      const codesign = run(`codesign -dvv ${shq(appDir)} 2>&1`);
+      const hasSignature = codesign && !codesign.includes("not signed");
+      findings.push({ check: "code_signing", status: hasSignature ? "pass" : "critical", detail: hasSignature ? "Signed" : "NOT SIGNED - will be rejected" });
+      // 5. Provisioning profile
+      const provProfile = run(`ls ${shq(appDir + "/embedded.mobileprovision")} 2>/dev/null`);
+      findings.push({ check: "provisioning_profile", status: provProfile ? "pass" : "warning", detail: provProfile ? "Present" : "No embedded.mobileprovision - may be App Store distribution" });
+      // 6. Entitlements
+      const entitlements = run(`codesign -d --entitlements - ${shq(appDir)} 2>/dev/null`);
+      const hasGetTaskAllow = entitlements && entitlements.includes("get-task-allow");
+      findings.push({ check: "entitlements_debug", status: hasGetTaskAllow ? "critical" : "pass", detail: hasGetTaskAllow ? "get-task-allow is TRUE - this is a DEBUG build, App Store will reject" : "get-task-allow not set or false - OK" });
+      // 7. Info.plist checks
+      const plistPath = `${appDir}/Info.plist`;
+      const plistJson = run(`plutil -convert json -o - ${shq(plistPath)} 2>/dev/null`);
+      if (plistJson) {
+        try {
+          const plist = JSON.parse(plistJson);
+          findings.push({ check: "bundle_version", status: plist.CFBundleShortVersionString ? "pass" : "critical", detail: plist.CFBundleShortVersionString || "MISSING" });
+          findings.push({ check: "min_os_version", value: plist.MinimumOSVersion || "unknown", status: "info" });
+          const ats = plist.NSAppTransportSecurity;
+          findings.push({ check: "app_transport_security", status: ats?.NSAllowsArbitraryLoads ? "warning" : "pass", detail: ats?.NSAllowsArbitraryLoads ? "NSAllowsArbitraryLoads=true - ATS disabled, needs justification" : "ATS enforced" });
+          // Privacy permission strings
+          const privacyKeys = ["NSCameraUsageDescription", "NSPhotoLibraryUsageDescription", "NSLocationWhenInUseUsageDescription", "NSMicrophoneUsageDescription", "NSContactsUsageDescription", "NSFaceIDUsageDescription"];
+          const declaredPerms = privacyKeys.filter(k => plist[k]);
+          findings.push({ check: "privacy_strings", value: `${declaredPerms.length} permissions declared`, status: "info", detail: declaredPerms.join(", ") || "None" });
+        } catch {}
+      }
+      // 8. Privacy manifest
+      const privacyManifest = run(`find ${shq(appDir)} -name "PrivacyInfo.xcprivacy" 2>/dev/null | head -1`);
+      findings.push({ check: "privacy_manifest", status: privacyManifest ? "pass" : "warning", detail: privacyManifest ? "PrivacyInfo.xcprivacy found" : "No privacy manifest - required for apps using Required Reason APIs" });
+      // 9. Embedded frameworks check
+      const frameworks = run(`ls ${shq(appDir + "/Frameworks/")} 2>/dev/null`);
+      if (frameworks) { findings.push({ check: "embedded_frameworks", value: frameworks.split("\n").length + " frameworks", status: "info", detail: frameworks }); }
+      // Summary
+      const critical = findings.filter(f => f.status === "critical").length;
+      const warnings = findings.filter(f => f.status === "warning").length;
+      return JSON.stringify({ archive: p, app: appName, summary: { critical, warnings, passed: findings.filter(f => f.status === "pass").length, total_checks: findings.length }, verdict: critical > 0 ? "FAIL - critical issues must be fixed" : warnings > 0 ? "WARN - review warnings before submission" : "PASS - ready for App Store", findings }, null, 2);
+    }
+    case "ios_export_ipa": {
+      if (!HAS_XCRUN) return "ERROR: xcrun not available - Xcode Command Line Tools required";
+      if (!args.archive_path) return "ERROR: archive_path is required";
+      if (!args.output_dir) return "ERROR: output_dir is required";
+      // finally, not success-path only: a rejection would otherwise leave the
+      // 10s heartbeat interval emitting progress frames forever.
+      const stopHeartbeat = startHeartbeat(ctx, "xcodebuild -exportArchive");
+      let res;
+      try {
+        res = await exportIpa({
+          archivePath: args.archive_path,
+          outputDir: args.output_dir,
+          method: args.method,
+          teamId: args.team_id,
+          provisioningProfiles: args.provisioning_profiles,
+          signingStyle: args.signing_style,
+          uploadSymbols: args.upload_symbols,
+          allowProvisioningUpdates: args.allow_provisioning_updates,
+          timeoutSec: args.timeout_sec,
+          signal: ctx.signal,
+        });
+      } finally {
+        stopHeartbeat();
+      }
+      // Progressive disclosure: the full xcodebuild log is large and almost
+      // never what the caller needs. Return the verdict plus the first errors.
+      return JSON.stringify(
+        {
+          ok: res.ok,
+          ipa: res.ipaPath || null,
+          exportOptions: res.exportOptionsPath,
+          errorCount: res.errors.length,
+          errors: res.errors.slice(0, 20),
+          hint: res.ok
+            ? undefined
+            : "Common causes: no App Store distribution certificate in the keychain, a provisioning profile that does not match the bundle ID, or signing_style=manual without provisioning_profiles.",
+        },
+        null,
+        2,
+      );
+    }
+    case "ios_testflight_validate": {
+      if (!HAS_XCRUN) return "ERROR: xcrun not available - Xcode Command Line Tools required";
+      const auth = resolveAuth({
+        apiKeyId: args.api_key_id,
+        apiIssuerId: args.api_issuer_id,
+        p8Path: args.p8_path,
+        appleId: args.apple_id,
+        keychainItem: args.keychain_item,
+        passwordEnvVar: args.password_env_var,
+        providerPublicId: args.provider_public_id,
+      });
+      if (args.list_providers) {
+        const res = await listProviders(auth, ctx.signal);
+        return JSON.stringify({ authTier: auth.tier, authMethod: auth.method, ...res }, null, 2);
+      }
+      if (!args.ipa_path) return "ERROR: ipa_path is required (or pass list_providers=true)";
+      // Same finally rationale as ios_export_ipa: never leak the heartbeat.
+      const stopHeartbeat = startHeartbeat(ctx, "altool --validate-app");
+      let res;
+      try {
+        res = await validateApp({
+          ipaPath: args.ipa_path,
+          platform: args.platform,
+          auth,
+          timeoutSec: args.timeout_sec,
+          signal: ctx.signal,
+        });
+      } finally {
+        stopHeartbeat();
+      }
+      return JSON.stringify(res, null, 2);
+    }
+    case "ios_app_store_audit": {
+      const archivePath = args.archive_path;
+      if (!archivePath) return "ERROR: archive_path is required";
+      if (!existsSync(archivePath)) return `ERROR: Archive not found at ${archivePath}`;
+      try {
+        const result = await runAppStoreAudit({
+          archivePath,
+          rules: args.rules || "all",
+        });
+        return JSON.stringify(result, null, 2);
+      } catch (err) {
+        return `ERROR: ${err.message}`;
+      }
+    }
+    case "ios_xcodebuild": {
+      if (!HAS_XCRUN) return "ERROR: xcrun not available - Xcode Command Line Tools required";
+      if (!args.project && !args.workspace) return "ERROR: project or workspace required";
+      if (args.project && args.workspace) return "ERROR: pass project OR workspace, not both";
+      const action = args.action || "build";
+      const config = args.configuration || "Release";
+      const dest = args.destination || "generic/platform=iOS Simulator";
+      const id = `xcresult-${new Date().toISOString().replace(/[-:.TZ]/g, "").slice(0, 14)}-${Math.random().toString(36).slice(2, 8)}`;
+      const xcresultPath = join(SCREENSHOT_DIR, `${id}.xcresult`);
+      const logPath = join(SCREENSHOT_DIR, `${id}.log`);
+      const target = args.workspace ? `-workspace ${shq(args.workspace)}` : `-project ${shq(args.project)}`;
+      const derivedFlag = args.derived_data_path ? `-derivedDataPath ${shq(args.derived_data_path)}` : "";
+      const actionMap = { "clean-build": "clean build", build: "build", test: "test", clean: "clean", archive: "archive" };
+      // extra_args is appended verbatim (multiple flags, so it can't be a single
+      // shq'd token), which makes it a shell passthrough. Reject the metacharacters
+      // that enable command chaining or substitution so it stays "extra xcodebuild
+      // flags" and cannot become an arbitrary-command tool.
+      const extra = args.extra_args || "";
+      if (/[;&|`$(){}<>\n\\]/.test(extra)) {
+        return "ERROR: extra_args may contain only plain flags and values (no shell metacharacters ; & | ` $ ( ) { } < > \\).";
+      }
+      const cmd = `xcodebuild ${target} -scheme ${shq(args.scheme)} -configuration ${shq(config)} -destination ${shq(dest)} -resultBundlePath ${shq(xcresultPath)} ${derivedFlag} ${actionMap[action]} ${extra}`.trim();
+      const timeout = (args.timeout_sec || 600) * 1000;
+      let lastLine = "";
+      const stopHeartbeat = startHeartbeat(ctx, `xcodebuild ${action}`, () => lastLine);
+      const res = await spawnCollect(cmd, { timeout, signal: ctx.signal, onLine: (l) => { lastLine = l; } });
+      stopHeartbeat();
+      const exitCode = res.timedOut || res.aborted ? 1 : res.code;
+      const raw = (res.truncated ? "[output truncated: kept the last 64MB]\n" : "") + res.output + (res.timedOut ? "\n[TIMEOUT]" : "") + (res.aborted ? "\n[CANCELLED]" : "");
+      writeFileSync(logPath, raw);
+      const errMatches = raw.match(/^.*error:.*$/gim) || [];
+      const warnMatches = raw.match(/^.*warning:.*$/gim) || [];
+      const errors = errMatches.length;
+      const warnings = warnMatches.length;
+      let testInfo = "";
+      const testMatch = raw.match(/Test Suite.*passed.*Executed (\d+) test[s]?, with (\d+) failure/i);
+      if (testMatch) testInfo = `, ${testMatch[1]} tests (${testMatch[2]} failed)`;
+      const status = exitCode === 0 ? "SUCCESS" : "FAILURE";
+      const truncNote = res.truncated ? "\nNote: output exceeded 64MB, the log holds only the tail." : "";
+      return fileResult(`Build: ${status} (${errors} errors, ${warnings} warnings${testInfo}) [${id}]\nProject: ${args.scheme} (${action}, ${config})\nLog: ${logPath}\nxcresult: ${xcresultPath}\nDrill in: ios_xcresult({id:"${id}", mode:"errors"})${truncNote}`, logPath);
+    }
+    case "ios_xcresult": {
+      const id = args.id;
+      if (!id || !/^xcresult-[\w-]+$/.test(id)) return "ERROR: invalid xcresult id";
+      const logPath = join(SCREENSHOT_DIR, `${id}.log`);
+      const xcresultPath = join(SCREENSHOT_DIR, `${id}.xcresult`);
+      if (!existsSync(logPath)) return `ERROR: no log for ${id} at ${logPath}`;
+      const raw = readFileSync(logPath, "utf-8");
+      const mode = args.mode || "summary";
+      if (mode === "log") {
+        const n = args.log_lines || 200;
+        const lines = raw.split("\n");
+        return lines.slice(-n).join("\n");
+      }
+      if (mode === "errors") {
+        const errs = (raw.match(/^.*error:.*$/gim) || []).map(l => l.trim());
+        return JSON.stringify({ id, count: errs.length, errors: errs }, null, 2);
+      }
+      if (mode === "warnings") {
+        const warns = (raw.match(/^.*warning:.*$/gim) || []).map(l => l.trim());
+        return JSON.stringify({ id, count: warns.length, warnings: warns }, null, 2);
+      }
+      if (mode === "tests") {
+        if (existsSync(xcresultPath)) {
+          const out = run(`xcrun xcresulttool get test-results tests --path ${shq(xcresultPath)} --format json 2>/dev/null`, { timeout: 20000 });
+          if (out && !out.startsWith("ERROR")) return out;
+        }
+        const failed = (raw.match(/^.*Test Case.*failed.*$/gim) || []).map(l => l.trim());
+        return JSON.stringify({ id, failed_count: failed.length, failed_tests: failed }, null, 2);
+      }
+      const errCount = (raw.match(/^.*error:.*$/gim) || []).length;
+      const warnCount = (raw.match(/^.*warning:.*$/gim) || []).length;
+      return JSON.stringify({ id, errors: errCount, warnings: warnCount, log_path: logPath, xcresult_path: xcresultPath }, null, 2);
+    }
+    case "ios_visual_diff": {
+      if (!existsSync(args.baseline)) return `ERROR: baseline not found: ${args.baseline}`;
+      if (!existsSync(args.current)) return `ERROR: current not found: ${args.current}`;
+      let PNG, pixelmatch;
+      try {
+        ({ PNG } = await import("pngjs"));
+        pixelmatch = (await import("pixelmatch")).default;
+      } catch (e) {
+        return `ERROR: visual diff requires pixelmatch + pngjs. Install: npm i -g pngjs pixelmatch (or rerun npm install in multi-agent-toolkit-mcp)`;
+      }
+      const a = PNG.sync.read(readFileSync(args.baseline));
+      const b = PNG.sync.read(readFileSync(args.current));
+      if (a.width !== b.width || a.height !== b.height) {
+        return JSON.stringify({ passed: false, reason: "size_mismatch", baseline_size: `${a.width}x${a.height}`, current_size: `${b.width}x${b.height}` }, null, 2);
+      }
+      const diff = new PNG({ width: a.width, height: a.height });
+      const threshold = args.threshold !== undefined ? args.threshold : 0.1;
+      const diffPixels = pixelmatch(a.data, b.data, diff.data, a.width, a.height, { threshold });
+      const total = a.width * a.height;
+      const diffPct = (diffPixels / total) * 100;
+      const maxPct = args.max_diff_pct !== undefined ? args.max_diff_pct : 1.0;
+      const passed = diffPct <= maxPct;
+      let diffImagePath = null;
+      if (args.output || !passed) {
+        diffImagePath = args.output || join(SCREENSHOT_DIR, `diff-${Date.now()}.png`);
+        writeFileSync(diffImagePath, PNG.sync.write(diff));
+      }
+      const report = JSON.stringify({ passed, diff_pct: parseFloat(diffPct.toFixed(4)), diff_pixels: diffPixels, total_pixels: total, threshold, max_diff_pct: maxPct, baseline: args.baseline, current: args.current, diff_image: diffImagePath }, null, 2);
+      return diffImagePath ? fileResult(report, diffImagePath) : report;
+    }
+    case "ios_list_crashes": {
+      const dir = join(homedir(), "Library", "Logs", "DiagnosticReports");
+      if (!existsSync(dir)) return JSON.stringify({ dir, count: 0, reports: [] }, null, 2);
+      const entries = readdirSync(dir).map((name) => {
+        try {
+          const st = statSync(join(dir, name));
+          return st.isFile() ? { name, mtimeMs: st.mtimeMs, size: st.size } : null;
+        } catch { return null; }
+      }).filter(Boolean);
+      const sinceMs = args.since_min !== undefined ? Date.now() - num(args.since_min, "since_min") * 60000 : undefined;
+      const selected = selectCrashReports(entries, { app: args.app, sinceMs, limit: args.limit !== undefined ? num(args.limit, "limit") : 20 });
+      const reports = selected.map((e) => ({
+        file: join(dir, e.name),
+        process: e.name.replace(/-\d{4}-\d{2}-\d{2}-\d{6}.*$/, ""),
+        modified: new Date(e.mtimeMs).toISOString(),
+        size: e.size,
+      }));
+      return JSON.stringify({ dir, count: reports.length, reports }, null, 2);
+    }
+    default: return null;
+  }
+}
+
+// ── Android Tools ──
+
+// Validation lives inside the flag builder so every call site - including new
+// ones - is covered: a raw `-s ${id}` reached execSync through run(), making a
+// model-controlled device_id a command injection.
+function adbFlag(id) { return id ? `-s ${deviceSerial(id)}` : ""; }
+
+const ANDROID_TOOLS = [
+  { name: "android_list_devices", description: "List connected Android devices and emulators", inputSchema: { type: "object", properties: {} } },
+  { name: "android_screenshot", description: "Capture an Android screenshot. Returns a base64 PNG by default; pass `path` to write the file and return only its location - a base64 image per capture exhausts the caller's context on multi-capture runs.", inputSchema: { type: "object", properties: { device_id: { type: "string" }, path: { type: "string", description: "Absolute file path to write the PNG to. The parent directory must already exist. Returns the path instead of the image." } } } },
+  { name: "android_tap", description: "Tap at coordinates on Android", inputSchema: { type: "object", properties: { x: { type: "number" }, y: { type: "number" }, device_id: { type: "string" } }, required: ["x", "y"] } },
+  { name: "android_swipe", description: "Swipe on Android", inputSchema: { type: "object", properties: { x1: { type: "number" }, y1: { type: "number" }, x2: { type: "number" }, y2: { type: "number" }, duration_ms: { type: "number" }, device_id: { type: "string" } }, required: ["x1", "y1", "x2", "y2"] } },
+  { name: "android_type_text", description: "Type text on Android", inputSchema: { type: "object", properties: { text: { type: "string" }, device_id: { type: "string" } }, required: ["text"] } },
+  { name: "android_key_event", description: "Send Android key event (HOME=3, BACK=4, ENTER=66)", inputSchema: { type: "object", properties: { keycode: { type: "number" }, device_id: { type: "string" } }, required: ["keycode"] } },
+  { name: "android_launch_app", description: "Launch Android app by package name", inputSchema: { type: "object", properties: { package_name: { type: "string" }, activity: { type: "string" }, device_id: { type: "string" } }, required: ["package_name"] } },
+  { name: "android_stop_app", description: "Force-stop Android app", inputSchema: { type: "object", properties: { package_name: { type: "string" }, device_id: { type: "string" } }, required: ["package_name"] } },
+  { name: "android_list_packages", description: "List installed Android packages", inputSchema: { type: "object", properties: { filter: { type: "string" }, device_id: { type: "string" } } } },
+  { name: "android_go_home", description: "Press Android home button", inputSchema: { type: "object", properties: { device_id: { type: "string" } } } },
+  { name: "android_go_back", description: "Press Android back button", inputSchema: { type: "object", properties: { device_id: { type: "string" } } } },
+  { name: "android_get_ui_tree", description: "Dump Android UI hierarchy (uiautomator XML with bounds, text, resource-id). The raw dump is unbounded; pass `path` to write it to a file instead of inlining, or filter:\"interactive\" for a compact JSON list of just the interactive elements (class, text, resource-id, center coords).", inputSchema: { type: "object", properties: { device_id: { type: "string" }, path: { type: "string", description: "Absolute file path to write the dump to: the raw XML, or the filtered JSON when filter is set. The parent directory must already exist." }, filter: { type: "string", enum: ["interactive"], description: "interactive: return only clickable/focusable elements as compact JSON instead of the raw XML" } } } },
+  { name: "android_set_dark_mode", description: "Enable/disable Android dark mode", inputSchema: { type: "object", properties: { enabled: { type: "boolean" }, device_id: { type: "string" } }, required: ["enabled"] } },
+  { name: "android_set_font_scale", description: "Set Android font scale (1.0=normal, 2.0=extra large)", inputSchema: { type: "object", properties: { scale: { type: "number" }, device_id: { type: "string" } }, required: ["scale"] } },
+  { name: "android_set_locale", description: "Set an app's locale (per-app locale, Android 13+/API 33). package_name is needed in practice: the per-app locale API is app-scoped, and device-wide locale change is not reachable over adb without root.", inputSchema: { type: "object", properties: { locale: { type: "string", description: "BCP-47 tag, e.g. tr-TR, en-US" }, package_name: { type: "string", description: "Target app package. Without it the call returns an error instead of silently doing nothing." }, device_id: { type: "string" } }, required: ["locale"] } },
+  { name: "android_set_location", description: "Set mock Android GPS location", inputSchema: { type: "object", properties: { latitude: { type: "number" }, longitude: { type: "number" }, device_id: { type: "string" } }, required: ["latitude", "longitude"] } },
+  { name: "android_grant_permission", description: "Grant Android runtime permission", inputSchema: { type: "object", properties: { package_name: { type: "string" }, permission: { type: "string" }, device_id: { type: "string" } }, required: ["package_name", "permission"] } },
+  { name: "android_revoke_permission", description: "Revoke Android runtime permission", inputSchema: { type: "object", properties: { package_name: { type: "string" }, permission: { type: "string" }, device_id: { type: "string" } }, required: ["package_name", "permission"] } },
+  { name: "android_record_screen", description: "Record the Android screen. action:\"start\" (default) spawns `adb shell screenrecord` in the background and returns immediately; action:\"stop\" ends the recording, pulls the file off the device and returns its local path. One recording per device; screenrecord hard-caps a segment at 180s.", inputSchema: { type: "object", properties: { action: { type: "string", enum: ["start", "stop"], description: "Default start" }, duration: { type: "number", description: "Time limit in seconds (start only, max 180, default 180)" }, path: { type: "string", description: "Local file path to pull the recording to (start only). Default rec_<timestamp>.mp4 in the tool's temp dir." }, device_id: { type: "string" } } } },
+  { name: "android_install_apk", description: "Install APK on Android", inputSchema: { type: "object", properties: { apk_path: { type: "string" }, device_id: { type: "string" } }, required: ["apk_path"] } },
+  { name: "android_uninstall_app", description: "Uninstall Android app", inputSchema: { type: "object", properties: { package_name: { type: "string" }, device_id: { type: "string" } }, required: ["package_name"] } },
+  { name: "android_logcat", description: "Get Android logcat entries", inputSchema: { type: "object", properties: { tag: { type: "string" }, lines: { type: "number" }, device_id: { type: "string" } } } },
+  { name: "android_get_screen_size", description: "Get Android screen resolution", inputSchema: { type: "object", properties: { device_id: { type: "string" } } } },
+  { name: "android_open_url", description: "Open URL or deep link on Android", inputSchema: { type: "object", properties: { url: { type: "string" }, device_id: { type: "string" } }, required: ["url"] } },
+  { name: "android_clear_app_data", description: "Clear all data for Android app", inputSchema: { type: "object", properties: { package_name: { type: "string" }, device_id: { type: "string" } }, required: ["package_name"] } },
+  { name: "android_accessibility_audit", description: "Audit Android app accessibility: missing contentDescription, small touch targets (<48dp), missing resource-id. Use scope to filter by resource-id prefix.", inputSchema: { type: "object", properties: { device_id: { type: "string" }, scope: { type: "string", description: "Filter: only audit elements whose resource-id contains this prefix (e.g. 'login_', 'com.example:id/login_'). Omit to audit all." } } } },
+  { name: "android_launch_time", description: "Measure Android app cold launch time (TotalTime in ms)", inputSchema: { type: "object", properties: { package_name: { type: "string" }, activity: { type: "string" }, device_id: { type: "string" } }, required: ["package_name"] } },
+  { name: "android_apk_audit", description: "Audit APK/AAB for Play Store compliance: debug flag, target SDK, permissions, signing, ProGuard", inputSchema: { type: "object", properties: { apk_path: { type: "string", description: "Path to .apk file" } }, required: ["apk_path"] } },
+  { name: "android_list_crashes", description: "Dump the Android crash log buffer (`adb logcat -b crash -d`), tail-bounded. Empty output means no crashes since the buffer was last cleared.", inputSchema: { type: "object", properties: { lines: { type: "number", description: "Max lines returned, from the end (default 200)" }, device_id: { type: "string" } } } },
+  { name: "android_set_orientation", description: "Rotate the Android screen to portrait or landscape. Disables accelerometer rotation and pins user_rotation, so the device stays put until rotation is re-enabled. Accounts for the device's natural orientation (detected via wm size), so landscape-natural tablets rotate correctly too. No iOS counterpart: simctl exposes no rotation lever.", inputSchema: { type: "object", properties: { orientation: { type: "string", enum: ["portrait", "landscape"] }, device_id: { type: "string" } }, required: ["orientation"] } },
+];
+
+async function handleAndroid(name, args, ctx = {}) {
+  if (!HAS_ADB) return `${ERROR_PREFIX}Android SDK not installed - adb not on PATH, so Android tools cannot run. Install platform-tools and ensure adb is on PATH.`;
+  const df = adbFlag(args.device_id);
+
+  switch (name) {
+    case "android_list_devices": return run("adb devices -l");
+    case "android_screenshot": {
+      const f = args.path ? String(args.path) : join(SCREENSHOT_DIR, `android_${Date.now()}.png`);
+      if (args.path) {
+        const parent = dirname(f);
+        if (!existsSync(parent)) return `${ERROR_PREFIX}directory does not exist: ${parent}`;
+      }
+      run(`adb ${df} shell screencap -p /sdcard/_mcp_screen.png`);
+      run(`adb ${df} pull /sdcard/_mcp_screen.png ${shq(f)}`);
+      run(`adb ${df} shell rm /sdcard/_mcp_screen.png`);
+      if (!existsSync(f)) return "ERROR: Screenshot failed";
+      if (args.path) return fileResult(`Screenshot written: ${f}`, f);
+      const buf = readFileSync(f);
+      return { type: "image", data: buf.toString("base64"), mimeType: "image/png", path: f };
+    }
+    case "android_tap": return run(`adb ${df} shell input tap ${num(args.x, "x")} ${num(args.y, "y")}`) || `Tapped (${args.x}, ${args.y})`;
+    case "android_swipe": return run(`adb ${df} shell input swipe ${num(args.x1, "x1")} ${num(args.y1, "y1")} ${num(args.x2, "x2")} ${num(args.y2, "y2")} ${num(args.duration_ms || 300, "duration_ms")}`) || "Swiped";
+    // `adb shell input text` wants spaces as %s; single-quote the result so the
+    // remaining characters cannot reach the shell as syntax.
+    case "android_type_text": return run(`adb ${df} shell input text ${shq(String(args.text ?? "").replace(/ /g, "%s"))}`) || `Typed: ${args.text}`;
+    case "android_key_event": return run(`adb ${df} shell input keyevent ${token(args.keycode, "keycode")}`) || `Key ${args.keycode}`;
+    case "android_launch_app": return args.activity ? run(`adb ${df} shell am start -n ${sanitizeId(args.package_name)}/${sanitizeId(args.activity)}`) : run(`adb ${df} shell monkey -p ${sanitizeId(args.package_name)} -c android.intent.category.LAUNCHER 1`) || `Launched`;
+    case "android_stop_app": return run(`adb ${df} shell am force-stop ${sanitizeId(args.package_name)}`) || "Stopped";
+    case "android_list_packages": { const out = run(`adb ${df} shell pm list packages`); return args.filter ? out.split("\n").filter(l => l.toLowerCase().includes(args.filter.toLowerCase())).join("\n") : out; }
+    case "android_go_home": return run(`adb ${df} shell input keyevent 3`) || "Home";
+    case "android_go_back": return run(`adb ${df} shell input keyevent 4`) || "Back";
+    case "android_get_ui_tree": {
+      const f = args.path ? String(args.path) : join(SCREENSHOT_DIR, `ui_${Date.now()}.xml`);
+      if (args.path) {
+        const parent = dirname(f);
+        if (!existsSync(parent)) return `${ERROR_PREFIX}directory does not exist: ${parent}`;
+      }
+      run(`adb ${df} shell uiautomator dump /sdcard/_mcp_ui.xml`);
+      run(`adb ${df} pull /sdcard/_mcp_ui.xml ${shq(f)}`);
+      run(`adb ${df} shell rm /sdcard/_mcp_ui.xml`);
+      if (!existsSync(f)) return "ERROR: UI dump failed";
+      if (args.filter === "interactive") {
+        const elements = interactiveElements(readFileSync(f, "utf-8"));
+        const report = JSON.stringify({ filter: "interactive", count: elements.length, elements }, null, 2);
+        // The persisted file must match the returned text: leaving the raw XML
+        // at `path` attached a resource_link to content the tool never showed.
+        if (args.path) {
+          writeFileSync(f, report);
+          return fileResult(report, f);
+        }
+        return report;
+      }
+      return args.path ? fileResult(`UI tree written: ${f}`, f) : readFileSync(f, "utf-8");
+    }
+    case "android_set_dark_mode": return run(`adb ${df} shell cmd uimode night ${args.enabled ? "yes" : "no"}`) || `Dark mode: ${args.enabled}`;
+    case "android_set_font_scale": return run(`adb ${df} shell settings put system font_scale ${num(args.scale, "scale")}`) || `Font scale: ${args.scale}`;
+    // The old SET_LOCALE broadcast is a dead pre-Android-7 mechanism: `am
+    // broadcast` exits 0 even when nothing handles the intent, and the previous
+    // implementation also sent stderr to /dev/null, so it reported success
+    // unconditionally. `cmd locale set-app-locales` is the supported per-app
+    // path (API 33+). Device-wide locale needs root and is out of scope.
+    case "android_set_locale": {
+      const pkg = sanitizeId(args.package_name);
+      if (!pkg) return `${ERROR_PREFIX}android_set_locale requires package_name (per-app locale API is app-scoped)`;
+      const locale = String(args.locale || "");
+      if (!/^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$/.test(locale)) {
+        return `${ERROR_PREFIX}invalid locale tag "${locale}" (expected BCP-47, e.g. tr-TR)`;
+      }
+      const out = run(`adb ${df} shell cmd locale set-app-locales ${pkg} --locales ${locale}`);
+      if (isFailure(out)) return out;
+      // `cmd` prints usage or an Exception on an unsupported platform rather
+      // than exiting non-zero, so inspect the output before claiming success.
+      if (/Unknown command|Exception|usage:/i.test(out)) {
+        return `${ERROR_PREFIX}per-app locale not supported on this device (needs API 33+). Device said: ${out.replace(/\s+/g, " ").slice(0, 300)}`;
+      }
+      // Read the locale back and COMPARE it. The previous form reported the
+      // REQUESTED value as fact and put the device's answer in a parenthetical,
+      // so a device that accepted the command but applied a different locale (or
+      // none at all) still read as success - the same report-without-checking
+      // shape the `Unknown command` branch above was added to remove.
+      const verify = run(`adb ${df} shell cmd locale get-app-locales ${pkg}`);
+      if (isFailure(verify)) {
+        return `${ERROR_PREFIX}set ${locale} for ${pkg} but could not read it back to confirm: ${verify}`;
+      }
+      const reported = verify.replace(/\s+/g, " ").trim();
+      // Output looks like `Locales for com.x for user 0 are [tr-TR]`. Compare
+      // case-insensitively, and accept the device answering with a more specific
+      // tag than asked for (`tr` -> `tr-TR`), which is correct, not a mismatch.
+      const bracketed = /\[([^\]]*)\]/.exec(reported)?.[1] ?? reported;
+      const want = locale.toLowerCase();
+      const got = bracketed.toLowerCase();
+      if (!(got === want || got.startsWith(`${want}-`) || want.startsWith(`${got}-`))) {
+        return `${ERROR_PREFIX}per-app locale not applied: asked for ${locale}, device reports "${reported.slice(0, 200)}"`;
+      }
+      return `Locale for ${pkg}: ${locale} (verified: ${bracketed})`;
+    }
+    case "android_set_location": return run(`adb ${df} emu geo fix ${num(args.longitude, "longitude")} ${num(args.latitude, "latitude")}`) || `Location set`;
+    case "android_grant_permission": return run(`adb ${df} shell pm grant ${sanitizeId(args.package_name)} ${token(args.permission, "permission")}`) || "Granted";
+    case "android_revoke_permission": return run(`adb ${df} shell pm revoke ${sanitizeId(args.package_name)} ${token(args.permission, "permission")}`) || "Revoked";
+    case "android_record_screen": {
+      const key = `android:${args.device_id || "default"}`;
+      if ((args.action || "start") === "stop") {
+        const rec = RECORDINGS.get(key);
+        if (!rec) return `${ERROR_PREFIX}no active Android recording${args.device_id ? ` on ${args.device_id}` : ""}. Start one with action:"start".`;
+        // SIGINT to screenrecord on the device is the supported stop: it makes
+        // the recorder finalize the mp4. Killing the local adb client does not
+        // reliably reach the remote process.
+        run(`adb ${df} shell pkill -2 screenrecord || adb ${df} shell kill -2 \\$(pidof screenrecord)`);
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+        try { rec.child.kill("SIGTERM"); } catch {}
+        rec.exited = true;
+        // The remote file is deleted, and the map entry released, only after a
+        // confirmed pull: rm-then-check lost the recording irrecoverably on a
+        // transient pull failure. Keeping the entry lets stop be retried.
+        const pull = run(`adb ${df} pull ${shq(rec.remotePath)} ${shq(rec.path)}`, { timeout: 60000 });
+        if (isFailure(pull)) return `${pull}\nThe recording is still on the device at ${rec.remotePath}; call action:"stop" again to retry the pull.`;
+        if (!existsSync(rec.path)) return `${ERROR_PREFIX}pull produced no file at ${rec.path}. The recording is still on the device at ${rec.remotePath}; call action:"stop" again to retry.`;
+        run(`adb ${df} shell rm -f ${shq(rec.remotePath)}`);
+        RECORDINGS.delete(key);
+        return fileResult(`Recording saved: ${rec.path}`, rec.path);
+      }
+      const existing = RECORDINGS.get(key);
+      if (existing) {
+        // The entry deliberately survives child exit (screenrecord self-stops at
+        // its 180s cap) so stop can still pull the file - but a start after that
+        // exit must not claim a recording is running when none is.
+        if (existing.exited) return `${ERROR_PREFIX}the previous recording finished but was not collected. Call action:"stop" to pull it before starting a new one.`;
+        return `${ERROR_PREFIX}a recording is already running${args.device_id ? ` on ${args.device_id}` : ""}. Stop it first with action:"stop".`;
+      }
+      const dur = Math.min(num(args.duration || 180, "duration"), 180);
+      const remotePath = `/sdcard/_mcp_rec_${Date.now()}.mp4`;
+      const localPath = args.path ? String(args.path) : join(SCREENSHOT_DIR, `rec_${Date.now()}.mp4`);
+      const parent = dirname(localPath);
+      if (!existsSync(parent)) return `${ERROR_PREFIX}directory does not exist: ${parent}`;
+      const argv = [...(args.device_id ? ["-s", deviceSerial(args.device_id)] : []), "shell", "screenrecord", "--time-limit", String(dur), remotePath];
+      const child = spawn("adb", argv, { stdio: "ignore" });
+      const entry = { child, remotePath, path: localPath, exited: false };
+      child.once("close", () => { if (RECORDINGS.get(key) === entry) entry.exited = true; });
+      RECORDINGS.set(key, entry);
+      return `Recording started (pid ${child.pid}, limit ${dur}s) -> ${localPath}\nCall android_record_screen with action:"stop" to finish.`;
+    }
+    case "android_install_apk": return await runAsync(`adb ${df} install -r ${shq(args.apk_path)}`, { timeout: 120000, signal: ctx.signal }) || "Installed";
+    case "android_uninstall_app": return run(`adb ${df} shell pm uninstall ${sanitizeId(args.package_name)}`) || "Uninstalled";
+    case "android_logcat": { const lines = args.lines !== undefined ? num(args.lines, "lines") : 50; const tf = args.tag ? `| grep -i ${shq(args.tag)}` : ""; return run(`adb ${df} logcat -d ${tf} | tail -${lines}`); }
+    case "android_get_screen_size": return run(`adb ${df} shell wm size`);
+    case "android_open_url": return run(`adb ${df} shell am start -a android.intent.action.VIEW -d ${shq(args.url)}`) || `Opened: ${args.url}`;
+    case "android_clear_app_data": return run(`adb ${df} shell pm clear ${sanitizeId(args.package_name)}`) || "Cleared";
+    case "android_accessibility_audit": {
+      run(`adb ${df} shell uiautomator dump /sdcard/_mcp_a11y.xml`);
+      const f = join(SCREENSHOT_DIR, `a11y_${Date.now()}.xml`);
+      run(`adb ${df} pull /sdcard/_mcp_a11y.xml ${shq(f)}`);
+      run(`adb ${df} shell rm /sdcard/_mcp_a11y.xml`);
+      if (!existsSync(f)) return "ERROR: UI dump failed";
+      const xml = readFileSync(f, "utf-8");
+      const scope = args.scope || null;
+      const issues = [];
+      let totalScanned = 0, totalSkipped = 0;
+      const nodeRegex = /<node[^>]*>/g;
+      let match;
+      while ((match = nodeRegex.exec(xml)) !== null) {
+        const node = match[0];
+        const cls = node.match(/class="([^"]*)"/)?.[1] || "";
+        const desc = node.match(/content-desc="([^"]*)"/)?.[1] || "";
+        const rid = node.match(/resource-id="([^"]*)"/)?.[1] || "";
+        const text = node.match(/text="([^"]*)"/)?.[1] || "";
+        const clickable = node.includes('clickable="true"');
+        const bounds = node.match(/bounds="\[(\d+),(\d+)\]\[(\d+),(\d+)\]"/);
+        if (clickable) {
+          if (scope && rid && !rid.includes(scope)) { totalSkipped++; continue; }
+          totalScanned++;
+          if (!desc && !text) issues.push({ severity: "critical", issue: "Missing contentDescription", element: cls, resourceId: rid });
+          if (!rid) issues.push({ severity: "warning", issue: "Missing resource-id (UI testing)", element: cls });
+          if (bounds) {
+            const w = parseInt(bounds[3]) - parseInt(bounds[1]);
+            const h = parseInt(bounds[4]) - parseInt(bounds[2]);
+            if (w < 48 || h < 48) issues.push({ severity: "important", issue: `Touch target too small: ${w}x${h}dp (min 48x48)`, element: cls, resourceId: rid });
+          }
+        }
+      }
+      return JSON.stringify({ scope: scope || "all", elements_scanned: totalScanned, elements_skipped: totalSkipped, total_issues: issues.length, critical: issues.filter(i => i.severity === "critical").length, important: issues.filter(i => i.severity === "important").length, warning: issues.filter(i => i.severity === "warning").length, issues }, null, 2);
+    }
+    case "android_launch_time": {
+      run(`adb ${df} shell am force-stop ${sanitizeId(args.package_name)}`);
+      const activity = sanitizeId(args.activity || `${args.package_name}/.MainActivity`);
+      const result = run(`adb ${df} shell am start -W -n ${activity} 2>&1`);
+      const totalTime = result.match(/TotalTime:\s*(\d+)/)?.[1];
+      const waitTime = result.match(/WaitTime:\s*(\d+)/)?.[1];
+      return JSON.stringify({ package: args.package_name, cold_start: true, total_time_ms: totalTime ? parseInt(totalTime) : null, wait_time_ms: waitTime ? parseInt(waitTime) : null, raw: result }, null, 2);
+    }
+    case "android_apk_audit": {
+      const p = args.apk_path;
+      if (!existsSync(p)) return `ERROR: APK not found at ${p}`;
+      const findings = [];
+      // 1. Basic info via aapt2
+      const aapt = run(`aapt2 dump badging ${shq(p)} 2>/dev/null`) || run(`aapt dump badging ${shq(p)} 2>/dev/null`);
+      if (aapt) {
+        const pkg = aapt.match(/package: name='([^']*)'/)?.[1];
+        const versionName = aapt.match(/versionName='([^']*)'/)?.[1];
+        const versionCode = aapt.match(/versionCode='([^']*)'/)?.[1];
+        const targetSdk = aapt.match(/targetSdkVersion:'(\d+)'/)?.[1];
+        const minSdk = aapt.match(/sdkVersion:'(\d+)'/)?.[1];
+        findings.push({ check: "package", value: pkg, status: "info" });
+        findings.push({ check: "version", value: `${versionName} (${versionCode})`, status: "info" });
+        findings.push({ check: "target_sdk", value: targetSdk, status: targetSdk && parseInt(targetSdk) >= 34 ? "pass" : "warning", detail: targetSdk && parseInt(targetSdk) < 34 ? `Target SDK ${targetSdk} - Google Play requires 34+ for new apps` : "OK" });
+        findings.push({ check: "min_sdk", value: minSdk, status: "info" });
+        // Permissions audit
+        const perms = [...aapt.matchAll(/uses-permission: name='([^']*)'/g)].map(m => m[1]);
+        const dangerousPerms = perms.filter(p => /(CAMERA|CONTACTS|LOCATION|MICROPHONE|PHONE|SMS|STORAGE|CALENDAR)/.test(p));
+        findings.push({ check: "permissions", value: `${perms.length} total, ${dangerousPerms.length} dangerous`, status: dangerousPerms.length > 5 ? "warning" : "info", detail: dangerousPerms.join(", ") || "None dangerous" });
+        // Debuggable check
+        const debuggable = aapt.includes("application-debuggable");
+        findings.push({ check: "debuggable", status: debuggable ? "critical" : "pass", detail: debuggable ? "App is DEBUGGABLE - Play Store will reject" : "Not debuggable - OK" });
+      } else {
+        findings.push({ check: "aapt", status: "warning", detail: "aapt2/aapt not found - install Android SDK Build-Tools for full audit" });
+      }
+      // 2. Signing check
+      const signingInfo = run(`apksigner verify --print-certs ${shq(p)} 2>&1`);
+      if (signingInfo && !signingInfo.includes("ERROR")) {
+        const hasV2 = signingInfo.includes("v2 scheme") || run(`apksigner verify -v ${shq(p)} 2>&1`)?.includes("Verified using v2");
+        findings.push({ check: "signing", status: "pass", detail: "APK is signed" });
+        findings.push({ check: "signing_v2", status: hasV2 ? "pass" : "warning", detail: hasV2 ? "v2+ signature present" : "Only v1 signature - consider v2+ for tamper protection" });
+      } else {
+        findings.push({ check: "signing", status: signingInfo?.includes("DOES NOT VERIFY") ? "critical" : "warning", detail: signingInfo || "apksigner not found" });
+      }
+      // 3. File size
+      try { const stat = run(`stat -f "%z" ${shq(p)} 2>/dev/null`) || run(`stat -c "%s" ${shq(p)} 2>/dev/null`); if (stat) { const mb = parseInt(stat) / 1048576; findings.push({ check: "apk_size", value: `${mb.toFixed(1)} MB`, status: mb > 150 ? "warning" : "pass", detail: mb > 150 ? "APK > 150MB - consider App Bundle (.aab)" : "OK" }); } } catch {}
+      // 4. ProGuard/R8 check
+      const hasMapping = run(`unzip -l ${shq(p)} 2>/dev/null | grep -c "classes.dex"`)?.trim();
+      const dexCount = parseInt(hasMapping) || 0;
+      findings.push({ check: "dex_files", value: `${dexCount} dex file(s)`, status: dexCount > 3 ? "warning" : "info", detail: dexCount > 3 ? "Many DEX files - ensure R8/ProGuard minification is enabled" : "OK" });
+      // Summary
+      const critical = findings.filter(f => f.status === "critical").length;
+      const warnings = findings.filter(f => f.status === "warning").length;
+      return JSON.stringify({ apk: p, summary: { critical, warnings, passed: findings.filter(f => f.status === "pass").length, total_checks: findings.length }, verdict: critical > 0 ? "FAIL - critical issues must be fixed" : warnings > 0 ? "WARN - review warnings" : "PASS - ready for Play Store", findings }, null, 2);
+    }
+    case "android_list_crashes": {
+      const lines = args.lines !== undefined ? num(args.lines, "lines") : 200;
+      const out = run(`adb ${df} logcat -b crash -d | tail -${lines}`);
+      if (isFailure(out)) return out;
+      return out.trim() || "No crashes in the crash buffer.";
+    }
+    case "android_set_orientation": {
+      const base = { portrait: 0, landscape: 1 }[args.orientation];
+      if (base === undefined) return `${ERROR_PREFIX}orientation must be portrait or landscape`;
+      // user_rotation counts from the device's NATURAL orientation, which on
+      // many tablets is landscape - a hardcoded {portrait:0, landscape:1}
+      // inverts the result there. `wm size` reports the rotation-independent
+      // physical size, so width > height identifies a landscape-natural panel.
+      // If the probe yields nothing, fall back to assuming portrait-natural.
+      const size = run(`adb ${df} shell wm size`);
+      const dims = /Physical size:\s*(\d+)x(\d+)/.exec(size);
+      const landscapeNatural = dims ? Number(dims[1]) > Number(dims[2]) : false;
+      const rotation = landscapeNatural ? 1 - base : base;
+      const lock = run(`adb ${df} shell settings put system accelerometer_rotation 0`);
+      if (isFailure(lock)) return lock;
+      const rotate = run(`adb ${df} shell settings put system user_rotation ${rotation}`);
+      return isFailure(rotate) ? rotate : `Orientation: ${args.orientation} (auto-rotate disabled${landscapeNatural ? ", landscape-natural device detected" : ""})`;
+    }
+    default: return null;
+  }
+}
+
+// ── Web Automation Tools (Playwright-powered) ──
+
+// Playwright is an optional peer dependency. Single browser instance, lazy-loaded.
+// Tools return a clear message if Playwright is not installed.
+
+let _browser = null;
+let _page = null;
+
+async function ensureBrowser(browserType = "chromium") {
+  if (_browser && _page) return _page;
+  let pw;
+  try {
+    pw = await import("playwright");
+  } catch {
+    throw new Error("Web tools require Playwright. Install once with: npm i -g playwright && npx playwright install chromium");
+  }
+  const engines = { chromium: pw.chromium, webkit: pw.webkit, firefox: pw.firefox };
+  const engine = engines[browserType] || pw.chromium;
+  _browser = await engine.launch({ headless: true });
+  const ctx = await _browser.newContext();
+  _page = await ctx.newPage();
+  return _page;
+}
+
+async function closeBrowser() {
+  try { await _page?.context()?.close(); } catch {}
+  try { await _browser?.close(); } catch {}
+  _page = null;
+  _browser = null;
+}
+
+const WEB_TOOLS = [
+  { name: "web_goto", description: "Open a URL in a headless browser (Playwright). Reuses a single browser instance across calls.", inputSchema: { type: "object", properties: { url: { type: "string" }, browser: { type: "string", enum: ["chromium", "webkit", "firefox"], description: "Default chromium; use webkit for Safari-like behavior" }, wait_until: { type: "string", enum: ["load", "domcontentloaded", "networkidle"] } }, required: ["url"] } },
+  { name: "web_screenshot", description: "Capture a screenshot of the current page. Returns a base64 PNG by default; pass `path` to write the file and return only its location.", inputSchema: { type: "object", properties: { full_page: { type: "boolean" }, path: { type: "string", description: "Absolute file path to write the PNG to. The parent directory must already exist. Returns the path instead of the image." } } } },
+  { name: "web_click", description: "Click an element by CSS selector or text. Auto-waits for element.", inputSchema: { type: "object", properties: { selector: { type: "string", description: "CSS selector, or 'text=...' / 'role=...'" }, timeout_ms: { type: "number" } }, required: ["selector"] } },
+  { name: "web_type", description: "Type text into an input matched by selector.", inputSchema: { type: "object", properties: { selector: { type: "string" }, text: { type: "string" }, clear_first: { type: "boolean" } }, required: ["selector", "text"] } },
+  { name: "web_eval", description: "Run arbitrary JavaScript in the page context and return the result as JSON.", inputSchema: { type: "object", properties: { script: { type: "string", description: "JS expression or function body (use `return ...`)" } }, required: ["script"] } },
+  { name: "web_wait_for", description: "Wait for a selector to appear (or a timeout).", inputSchema: { type: "object", properties: { selector: { type: "string" }, timeout_ms: { type: "number" }, state: { type: "string", enum: ["attached", "detached", "visible", "hidden"] } }, required: ["selector"] } },
+  { name: "web_get_text", description: "Extract textContent of the first match of a selector.", inputSchema: { type: "object", properties: { selector: { type: "string" } }, required: ["selector"] } },
+  { name: "web_close", description: "Close the current browser context and release resources.", inputSchema: { type: "object", properties: {} } },
+];
+
+async function handleWeb(name, args) {
+  if (name === "web_close") { await closeBrowser(); return "Browser closed"; }
+  const page = await ensureBrowser(args.browser);
+  switch (name) {
+    case "web_goto": {
+      await page.goto(args.url, { waitUntil: args.wait_until || "load", timeout: 30000 });
+      return `Opened ${args.url} (title: "${await page.title()}")`;
+    }
+    case "web_screenshot": {
+      const path = args.path ? String(args.path) : join(SCREENSHOT_DIR, `web_${Date.now()}.png`);
+      if (args.path && !existsSync(dirname(path))) return `${ERROR_PREFIX}directory does not exist: ${dirname(path)}`;
+      const buf = await page.screenshot({ fullPage: args.full_page ?? true });
+      writeFileSync(path, buf);
+      if (args.path) return fileResult(`Screenshot written: ${path}`, path);
+      return { type: "image", data: buf.toString("base64"), mimeType: "image/png", path };
+    }
+    case "web_click": {
+      await page.click(args.selector, { timeout: args.timeout_ms || 5000 });
+      return `Clicked: ${args.selector}`;
+    }
+    case "web_type": {
+      if (args.clear_first) await page.fill(args.selector, "");
+      await page.fill(args.selector, args.text);
+      return `Typed into ${args.selector}: ${args.text.length} chars`;
+    }
+    case "web_eval": {
+      const fn = args.script.includes("return ") ? `(() => { ${args.script} })()` : args.script;
+      const result = await page.evaluate(fn);
+      return JSON.stringify(result);
+    }
+    case "web_wait_for": {
+      await page.waitForSelector(args.selector, { timeout: args.timeout_ms || 5000, state: args.state || "visible" });
+      return `${args.selector} is ${args.state || "visible"}`;
+    }
+    case "web_get_text": {
+      const text = await page.locator(args.selector).first().textContent();
+      return text ?? "";
+    }
+    default: return null;
+  }
+}
+
+// ── Autonomous Agent DSL (batch step execution) ──
+
+const AGENT_TOOLS = [
+  {
+    name: "agent_run_steps",
+    description: "Execute a sequence of device/web/design actions as a single batch. Each step is {tool: <ios_* | android_* | web_* | design_* tool name>, args: {...}, continue_on_error?: bool, wait_ms?: number}. Returns per-step status plus a verdict. A step whose command fails is reported status \"error\"; unless it sets continue_on_error the batch stops there and the result is flagged as an error. Nested agent_* steps are refused. Use this to script multi-step flows (login, navigation, form fill) without multiple MCP round trips.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        steps: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              tool: { type: "string", description: "Name of an ios_* / android_* / web_* / design_* tool" },
+              args: { type: "object" },
+              continue_on_error: { type: "boolean", description: "If true, record the error and move on. Default false." },
+              wait_ms: { type: "number", description: "Sleep this many ms after this step before the next one." },
+            },
+            required: ["tool"],
+          },
+          description: "Ordered list of steps",
+        },
+        stop_on_first_error: { type: "boolean", description: "Default true. Set false to run every step regardless." },
+      },
+      required: ["steps"],
+    },
+  },
+];
+
+// design_* is dispatched here too: the tool description offers it, and a design
+// audit is a legitimate step in a scripted flow. agent_* is refused on purpose -
+// a batch able to nest itself has no recursion bound.
+async function dispatchStep(tool, stepArgs) {
+  if (tool.startsWith("agent_")) throw new Error(`Nested batch steps are not supported: ${tool}`);
+  let result;
+  if (tool.startsWith("ios_")) result = await handleIOS(tool, stepArgs);
+  else if (tool.startsWith("android_")) result = await handleAndroid(tool, stepArgs);
+  else if (tool.startsWith("web_")) result = await handleWeb(tool, stepArgs);
+  else if (tool.startsWith("design_")) result = await handleDesign(tool, stepArgs, designCtx);
+  else throw new Error(`Unknown tool: ${tool}`);
+  // Every handler's `default:` arm returns null, and that is its only source of
+  // null, so null means "I do not recognise this tool". The throw below used to
+  // fire only for a name matching no prefix at all, so a typo that kept the
+  // family - ios_taap, design_reprot - fell through to the handler, came back
+  // null, and was recorded as a step with status "ok" and result "null". Same
+  // false-success class as the batch runner not applying isFailure().
+  if (result === null || result === undefined) throw new Error(`Unknown tool: ${tool}`);
+  return result;
+}
+
+async function handleAgent(name, args) {
+  if (name !== "agent_run_steps") return null;
+  const steps = Array.isArray(args.steps) ? args.steps : [];
+  const stopOnError = args.stop_on_first_error !== false;
+  const results = [];
+  let aborted = false;
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    const stepArgs = step.args || {};
+    let outcome;
+    try {
+      const result = await dispatchStep(step.tool, stepArgs);
+      // A failing CLI does not throw: run() returns the ERROR_PREFIX marker
+      // string instead. The CallTool handler makes that judgement with
+      // isFailure() before answering the host, and the batch has to make the
+      // same one - reading the marker as a successful result reported a broken
+      // step as status "ok", left errors at 0, published verdict "all_ok", and
+      // silently defeated stop_on_first_error.
+      if (isFailure(result)) {
+        outcome = {
+          step: i + 1,
+          tool: step.tool,
+          status: "error",
+          error: String(result).slice(ERROR_PREFIX.length),
+        };
+      } else {
+        outcome = {
+          step: i + 1,
+          tool: step.tool,
+          status: "ok",
+          result: typeof result === "object"
+            ? (result?.type === "file" ? String(result.text).slice(0, 500) : "(binary)")
+            : String(result).slice(0, 500),
+        };
+      }
+    } catch (e) {
+      outcome = { step: i + 1, tool: step.tool, status: "error", error: truncateError(e.message) };
+    }
+    results.push(outcome);
+    if (outcome.status === "error" && !step.continue_on_error && stopOnError) {
+      aborted = true;
+      break;
+    }
+    if (step.wait_ms) await new Promise((r) => setTimeout(r, step.wait_ms));
+  }
+  const errors = results.filter((r) => r.status === "error").length;
+  const text = JSON.stringify(
+    {
+      total_steps: steps.length,
+      executed: results.length,
+      errors,
+      verdict: errors === 0 ? "all_ok" : errors === results.length ? "all_failed" : "partial",
+      aborted,
+      results,
+    },
+    null,
+    2,
+  );
+  // An abort is an unambiguous failure of the batch as requested, so the host
+  // sees isError. Errors the caller opted into with continue_on_error are not -
+  // there the verdict carries the nuance and the call itself succeeded.
+  return { type: "batch", text, isError: aborted };
+}
+
+// ── Server ──
+
+const ALL_TOOLS = [...IOS_TOOLS, ...ANDROID_TOOLS, ...WEB_TOOLS, ...AGENT_TOOLS, ...DESIGN_TOOLS];
+
+// Name -> inputSchema, so the CallTool boundary can enforce the declared shape.
+const TOOL_SCHEMAS = new Map(ALL_TOOLS.map((t) => [t.name, t.inputSchema || {}]));
+
+// Minimal JSON-Schema-subset validator. The low-level MCP Server does NOT check
+// arguments against inputSchema, so every declared `type`/`enum`/`required` was
+// documentation only - a string reached a handler that interpolated it as a
+// number, which is the root cause of the shell-injection class. This enforces
+// the declared contract at the one boundary every tool passes through. Zero
+// dependencies (no ajv): supports type (string/number/integer/boolean/array/
+// object), required, and enum - the only constructs the tool schemas use.
+function schemaTypeOk(value, type) {
+  switch (type) {
+    // A scalar is a fine string (paths/schemes have always arrived as strings,
+    // and a number/boolean stringifies harmlessly). Reject only arrays/objects.
+    case "string": return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+    // Lenient-but-safe: accept a numeric string ("50") the way callers have
+    // always sent it, but reject anything that is not a finite number ("50; rm"
+    // -> NaN -> rejected). This is what blocks the shell-injection class without
+    // breaking a caller that passes numbers as JSON strings.
+    case "number": return typeof value !== "object" && value !== "" && Number.isFinite(Number(value));
+    case "integer": return typeof value !== "object" && value !== "" && Number.isInteger(Number(value));
+    case "boolean": return typeof value === "boolean";
+    case "array": return Array.isArray(value);
+    case "object": return value !== null && typeof value === "object" && !Array.isArray(value);
+    default: return true; // unknown/absent type: accept
+  }
+}
+
+function validateArgs(name, args) {
+  const schema = TOOL_SCHEMAS.get(name);
+  if (!schema || schema.type !== "object") return null;
+  const props = schema.properties || {};
+  for (const req of schema.required || []) {
+    if (args[req] === undefined || args[req] === null) {
+      return `missing required argument: ${req}`;
+    }
+  }
+  for (const [key, spec] of Object.entries(props)) {
+    if (args[key] === undefined || args[key] === null) continue;
+    if (spec.type && !schemaTypeOk(args[key], spec.type)) {
+      return `argument '${key}' must be ${spec.type}, got ${Array.isArray(args[key]) ? "array" : typeof args[key]}`;
+    }
+    if (Array.isArray(spec.enum) && !spec.enum.includes(args[key])) {
+      return `argument '${key}' must be one of ${JSON.stringify(spec.enum)}`;
+    }
+  }
+  return null;
+}
+
+// Tool annotations (MCP 2025-11-25). Hosts use these for permission prompts and
+// for deciding what may run unattended, so the classification lives here in one
+// auditable place rather than inline on every tool literal.
+const READ_ONLY_TOOLS = new Set([
+  "ios_list_devices", "ios_screenshot", "ios_list_apps", "ios_get_ui_tree", "ios_get_app_container",
+  "ios_accessibility_audit", "ios_archive_audit", "ios_app_store_audit", "ios_xcresult", "ios_visual_diff",
+  "ios_list_crashes",
+  "android_list_devices", "android_screenshot", "android_get_ui_tree", "android_list_packages",
+  "android_logcat", "android_get_screen_size", "android_accessibility_audit", "android_apk_audit",
+  "android_list_crashes",
+  "web_screenshot", "web_get_text",
+  "design_mock_detect", "design_scenario_inventory", "design_ui_geometry", "design_visual_compare",
+]);
+
+// Irreversible on the target device: data loss the caller cannot undo.
+const DESTRUCTIVE_TOOLS = new Set([
+  "ios_erase_device", "ios_keychain_reset", "ios_reset_permissions",
+  "android_clear_app_data", "android_uninstall_app",
+  // android_install_apk uses `-r` (reinstall), overwriting an installed app;
+  // ios_add_media writes into the simulator photo library. Both mutate device
+  // state, so destructiveHint:false was a stronger claim than the spec default.
+  "android_install_apk", "ios_add_media",
+]);
+
+// Repeating the call lands the device in the same state.
+const IDEMPOTENT_TOOLS = new Set([
+  "ios_boot_device", "ios_go_home", "ios_terminate_app", "ios_set_appearance", "ios_set_content_size",
+  "ios_set_locale", "ios_set_location", "ios_clear_location", "ios_set_increase_contrast",
+  "ios_status_bar", "ios_grant_permission", "ios_revoke_permission",
+  "android_go_home", "android_stop_app", "android_set_dark_mode", "android_set_font_scale",
+  "android_set_locale", "android_set_location", "android_grant_permission", "android_revoke_permission",
+  "android_set_orientation",
+  "web_close",
+]);
+
+// Web tools reach arbitrary sites; everything else talks to a local simulator,
+// emulator, archive or build output.
+const withAnnotations = (tool) => ({
+  ...tool,
+  annotations: {
+    readOnlyHint: READ_ONLY_TOOLS.has(tool.name),
+    destructiveHint: DESTRUCTIVE_TOOLS.has(tool.name),
+    idempotentHint: IDEMPOTENT_TOOLS.has(tool.name),
+    // agent_run_steps dispatches web_* steps, so it reaches the open web too.
+    openWorldHint: tool.name.startsWith("web_") || tool.name === "agent_run_steps",
+  },
+});
+
+// -- outputSchema + structuredContent --
+//
+// The 2026-07-28 spec makes outputSchema a full JSON Schema 2020-12 and lets
+// structuredContent be any JSON value. Declaring it turns a payload from "text
+// the model has to parse" into a contract the host can validate, and it is what
+// lets a caller rely on a field being there.
+//
+// Only tools whose shape was read off the return statement are listed. A schema
+// that does not match the payload is worse than no schema, because the host
+// rejects a perfectly good result, so these are deliberately absent until their
+// shape is pinned:
+//
+//   ios_xcresult          four shapes depending on mode
+//   ios_app_store_audit   the object is built in tools/ios-app-store-audit
+//   design_mock_detect, design_scenario_inventory, design_visual_compare,
+//   design_report         built in tools/design-check
+//   web_eval              returns whatever the evaluated expression produced
+//
+// Text content stays on every result, so a host that ignores structuredContent
+// sees no change.
+
+const ISSUE_LIST = {
+  type: "array",
+  items: {
+    type: "object",
+    properties: {
+      severity: { type: "string", enum: ["critical", "important", "warning"] },
+      message: { type: "string" },
+    },
+  },
+};
+
+const ACCESSIBILITY_AUDIT_SCHEMA = {
+  type: "object",
+  required: ["total_issues", "critical", "important", "warning", "issues"],
+  properties: {
+    scope: { type: "string" },
+    elements_scanned: { type: "integer" },
+    elements_skipped: { type: "integer" },
+    total_issues: { type: "integer" },
+    critical: { type: "integer" },
+    important: { type: "integer" },
+    warning: { type: "integer" },
+    issues: ISSUE_LIST,
+  },
+};
+
+const AUDIT_SUMMARY = {
+  type: "object",
+  properties: {
+    critical: { type: "integer" },
+    warnings: { type: "integer" },
+    passed: { type: "integer" },
+    total_checks: { type: "integer" },
+  },
+};
+
+const bundleAuditSchema = (pathKey) => ({
+  type: "object",
+  required: ["summary", "verdict", "findings"],
+  properties: {
+    [pathKey]: { type: "string" },
+    app: { type: "string" },
+    summary: AUDIT_SUMMARY,
+    verdict: { type: "string" },
+    findings: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          status: { type: "string", enum: ["pass", "warning", "critical"] },
+          rule: { type: "string" },
+          message: { type: "string" },
+        },
+      },
+    },
+  },
+});
+
+const OUTPUT_SCHEMAS = {
+  ios_accessibility_audit: ACCESSIBILITY_AUDIT_SCHEMA,
+  android_accessibility_audit: ACCESSIBILITY_AUDIT_SCHEMA,
+
+  ios_archive_audit: bundleAuditSchema("archive"),
+  android_apk_audit: bundleAuditSchema("apk"),
+
+  // ios_list_devices deliberately has NO outputSchema.
+  //
+  // It declared `{ type: "array", items: {...} }`, which is not a legal
+  // outputSchema: MCP's `structuredContent` is an OBJECT, so the schema that
+  // describes it must be `type: "object"`. Claude Code validates the entire
+  // tools/list response, so ONE bad schema on the FIRST tool took down every
+  // tool the server serves (78 at the time):
+  //
+  //   Reconnected to dev-toolkit, but fetching tools failed:
+  //   path: [tools, 0, outputSchema, type], message: Invalid input: expected "object"
+  //
+  // The server read "connected - tools fetch failed" with every tool unavailable,
+  // and nothing in this repo objected: gate 9 checked that declared schemas come
+  // WITH structuredContent, never that a schema is spec-legal. Gate 9b now does.
+  //
+  // Not fixed by wrapping the payload as `{ devices: [...] }`: this tool's text
+  // output is a JSON array that callers parse, so re-shaping it is a breaking
+  // change bought for structured output nobody requested. Dropping the
+  // declaration restores a legal tools/list and leaves the text byte-identical.
+
+  // Two shapes, both keyed on `passed`: a size mismatch short-circuits before
+  // any pixel comparison, so the diff fields are absent in that one.
+  ios_visual_diff: {
+    type: "object",
+    required: ["passed"],
+    properties: {
+      passed: { type: "boolean" },
+      reason: { type: "string" },
+      baseline_size: { type: "string" },
+      current_size: { type: "string" },
+      diff_pct: { type: "number" },
+      diff_pixels: { type: "integer" },
+      total_pixels: { type: "integer" },
+      threshold: { type: "number" },
+      max_diff_pct: { type: "number" },
+      baseline: { type: "string" },
+      current: { type: "string" },
+      diff_image: { type: "string" },
+    },
+  },
+
+  ios_list_crashes: {
+    type: "object",
+    required: ["dir", "count", "reports"],
+    properties: {
+      dir: { type: "string" },
+      count: { type: "integer" },
+      reports: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            file: { type: "string" },
+            process: { type: "string" },
+            modified: { type: "string" },
+            size: { type: "integer" },
+          },
+        },
+      },
+    },
+  },
+
+  android_launch_time: {
+    type: "object",
+    required: ["package", "cold_start"],
+    properties: {
+      package: { type: "string" },
+      cold_start: { type: "boolean" },
+      total_time_ms: { type: ["integer", "null"] },
+      wait_time_ms: { type: ["integer", "null"] },
+      raw: { type: "string" },
+    },
+  },
+
+  design_ui_geometry: {
+    type: "object",
+    required: ["platform", "unit", "count", "elements"],
+    properties: {
+      platform: { type: "string", enum: ["ios", "android"] },
+      unit: { type: "string", enum: ["points", "pixels"] },
+      source: { type: "string" },
+      screen: {
+        type: ["object", "null"],
+        properties: { w: { type: "number" }, h: { type: "number" } },
+      },
+      count: { type: "integer" },
+      elements: { type: "array", items: { type: "object" } },
+    },
+  },
+
+  // verdict is the field the pipeline gates read, so it is required and
+  // enumerated rather than a free string.
+  agent_run_steps: {
+    type: "object",
+    required: ["total_steps", "executed", "errors", "verdict", "aborted", "results"],
+    properties: {
+      total_steps: { type: "integer" },
+      executed: { type: "integer" },
+      errors: { type: "integer" },
+      verdict: { type: "string", enum: ["all_ok", "all_failed", "partial"] },
+      aborted: { type: "boolean" },
+      results: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            tool: { type: "string" },
+            status: { type: "string", enum: ["ok", "error"] },
+            output: { type: "string" },
+          },
+        },
+      },
+    },
+  },
+};
+
+const withOutputSchema = (tool) =>
+  OUTPUT_SCHEMAS[tool.name] ? { ...tool, outputSchema: OUTPUT_SCHEMAS[tool.name] } : tool;
+
+// structuredContent is attached only when the tool declares a schema and its
+// payload really is JSON. A tool that unexpectedly returned prose still gets
+// its text content rather than a malformed structured field.
+function withStructured(name, text) {
+  if (!OUTPUT_SCHEMAS[name]) return { content: [{ type: "text", text }] };
+  try {
+    return { content: [{ type: "text", text }], structuredContent: JSON.parse(text) };
+  } catch {
+    return { content: [{ type: "text", text }] };
+  }
+}
+
+const ANNOTATED_TOOLS = ALL_TOOLS.map(withAnnotations).map(withOutputSchema);
+
+const PKG = JSON.parse(readFileSync(join(__dirname, "package.json"), "utf8"));
+
+const server = new Server(
+  { name: "multi-agent-toolkit-mcp", version: PKG.version },
+  { capabilities: { tools: {} } }
+);
+
+const designCtx = {
+  run,
+  iosDevice,
+  adbFlag,
+  idb,
+  hasIdb: HAS_IDB,
+  dumperScript: join(__dirname, "ui-tree-dumper.swift"),
+};
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: ANNOTATED_TOOLS }));
+
+server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+  const { name, arguments: args } = request.params;
+  // Long-running tools (xcodebuild, export, validate, install) report progress
+  // when the client sent a progressToken, and abandon their child process when
+  // the client cancels the request. Everything else ignores the context.
+  const progressToken = request.params._meta?.progressToken;
+  let tick = 0;
+  const ctx = {
+    signal: extra?.signal,
+    progress:
+      progressToken !== undefined && extra?.sendNotification
+        ? (message) => {
+            extra
+              .sendNotification({
+                method: "notifications/progress",
+                params: { progressToken, progress: ++tick, message },
+              })
+              .catch(() => {});
+          }
+        : null,
+  };
+  try {
+    // Enforce the declared input schema before any handler sees the arguments:
+    // a type mismatch (string where a number is declared) is rejected here
+    // instead of reaching a bare shell interpolation downstream.
+    const schemaError = validateArgs(name, args || {});
+    if (schemaError) {
+      return { content: [{ type: "text", text: `${ERROR_PREFIX}invalid arguments: ${schemaError}` }], isError: true };
+    }
+    let result;
+    if (name.startsWith("ios_")) result = await handleIOS(name, args || {}, ctx);
+    else if (name.startsWith("android_")) result = await handleAndroid(name, args || {}, ctx);
+    else if (name.startsWith("web_")) result = await handleWeb(name, args || {});
+    else if (name.startsWith("agent_")) result = await handleAgent(name, args || {});
+    else if (name.startsWith("design_")) result = await handleDesign(name, args || {}, designCtx);
+    else return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
+    // Same reason as dispatchStep: a handler returns null only from its
+    // `default:` arm, so an unrecognised name that happens to carry a known
+    // family prefix used to answer the host with the literal text "null" and no
+    // isError flag - a failure that reads as success.
+    if (result === null || result === undefined) {
+      return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
+    }
+    if (typeof result === "object" && result?.type === "image") {
+      return {
+        content: [
+          { type: "image", data: result.data, mimeType: result.mimeType },
+          { type: "text", text: `Screenshot: ${result.path}` },
+          ...(result.path ? [{ type: "resource_link", uri: `file://${result.path}`, name: basename(result.path), mimeType: result.mimeType }] : []),
+        ],
+      };
+    }
+    // File-returning tools (screenshot with `path`, build logs, diff images,
+    // recordings) carry a resource_link per file alongside the text, per the
+    // 2025-06-18 MCP spec, so a host can open the artifact without parsing
+    // the path out of prose. structuredContent still applies when the text
+    // is JSON and the tool declares a schema.
+    if (typeof result === "object" && result?.type === "file") {
+      const envelope = withStructured(name, result.text);
+      for (const f of result.files) {
+        envelope.content.push({ type: "resource_link", uri: `file://${f.path}`, name: f.name });
+      }
+      return envelope;
+    }
+    // The batch report is always the payload; whether the envelope is an error
+    // is decided inside handleAgent (abort yes, opted-into failures no).
+    if (typeof result === "object" && result?.type === "batch") {
+      // The report is JSON either way, so it carries structuredContent even on
+      // the error envelope - a caller reading `verdict` needs it most when the
+      // batch failed.
+      const envelope = withStructured(name, result.text);
+      return result.isError ? { ...envelope, isError: true } : envelope;
+    }
+    // A command failure must surface as an MCP error result, not as text that
+    // reads like success to the host and to the pipeline gates.
+    if (isFailure(result)) {
+      return { content: [{ type: "text", text: String(result) }], isError: true };
+    }
+    return withStructured(name, String(result));
+  } catch (e) {
+    return {
+      content: [{ type: "text", text: `${ERROR_PREFIX}${truncateError(e.message)}` }],
+      isError: true,
+    };
+  }
+});
+
+// Recorder children must not outlive the server: `simctl io recordVideo` has no
+// time limit, so an orphan keeps writing until the disk fills. SIGINT is the
+// finalizing stop for both recorders, so the files stay playable.
+function stopRecorders() {
+  for (const rec of RECORDINGS.values()) {
+    try { rec.child.kill("SIGINT"); } catch {}
+  }
+}
+
+process.on("SIGTERM", async () => { stopRecorders(); await closeBrowser(); process.exit(0); });
+process.on("SIGINT", async () => { stopRecorders(); await closeBrowser(); process.exit(0); });
+
+const transport = new StdioServerTransport();
+await server.connect(transport);