MCP Connect

🚀 @plaintest/mcp-connect

@plaintest/mcp-connect 是一个模型上下文协议（MCP）服务器，它使 AI 助手能够控制 iOS 模拟器并自动化浏览器操作。该服务器将 xcrun simctl、fb-idb 和 Puppeteer 的强大功能集成到一个统一的服务器中。

🚀 快速开始

要使用 @plaintest/mcp-connect，你需要满足以下先决条件：

• macOS 系统，并安装 Xcode 和 iOS 模拟器
• Node.js 版本 >= 18
• 用于浏览器自动化的 Chrome/Chromium 浏览器
• fb-idb（可选，用于增强 iOS 手势操作）

✨ 主要特性

iOS 模拟器工具

• 截图功能：支持以多种格式（PNG、JPEG、TIFF、BMP、GIF）捕获屏幕截图。
• 设备管理：列出模拟器，并获取已启动设备的信息。
• 手势操作：支持点击、滑动操作，并可控制滑动时长（需要 fb-idb）。
• 输入功能：在聚焦的字段中输入文本，按下系统按钮。
• 导航功能：打开 URL 和深度链接。
• UI 检查：获取无障碍访问树（需要 fb-idb）。
• 重置功能：将模拟器恢复到出厂设置。

浏览器自动化工具

• 启动与控制：启动 Chrome/Chromium 浏览器，并导航到指定 URL。
• 截图功能：捕获全页或特定元素的屏幕截图。
• DOM 交互：点击元素、输入文本、查询元素。
• 检查功能：获取 DOM 树、元素信息和页面信息。
• JavaScript 执行：在页面上下文中执行任意 JavaScript 代码。
• Metro 打包器：为 React Native 开发提供快捷操作。

📦 安装指南

选项 1：快速安装（推荐）

运行 MCP 客户端的安装程序：

# 适用于 Claude Code
npx @plaintest/mcp-connect install claude

# 适用于 Cursor
npx @plaintest/mcp-connect install cursor

# 适用于 Windsurf
npx @plaintest/mcp-connect install windsurf

# 适用于 Cline (VS Code)
npx @plaintest/mcp-connect install cline

# 适用于 GitHub Copilot (VS Code)
npx @plaintest/mcp-connect install copilot

# 一次性为所有客户端安装
npx @plaintest/mcp-connect install --all

重启编辑器后，工具即可使用。

选项 2：全局安装

全局安装 mcp-connect，使其作为命令可用：

npm install -g @plaintest/mcp-connect

然后手动配置 MCP 客户端：

{
  "mcpServers": {
    "mcp-connect": {
      "command": "mcp-connect"
    }
  }
}

选项 3：手动配置

如果你不想全局安装，可以配置 MCP 客户端使用 npx：

{
  "mcpServers": {
    "mcp-connect": {
      "command": "npx",
      "args": ["-y", "@plaintest/mcp-connect"]
    }
  }
}

配置文件位置：

• Claude Code：使用 claude mcp add 命令（安装时自动配置）
• Cursor：~/.cursor/mcp.json
• Windsurf：~/.codeium/windsurf/mcp_config.json
• Cline：~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Copilot：~/Library/Application Support/Code/User/settings.json（在 github.copilot.chat.experimental.mcp.servers 下）

📚 详细文档

CLI 命令

npx @plaintest/mcp-connect install <client>    # 为客户端安装配置
npx @plaintest/mcp-connect uninstall <client>  # 从客户端移除配置
npx @plaintest/mcp-connect list                # 列出支持的客户端
npx @plaintest/mcp-connect status              # 显示安装状态
npx @plaintest/mcp-connect help                # 显示帮助信息

工具过滤

默认情况下，mcp-connect 会根据你的系统自动检测启用哪些工具：

• iOS 模拟器工具：如果安装了 Xcode/xcrun，则启用。
• 浏览器工具：如果找到 Chrome/Chromium 浏览器，则启用。 这样可以减少上下文使用，并通过仅显示相关工具来避免混淆。

覆盖自动检测

要手动控制启用哪些工具，可以使用 --only 标志：

npx @plaintest/mcp-connect --only=browser     # 仅启用浏览器工具
npx @plaintest/mcp-connect --only=simulator   # 仅启用 iOS 模拟器工具
npx @plaintest/mcp-connect --only=all         # 强制启用所有工具

要在 MCP 客户端中使用过滤功能，请更新你的配置：

{
  "mcpServers": {
    "mcp-connect": {
      "command": "npx",
      "args": ["-y", "@plaintest/mcp-connect", "--only=browser"]
    }
  }
}

可用工具

iOS 模拟器工具（10 个）

浏览器自动化工具（14 个）

💻 使用示例

截取 iOS 模拟器屏幕截图

AI: 使用 capture_simulator_screenshot 截取屏幕截图

浏览器导航与交互

AI: 启动浏览器并导航到 http://localhost:8081
AI: 点击选择器为 ".reload-button" 的元素
AI: 截取屏幕截图

iOS 手势自动化

AI: 在坐标 (200, 400) 处点击屏幕
AI: 在 0.3 秒内从 (200, 600) 滑动到 (200, 200)
AI: 在聚焦的输入框中输入 "Hello World"

点击/滑动手势设置

为了使 tap_screen 和 swipe 操作可靠运行，需要安装 fb-idb：

brew tap facebook/fb
brew install idb-companion

如果未安装 fb-idb：

• 点击操作将回退到 AppleScript（可靠性较低）
• 滑动操作将不可用

🔧 技术细节

故障排除

未找到 Chrome 浏览器

安装 Google Chrome 或设置自定义路径：

• 服务器会在标准 macOS 位置查找 Chrome 浏览器
• 也支持 Chromium 和 Chrome Canary

未检测到模拟器

1. 打开 Xcode > 打开开发者工具 > 模拟器
2. 启动一个模拟器
3. 验证：xcrun simctl list devices booted

fb-idb 无法正常工作

# 重新安装
brew uninstall idb-companion
brew tap facebook/fb
brew install idb-companion

# 验证
which idb

手势操作权限被拒

授予无障碍访问权限：

1. 系统设置 > 隐私与安全 > 无障碍访问
2. 添加终端（或你的 shell 应用）
3. 重启编辑器

开发

# 克隆仓库
git clone https://github.com/Plaintest/plaintest-mcp.git
cd plaintest-mcp

# 安装依赖
npm install

# 构建项目
npm run build

# 本地运行
node dist/index.js

# 监听模式
npm run dev

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

作者

George Al-Haddad - Plaintest