xcforge — iOS Development MCP Server & CLI

xcforge is a native Swift MCP server and CLI for iOS development. 109 MCP tools, 113 CLI commands across 19 groups, zero runtime dependencies. It provides build, test, simulator management, physical device support via devicectl, Swift package workflows, UI automation via WebDriverAgent with native HID fallback, ultra-fast screenshots, clipboard access, video recording, location simulation, appearance control, status bar overrides, smart log filtering, visual regression, multi-device checks, accessibility/localization layout checks, session profiles, structured diagnosis workflows, multi-step plan execution, visual pose iteration, bless (baseline+test+diff in one call), agent-optimized test output with known-failures gating, and test plan inspection. Every MCP tool has a CLI equivalent.

Key advantages over alternatives:

• Screenshots in 0.3s (44x faster) via CoreSimulator IOSurface API
• Native HID taps/swipes in <5ms (bypasses WDA when available)
• Structured xcresult parsing — pass/fail counts, failure file:line, failure screenshots
• One-call alert batching (accept_all) handles 3+ permission dialogs
• Topic-filtered logs — 90% fewer tokens, 8 topics with line counts
• Element-to-element drag & drop in 1 call
• Auto-scroll to off-screen elements (3-tier fallback)
• View hierarchy in ~20ms (750x faster)
• Physical device support — install, launch, terminate, list apps via devicectl
• Session profiles — save/switch named default sets for quick context switching

Reference Loading Guide

Load reference files when using or advising on any xcforge tool. Each reference covers one tool category with exact parameters, return values, and usage patterns.

Auto-Detection — How Parameters Resolve

All tools that accept project, scheme, simulator, bundle_id, or app_path follow this resolution order:

1. Explicit parameter — highest priority
2. In-session value — set this session via set_defaults/profile_switch, auto-promoted, or already resolved
3. Repo config — .xcforge.yaml at the repo root (committed team config; xcforge init scaffolds it)
4. Persisted defaults — machine-global ~/.xcforge/defaults.json
5. Auto-detect — scans working directory for .xcodeproj/.xcworkspace, queries xcodebuild for schemes, finds booted simulator
6. Error with options — lists available choices if detection fails

Repo config beats persisted defaults (committed .xcforge.yaml outranks the personal machine-global file — like git local > global). .xcforge.yaml also supports repo-only configuration and testPlan keys.

Auto-promotion: 3 consecutive calls with the same explicit value auto-promotes it to a session default.

Most tools work with zero parameters for single-project repos with one booted simulator.

Common Workflows

Build & Launch (Cmd+R equivalent)

build_run_sim()  → builds + boots + installs + launches in parallel (~9s faster)

Test → Fix → Verify (MCP)

build_and_test()                              → build + test in one call (preferred)
build_and_test(filter: "testFoo")             → build + run specific test (auto-resolves target)
test_failures(include_console: true)          → error messages + file:line + console
# fix the code...
build_and_test(filter: "testFoo")             → verify fix

Discover Tests → Run Specific Test (MCP)

list_tests()                                  → enumerate Target/Class/method identifiers
test_sim(filter: "MyClass/testFoo")           → run specific test (auto-resolves target)

TDD Loop (CLI)

xcforge build run                             → Cmd+R equivalent: build + boot + install + launch
xcforge build-test                            → build + test in one step (preferred for TDD)
xcforge build-test --filter "testFoo"         → build + run specific test
xcforge build-test --env BLESS_BASELINE=1     → inject TEST_RUNNER_BLESS_BASELINE=1 into test process
xcforge build-test --for agent                → slim ≤10-field JSON (agent-safe output)
xcforge build-test --gate                     → subtract .xcforge/known-failures.yaml from pass/fail
xcforge test list                             → list all test identifiers
xcforge test --filter "MyTests/testFoo"       → run specific test (auto-resolves target)
xcforge test rerun-failed                     → replay only failures from last run (.xcforge/last-failures.json)
xcforge test plan inspect --plan AllTests     → inspect .xctestplan configurations + targets
xcforge test failures --include-console       → drill into failures
xcforge test coverage --file Foo.swift        → per-function coverage
xcforge build diagnose                        → structured diagnostics from last build's xcresult

