axbridge-mcp 0.0.0-stage → 0.1.1

package/LICENSE

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

package/README.md

@@ -1,3 +1,16 @@
-# Temporary Holding Version
+# axbridge-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MCP server for [axbridge](https://github.com/jx-grxf/axbridge): lets Claude Code, Codex,
+Cursor and other MCP clients use an iOS app in the Simulator as text. It reads the screen
+from the accessibility tree, taps by name, types, scrolls and goes back, and manages
+simulators, builds, screenshots, recordings and visual diffs.
+
+```bash
+claude mcp add axbridge -- npx -y axbridge-mcp
+```
+
+The app under test needs the AXBridge Swift package and one call to `AXBridge.start()`.
+Setup, the full tool list and measurements are in the
+[main README](https://github.com/jx-grxf/axbridge#readme).
+
+Requires macOS with Xcode and Node.js 20+. MIT licensed.

package/dist/bridge.js

@@ -0,0 +1,67 @@
+import { createServer } from "node:net";
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, writeFile, chmod } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { CommandError } from "./exec.js";
+const STATE_DIR = join(homedir(), ".cache", "axbridge");
+const STATE_FILE = join(STATE_DIR, "sessions.json");
+const sessions = new Map();
+let loaded = false;
+async function load() {
+    if (loaded)
+        return;
+    loaded = true;
+    try {
+        const saved = JSON.parse(await readFile(STATE_FILE, "utf8"));
+        for (const s of saved)
+            sessions.set(s.udid, s);
+    }
+    catch {
+        // first run
+    }
+}
+async function persist() {
+    await mkdir(STATE_DIR, { recursive: true });
+    await writeFile(STATE_FILE, JSON.stringify([...sessions.values()], null, 2));
+    await chmod(STATE_FILE, 0o600);
+}
+export function freePort() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            const port = typeof address === "object" && address ? address.port : 0;
+            server.close(() => resolve(port));
+        });
+    });
+}
+export async function newSession(udid, bundleId) {
+    await load();
+    const session = { udid, bundleId, port: await freePort(), token: randomBytes(24).toString("hex") };
+    sessions.set(udid, session);
+    await persist();
+    return session;
+}
+export async function sessionFor(udid) {
+    await load();
+    const session = sessions.get(udid);
+    if (!session)
+        throw new CommandError("The app was not launched through axbridge on this simulator. Call `launch` first.");
+    return session;
+}
+export async function call(session, method, path, body = "", timeoutMs = 15_000) {
+    try {
+        const response = await fetch(`http://127.0.0.1:${session.port}${path}`, {
+            method,
+            body: method === "POST" ? body : undefined,
+            headers: { "X-AXBridge-Token": session.token, "Content-Type": "text/plain; charset=utf-8" },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        return { status: response.status, text: await response.text() };
+    }
+    catch (error) {
+        throw new CommandError(`The bridge in the app does not answer (${error.message}). Is it a Debug build with AXBridge.start(), and was it launched with \`launch\`?`);
+    }
+}

package/dist/build.js

@@ -0,0 +1,32 @@
+import { createHash } from "node:crypto";
+import { readdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { run, CommandError } from "./exec.js";
+export async function buildForSimulator(opts) {
+    if (!opts.project && !opts.workspace)
+        throw new CommandError("Pass project (.xcodeproj) or workspace (.xcworkspace).");
+    const container = resolve(opts.workspace ?? opts.project);
+    const key = createHash("sha1").update(`${container}|${opts.scheme}`).digest("hex").slice(0, 12);
+    const derived = join(homedir(), ".cache", "axbridge", "DerivedData", key);
+    await run("xcodebuild", [
+        opts.workspace ? "-workspace" : "-project", container,
+        "-scheme", opts.scheme,
+        "-configuration", opts.configuration,
+        "-destination", `id=${opts.udid}`,
+        "-derivedDataPath", derived,
+        "build",
+    ], { timeoutMs: 30 * 60_000 });
+    const products = join(derived, "Build", "Products", `${opts.configuration}-iphonesimulator`);
+    const apps = (await readdir(products)).filter((f) => f.endsWith(".app"));
+    if (apps.length === 0)
+        throw new CommandError(`No .app in ${products}`);
+    // A scheme can build extensions or test hosts next to the app; the scheme's own app
+    // usually carries its name.
+    const app = apps.find((a) => a.replace(/\.app$/, "") === opts.scheme) ?? apps[0];
+    const appPath = join(products, app);
+    return { appPath, bundleId: await bundleIdOf(appPath) };
+}
+export async function bundleIdOf(appPath) {
+    return run("/usr/libexec/PlistBuddy", ["-c", "Print :CFBundleIdentifier", join(appPath, "Info.plist")]);
+}

package/dist/cli.js

@@ -0,0 +1,161 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir, platform } from "node:os";
+import { dirname, join } from "node:path";
+import { run } from "./exec.js";
+import { listDevices, resolveDevice } from "./devices.js";
+import { sessionFor, call } from "./bridge.js";
+import { VERSION, newerVersion } from "./version.js";
+const HELP = `axbridge ${VERSION}: drive iOS Simulator apps as text from coding agents
+
+Usage
+  npx axbridge-mcp                 start the MCP server (stdio); this is what agents run
+  npx axbridge-mcp setup <agent>   register the MCP server: claude, codex, cursor or all
+                                   (cursor: add --project for .cursor/mcp.json in this folder)
+  npx axbridge-mcp doctor          check Xcode, simulators, Node and the installed version
+  npx axbridge-mcp screen [device] print the current screen of an app launched by axbridge
+  npx axbridge-mcp --version
+
+Docs: https://github.com/jx-grxf/axbridge`;
+const ok = (s) => console.log(`  ✓ ${s}`);
+const bad = (s) => console.log(`  ✗ ${s}`);
+const SERVER = { command: "npx", args: ["-y", "axbridge-mcp"] };
+async function has(cmd) {
+    return run("/usr/bin/which", [cmd]).then(() => true, () => false);
+}
+async function doctor() {
+    let failures = 0;
+    console.log(`axbridge ${VERSION}`);
+    if (platform() === "darwin")
+        ok("macOS");
+    else {
+        bad("macOS is required (the iOS Simulator only runs there)");
+        failures++;
+    }
+    const major = Number(process.versions.node.split(".")[0]);
+    if (major >= 20)
+        ok(`Node.js ${process.versions.node}`);
+    else {
+        bad(`Node.js ${process.versions.node}; 20 or newer is required`);
+        failures++;
+    }
+    try {
+        ok((await run("xcodebuild", ["-version"])).split("\n")[0]);
+    }
+    catch {
+        bad("xcodebuild not found; install Xcode and run `sudo xcode-select -s /Applications/Xcode.app`");
+        failures++;
+    }
+    try {
+        const devices = await listDevices();
+        const booted = devices.filter((d) => d.state === "Booted");
+        ok(`simctl: ${devices.filter((d) => d.available).length} simulators, ${booted.length} booted${booted.length ? ` (${booted.map((d) => d.name).join(", ")})` : ""}`);
+    }
+    catch (error) {
+        bad(`xcrun simctl failed: ${error.message}`);
+        failures++;
+    }
+    if (await has("sips"))
+        ok("sips (screenshots)");
+    else {
+        bad("sips missing; screenshots will fail");
+        failures++;
+    }
+    const latest = await newerVersion(3000);
+    if (latest)
+        bad(`axbridge ${latest} is available; npx picks it up with \`npx -y axbridge-mcp@latest\``);
+    else
+        ok("up to date (or offline)");
+    return failures ? 1 : 0;
+}
+async function setupClaude() {
+    if (!(await has("claude"))) {
+        bad("claude CLI not found; run: claude mcp add axbridge --scope user -- npx -y axbridge-mcp");
+        return;
+    }
+    await run("claude", ["mcp", "remove", "axbridge", "--scope", "user"]).catch(() => undefined);
+    await run("claude", ["mcp", "add", "axbridge", "--scope", "user", "--", ...[SERVER.command, ...SERVER.args]]);
+    ok("Claude Code: added for your user (all projects)");
+}
+async function setupCodex() {
+    const file = join(homedir(), ".codex", "config.toml");
+    const current = existsSync(file) ? await readFile(file, "utf8") : "";
+    if (/^\[mcp_servers\.axbridge\]/m.test(current)) {
+        ok(`Codex: already in ${file}`);
+        return;
+    }
+    await mkdir(dirname(file), { recursive: true });
+    const block = `\n[mcp_servers.axbridge]\ncommand = "npx"\nargs = ["-y", "axbridge-mcp"]\n`;
+    await writeFile(file, current.replace(/\n*$/, "\n") + block);
+    ok(`Codex: added to ${file}`);
+}
+async function setupCursor(project) {
+    const file = project ? join(process.cwd(), ".cursor", "mcp.json") : join(homedir(), ".cursor", "mcp.json");
+    let config = {};
+    if (existsSync(file)) {
+        try {
+            config = JSON.parse(await readFile(file, "utf8"));
+        }
+        catch {
+            bad(`Cursor: ${file} is not valid JSON, left unchanged`);
+            return;
+        }
+    }
+    config.mcpServers = { ...(config.mcpServers ?? {}), axbridge: SERVER };
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(file, JSON.stringify(config, null, 2) + "\n");
+    ok(`Cursor: written to ${file}`);
+}
+async function setup(agent, flags) {
+    const targets = agent === "all" ? ["claude", "codex", "cursor"] : agent ? [agent] : [];
+    if (targets.length === 0 || targets.some((t) => !["claude", "codex", "cursor"].includes(t))) {
+        console.log("Usage: npx axbridge-mcp setup claude|codex|cursor|all [--project]");
+        return 1;
+    }
+    for (const t of targets) {
+        if (t === "claude")
+            await setupClaude();
+        if (t === "codex")
+            await setupCodex();
+        if (t === "cursor")
+            await setupCursor(flags.includes("--project"));
+    }
+    console.log("\nNext: add the AXBridge Swift package to your app and call AXBridge.start(). See the README.");
+    return 0;
+}
+async function screen(device) {
+    const d = await resolveDevice(device);
+    const reply = await call(await sessionFor(d.udid), "GET", "/screen");
+    console.log(reply.text);
+    return reply.status === 200 ? 0 : 1;
+}
+export async function runCli(args) {
+    const [command, ...rest] = args;
+    try {
+        switch (command) {
+            case "--version":
+            case "-v":
+            case "version":
+                console.log(VERSION);
+                return 0;
+            case "doctor":
+                return await doctor();
+            case "setup":
+                return await setup(rest.find((a) => !a.startsWith("-")), rest);
+            case "screen":
+                return await screen(rest[0]);
+            case "help":
+            case "--help":
+            case "-h":
+                console.log(HELP);
+                return 0;
+            default:
+                console.log(HELP);
+                return 1;
+        }
+    }
+    catch (error) {
+        console.error(error.message);
+        return 1;
+    }
+}

package/dist/devices.js

@@ -0,0 +1,51 @@
+import { simctl, CommandError } from "./exec.js";
+export async function listDevices() {
+    const raw = JSON.parse(await simctl(["list", "devices", "--json"]));
+    const out = [];
+    for (const [runtimeId, list] of Object.entries(raw.devices)) {
+        const runtime = runtimeId.replace("com.apple.CoreSimulator.SimRuntime.", "").replace(/-(\d+)-(\d+)$/, " $1.$2");
+        for (const d of list) {
+            out.push({ udid: d.udid, name: d.name, state: d.state, runtime, available: d.isAvailable });
+        }
+    }
+    return out;
+}
+const UDID = /^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$/i;
+/** Pure resolution so it can be tested: "booted", a UDID, or an exact (then partial) name. */
+export function pickDevice(devices, query) {
+    const q = (query ?? "booted").trim();
+    if (q === "booted") {
+        const booted = devices.filter((d) => d.state === "Booted");
+        if (booted.length === 1)
+            return booted[0];
+        if (booted.length === 0)
+            throw new CommandError("No simulator is booted. Use `boot` with a device name, or `devices` to list them.");
+        throw new CommandError(`${booted.length} simulators are booted; pass device as one of: ${booted.map((d) => `"${d.name}"`).join(", ")}`);
+    }
+    if (UDID.test(q)) {
+        const hit = devices.find((d) => d.udid.toLowerCase() === q.toLowerCase());
+        if (hit)
+            return hit;
+        throw new CommandError(`No simulator with UDID ${q}`);
+    }
+    const available = devices.filter((d) => d.available);
+    const exact = available.filter((d) => d.name === q);
+    const pool = exact.length ? exact : available.filter((d) => d.name.toLowerCase().includes(q.toLowerCase()));
+    if (pool.length === 0)
+        throw new CommandError(`No simulator named "${q}". Use \`devices\` to list them.`);
+    // Several runtimes can carry the same name; prefer a booted one, then the newest runtime.
+    const ranked = [...pool].sort((a, b) => Number(b.state === "Booted") - Number(a.state === "Booted") || b.runtime.localeCompare(a.runtime, undefined, { numeric: true }));
+    return ranked[0];
+}
+export async function resolveDevice(query) {
+    return pickDevice(await listDevices(), query);
+}
+export async function ensureBooted(device) {
+    if (device.state !== "Booted") {
+        await simctl(["boot", device.udid]).catch((e) => {
+            if (!/current state: Booted/.test(e.message))
+                throw e;
+        });
+    }
+    await simctl(["bootstatus", device.udid, "-b"], { timeoutMs: 180_000 });
+}

package/dist/exec.js

@@ -0,0 +1,28 @@
+import { execFile, spawn } from "node:child_process";
+export class CommandError extends Error {
+}
+export function run(cmd, args, opts = {}) {
+    return new Promise((resolve, reject) => {
+        execFile(cmd, args, { env: opts.env ?? process.env, timeout: opts.timeoutMs ?? 120_000, maxBuffer: 64 * 1024 * 1024, cwd: opts.cwd }, (error, stdout, stderr) => {
+            if (error) {
+                const output = `${stdout ?? ""}\n${stderr ?? ""}`;
+                // xcodebuild buries the cause under hundreds of lines; the error: lines are what matters.
+                const errors = [...new Set(output.split("\n").map((l) => l.trim()).filter((l) => /^\/.*: error: /.test(l)))];
+                const detail = errors.length
+                    ? errors.slice(0, 10).join("\n")
+                    : (stderr || stdout || error.message).toString().trim().split("\n").slice(-12).join("\n");
+                reject(new CommandError(`${cmd} ${args.slice(0, 3).join(" ")}: ${detail}`));
+            }
+            else {
+                resolve(stdout.toString().trim());
+            }
+        });
+    });
+}
+export function simctl(args, opts = {}) {
+    return run("xcrun", ["simctl", ...args], opts);
+}
+export function background(cmd, args) {
+    return spawn(cmd, args, { stdio: "ignore" });
+}
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

package/dist/images.js

@@ -0,0 +1,50 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { PNG } from "pngjs";
+import pixelmatch from "pixelmatch";
+import { run, simctl } from "./exec.js";
+export const OUTPUT_DIR = process.env.AXBRIDGE_OUTPUT_DIR ?? join(tmpdir(), "axbridge");
+function stamp() {
+    const time = new Date().toISOString().replace(/[-:]/g, "").replace(/\..*/, "").replace("T", "-");
+    return `${time}-${Math.random().toString(36).slice(2, 6)}`;
+}
+export async function screenshot(udid, opts) {
+    await mkdir(OUTPUT_DIR, { recursive: true });
+    const stem = (opts.name ?? stamp()).replace(/[^\w.-]+/g, "-");
+    const full = join(OUTPUT_DIR, `${stem}.png`);
+    await simctl(["io", udid, "screenshot", "--type=png", full]);
+    let source = full;
+    if (opts.crop) {
+        const { x, y, w, h, scale } = opts.crop;
+        const pad = 8;
+        const px = Math.max(0, Math.round((x - pad) * scale));
+        const py = Math.max(0, Math.round((y - pad) * scale));
+        source = join(OUTPUT_DIR, `${stem}.crop.png`);
+        await run("sips", [
+            "--cropOffset", String(py), String(px),
+            "-c", String(Math.round((h + 2 * pad) * scale)), String(Math.round((w + 2 * pad) * scale)),
+            full, "--out", source,
+        ]);
+    }
+    const small = join(OUTPUT_DIR, `${stem}.small.jpg`);
+    await run("sips", ["-s", "format", "jpeg", "-s", "formatOptions", "70", "--resampleWidth", String(opts.width), source, "--out", small]);
+    return { full, small, data: (await readFile(small)).toString("base64") };
+}
+/** Compares two PNG files; the actual image is scaled to the reference size first. */
+export async function compare(actualPath, referencePath, threshold = 0.1) {
+    await mkdir(OUTPUT_DIR, { recursive: true });
+    const reference = PNG.sync.read(await readFile(referencePath));
+    let actual = PNG.sync.read(await readFile(actualPath));
+    if (actual.width !== reference.width || actual.height !== reference.height) {
+        const scaled = join(OUTPUT_DIR, `scaled-${stamp()}.png`);
+        await run("sips", ["-z", String(reference.height), String(reference.width), actualPath, "--out", scaled]);
+        actual = PNG.sync.read(await readFile(scaled));
+    }
+    const { width, height } = reference;
+    const diff = new PNG({ width, height });
+    const diffPixels = pixelmatch(reference.data, actual.data, diff.data, width, height, { threshold });
+    const diffImage = join(OUTPUT_DIR, `diff-${stamp()}.png`);
+    await writeFile(diffImage, PNG.sync.write(diff));
+    return { diffPixels, diffPercent: Math.round((diffPixels / (width * height)) * 10_000) / 100, diffImage };
+}

package/dist/index.js

@@ -0,0 +1,369 @@
+#!/usr/bin/env node
+import { mkdtemp, writeFile, readdir, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { background, run, simctl, sleep, CommandError } from "./exec.js";
+import { listDevices, resolveDevice, ensureBooted } from "./devices.js";
+import { newSession, sessionFor, call } from "./bridge.js";
+import { screenshot, compare, OUTPUT_DIR } from "./images.js";
+import { buildForSimulator, bundleIdOf } from "./build.js";
+import { VERSION, newerVersion, updateHint } from "./version.js";
+if (process.argv.length > 2) {
+    const { runCli } = await import("./cli.js");
+    process.exit(await runCli(process.argv.slice(2)));
+}
+const latest = await newerVersion();
+const INSTRUCTIONS = `axbridge drives iOS Simulator apps as text.
+Workflow: \`launch\` (or \`build_and_run\`) starts the app with the bridge and returns the screen as text.
+Then use \`tap\`, \`type\`, \`scroll\`, \`back\`, \`go\`; each returns the new screen as text, so \`screen\` is rarely needed.
+Targets for tap: exact or partial label/value text, "#3" (number from the last listing) or "id:identifier".
+Use \`screenshot\` only to judge visuals; pass \`element\` to crop to one element. Several devices can run at once:
+pass \`device\` (name, UDID or "booted") to every call.${latest ? `\n\n${updateHint(latest)}` : ""}`;
+const server = new McpServer({ name: "axbridge", version: VERSION }, { instructions: INSTRUCTIONS });
+let updateMentioned = false;
+function text(t) {
+    return { content: [{ type: "text", text: t }] };
+}
+function tool(name, description, shape, handler) {
+    server.registerTool(name, { description, inputSchema: shape }, (async (args) => {
+        try {
+            const result = await handler(args);
+            if (latest && !updateMentioned) {
+                updateMentioned = true;
+                result.content.push({ type: "text", text: `\n${updateHint(latest)}` });
+            }
+            return result;
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: error.message }], isError: true };
+        }
+    }));
+}
+const device = z.string().optional().describe('Simulator name, UDID or "booted" (default). Required when several are booted.');
+function describe(d) {
+    return `${d.name} (${d.runtime}) ${d.udid} ${d.state}`;
+}
+async function bootedDevice(query) {
+    const d = await resolveDevice(query);
+    await ensureBooted(d);
+    return d;
+}
+// MARK: Devices
+tool("devices", "List simulators with name, runtime, UDID and state. Booted ones first.", {
+    all: z.boolean().optional().describe("Include unavailable devices"),
+}, async ({ all }) => {
+    const list = (await listDevices())
+        .filter((d) => all || d.available)
+        .sort((a, b) => Number(b.state === "Booted") - Number(a.state === "Booted") || a.name.localeCompare(b.name));
+    return text(list.map(describe).join("\n") || "no simulators");
+});
+tool("boot", "Boot a simulator and wait until it is ready. Optionally open Simulator.app to watch.", {
+    device: z.string().describe("Name or UDID"),
+    show: z.boolean().optional().describe("Open Simulator.app"),
+}, async ({ device: query, show }) => {
+    const d = await bootedDevice(query);
+    if (show)
+        background("open", ["-a", "Simulator", "--args", "-CurrentDeviceUDID", d.udid]);
+    return text(`booted: ${describe({ ...d, state: "Booted" })}`);
+});
+tool("shutdown", 'Shut down a simulator, or every booted one with device "all".', { device }, async ({ device: query }) => {
+    if (query === "all") {
+        await simctl(["shutdown", "all"]);
+        return text("all simulators shut down");
+    }
+    const d = await resolveDevice(query);
+    await simctl(["shutdown", d.udid]);
+    return text(`shut down: ${d.name}`);
+});
+tool("create_device", 'Create a simulator, e.g. name "Test 13 mini", type "iPhone 13 mini". Runtime defaults to the newest iOS.', {
+    name: z.string(),
+    type: z.string().describe('Device type name as in `xcrun simctl list devicetypes`, e.g. "iPhone 17"'),
+    runtime: z.string().optional().describe('e.g. "iOS 27.2"; newest iOS when omitted'),
+}, async ({ name, type, runtime }) => {
+    const raw = JSON.parse(await simctl(["list", "runtimes", "--json"]));
+    const ios = raw.runtimes.filter((r) => r.isAvailable && r.name.startsWith("iOS"));
+    const chosen = runtime ? ios.find((r) => r.name === runtime) : ios[ios.length - 1];
+    if (!chosen)
+        throw new CommandError(`No iOS runtime "${runtime}". Available: ${ios.map((r) => r.name).join(", ")}`);
+    const udid = await simctl(["create", name, type, chosen.identifier]);
+    return text(`created ${name} (${type}, ${chosen.name}) ${udid}`);
+});
+// MARK: App lifecycle
+const launchShape = {
+    device,
+    reset: z.enum(["keep", "fresh"]).optional().describe("fresh deletes the app's data first, like a new install"),
+    args: z.array(z.string()).optional().describe("Extra launch arguments"),
+    env: z.record(z.string(), z.string()).optional().describe("Environment variables for the app"),
+    defaults: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional()
+        .describe("UserDefaults to write before launch, e.g. to mark onboarding as done"),
+};
+async function launchApp(d, bundleId, opts) {
+    // SwiftUI only builds its accessibility tree while accessibility is on.
+    for (const key of ["ApplicationAccessibilityEnabled", "AutomationEnabled"]) {
+        await simctl(["spawn", d.udid, "defaults", "write", "com.apple.Accessibility", key, "-bool", "true"]);
+    }
+    // The swipe-typing tutorial covers half the screen the first time a field is focused.
+    for (const domain of ["com.apple.Preferences", "com.apple.keyboard.preferences"]) {
+        await simctl(["spawn", d.udid, "defaults", "write", domain, "DidShowContinuousPathIntroduction", "-bool", "true"]);
+    }
+    await simctl(["terminate", d.udid, bundleId]).catch(() => undefined);
+    if (opts.reset === "fresh") {
+        const data = await simctl(["get_app_container", d.udid, bundleId, "data"]);
+        await run("/bin/rm", ["-rf", join(data, "Library"), join(data, "Documents"), join(data, "tmp")]);
+    }
+    for (const [key, value] of Object.entries(opts.defaults ?? {})) {
+        const kind = typeof value === "boolean" ? "-bool" : typeof value === "number" ? (Number.isInteger(value) ? "-int" : "-float") : "-string";
+        await simctl(["spawn", d.udid, "defaults", "write", bundleId, key, kind, String(value)]);
+    }
+    const session = await newSession(d.udid, bundleId);
+    const env = { ...process.env, SIMCTL_CHILD_AXBRIDGE_PORT: String(session.port), SIMCTL_CHILD_AXBRIDGE_TOKEN: session.token };
+    for (const [k, v] of Object.entries(opts.env ?? {}))
+        env[`SIMCTL_CHILD_${k}`] = v;
+    await simctl(["launch", "--terminate-running-process", d.udid, bundleId, "--axbridge", ...(opts.args ?? [])], { env });
+    const deadline = Date.now() + 30_000;
+    while (Date.now() < deadline) {
+        try {
+            const reply = await call(session, "GET", "/screen", "", 2_000);
+            if (reply.status === 200 && !reply.text.startsWith("(empty"))
+                return `${bundleId} running on ${d.name}\n\n${reply.text}`;
+        }
+        catch {
+            // still launching
+        }
+        await sleep(700);
+    }
+    throw new CommandError(`${bundleId} launched on ${d.name}, but the bridge did not answer within 30 s. Is AXBridge.start() called in a Debug build?`);
+}
+tool("launch", "Launch an installed app with the bridge and return its first screen as text.", {
+    bundleId: z.string(), ...launchShape,
+}, async ({ device: query, bundleId, ...opts }) => text(await launchApp(await bootedDevice(query), bundleId, opts)));
+tool("build_and_run", "Build an Xcode scheme for the simulator (Debug), install and launch it with the bridge.", {
+    project: z.string().optional().describe(".xcodeproj path"),
+    workspace: z.string().optional().describe(".xcworkspace path"),
+    scheme: z.string(),
+    configuration: z.string().optional().describe("Default Debug; the bridge exists only in Debug"),
+    ...launchShape,
+}, async ({ device: query, project, workspace, scheme, configuration, ...opts }) => {
+    const d = await bootedDevice(query);
+    const built = await buildForSimulator({ project, workspace, scheme, udid: d.udid, configuration: configuration ?? "Debug" });
+    await simctl(["install", d.udid, built.appPath]);
+    return text(await launchApp(d, built.bundleId, opts));
+});
+tool("install", "Install a .app bundle built for the simulator.", { device, appPath: z.string() }, async ({ device: query, appPath }) => {
+    const d = await bootedDevice(query);
+    await simctl(["install", d.udid, appPath]);
+    return text(`installed ${await bundleIdOf(appPath)} on ${d.name}`);
+});
+tool("terminate", "Quit an app.", { device, bundleId: z.string() }, async ({ device: query, bundleId }) => {
+    const d = await resolveDevice(query);
+    await simctl(["terminate", d.udid, bundleId]);
+    return text(`terminated ${bundleId}`);
+});
+tool("uninstall", "Remove an app and its data.", { device, bundleId: z.string() }, async ({ device: query, bundleId }) => {
+    const d = await resolveDevice(query);
+    await simctl(["uninstall", d.udid, bundleId]);
+    return text(`uninstalled ${bundleId}`);
+});
+// MARK: Reading and acting as text
+async function bridgeCall(query, method, path, body = "") {
+    const d = await resolveDevice(query);
+    const reply = await call(await sessionFor(d.udid), method, path, body);
+    if (reply.status === 202)
+        return text(`${reply.text}\n(Use a coordinate tap from another tool for this element.)`);
+    if (reply.status >= 400)
+        throw new CommandError(reply.text);
+    return text(reply.text);
+}
+tool("screen", "The current screen as text: number, kind, label = value, id, centre point.", { device }, ({ device: q }) => bridgeCall(q, "GET", "/screen"));
+tool("tap", 'Activate an element by text, "#n" from the last listing or "id:identifier". Returns the new screen.', {
+    target: z.string(), device,
+}, ({ target, device: q }) => bridgeCall(q, "POST", "/tap", target));
+tool("type", "Insert text into the focused field (tap it first). No keyboard needed; any characters work.", {
+    text: z.string(), clear: z.boolean().optional().describe("Empty the field first"), device,
+}, async ({ text: value, clear, device: q }) => {
+    if (clear)
+        await bridgeCall(q, "POST", "/clear");
+    return bridgeCall(q, "POST", "/type", value);
+});
+tool("scroll", "Scroll the main scroll view of the screen.", {
+    direction: z.enum(["down", "up", "top", "bottom", "left", "right"]).optional(), device,
+}, ({ direction, device: q }) => bridgeCall(q, "POST", "/scroll", direction ?? "down"));
+tool("back", "Close the top sheet, or pop the navigation stack.", { device }, ({ device: q }) => bridgeCall(q, "POST", "/back"));
+tool("go", "Open a deep link inside the app (no system prompt when the app passes openURL to AXBridge.start).", {
+    url: z.string(), device,
+}, ({ url, device: q }) => bridgeCall(q, "POST", "/go", url));
+// MARK: Device state
+tool("set_location", "Set the simulated GPS position.", {
+    latitude: z.number(), longitude: z.number(), device,
+}, async ({ latitude, longitude, device: q }) => {
+    const d = await bootedDevice(q);
+    await simctl(["location", d.udid, "set", `${latitude},${longitude}`]);
+    return text(`location ${latitude},${longitude} on ${d.name}`);
+});
+tool("set_appearance", "Switch light or dark mode.", { mode: z.enum(["light", "dark"]), device }, async ({ mode, device: q }) => {
+    const d = await bootedDevice(q);
+    await simctl(["ui", d.udid, "appearance", mode]);
+    return text(`${mode} mode on ${d.name}`);
+});
+const TEXT_SIZES = [
+    "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",
+];
+tool("set_text_size", "Set Dynamic Type. large is the default; accessibility-* are the largest.", {
+    size: z.enum(TEXT_SIZES), device,
+}, async ({ size, device: q }) => {
+    const d = await bootedDevice(q);
+    await simctl(["ui", d.udid, "content_size", size]);
+    return text(`text size ${size} on ${d.name}`);
+});
+tool("status_bar", "Clean status bar for screenshots (9:41, full battery and signal), or clear the override.", {
+    clear: z.boolean().optional(), time: z.string().optional().describe('Default "9:41"'), device,
+}, async ({ clear, time, device: q }) => {
+    const d = await bootedDevice(q);
+    if (clear) {
+        await simctl(["status_bar", d.udid, "clear"]);
+        return text("status bar override cleared");
+    }
+    await simctl(["status_bar", d.udid, "override", "--time", time ?? "9:41", "--batteryState", "charged", "--batteryLevel", "100",
+        "--cellularMode", "active", "--cellularBars", "4", "--wifiBars", "3", "--dataNetwork", "wifi"]);
+    return text(`status bar ${time ?? "9:41"} on ${d.name}`);
+});
+tool("permission", "Grant, revoke or reset a privacy permission without the system prompt.", {
+    bundleId: z.string(),
+    action: z.enum(["grant", "revoke", "reset"]),
+    service: z.enum(["all", "calendar", "contacts-limited", "contacts", "location", "location-always", "photos-add", "photos",
+        "media-library", "microphone", "motion", "reminders", "siri", "camera", "notifications"]),
+    device,
+}, async ({ bundleId, action, service, device: q }) => {
+    const d = await bootedDevice(q);
+    await simctl(["privacy", d.udid, action, service, bundleId]);
+    return text(`${action} ${service} for ${bundleId}`);
+});
+tool("push", "Deliver a push notification payload to the app.", {
+    bundleId: z.string(), payload: z.record(z.string(), z.unknown()).describe('APNs JSON, e.g. {"aps":{"alert":"Hello"}}'), device,
+}, async ({ bundleId, payload, device: q }) => {
+    const d = await bootedDevice(q);
+    const dir = await mkdtemp(join(tmpdir(), "axbridge-push-"));
+    const file = join(dir, "payload.json");
+    await writeFile(file, JSON.stringify(payload));
+    await simctl(["push", d.udid, bundleId, file]);
+    return text(`push delivered to ${bundleId}`);
+});
+// MARK: Images
+tool("screenshot", "Screenshot as a small JPEG for visual checks. element crops to one element; the full PNG path is returned too.", {
+    device,
+    element: z.string().optional().describe("Crop to this element (same targets as tap)"),
+    width: z.number().int().min(200).max(1600).optional().describe("Pixel width of the returned image, default 500"),
+    name: z.string().optional().describe("File name stem"),
+}, async ({ device: q, element, width, name }) => {
+    const d = await bootedDevice(q);
+    let crop;
+    if (element) {
+        const reply = await call(await sessionFor(d.udid), "POST", "/frame", element);
+        if (reply.status !== 200)
+            throw new CommandError(reply.text);
+        const [x, y, w, h, scale] = reply.text.split(" ").map(Number);
+        crop = { x, y, w, h, scale };
+    }
+    const shot = await screenshot(d.udid, { name, width: width ?? 500, crop });
+    return { content: [{ type: "image", data: shot.data, mimeType: "image/jpeg" }, { type: "text", text: `full: ${shot.full}` }] };
+});
+tool("screenshots", "The same moment on several simulators, e.g. to compare layouts across widths.", {
+    devices: z.array(z.string()).min(1).max(6), width: z.number().int().min(200).max(1000).optional(),
+}, async ({ devices: queries, width }) => {
+    const content = [];
+    for (const q of queries) {
+        const d = await bootedDevice(q);
+        const shot = await screenshot(d.udid, { name: `${d.name}-${Date.now()}`, width: width ?? 400 });
+        content.push({ type: "text", text: `${d.name}: ${shot.full}` }, { type: "image", data: shot.data, mimeType: "image/jpeg" });
+    }
+    return { content };
+});
+const recordings = new Map();
+tool("record_start", "Start a screen recording (H.264 .mov).", { device }, async ({ device: q }) => {
+    const d = await bootedDevice(q);
+    if (recordings.has(d.udid))
+        throw new CommandError(`Already recording ${d.name}`);
+    const path = join(OUTPUT_DIR, `${d.name.replace(/\W+/g, "-")}-${Date.now()}.mov`);
+    const process = background("xcrun", ["simctl", "io", d.udid, "recordVideo", "--codec=h264", "--force", path]);
+    recordings.set(d.udid, { process, path });
+    return text(`recording ${d.name} → ${path}`);
+});
+tool("record_stop", "Stop the recording and return the file path.", { device }, async ({ device: q }) => {
+    const d = await resolveDevice(q);
+    const rec = recordings.get(d.udid);
+    if (!rec)
+        throw new CommandError(`No recording running on ${d.name}`);
+    rec.process.kill("SIGINT");
+    await new Promise((r) => rec.process.once("exit", r));
+    recordings.delete(d.udid);
+    return text(`saved ${rec.path}`);
+});
+tool("compare", "Pixel-compare the current screen (or an image file) with a reference PNG. Returns the share of differing pixels and a diff image.", {
+    reference: z.string().describe("Reference PNG path"),
+    actual: z.string().optional().describe("PNG path; takes a fresh screenshot of device when omitted"),
+    threshold: z.number().min(0).max(1).optional().describe("Per-pixel colour tolerance, default 0.1"),
+    device,
+}, async ({ reference, actual, threshold, device: q }) => {
+    let actualPath = actual;
+    if (!actualPath) {
+        const d = await bootedDevice(q);
+        actualPath = (await screenshot(d.udid, { width: 400 })).full;
+    }
+    const result = await compare(actualPath, reference, threshold ?? 0.1);
+    return text(`${result.diffPercent}% of pixels differ (${result.diffPixels}). Diff image: ${result.diffImage}`);
+});
+// MARK: Updates
+async function findPins(root, depth = 0, found = []) {
+    if (depth > 5 || found.length > 20)
+        return found;
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return found;
+    }
+    for (const entry of entries) {
+        if (entry.name.startsWith(".") && entry.name !== ".mcp.json" && entry.name !== ".cursor" && entry.name !== ".codex")
+            continue;
+        if (["node_modules", "DerivedData", "build", "Pods", ".build"].includes(entry.name))
+            continue;
+        const path = join(root, entry.name);
+        if (entry.isDirectory()) {
+            await findPins(path, depth + 1, found);
+        }
+        else if (/^(Package\.swift|Package\.resolved|project\.yml|project\.pbxproj|\.mcp\.json|mcp\.json|config\.toml)$/.test(entry.name)) {
+            const lines = (await readFile(path, "utf8").catch(() => "")).split("\n");
+            lines.forEach((line, i) => {
+                if (/axbridge/i.test(line) && /\d+\.\d+\.\d+|revision|version/i.test(line))
+                    found.push(`${path}:${i + 1}: ${line.trim()}`);
+            });
+        }
+    }
+    return found;
+}
+tool("update", "Check for a newer axbridge, preload it for npx and list where the app and agent configs pin a version.", {
+    project: z.string().optional().describe("App repository to search for version pins (Package.swift, Package.resolved, project.yml, MCP configs)"),
+}, async ({ project }) => {
+    const newest = await newerVersion(5000);
+    const lines = [];
+    if (!newest) {
+        lines.push(`axbridge-mcp ${VERSION} is the newest version (or npm is unreachable).`);
+    }
+    else {
+        await run("npx", ["-y", `axbridge-mcp@${newest}`, "--version"], { timeoutMs: 180_000 });
+        lines.push(`axbridge ${newest} is available, this server runs ${VERSION}. npx now has ${newest} cached.`, "1. Restart the axbridge MCP server so the new version runs (Claude Code: /mcp, then reconnect axbridge; Codex and Cursor: restart the session). If a config pins a version, raise it.", `2. Raise the AXBridge Swift package to ${newest} (tag v${newest}) and rebuild the app; app and server should run the same version.`, `Release notes: https://github.com/jx-grxf/axbridge/releases/tag/v${newest}`);
+    }
+    if (project) {
+        const pins = await findPins(project);
+        lines.push("", pins.length ? `Version pins in ${project}:\n${pins.join("\n")}` : `No axbridge version pins found in ${project}.`);
+    }
+    return text(lines.join("\n"));
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/version.js

@@ -0,0 +1,60 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export const VERSION = "0.1.1";
+const CACHE = join(homedir(), ".cache", "axbridge", "update.json");
+const DAY = 24 * 60 * 60 * 1000;
+/** Semver-ish comparison of x.y.z; pre-release tags count as older than the release. */
+export function isNewer(candidate, current) {
+    const parse = (v) => {
+        const [core, pre] = v.replace(/^v/, "").split("-", 2);
+        return { nums: core.split(".").map((n) => Number.parseInt(n, 10) || 0), pre: pre ?? "" };
+    };
+    const a = parse(candidate), b = parse(current);
+    for (let i = 0; i < 3; i++) {
+        const diff = (a.nums[i] ?? 0) - (b.nums[i] ?? 0);
+        if (diff !== 0)
+            return diff > 0;
+    }
+    if (a.pre === b.pre)
+        return false;
+    if (!a.pre)
+        return true;
+    if (!b.pre)
+        return false;
+    return a.pre > b.pre;
+}
+/**
+ * The newest published version, or null when offline, disabled or not newer. Checks npm at
+ * most once a day and never waits longer than `timeoutMs`.
+ */
+export async function newerVersion(timeoutMs = 1500) {
+    if (process.env.AXBRIDGE_NO_UPDATE_CHECK)
+        return null;
+    let latest;
+    try {
+        const cached = JSON.parse(await readFile(CACHE, "utf8"));
+        if (Date.now() - cached.checkedAt < DAY)
+            latest = cached.latest;
+    }
+    catch {
+        // no cache yet
+    }
+    if (!latest) {
+        try {
+            const response = await fetch("https://registry.npmjs.org/axbridge-mcp/latest", { signal: AbortSignal.timeout(timeoutMs) });
+            if (!response.ok)
+                return null;
+            latest = (await response.json()).version;
+            await mkdir(join(homedir(), ".cache", "axbridge"), { recursive: true });
+            await writeFile(CACHE, JSON.stringify({ checkedAt: Date.now(), latest }));
+        }
+        catch {
+            return null;
+        }
+    }
+    return latest && isNewer(latest, VERSION) ? latest : null;
+}
+export function updateHint(latest) {
+    return `axbridge ${latest} is available (running ${VERSION}). Call the \`update\` tool, or tell the user.`;
+}

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "axbridge-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "MCP server that lets coding agents drive iOS Simulator apps as text: read the screen from the accessibility tree, tap by name, type, scroll, plus device, app and screenshot tools.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ios",
+    "ios-simulator",
+    "simulator",
+    "xcode",
+    "swiftui",
+    "accessibility",
+    "ui-testing",
+    "claude-code",
+    "codex",
+    "cursor",
+    "ai-agent"
+  ],
+  "license": "MIT",
+  "author": "Johannes Grof",
+  "homepage": "https://github.com/jx-grxf/axbridge#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jx-grxf/axbridge.git",
+    "directory": "mcp"
+  },
+  "bugs": "https://github.com/jx-grxf/axbridge/issues",
+  "type": "module",
+  "bin": {
+    "axbridge-mcp": "dist/index.js",
+    "axbridge": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "os": [
+    "darwin"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "pixelmatch": "^8.0.0",
+    "pngjs": "^7.0.0",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/pngjs": "^6.0.5",
+    "typescript": "^7.0.2",
+    "vitest": "^5.1.0"
+  }
+}