📱 MCP Server for iOS Simulator

这是一个 Model Context Protocol (MCP) 服务器，它允许大型语言模型（LLMs）通过自然语言命令与 iOS 模拟器进行交互。

ℹ️ 概述

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

• 详细用法请参见安装指南和支持命令部分。
• 您可以通过直接的 MCP 集成或作为独立库来使用此服务器。
• 查看架构部分以了解组件如何协同工作以实现对 iOS 模拟器的自然语言控制。

🎮 模拟器控制

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

📱 应用程序管理

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

🖱️ UI 交互与测试

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

🛠️ 开发与调试

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

⚡ 高级功能

• 其他功能包括：

  • 位置模拟
  • 媒体注入
  • URL 方案处理
  • 联系人数据库管理
  • 密钥链操作

• 详细用法请参见安装指南和支持命令部分。

• 您可以通过直接的 MCP 集成或作为独立库来使用此服务器。

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

📋 系统要求

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

🚀 安装

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

1. 只需告诉 Cline：

Add this mcp to cline https://github.com/InditexTech/mcp-server-simulator-ios-idb

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

或者，您可以手动安装：

# Clone the repository
git clone https://github.com/InditexTech/mcp-server-simulator-ios-idb.git
cd mcp-server-simulator-ios-idb

# Create and activate Python virtual environment
python3 -m venv venv
source venv/bin/activate  # On Unix/macOS

# Install dependencies
npm install

# Build the project
npm run build

# Start the project
npm start

# Run tests
npm test

安装过程将自动执行以下步骤：

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

注意：使用服务器时，请确保虚拟环境已激活。如果您关闭终端并稍后返回，则需要先使用 source venv/bin/activate 命令重新激活虚拟环境，然后才能运行 npm start。

🔌 MCP 集成

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

1. 在 Claude 桌面应用程序的 MCP 设置中添加服务器：

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

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

create a simulator session with iPhone 14
install app /path/to/my-app.ipa
launch app com.example.myapp
tap at 100, 200
take a screenshot

📚 作为库使用

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

🔰 基本用法

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

async function main() {
  // Create an instance of the MCP server
  const { orchestrator } = createMCPServer();
  
  // Process natural language commands
  
  // Create a simulator session
  const sessionResult = await orchestrator.processInstruction('create session');
  console.log(`Session created: ${sessionResult.data}`);
  
  // Interact with the simulator
  await orchestrator.processInstruction('tap at 100, 200');
  
  // Capture a screenshot
  const screenshotResult = await orchestrator.processInstruction('take screenshot');
  console.log(`Screenshot saved at: ${screenshotResult.data}`);
}

main().catch(console.error);

🚀 高级用法

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

import { 
  IDBManager, 
  NLParser, 
  MCPOrchestrator,
  ParserToOrchestrator,
  OrchestratorToIDB
} from 'mcp-server-simulator-ios-idb';

// Create instances
const idbManager = new IDBManager();
const parser = new NLParser();
const orchestrator = new MCPOrchestrator(parser, idbManager);

// Use the components directly
const sessionId = await idbManager.createSimulatorSession({
  deviceName: 'iPhone 12',
  platformVersion: '15.0'
});

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

🏗️ 项目结构

mcp-server-simulator-ios-idb/
├── src/                      # Source code
│   ├── adapters/             # Adapter components
│   ├── idb/                  # IDB manager implementation
│   ├── mcp/                  # MCP server implementation
│   ├── orchestrator/         # Command orchestrator
│   ├── parser/              # Natural language parser
│   └── index.ts             # Main entry point
├── types/                   # TypeScript type definitions
├── scripts/                 # Installation scripts
├── package.json            # Project configuration
└── tsconfig.json          # TypeScript configuration

🎯 支持的命令

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

🎮 模拟器管理

