技术文档摘要

📱 MCP Server for iOS Simulator

这是一个模型上下文协议（MCP）服务器，它使大型语言模型（LLMs）能够通过自然语言命令与iOS模拟器进行交互。

ℹ️ 概述

此MCP服务器在大型语言模型（LLMs）和iOS模拟器之间提供了一个桥梁，通过自然语言命令实现全面控制。以下是它可以完成的任务：

对于详细使用，请参阅安装指南和支持命令部分。您可以直接通过MCP集成或作为独立库来使用此服务器。

查看架构部分以了解组件如何协同工作，以实现对iOS模拟器的自然语言控制。

🎮 模拟器控制

• 创建和管理模拟器会话
• 启动、关闭并监控模拟器状态
• 列出可用和正在运行的模拟器
• 将焦点放在模拟器窗口上

📱 应用程序管理

• 安装和管理iOS应用程序
• 启动、终止和卸载应用
• 监控应用状态并验证安装
• 处理应用权限和配置

🖱️ 用户界面交互与测试

• 与模拟器用户界面交互
• 执行点击、滑动和按钮按压操作
• 输入文本和键序列
• 访问用于UI测试的可访问性元素
• 录制UI交互视频

🛠️ 开发与调试

• 捕获屏幕截图和系统日志
• 实时调试应用
• 监控和分析崩溃日志
• 安装动态库并管理应用数据

⚡ 高级功能

• 其他功能包括：
  • 位置模拟
  • 媒体注入
  • URL方案处理
  • 联系人数据库管理
  • 密钥链操作

对于详细使用，请参阅安装指南和支持命令部分。您可以直接通过MCP集成或作为独立库来使用此服务器。

查看架构部分以了解组件如何协同工作，以实现对iOS模拟器的自然语言控制。

📋 要求

• macOS：支持iOS模拟器
• Node.js：v14.0.0 或更高版本
• Homebrew：用于安装依赖项
• XCode：已安装iOS模拟器

🚀 安装

最简单的安装方式是通过Cline：

1. 简单地请求Cline：

添加此mcp到cline https://github.com/InditexTech/mcp-server-simulator-ios-idb

2. Cline将自动处理安装过程，包括依赖管理和配置。

或者，您可以手动安装：

# 克隆仓库
git clone https://github.com/InditexTech/mcp-server-simulator-ios-idb.git
cd mcp-server-simulator-ios-idb

# 创建并激活Python虚拟环境
python3 -m venv venv
source venv/bin/activate  # 在Unix/macOS上

# 安装依赖项
npm install

# 构建项目
npm run build

# 启动项目
npm start

# 运行测试
npm test

安装过程将自动：

1. 检查您是否在运行macOS
2. 通过Homebrew安装idb-companion
3. 在虚拟环境中通过pip安装fb-idb

注意：在使用服务器期间，请确保虚拟环境处于激活状态。如果您关闭终端并稍后返回，需要先使用source venv/bin/activate命令重新激活虚拟环境，然后再运行npm start。

🔌 MCP集成

要将此服务器与Claude或其他LLM助手一起使用：

1. 将服务器添加到Claude Desktop中的MCP设置中：

{
  "mcpServers": {
    "ios-simulator": {
      "command": "node",
      "args": ["/path/to/mcp-server-simulator-ios-idb/dist/index.js"],
      "env": {}
    }
  }
}

2. LLM现在可以使用自然语言命令来控制iOS模拟器：

创建一个带有iPhone 14的模拟器会话
安装应用 /path/to/my-app.ipa
启动应用 com.example.myapp
点击 100, 200
截屏

📚 作为库使用

您还可以在自己的项目中将此包作为库使用：

🔰 基本使用

import { createMCPServer } from 'mcp-server-simulator-ios-idb';

async function main() {
  // 创建MCP服务器实例
  const { orchestrator } = createMCPServer();
  
  // 处理自然语言命令
  
  // 创建模拟器会话
  const sessionResult = await orchestrator.processInstruction('创建会话');
  console.log(`会话创建：${sessionResult.data}`);
  
  // 与模拟器交互
  await orchestrator.processInstruction('点击 100, 200');
  
  // 捕获屏幕截图
  const screenshotResult = await orchestrator.processInstruction('截屏');
  console.log(`屏幕截图保存于：${screenshotResult.data}`);
}

main().catch(console.error);

🚀 高级使用

您也可以直接使用各个组件：

import { 
  IDBManager, 
  NLParser, 
  MCPOrchestrator,
  ParserToOrchestrator,
  OrchestratorToIDB
} from 'm-服务器模拟器-ios-idb';

// 创建实例
const idbManager = new IDBManager();
const parser = new NLParser();
const orchestrator = new MCPOrchestrator(parser, idbManager);

// 直接使用组件
const sessionId = await idbManager.createSimulatorSession({
  deviceName: 'iPhone 12',
  platformVersion: '15.0'
});

await idbManager.tap(sessionId, 100, 200);

🏗️ 项目结构

mcp-server-simulator-ios-idb/
├── src/                      # 源代码
│   ├── adapters/             # 适配器组件
│   ├── idb/                  # IDB管理器实现
│   ├── mcp/                  # MCP服务器实现
│   ├── orchestrator/         # 命令协调器
│   ├── parser/              # 自然语言解析器
│   └── index.ts             # 主入口点
├── types/                   # TypeScript类型定义
├── scripts/                 # 安装脚本
├── package.json            # 项目配置
└── tsconfig.json          # TypeScript配置