Bless Workflow (baseline + tests + diff in one call)

xcforge bless --baseline login-screen --tests "UITests/LoginTests"
# MCP:
bless(baseline: "login-screen", tests: "UITests/LoginTests")

UI Automation Flow

build_run_sim()                               → app running in simulator
handle_alert(action: "accept_all")            → dismiss permission dialogs
find_element(using: "accessibility id", value: "Save", scroll: true)
click_element(element_id: "...")
screenshot()                                  → verify result

Multi-Step UI Plan (1 call replaces 15+ round-trips)

run_plan(steps: [
  {"find": "Login", "as": "$loginBtn"},
  {"click": "$loginBtn"},
  {"waitFor": "Welcome", "timeout": 5},
  {"verify": {"screenContains": "Dashboard"}},
  {"screenshot": "after_login"}
])
# If a judge step suspends:
run_plan_decide(session_id: "...", decision: "accept")

Multi-Step UI Plan (CLI)

xcforge plan run --file login-flow.json               → execute plan from file
xcforge plan run --file login-flow.json --json         → structured JSON output
xcforge plan decide --session-id UUID --decision skip  → resume suspended plan

Debug with Logs

start_log_capture(mode: "smart")
# reproduce the issue...
read_logs()                                   → app + crashes + topic menu
read_logs(include: ["network"])               → add network topic
wait_for_log(pattern: "error.*timeout", timeout: 10)

Visual Regression

screenshot() → save_visual_baseline(name: "login-screen")
# make changes...
compare_visual(name: "login-screen")          → pixel diff + match %

Multi-Device Check

multi_device_check(
  app_path: "/path/to/App.app",
  simulators: "iPhone 16,iPad Pro 13-inch (M4)",
  dark_mode: true, landscape: true
)

Video Recording

record_video_start()                          → starts .mov recording
# perform actions...
record_video_stop()                           → returns file path

Screenshot Prep (Clean Status Bar)

sim_statusbar(time: "9:41", battery_level: 100, battery_state: "charged", cellular_bars: 4, wifi_bars: 3)
set_sim_appearance(appearance: "light")
screenshot()
sim_statusbar_clear()

Location Testing

set_sim_location(latitude: 37.7749, longitude: -122.4194)  → San Francisco
# test location features...
reset_sim_location()

Session Profiles (MCP)

set_defaults(project: "MyApp.xcodeproj", scheme: "MyApp", simulator: "iPhone 16 Pro")
profile_save(name: "iphone-debug")
set_defaults(simulator: "iPad Pro 13-inch (M4)")
profile_save(name: "ipad-debug")
profile_switch(name: "iphone-debug")          → switch context instantly
profile_list()                                → see all saved profiles

Physical Device Workflow

list_devices()                                → connected devices
device_info(device: "iPhone")                 → detailed info
device_install(device: "iPhone", app_path: "/path/to/App.app")
device_launch(device: "iPhone", bundle_id: "com.app.id")
device_apps(device: "iPhone")                 → list installed apps
device_terminate(device: "iPhone", identifier: "com.app.id")

Swift Package Workflow (MCP)

swift_package_build()                         → build in current directory
swift_package_test(filter: "MyTests")         → run specific tests
swift_package_run(executable: "mytool")       → run an executable target
swift_package_list()                          → show dependency tree
swift_package_clean()                         → clean build artifacts

Swift Package Workflow (CLI)

xcforge spm build                             → build package
xcforge spm test --filter "MyTests"           → run filtered tests
xcforge spm run mytool -- --verbose            → run with args
xcforge spm list                              → dependency tree
xcforge spm clean                             → clean artifacts

LLDB Debugging (MCP — session-based)

