preflight-ios-mcp

Preflight MCP

功能最全面的 MCP（Model Context Protocol）iOS 模拟器自动化服务。让 Claude、ChatGPT、Cursor、Windsurf 等 AI Agent 以及任何兼容 MCP 的工具全面控制 iOS 模拟器——点击、滑动、输入、读取无障碍树、检查 App 数据、截取屏幕截图、录制视频、管理设备，并实时调试 App。

涵盖 14 个类别，共 82 个工具。不会干扰光标——可在后台静默运行，你仍可照常使用 Mac。

受用于 Web 自动化的 Playwright MCP 启发，Preflight 将相同的结构化、无障碍优先方法带到 iOS。

为什么选择 Preflight？

• 不会占用磁盘空间——屏幕截图和视频帧会直接返回到聊天中，不会留下堆积的文件夹。
• 针对 AI 优化——压缩图片，尽可能减少 Token 用量。视频会转换为关键帧（大多数 AI 模型无法查看视频文件）。
• 无障碍优先——如同 Playwright 的 browser_snapshot，使用 simulator_snapshot 即可了解屏幕内容，无需视觉模型。
• 不占用光标——通过 idb（IndigoHID）注入触控，Mac 光标保持不动。
• 82 个工具——从基本的点击／滑动，到 StoreKit 测试、网络调节、内存分析和崩溃日志分析。

快速开始

前置条件

• 已安装 Xcode 和 iOS Simulator 的 macOS
• Node.js 18+
• Facebook idb（推荐，可避免占用光标）

安装 idb（推荐）

brew tap facebook/fb
brew install idb-companion
pip3 install fb-idb

如果未安装 idb，服务会回退到 CGEvent 鼠标注入（可以正常工作，但会短暂移动光标）。

通过 npm 安装（推荐）

npm install -g preflight-ios-mcp

从源代码构建

git clone https://github.com/EthanAckerman-git/Preflight.git
cd Preflight
npm install
npm run build

按 IDE／AI 工具配置

如果通过 pip 安装了 idb，请将 Python bin 目录添加到 PATH（例如 ~/Library/Python/3.x/bin）。

Claude Code

claude mcp add preflight -- npx preflight-ios-mcp

也可以将以下内容添加到项目根目录中的 .mcp.json：