🎯 支持的命令

NLParser支持以下自然语言命令：

🎮 模拟器管理

命令	描述	示例
创建会话	创建新的模拟器会话	"创建会话", "创建模拟器 iPhone 12"
终止会话	终止当前会话	"终止会话", "关闭模拟器"
列出模拟器	列出可用模拟器	"列出模拟器", "显示模拟器"
列出已启动模拟器	列出正在运行的模拟器	"列出已启动模拟器", "显示运行中的模拟器"
启动模拟器	通过UDID启动模拟器	"启动模拟器 5A321B8F-4D85-4267-9F79-2F5C91D142C2"
关闭模拟器	关闭模拟器	"关闭模拟器 5A321B8F-4D85-4267-9F79-2F5C91D142C2"
将模拟器置于前台	将模拟器窗口置于前台	"将模拟器置于前台", "将模拟器带到前面"
列出模拟器会话	列出活动的模拟器会话	"列出模拟器会话", "显示活动会话"

📱 应用程序管理

命令	描述	示例
安装应用	在模拟器上安装应用	"安装应用 /path/to/app.ipa"
启动应用	在模拟器上启动应用	"启动应用 com.example.app"
终止应用	终止正在运行的应用	"终止应用 com.example.app"
卸载应用	卸载应用	"卸载应用 com.example.app"
列出应用	列出已安装的应用	"列出应用", "显示已安装的应用"
检查应用是否已安装	检查应用是否已安装	"com.example.app 是否已安装"

🖱️ 用户界面交互

命令	描述	示例
点击	在特定坐标处点击	"点击 100, 200"
滑动	执行滑动手势	"从 100, 200 滑动到 300, 400"
按下按钮	按下设备按钮	"按下按钮 HOME", "按下按钮 SIRI"
输入文本	输入文本	"输入文本 Hello World"
按键	通过代码按下键	"按下键 4"
按键序列	按下一系列键	"按下键序列 4 5 6"

♿ 可访问性

命令	描述	示例
描述元素	列出所有可访问性元素	"描述所有元素", "显示可访问性元素"
描述点	描述坐标处的元素	"描述点 100, 200", "150, 300 是什么"

📸 捕获和日志

命令	描述	示例
截屏	捕获屏幕截图	"截屏", "捕获屏幕"
录像	记录屏幕活动	"录像 /path/output.mp4"
停止录像	停止录像	"停止录像", "停止录像录制"
获取日志	获取系统或应用日志	"获取日志", "获取 com.example.app 的日志"

🐛 调试

命令	描述	示例
开始调试	开始调试会话	"调试应用 com.example.app", "开始调试 com.example.app"
结束调试	结束调试会话	"结束调试", "终止调试会话"
调试状态	获取调试会话状态	"调试状态", "显示调试信息"

💥 崩溃日志

命令	描述	示例
列出崩溃日志	列出可用的崩溃日志	"列出崩溃日志", "显示崩溃日志"
显示崩溃日志	显示崩溃日志的内容	"显示崩溃日志 crash_2023-01-01"
删除崩溃日志	删除崩溃日志	"删除崩溃日志", "清除崩溃日志"

🔧 额外命令

命令	描述	示例
安装动态库	安装动态库	"安装动态库 /path/to/library.dylib"
打开URL	在模拟器中打开URL	"打开URL https://example.com"
清除密钥链	清除模拟器的密钥链	"清除密钥链"
设置位置	设置模拟器的位置	"设置位置 37.7749, -122.4194"
添加媒体	将媒体添加到相机胶卷	"添加媒体 /path/to/image.jpg"
批准权限	批准应用权限	"批准权限 com.example.app 照片 相机"
更新联系人	更新联系人数据库	"更新联系人 /path/to/contacts.sqlite"

接口支持idb CLI工具提供的所有命令，提供了全面的操作集，用于iOS模拟器自动化。

🔍 架构

服务器由三个主要组件组成：

1. IDBManager：低级组件，通过idb直接与iOS模拟器交互。
2. NLParser：解释自然语言指令并将其转换为结构化命令的组件。
3. MCPOrchestrator：中心组件，协调解析器和IDBManager之间的交互。

这些组件通过适配器连接：

• ParserToOrchestrator：将解析器结果转换为协调器命令。
• OrchestratorToIDB：将协调器命令翻译成IDBManager调用。

🔌 MCP集成

要将此服务器与模型上下文协议一起使用：

1. 将服务器添加到您的MCP设置中：

{
  "mcpServers": {
    "ios-simulator": {
      "command": "node",
      "args": ["/path/to/mcp-server-simulator-ios-idb/dist/index.js"],
      "env": {}
    }
  }
}

2. 在您的LLM应用程序中连接到服务器：

const result = await useMcpTool({
  serverName: "ios-simulator",
  toolName: "process-instruction",
  arguments: {
    instruction: "创建模拟器会话"
  }
});

🙏 致谢

如果没有facebook/idb，这个项目是不可能实现的，它提供了底层的iOS模拟器控制能力。我们向Facebook/Meta团队以及所有参与idb项目的贡献者表示衷心的感谢，感谢他们创造了这样一个强大且可靠的工具。

📄 许可证

此工具在Apache-2.0条款下作为开源软件提供。