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