{
  "mcpServers": {
    "preflight": {
      "command": "npx",
      "args": ["preflight-ios-mcp"],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Cursor

将以下内容添加到 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（按项目配置）：

{
  "mcpServers": {
    "preflight": {
      "command": "npx",
      "args": ["preflight-ios-mcp"],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

然后在 Cursor 中前往：Settings → MCP，确认 "preflight" 显示为已连接。

Windsurf

将以下内容添加到 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "preflight": {
      "command": "npx",
      "args": ["preflight-ios-mcp"],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

然后在 Windsurf 中前往：Settings → Cascade → MCP，确认 "preflight" 已显示。

VS Code（Copilot / Cline / Continue）

将以下内容添加到项目中的 .vscode/mcp.json：

{
  "servers": {
    "preflight": {
      "command": "npx",
      "args": ["preflight-ios-mcp"],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

对于 Cline（VS Code 扩展），请将以下内容添加到 ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json：

{
  "mcpServers": {
    "preflight": {
      "command": "npx",
      "args": ["preflight-ios-mcp"],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Zed

将以下内容添加到 ~/.config/zed/settings.json：

{
  "context_servers": {
    "preflight": {
      "command": {
        "path": "npx",
        "args": ["preflight-ios-mcp"],
        "env": {
          "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
        }
      }
    }
  }
}

任何兼容 MCP 的客户端

Preflight 使用标准 MCP stdio 传输。配置客户端以运行：

npx preflight-ios-mcp

设置 PATH 环境变量，使其包含 idb 的位置，从而实现不占用光标的触控注入。

工具参考

观察（6 个工具）

工具	描述
simulator_screenshot	获取针对 AI 聊天优化的 JPEG 屏幕截图（约 200-400KB）。以内嵌图片形式返回。
simulator_list_devices	列出模拟器及其名称、UDID、状态和运行时。筛选条件：booted、available、all。
simulator_list_apps	列出已安装的 App 及其 Bundle ID。设置 includeSystem 可包含系统 App。
simulator_app_info	获取 App 元数据：名称、版本、Bundle 路径、数据路径和类型。
simulator_get_clipboard	读取模拟器的剪贴板文本。
simulator_get_screen_info	获取窗口几何信息、坐标映射和缩放系数。用于调试点击精度。

用户交互（6 个工具）

工具	描述
simulator_tap	在模拟器屏幕坐标 (x, y) 处点击。通过 idb 操作，无需光标。
simulator_swipe	在两点之间滑动。支持从 x=1 处边缘滑动返回。
simulator_long_press	按住指定时长。用于打开上下文菜单、开始拖动。
simulator_type_text	在当前聚焦的字段中输入文本。
simulator_press_key	按下特殊键（return、escape、箭头键、F 键），并可使用修饰键。
simulator_navigate_back	通过 Cmd+[ 返回。用于解决边缘滑动的限制。

受 Playwright 启发的工具（3 个）

工具	描述
simulator_snapshot	优先于屏幕截图使用。 提供结构化无障碍树——角色、标签、值和位置。无需视觉模型。类似于 Playwright 的 browser_snapshot。
simulator_wait_for_element	等待元素出现（按标签、角色或文本匹配）。按可配置的超时时间轮询。类似于 Playwright 的 browser_wait_for。
simulator_element_exists	快速布尔值检查：当前屏幕上是否存在符合条件的元素？

设备管理（6 个工具）

工具	描述
simulator_boot	按名称或 UDID 启动设备。可选等待启动完成的 waitForBoot 轮询。
simulator_shutdown	关闭正在运行的模拟器。
simulator_erase	恢复出厂设置——抹掉所有内容和设置。
simulator_open_url	打开 URL 或深层链接（例如，myapp://screen）。
simulator_open_simulator	打开 Simulator.app 应用程序。
simulator_get_booted_sim_id	获取当前已启动模拟器的 UDID。

应用管理（4 个工具）

工具	描述
simulator_launch_app	按 bundle ID 启动应用，可选传入参数和环境变量。
simulator_terminate_app	强制终止正在运行的应用。
simulator_install_app	从本地路径安装 .app bundle 或 .ipa。
simulator_uninstall_app	按 bundle ID 卸载应用。

调试与诊断（9 个工具）

工具	描述
simulator_get_logs	查询设备日志。可按进程、子系统、级别、时间范围和消息内容筛选。
simulator_stream_logs	实时流式传输日志，包含启动、读取和停止生命周期。缓冲区可配置。
simulator_get_app_container	获取应用的 bundle、数据或共享组容器的文件系统路径。
simulator_list_app_files	浏览应用的 Documents/、Library/、Caches/、tmp/ 目录。
simulator_read_app_file	从应用数据中读取 plist（→JSON）、SQLite（→架构）和文本文件。
simulator_get_crash_logs	获取崩溃报告，包含堆栈跟踪和线程状态。
simulator_diagnose	Xcode 版本、磁盘使用情况、已启动设备和系统信息。
simulator_accessibility_audit	完整的 iOS 无障碍树——包含带标签、框架和角色的真实 UIButton/UILabel 元素。
simulator_describe_point	返回给定坐标处的无障碍元素。

系统模拟（5 个工具）

工具	描述
simulator_set_location	设置 GPS 坐标（lat/lng）。测试基于位置的功能。
simulator_send_push	发送包含完整 APNs 负载 JSON 的推送通知。
simulator_set_clipboard	设置模拟器剪贴板文本。
simulator_add_media	从本地文件向相机胶卷添加照片/视频。
simulator_grant_permission	授予、撤销或重置权限（相机、位置、照片、联系人、麦克风等）。

UI 配置（4 个工具）

工具	描述
simulator_set_appearance	在浅色模式和深色模式之间切换。
simulator_override_status_bar	设置时间、电池、信号、运营商和网络类型。
simulator_record_video	开始录屏。停止后，会提取关键帧作为图片用于 AI 聊天。
simulator_stop_recording	停止录屏。以内联方式返回关键帧（不会产生磁盘杂项）。可选使用 savePath 保存视频。

高级调试与测试（18 个工具）

工具	描述
simulator_set_content_size	设置 Dynamic Type 首选字号（从超小到辅助功能 XXXL，共 13 个类别）。
simulator_set_increase_contrast	切换“增强对比度”辅助功能设置。
simulator_location_scenario	运行预定义的 GPS 路线：高速公路驾驶、城市跑步、城市骑行。
simulator_location_route	沿自定义航点模拟移动，并可配置速度。
simulator_memory_warning	触发模拟内存警告（didReceiveMemoryWarning）。
simulator_keychain	添加根证书、添加证书，或重置设备钥匙串。
simulator_icloud_sync	在设备上触发 iCloud 同步。
simulator_verbose_logging	启用或禁用详细设备日志，以进行深入调试。
simulator_install_app_data	安装 .xcappdata 软件包以恢复测试数据快照。
simulator_get_env	读取运行中模拟器的环境变量。
simulator_biometric	为身份验证测试注册、取消注册、匹配或模拟 Face ID / Touch ID 验证失败。
simulator_network_status	获取网络配置，包括 DNS、接口和连接状态。
simulator_defaults_read	在模拟器内部读取 UserDefaults（检查应用偏好设置和功能标志）。
simulator_defaults_write	在模拟器内部写入 UserDefaults（设置标志、注入测试配置）。
simulator_rotate	向左或向右旋转模拟器。
simulator_notify_post	发送 Darwin 通知以触发系统事件。
simulator_set_locale	设置设备区域设置，以进行国际化测试。
simulator_trigger_siri	调用 Siri 进行语音命令测试。

辅助功能设置（4 个工具）

工具	描述
simulator_set_reduce_motion	切换“减弱动态效果”辅助功能设置（通过 defaults write + 通知）。
simulator_set_smart_invert	切换“智能反转颜色”（通过 defaults write + 通知）。
simulator_set_bold_text	切换“粗体文本”（通过 defaults write + 通知）。
simulator_set_reduce_transparency	切换“降低透明度”（通过 defaults write + 通知）。

设备创建与管理（4 个工具）

工具	描述
simulator_create_device	使用设备类型和运行时创建新的模拟器。
simulator_delete_device	永久删除模拟器设备。
simulator_rename_device	重命名现有设备。
simulator_clone_device	克隆设备及其全部状态。

StoreKit 测试（6 个工具）——Xcode 14-16

工具	描述
simulator_storekit_config	启用或禁用 StoreKit 测试模式。
simulator_storekit_transactions	列出所有 StoreKit 测试交易。
simulator_storekit_delete_transactions	清除所有测试交易。
simulator_storekit_manage_subscription	使订阅过期或强制续订。
simulator_storekit_manage_transaction	退款、批准或拒绝“购买前询问”交易。
simulator_storekit_reset_eligibility	重置所有产品的入门优惠资格。

网络测试（2 个工具）

工具	描述
simulator_network_condition	使用预设值（3G、LTE、Edge、WiFi、100% 丢包）或自定义带宽、延迟和丢包率来限制网络。
simulator_network_capture	捕获网络活动摘要——活动连接、DNS、网络接口。

调试与性能分析（5 个工具）

工具	描述
simulator_leak_check	通过 Apple 的 leaks 工具检查正在运行的应用是否存在内存泄漏。
simulator_heap_info	导出堆分配摘要——按类统计对象数量及总内存。
simulator_vmmap	显示虚拟内存映射——区域、大小、权限。
simulator_sample_process	对进程进行采样，以检测 CPU 热点并分析卡顿。
simulator_thermal_state	模拟热压力状态变化（nominal、fair、serious、critical）。

架构

src/
├── index.ts                    # MCP server entry, 82 tool registrations
├── helpers/
│   ├── idb.ts                  # Facebook idb CLI wrapper (cursor-free touch)
│   ├── simctl.ts               # xcrun simctl command wrapper
│   ├── applescript.ts          # Keyboard input + CGEvent fallback
│   ├── coordinate-mapper.ts    # Simulator points → macOS screen coords
│   ├── mouse-events.swift      # Native Swift CGEvent binary (fallback)
│   └── logger.ts               # Structured stderr logging
└── tools/
    ├── screenshot.ts           # JPEG capture optimized for AI chat
    ├── interaction.ts          # Tap, swipe, long press, type, key
    ├── device.ts               # Boot, shutdown, erase, open URL
    ├── app.ts                  # Install, launch, terminate, list
    ├── system.ts               # Location, push, clipboard, media, permissions
    ├── ui.ts                   # Appearance, status bar, video recording, navigate back
    ├── debug.ts                # Logs, files, crash reports, accessibility
    ├── advanced.ts             # Dynamic Type, keychain, iCloud, biometric, defaults, accessibility, rotation, locale
    ├── storekit.ts             # StoreKit testing — transactions, subscriptions, eligibility
    ├── network.ts              # Network conditioning (dnctl/pfctl) and capture
    ├── profiling.ts            # Memory profiling — leaks, heap, vmmap, sample, thermal
    └── playwright.ts           # Snapshot, wait_for_element, element_exists

设计理念

以无障碍为先，类似 Playwright MCP：

1. 使用 simulator_snapshot 了解屏幕内容（结构化文本，无需视觉模型）
2. 使用快照中的坐标调用 simulator_tap、simulator_swipe 等工具
3. 需要视觉验证时，使用 simulator_screenshot
4. 与转换后出现的元素交互前，使用 simulator_wait_for_element

避免磁盘杂乱：

• 截图以 base64 格式返回到聊天中——不会让桌面堆满文件夹
• 视频录制会在停止时提取关键帧并作为内嵌图片显示
• 如果确实需要将文件保存到磁盘，可选用 savePath 参数

触摸注入管线

simulator_tap(x=200, y=400)
    │
    ├─ idb available? ──YES──► idb ui tap --udid <UDID> 200 400
    │                           (IndigoHID → real iOS touch event)
    │                           (zero cursor movement)
    │
    └─ idb unavailable? ──► coordinate mapper → macOS screen coords
                             → Swift CGEvent binary → mouse down/up

演示应用

demo-app/ 中包含一个 SwiftUI 演示应用，可用于测试所有 MCP 功能：

cd demo-app
xcodebuild -project MCPDemo.xcodeproj -scheme MCPDemo \
  -destination 'platform=iOS Simulator,name=iPhone 16 Pro' \
  build

演示应用包含 7 个标签页，可用于测试每类工具：

• 交互：按钮、文本字段、长按区域、导航栈、可滚动列表
• 位置：实时 GPS 显示，用于测试 simulator_set_location
• 通知：推送通知显示，用于测试 simulator_send_push
• 设置：剪贴板、文件 I/O、无障碍切换项、UserDefaults
• StoreKit：模拟购买和订阅，用于测试 StoreKit 工具
• 网络：连接监控和延迟测试，用于测试网络调节功能
• 调试：内存/CPU 压力测试、热状态、无障碍设置观察器、生物识别认证

配置

环境变量

变量	默认值	描述
LOG_LEVEL	info	日志级别：debug、info、warn、error
PREFLIGHT_FILTERED_TOOLS	（无）	要禁用的工具名称列表，以逗号分隔
PREFLIGHT_IDB_PATH	（自动检测）	idb 二进制文件的自定义路径
PATH	系统 PATH	必须包含 idb 二进制文件所在位置

提示词示例

QA 测试

“启动 iPhone 16 Pro 模拟器，在其中安装位于 ./build/MyApp.app 的应用，启动应用，并截取主屏幕。然后点击登录按钮，在电子邮件字段中输入 [email protected]，并验证表单校验是否有效。”

无障碍优先工作流（Playwright 风格）

“为当前屏幕拍摄快照，查看可用元素。然后点击标记为 ‘Sign In’ 的按钮，并等待电子邮件文本字段出现。”

调试

“我的应用启动时崩溃了。检查 MyApp 的崩溃日志，然后获取最近 5 分钟经过筛选、仅包含 MyApp 进程的设备日志。”

深色模式测试

“切换到深色模式并截图，然后切换到浅色模式并再次截图。”

故障排除

未检测到 idb

如果工具显示 [CGEvent fallback] 而不是 [cursor-free]：

1. 验证是否已安装 idb：运行 which idb，或检查 ~/Library/Python/3.x/bin/idb
2. 将 idb 路径添加到 MCP 配置的 PATH 环境变量中
3. 或直接设置 PREFLIGHT_IDB_PATH

未找到模拟器

1. 打开 Simulator.app：open -a Simulator
2. 启动设备：使用 simulator_boot 或 xcrun simctl boot "iPhone 16 Pro"

辅助功能权限错误

1. 前往“系统设置” →“隐私与安全性” →“辅助功能”
2. 添加你的终端应用（Terminal.app、iTerm、Claude Code、Cursor、Windsurf 等）

开发

npm run dev    # Watch mode (TypeScript only)
npm run build  # Full rebuild (TypeScript + Swift binary)
node dist/index.js  # Run directly

许可证

MIT 许可证 — 详情请参阅 LICENSE。