内容
# 预检 MCP
用于 iOS 模拟器自动化的最全面的 MCP（模型上下文协议）服务器。 为 Claude、ChatGPT、Cursor、Windsurf 等 AI 代理以及任何兼容 MCP 的工具提供对 iOS 模拟器的完全控制 - 点击、滑动、输入、读取辅助树、检查应用数据、捕获截图、录制视频、管理设备、实时调试应用。
**82 种工具**，涵盖 14 个类别。 零光标干扰 - 在您使用 Mac 的同时在后台静默运行。
灵感来自用于网页自动化的 [Playwright MCP](https://github.com/anthropics/mcp-server-playwright) - Preflight 将同样的结构化无障碍优先方法带到 iOS。
[](https://www.npmjs.com/package/preflight-ios-mcp)
[](https://opensource.org/licenses/MIT)
## 为什么选择 Preflight？
- **无磁盘混乱** - 截图和视频帧直接返回聊天中。 无文件夹占用。
- **AI 优化** - 图像压缩以最小化 token 使用。 视频 → 关键帧（大多数 AI 模型无法查看视频文件）。
- **无障碍优先** - 像 Playwright 的 `browser_snapshot` 一样，使用 `simulator_snapshot` 在不使用视觉模型的情况下理解屏幕。
- **无光标** - 通过 idb（IndigoHID）进行触摸注入 - 您的 Mac 光标保持不动。
- **82 种工具** - 从基本的点击/滑动到 StoreKit 测试、网络调节、内存分析和崩溃日志分析。
## 快速入门
### 先决条件
- 安装了 Xcode 和 iOS 模拟器的 macOS
- Node.js 18+
- [Facebook idb](https://fbidb.io/)（推荐用于无光标操作）
### 安装 idb（推荐）
```bash
brew tap facebook/fb
brew install idb-companion
pip3 install fb-idb
```
> 如果没有 idb，服务器将回落到 CGEvent 鼠标注入（有效但会短暂移动您的光标）。
### 通过 npm 安装（推荐）
```bash
npm install -g preflight-ios-mcp
```
### 从源代码构建
```bash
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 代码
```bash
claude mcp add preflight -- npx preflight-ios-mcp
```
或添加到项目根目录中的 **.mcp.json**：
```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**（按项目）：
```json
{
"mcpServers": {
"preflight": {
"command": "npx",
"args": ["preflight-ios-mcp"],
"env": {
"PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
}
}
}
}
```
然后在 Cursor 中：**设置 → MCP** - 验证“preflight”显示为已连接。
### Windsurf
添加到 **~/.codeium/windsurf/mcp_config.json**：
```json
{
"mcpServers": {
"preflight": {
"command": "npx",
"args": ["preflight-ios-mcp"],
"env": {
"PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
}
}
}
}
```
然后在 Windsurf 中：**设置 → Cascade → MCP** - 验证“preflight”出现。
### VS Code（Copilot / Cline / Continue）
在项目中将以下内容添加到 **.vscode/mcp.json**：
```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**：
```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**：
```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 传输。 配置您的客户端以运行：
```bash
npx preflight-ios-mcp
```
将 `PATH` 环境变量设置为包含 idb 位置以进行无光标触摸注入。
## 工具参考
### 观察（6 种工具）
| 工具 | 描述 |
|------|-------------|
| `simulator_screenshot` | 拍摄优化为 AI 聊天的 JPEG 截图（~200-400KB）。 返回图像内联。 |
| `simulator_list_devices` | 列出模拟器，包含名称、UDID、状态、运行时。 过滤器：`booted`、`available`、`all`。 |
| `simulator_list_apps` | 列出已安装的应用，包含 bundle 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+[ 导航返回。 解决边缘滑动限制的变通方法。 |
### 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 包或 .ipa。 |
| `simulator_uninstall_app` | 按 bundle 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 坐标（纬度/经度）。 测试基于位置的功能。 |
| `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` | 开始屏幕录制。 停止时，关键帧会作为图像提取。 |
| `simulator_stop_recording` | 停止录制。 返回关键帧内联（无磁盘混乱）。 可选 `savePath` 以保留视频。 |
### 高级调试和测试（18 种工具）
| 工具 | 描述 |
|------|-------------|
| `simulator_set_content_size` | 设置动态类型首选大小（13 个类别，从超小到 accessibility-XXXL）。 |
| `simulator_set_increase_contrast` | 切换增加对比度无障碍设置。 |
| `simulator_location_scenario` | 运行预定义的 GPS 路线：Freeway Drive、City Run、City Bicycle Ride。 |
| `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's `leaks` 工具检查正在运行的应用的内存泄漏。 |
| `simulator_heap_info` | 转储堆分配摘要 - 按类计算对象数量、总内存。 |
| `simulator_vmmap` | 显示虚拟内存映射 - 区域、大小、权限。 |
| `simulator_sample_process` | 采样进程以检测 CPU 热点和挂起分析。 |
| `simulator_thermal_state` | 模拟热压状态变化（名义、一般、严重、临界）。 |
## 架构
```
src/
├── index.ts # MCP 服务器入口，82 种工具注册
├── helpers/
│ ├── idb.ts # Facebook idb CLI 包装器（无光标触摸）
│ ├── simctl.ts # xcrun simctl 命令包装器
│ ├── applescript.ts # 键盘输入 + CGEvent 备用
│ ├── coordinate-mapper.ts # 模拟器点 → macOS 屏幕坐标
│ ├── mouse-events.swift # 本机 Swift CGEvent 二进制文件（备用）
│ └── logger.ts # 结构化 stderr 日志记录
└── tools/
├── screenshot.ts # 针对 AI 聊天的 JPEG 捕获优化
├── interaction.ts # 点击、滑动、长按、输入、按键
├── device.ts # 启动、关闭、擦除、打开 URL
├── app.ts # 安装、启动、终止、列表
├── system.ts # 位置、推送、剪贴板、媒体、权限
├── ui.ts # 外观、状态栏、视频录制、返回导航
├── debug.ts # 日志、文件、崩溃报告、无障碍
├── advanced.ts # 动态类型、密钥链、iCloud、生物识别、默认值、无障碍、旋转、区域设置
├── storekit.ts # StoreKit 测试 - 交易、订阅、资格
├── network.ts # 网络调节（dnctl/pfctl）和捕获
├── profiling.ts # 内存性能分析 - 泄漏、堆、vmmap、采样、热状态
└── playwright.ts # 快照、等待元素、元素存在
```
### 设计理念
**优先考虑无障碍，像 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 可用？ ──YES──► idb ui tap --udid <UDID> 200 400
│ (IndigoHID → 真实的 iOS 触摸事件)
│ (零光标移动)
│
└─ idb 不可用？ ──► 坐标映射器 → macOS 屏幕坐标
→ Swift CGEvent 二进制文件 → 鼠标按下/抬起
```
## 演示应用
`demo-app/` 中包含一个 SwiftUI 演示应用，用于测试所有 MCP 功能：
```bash
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），启动它，并截取主屏幕的截图。然后点击登录按钮，输入 test@email.com 到电子邮件字段，并验证表单验证是否有效。”
### 无障碍优先工作流（类似 Playwright）
> “截取当前屏幕的快照以查看有哪些元素可用。然后点击标记为‘注册’的按钮，并等待电子邮件文本字段出现。”
### 调试
> “我的应用在启动时崩溃。检查 MyApp 的崩溃日志，然后获取 MyApp 进程过滤的过去 5 分钟的设备日志。”
### 暗黑模式测试
> “切换到暗黑模式，截取截图，然后切换到亮模式并再次截取截图。”
## 故障排除
### 检测不到 idb
如果工具显示 `[CGEvent 备用]` 而不是 `[无光标]`：
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 等）
## 开发
```bash
npm run dev # 监视模式（仅限 TypeScript）
npm run build # 完整重建（TypeScript + Swift 二进制文件）
node dist/index.js # 直接运行
```
## 许可证
MIT 许可证 - 参见 [LICENSE](LICENSE) 了解详情。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器