使用说明

飞行前MCP

用于iOS模拟器自动化的最全面的MCP（模型上下文协议）服务器。为Claude、ChatGPT、Cursor、Windsurf和任何MCP兼容工具等AI代理提供对iOS模拟器的完全控制——点击、滑动、键入、读取可访问性树、检查应用程序数据、捕获屏幕截图、录制视频、管理设备和实时调试应用程序。

82工具 横跨14个类别。零光标干扰-在使用Mac时在后台默默工作。

灵感源自剧作家MCP Preflight为iOS带来了同样的结构化可访问性优先方法。

为什么选择Preflight？

无磁盘杂乱 --截图和视频帧直接返回聊天。没有文件夹填满。
AI优化 --压缩图像以减少令牌使用。视频→ 关键帧（大多数AI模型无法查看视频文件）。
可访问性优先 --就像剧作家的 browser_snapshot，使用 simulator_snapshot 在没有视觉模型的情况下理解屏幕。
无光标 --通过idb（IndigoHID）进行触摸注入——您的Mac光标保持不变。
82工具 --从基本的点击/滑动到StoreKit测试、网络调节、内存分析和崩溃日志分析。

快速开始

先决条件

安装了Xcode和iOS模拟器的macOS
Node.js 18+
Facebook ID （建议用于无光标操作）

安装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工具进行设置

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

克劳德代码

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/mcp.json （全球）或 .cursor/mcp.json （每个项目）：

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

然后在游标中： 设置→ MCP --确认“飞行前”显示为已连接。

帆板运动

添加 ~/.codium/wundsurf/mcp_gonfig.json:

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

然后在Windsurf： 设置→ 级联→ MCP --确认“飞行前”出现。

VS代码（复制/临床/继续）

添加 .vcode/mcp.json 在您的项目中：

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

对于 克莱恩 （VS代码扩展名），添加到 ~/库/应用程序支持/代码/用户/全局存储/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"
      }
    }
  }
}

泽德

添加 ~/.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`	列出带有捆绑包ID的已安装应用程序。切换 `includeSystem` 对于系统应用程序。
`simulator_app_info`	获取应用元数据：名称、版本、捆绑包路径、数据路径、类型。
`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`	使用修改器按特殊键（回车、转义、箭头、F键）。
`simulator_navigate_back`	通过Cmd+[返回。解决边缘滑动限制

剧作家灵感（3个工具）

工具	说明
`simulator_snapshot`	比截图更受欢迎。结构化可访问性树——角色、标签、值、位置。不需要视觉模型。就像剧作家的 `browser_snapshot`.
`simulator_wait_for_element`	等待元素出现（按标签、角色或文本）。具有可配置超时的轮询。就像剧作家的 `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`	通过带有可选参数和环境变量的捆绑包ID启动。
`simulator_terminate_app`	强制终止正在运行的应用程序。
`simulator_install_app`	从本地路径安装.app捆绑包或.ipa。
`simulator_uninstall_app`	按捆绑包ID卸载

调试与诊断（9个工具）

工具	说明
`simulator_get_logs`	查询设备日志。按流程、子系统、级别、时间范围、消息内容过滤。
`simulator_stream_logs`	具有启动/读取/停止生命周期的实时日志流。可配置缓冲区。
`simulator_get_app_container`	获取应用程序包、数据或共享组容器的文件系统路径。
`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`	设置动态类型首选大小（从超小到可访问性XXXL的13个类别）。
`simulator_set_increase_contrast`	切换“增加对比度”辅助功能设置。
`simulator_location_scenario`	运行预定义的GPS路线：高速公路行驶、城市跑步、城市自行车骑行。
`simulator_location_route`	以可配置的速度模拟沿自定义航路点的移动。
`simulator_memory_warning`	触发模拟内存警告（didDeceiveMemoryWarning）。
`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`	切换“减少运动”辅助功能设置（通过默认写入+通知）。
`simulator_set_smart_invert`	切换智能反转颜色（通过默认写入+通知）。
`simulator_set_bold_text`	切换粗体文本（通过默认写入+通知）。
`simulator_set_reduce_transparency`	切换降低透明度（通过默认写入+通知）。

设备创建和管理（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`	模拟热压状态变化（标称、一般、严重、临界）。

建筑

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

设计理念

可访问性优先，如剧作家MCP：

使用 simulator_snapshot 理解屏幕（结构化文本，无视觉模型）
使用快照中的坐标 simulator_tap, simulator_swipe等等。
使用 simulator_screenshot 当您需要视觉验证时
使用 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

演示应用程序

SwiftUI演示应用程序包含在 demo-app/ 用于测试所有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、可访问性切换、用户默认值
StoreKit：模拟购买和订阅以测试StoreKit工具
网络：网络调节的连接监控和延迟测试
调试：内存/CPU压力测试、热状态、可访问性设置观察者、生物特征认证

配置

环境变量

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

示例提示

QA测试

“启动iPhone 16 Pro模拟器，在./build/MyApp.app上安装我的应用程序，启动它，并拍摄主屏幕的屏幕截图。然后点击登录按钮，键入test@email.com在电子邮件字段中，验证表单验证是否有效。"

可访问性优先工作流程（剧作家风格）

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

调试

“我的应用程序在启动时崩溃。请检查MyApp的崩溃日志，然后将最后5分钟的设备日志过滤到MyApp进程中。”

暗模式测试

“切换到暗模式，截图，然后切换到亮模式并再次截图。”

故障排除

未检测到idb

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

验证是否安装了idb： which idb 或检查 ~/Library/Python/3.x/bin/idb
将idb路径添加到MCP配置中 PATH env 是
或设置 PREFLIGHT_IDB_PATH 直接

未找到模拟器

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

访问权限错误

转到系统设置→ 隐私和安全→ 无障碍
添加您的终端应用程序（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许可证——见许可证了解详情。