JinDaGe - mcp-connect MCP Details

article

README

🚀 @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 个）

| 工具 | 描述 | |------|-------------| | capture_simulator_screenshot | 带有格式/掩码选项的屏幕截图捕获 | | list_simulators | 列出所有模拟器（已启动或全部） | | get_simulator_info | 获取当前已启动模拟器的信息 | | tap_screen | 在指定坐标 (x, y) 处点击屏幕 | | swipe | 在指定时间内从 (x1, y1) 滑动到 (x2, y2) | | simulator_type_text | 在聚焦的输入字段中输入文本 | | press_button | 按下系统按钮（主页、锁定、Siri、音量） | | open_url | 在模拟器中打开 URL 或深度链接 | | erase_simulator | 将模拟器恢复到出厂设置 | | get_ui_tree | 获取无障碍访问树（需要 fb-idb） |

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

| 工具 | 描述 | |------|-------------| | launch_browser | 启动 Chrome/Chromium 实例 | | navigate | 导航到指定 URL | | capture_screenshot | 捕获页面或元素的屏幕截图 | | click_element | 通过 CSS 选择器点击元素 | | type_text | 在输入字段中输入文本 | | get_page_info | 获取 URL、标题、视口信息 | | get_dom_tree | 获取具有深度控制的 HTML 结构 | | evaluate_javascript | 在页面上下文中执行 JavaScript 代码 | | query_elements | 通过 CSS 选择器查找元素 | | get_element_info | 获取元素的位置、样式、内容信息 | | close_browser | 关闭浏览器并清理资源 | | open_metro_bundler | 打开 React Native Metro 打包器 UI | | get_metro_logs | 从 Metro UI 中提取日志 | | reload_metro | 触发 Metro 重新加载 |

💻 使用示例

截取 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

未检测到模拟器

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

fb-idb 无法正常工作

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

# 验证
which idb

手势操作权限被拒

授予无障碍访问权限：

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

开发

# 克隆仓库
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

mcp-connect