lldb_attach(bundleId: "com.example.App")      → { sessionId, pid, status: "stopped" }
lldb_set_breakpoint(sessionId: "...", file: "Foo.swift", line: 42)
lldb_continue(sessionId: "...", mode: "continue")   → runs until breakpoint; 10s timeout
lldb_backtrace(sessionId: "...", threadIndex: 0)    → structured frames
lldb_inspect_variable(sessionId: "...", expression: "self.count")
lldb_run_command(sessionId: "...", command: "thread list")
lldb_detach(sessionId: "...")

LLDB Debugging (CLI — one-shot)

xcforge debug attach --bundle-id com.example.App   → prints sessionId
xcforge debug backtrace --bundle-id com.example.App
xcforge debug inspect --bundle-id com.example.App --expression "self.count"
xcforge debug breakpoint set --bundle-id com.example.App --file Foo.swift --line 42
xcforge debug continue --bundle-id com.example.App --mode step-over
xcforge debug run --bundle-id com.example.App --command "thread list"

Clipboard Access

clipboard_set(text: "test data")              → write to pasteboard
clipboard_get()                               → read pasteboard content

Common Mistakes

1. Starting log capture after the event — start_log_capture only captures from the moment it's called. Start capture BEFORE reproducing the issue.

1. Not using `accept_all` after fresh install — First app launch shows 2-3 permission dialogs. Call handle_alert(action: "accept_all") right after launch_app or build_run_sim.

1. Manual swipe loops to find elements — Use find_element(scroll: true) instead. It handles auto-scrolling with 3-tier fallback (scrollToVisible, calculated drag, iterative with stall detection).

1. Using `get_source` for every element lookup — find_element is faster and more reliable. Use get_source only when you need the full hierarchy for analysis.

1. Ignoring topic menu in `read_logs` — The topic menu shows line counts. Use include to add specific topics rather than reading everything.

1. Not setting defaults for repeated operations — Call set_defaults(project: "...", scheme: "...", simulator: "...") at the start of a session to avoid repeating parameters.

1. Using `test_sim` then parsing output for failures — Use test_failures for detailed failure info with file:line and screenshots. test_sim gives the summary; test_failures gives the details.

1. Forgetting WDA session — UI automation tools require WebDriverAgent running on the simulator. If wda_status fails, WDA needs to be started. build_run_sim does NOT start WDA automatically.

Sub-pitfall: WDA can't see SwiftUI sheets / alerts / `fullScreenCover`. Those mount in a secondary window owned by the app. Queries reach them only when the WDA session is bound to the app's bundle id. Run xcforge ui session --bundle-id <id> once — WDAClient persists the binding across recreates from then on, and the CLI verifies the binding via GET /session/<sid>, exiting non-zero on mismatch (no more silent no-binds). If ui find / tap-by-id 404s on an id you can see in ui ls, this is almost always why.

Sub-pitfall: `xcforge ui ls` returning 300+ macOS menubar elements. That's AXP returning Simulator.app's chrome instead of the iOS app tree. ui ls --source auto (default) flips to WDA when an iOS sim is booted — pre-1.4.1 it always preferred AXP. If you still get the wrong tree, force it: --source wda.

Sub-pitfall: `xcforge pose --screenshot` capturing the launch zoom animation. pose now waits 1.5s by default before capturing so the iOS launch zoom can settle. Override with --screenshot-delay <sec> (use 0 for legacy immediate-capture).

1. Not clearing status bar overrides — sim_statusbar overrides persist until cleared. Always call sim_statusbar_clear() after capturing screenshots with overrides.

1. Confusing simulator vs device tools — Simulator tools (sim, build_sim, etc.) don't work with physical devices. Use device_* tools (list_devices, device_install, etc.) for physical iOS devices connected via USB/WiFi.

1. Using `build_sim` for Swift packages — Swift packages don't have .xcodeproj files. Use swift_package_build / swift_package_test instead.