使用说明

用于Cursor的iOS模拟器MCP扩展

注：此包目前正在开发中，尚未发布到npm。请参阅下面的安装说明。

MCP（模型上下文协议）服务器，使Cursor的AI能够“看到”您的iOS模拟器。当您对React Native应用程序进行UI更改时，此扩展会自动捕获屏幕截图，并将其暴露给Cursor的AI进行视觉分析和反馈。

🚀 快速开始

安装

当前安装方法（开发）：

克隆此存储库：

git clone https://github.com/emcap/ios-simulator-mcp.git
cd ios-simulator-mcp

安装和构建：

./install-mcp.sh

这将安装依赖项并构建MCP服务器。

配置

添加到光标设置中：

路径： Cursor → Settings (⌘,) → Features → Model Context Protocol

配置：

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

重要提示： 替换 /absolute/path/to/emCap 使用克隆此存储库的实际绝对路径。

未来：npm安装（即将推出）

一旦发布到npm，你就可以通过以下方式安装：

# Using npx (no installation needed)
npx @emcap/ios-simulator-mcp

# Or install globally
npm install -g @emcap/ios-simulator-mcp

并使用更简单的配置：

{
  "mcpServers": {
    "ios-simulator": {
      "command": "npx",
      "args": ["-y", "@emcap/ios-simulator-mcp"]
    }
  }
}

用法

添加配置后重新启动Cursor
启动iOS模拟器： npm run ios

询问Cursor的AI：

"Can you capture a screenshot of the simulator?"
"Show me the latest screenshot"
"Analyze the current UI layout"

就是这样！ 🎉

✨ 特性

📸 自动截图：当UI相关文件发生变化时自动截图
🎯 手动捕获：通过AI命令按需截图
👁️ AI视觉：将屏幕截图暴露给Cursor的AI，以进行视觉反馈和分析
🔍 智能检测：智能检测与UI相关的文件更改
📚 屏幕截图历史记录：维护最近截图的历史记录
🎨 React原生优化：专为React Native开发而设计

📋 需求

macOS（iOS模拟器所需）
已安装Xcode和iOS模拟器
Node.js 18+和npm
光标编辑器
React Native项目

📖 文档

快速入门指南
用法示例
架构概述
出版指南（适用于维护人员-软件包尚未发布）

🛠️ 发展与贡献

如果你想贡献或进行本地修改：

在中编辑源文件 mcp-server/src/
重建： npm run build-mcp （从项目根开始）或 npm run build （来自mcp服务器目录）
重新启动Cursor以重新加载MCP服务器

重建后，MCP服务器将使用您的本地更改。

用法

启动iOS模拟器

在使用扩展程序之前，请确保您的iOS模拟器正在运行：

# Open your React Native app
npm run ios
# or
yarn ios

自动截图

扩展程序会自动监视UI相关文件的更改：

.tsx, .jsx, .ts, .js UI目录中的文件（组件、屏幕、视图、页面、应用程序、src）
包含React原生UI组件的文件

保存UI文件时，扩展名为：

等待2秒以进行其他更改（取消公告）
从启动的模拟器中捕获屏幕截图
使其可用于Cursor的AI

手动截图

您可以要求Cursor的AI手动捕获屏幕截图：

"Can you capture a screenshot of the iOS simulator?"
"Take a screenshot and tell me if the login button looks correct"
"Show me what the app looks like right now"

AI将使用 capture_simulator_screenshot 截图工具。

查看屏幕截图

让AI查看截图：

"Show me the latest screenshot"
"What does the simulator look like?"
"Can you analyze the current UI?"

AI将访问 simulator://latest-screenshot 资源。

检查模拟器状态

"Is the iOS simulator running?"
"Show me available simulators"

AI将使用 get_simulator_status 工具。

切换自动捕获

"Disable automatic screenshot capture"
"Enable auto-capture for screenshots"

AI将使用 toggle_auto_capture 工具。

运作原理

建筑

┌─────────────────┐
│  React Native   │
│   Source Files  │
└────────┬────────┘
         │
         │ File Changes
         ↓
┌─────────────────┐
│  File Watcher   │
│   (Chokidar)    │
└────────┬────────┘
         │
         │ UI Change Detected
         ↓
┌─────────────────┐       ┌──────────────┐
│   Simulator     │◄──────│  xcrun       │
│   Manager       │       │  simctl      │
└────────┬────────┘       └──────────────┘
         │
         │ Screenshot Captured
         ↓
┌─────────────────┐
│  MCP Resources  │
│  & Tools        │
└────────┬────────┘
         │
         │ Stdio Protocol
         ↓
┌─────────────────┐
│  Cursor AI      │
│  (Claude)       │
└─────────────────┘

组件

模拟器管理器 (src/simulator.ts)
- 使用以下命令捕获屏幕截图 xcrun simctl io booted screenshot
- 管理屏幕截图存储和清理
- 检索模拟器状态和设备信息
文件监视器 (src/watcher.ts)
- 监视React Native项目文件的更改
- 使用关键字和目录模式检测与UI相关的更改
- 去抖动更改以避免过多的屏幕截图
- 触发自动截图捕获
MCP服务器 (src/index.ts)
- 将屏幕截图显示为MCP资源
- 提供手动截图和模拟器管理工具
- 通过stdio协议与Cursor通信