命令	描述	示例
创建会话	创建一个新的模拟器会话	"create session", "create simulator iPhone 12"
终止会话	终止当前会话	"terminate session", "close simulator"
列出模拟器	列出可用的模拟器	"list simulators", "show simulators"
列出已启动的模拟器	列出正在运行的模拟器	"list booted simulators", "show running simulators"
启动模拟器	通过 UDID 启动模拟器	"boot simulator 5A321B8F-4D85-4267-9F79-2F5C91D142C2"
关闭模拟器	关闭模拟器	"shutdown simulator 5A321B8F-4D85-4267-9F79-2F5C91D142C2"
聚焦模拟器	将模拟器窗口置于最前端	"focus simulator", "bring simulator to front"
列出模拟器会话	列出活动的模拟器会话	"list simulator sessions", "show active sessions"

📱 应用管理

命令	描述	示例
安装应用	在模拟器上安装应用	"install app /path/to/app.ipa"
启动应用	在模拟器上启动应用	"launch app com.example.app"
终止应用	终止正在运行的应用	"terminate app com.example.app"
卸载应用	卸载应用	"uninstall app com.example.app"
列出应用	列出已安装的应用程序	"list apps", "show installed apps"
检查应用是否已安装	检查应用是否已安装	"is app com.example.app installed"

🖱️ UI 交互

命令	描述	示例
点击	在特定坐标处点击	"tap at 100, 200"
滑动	执行滑动手势	"swipe from 100, 200 to 300, 400"
按按钮	按下设备按钮	"press button HOME", "press button SIRI"
输入文本	输入文本	"input text Hello World"
按键	按下指定代码的键	"press key 4"
按键序列	按下一组按键	"press key sequence 4 5 6"

♿ 辅助功能

命令	描述	示例
描述元素	列出所有辅助功能元素	"describe all elements", "show accessibility elements"
描述点	描述坐标处的元素	"describe point 100, 200", "what's at 150, 300"

📸 捕获和日志

命令	描述	示例
截图	捕获屏幕截图	"take screenshot", "capture screen"
录制视频	录制屏幕活动	"record video /path/output.mp4"
停止录制	停止视频录制	"stop recording", "stop video recording"
获取日志	检索系统或应用程序日志	"get logs", "get logs for com.example.app"

🐛 调试

命令	描述	示例
开始调试	启动一个调试会话	"debug app com.example.app", "start debug com.example.app"
停止调试	停止一个调试会话	"stop debug", "terminate debug session"
调试状态	获取调试会话的状态	"debug status", "show debug info"

💥 崩溃日志

命令	描述	示例
列出崩溃日志	列出可用的崩溃日志	"list crash logs", "show crash logs"
显示崩溃日志	显示崩溃日志的内容	"show crash log crash_2023-01-01"
删除崩溃日志	删除崩溃日志	"delete crash logs", "clear crash logs"

🔧 其他命令

命令	描述	示例
安装动态库	安装动态库	"install dylib /path/to/library.dylib"
打开URL	在模拟器中打开一个URL	"open url https://example.com"
清除钥匙串	清除模拟器的钥匙串	"clear keychain"
设置位置	设置模拟器的位置	"set location 37.7749, -122.4194"
添加媒体	将媒体添加到相机胶卷	"add media /path/to/image.jpg"
批准权限	批准应用程序权限	"approve permissions com.example.app photos camera"
更新联系人	更新联系人数据库	"update contacts /path/to/contacts.sqlite"

该界面支持idb CLI工具中的所有命令，为iOS模拟器自动化提供了一整套操作。

🔍 架构

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

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

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

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

🔌 MCP集成

要使用此服务器与模型上下文协议（MCP）：

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

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

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

const result = await useMcpTool({
  serverName: "ios-simulator",
  toolName: "process-instruction",
  arguments: {
    instruction: "create simulator session"
  }
});

🙏 致谢

这个项目之所以能够实现，离不开facebook/idb的支持，它提供了基础的iOS模拟器控制能力。我们衷心感谢Facebook/Meta团队以及所有为idb项目做出贡献的人们，感谢他们创造了这样一个强大且可靠的工具。

📄 许可证

本工具依据Apache-2.0条款作为开源软件提供。