MCP资源

simulator://latest-screenshot -最新截图（PNG图像）
simulator://screenshot-history -包含元数据的所有屏幕截图的JSON列表
simulator://screenshot/{timestamp} -按时间戳显示的具体截图

MCP工具

capture_simulator_screenshot -手动捕获屏幕截图
- 可选的 description 上下文参数
get_simulator_status -检查模拟器是否正在运行并列出设备
toggle_auto_capture -启用或禁用自动捕获
- 必需 enabled 布尔参数
get_watcher_status -获取文件监视器状态和配置

配置

屏幕截图存储

屏幕截图存储在 .emcap-screenshots/ 目录（默认情况下忽略git）。

文件监视

配置要查看的文件 mcp-server/src/config.ts:

export const config = {
  // Maximum screenshots to keep
  maxScreenshots: 50,
  
  // File patterns to watch
  watchPatterns: [
    '**/*.tsx',
    '**/*.jsx',
    '**/*.ts',
    '**/*.js'
  ],
  
  // Directories to ignore
  ignorePatterns: [
    '**/node_modules/**',
    '**/dist/**',
    '**/build/**',
    '**/.git/**',
    '**/android/**',
    '**/__tests__/**'
  ],
  
  // Debounce delay (ms)
  debounceDelay: 2000,
  
  // UI detection keywords
  uiKeywords: [
    'View',
    'Text',
    'Image',
    'Button',
    'TouchableOpacity',
    'ScrollView',
    'FlatList',
    'StyleSheet',
    'style',
    'render'
  ]
};

发展

建筑

cd mcp-server
npm run build

发展模式

注意更改并自动重建：

cd mcp-server
npm run dev

测试

手动启动MCP服务器：

cd mcp-server
npm start

检查Cursor的MCP输出面板中的日志

故障排除

“未找到已启动的iOS模拟器”

解决方案：确保您的iOS模拟器正在运行：

npm run ios
# or launch from Xcode

未自动捕获屏幕截图

可能的原因:

自动捕获已禁用
- 问AI：“启用自动捕捉”
模拟器未运行
- 检查：“iOS模拟器是否正在运行？”
文件监视器未检测到更改
- 检查模式 config.ts
- 问AI：“观察者的状态是什么？”

MCP服务器未连接

解决方案:

检查服务器是否已构建： mcp-server/dist/index.js 应该存在
- 如果没有，运行： ./install-mcp.sh 或 cd mcp-server && npm run build
验证Cursor的MCP配置中的路径是否正确（必须是绝对路径）
- 使用完整路径，如： /Users/username/path/to/emCap/mcp-server/dist/index.js
检查Node.js版本： node --version （要求18+）
配置更改后重新启动Cursor
检查Cursor的MCP日志以了解详细错误（查看→ 输出→ 选择“ios模拟器”）

截图目录已满

解决方案：服务器仅自动维护最近的50个屏幕截图。您可以在中进行调整 config.ts:

maxScreenshots: 50  // Change this value

项目结构

emCap/
├── mcp-server/              # MCP server source code
│   ├── src/
│   │   ├── index.ts         # Main MCP server
│   │   ├── simulator.ts     # Screenshot capture logic
│   │   ├── watcher.ts       # File watching logic
│   │   ├── types.ts         # TypeScript type definitions
│   │   └── config.ts        # Configuration
│   ├── package.json
│   └── tsconfig.json
├── .emcap-screenshots/      # Screenshot storage (git-ignored)
├── .cursorrules             # Cursor rules for MCP usage
├── cursor-mcp-config.json   # Cursor MCP configuration
├── install-mcp.sh           # Installation script
└── README.md                # This file

用例

UI开发反馈

让AI检查您的UI更改：

"I just updated the login screen styling. Can you take a screenshot and give me feedback?"

Bug验证

验证视觉错误是否已修复：

"I fixed the button alignment issue. Take a screenshot and verify it looks correct now."

设计实现

将实施与设计进行比较：

"Here's the design spec. Take a screenshot and tell me what doesn't match."

多屏幕工作流

浏览屏幕并捕获：

"I'm going to navigate to the profile screen. When I'm done, capture it and check the layout."

贡献

欢迎投稿！贡献：

分叉存储库
创建要素分支： git checkout -b feature/your-feature
在中进行更改 mcp-server/src/
重建： npm run build-mcp （从项目根开始）或 cd mcp-server && npm run build
通过重新启动Cursor来测试您的更改
提交您的更改： git commit -am 'Add some feature'
推到分支： git push origin feature/your-feature
提交拉取请求

请确保您的代码：

遵循现有代码样式
包括适当的类型定义
已经用真实的React Native项目进行了测试
必要时更新文档

许可证

麻省理工学院

致谢

内置于模型上下文协议SDK
用途监视器用于文件查看
由苹果公司提供技术支持 xcrun simctl 用于iOS模拟器控制