MCP Baepsae

🚀 mcp-baepsae

Baepsae（棕頭鴉雀）是一種小巧的韓國鳥類，體型圓潤、胖乎乎的，還總是蹦蹦跳跳地嘰嘰喳喳叫。它以堅韌不拔的精神著稱，即便小鳥想跟上鸛的步伐，也絕不放棄。這個項目同樣小巧，但它會不知疲倦地攻克你的模擬器難題。

這是一個用於iOS模擬器和macOS應用自動化的本地MCP服務器，具備TypeScript MCP層和Swift原生橋接功能。

韓語文檔請參考 README-KR.md。

🚀 快速開始

本項目是用於iOS模擬器和macOS應用自動化的本地MCP服務器，支持多種客戶端集成，下面將詳細介紹使用前的準備工作、安裝方法、配置步驟等內容。

✨ 主要特性

• 具備TypeScript MCP層和Swift原生橋接，可用於iOS模擬器和macOS應用自動化。
• 支持多種客戶端，如Claude Code、Claude Desktop、Codex CLI等。
• 提供豐富的工具命令，可進行UI檢查、輸入自動化等操作。

📦 安裝指南

前提條件

• macOS 14及以上版本。
• 安裝Xcode和iOS Simulator。
• Node.js 18及以上版本。
• Swift 6及以上版本。

安裝方式

選項A) 使用npm（最簡單）

# 無需安裝直接運行
npx mcp-baepsae@latest

# 或者全局安裝
npm install -g mcp-baepsae

在macOS上，Swift原生二進制文件會在安裝過程中自動構建。如果沒有安裝Swift，服務器仍然可以使用基於simctl的功能。

選項B) 從源代碼安裝

git clone https://github.com/oozoofrog/mcp-baepsae.git
cd mcp-baepsae
npm install
npm run build

💻 使用示例

基礎用法

模擬器應用可訪問性快速入門（應用UI內）：

// 1) 在目標模擬器中啟動應用
launch_app({ udid: "...", bundleId: "com.example.app" })

// 2) 檢查或搜索可訪問性樹（默認在應用內容範圍內）
sim_describe_ui({ udid: "..." })
sim_search_ui({ udid: "...", query: "Login" })

// 3) 通過可訪問性標識符/標籤進行交互
sim_tap({ udid: "...", id: "login-button" })

// 可選：在選擇器查找中包含模擬器的系統UI
sim_tap({ udid: "...", label: "Home", all: true })

打開URL（iOS模擬器）：

// 打開Naver移動版
open_url({ udid: "...", url: "https://m.naver.com" })

管理應用（iOS模擬器）：

// 安裝應用
install_app({ udid: "...", path: "/path/to/App.app" })

// 啟動Safari
launch_app({ udid: "...", bundleId: "com.apple.mobilesafari" })

// 終止Safari
terminate_app({ udid: "...", bundleId: "com.apple.mobilesafari" })

macOS應用自動化：

// 列出正在運行的macOS應用
list_apps({})

// 對macOS應用進行截圖
mac_screenshot_app({ bundleId: "com.apple.Safari" })

📚 詳細文檔

平臺支持

為什麼僅支持macOS？

Swift原生橋接（baepsae-native）使用特定於macOS的框架（AppKit、CoreGraphics、輔助功能）與iOS模擬器和macOS應用進行交互。這些框架在Linux或Windows上不可用。TypeScript MCP層還依賴於xcrun simctl，它是Xcode命令行工具的一部分，僅在macOS上可用。

要求總結：

• macOS 14或更高版本 —— iOS模擬器自動化和輔助功能API訪問必需。
• Xcode或Xcode命令行工具 —— 原生二進制文件的Swift 6+編譯和xcrun simctl命令必需。
• Node.js >= 18.0.0 —— 運行TypeScript MCP服務器必需。

權限

進行UI檢查和輸入自動化功能（使用sim_* / mac_*作用域的工具，如sim_describe_ui、mac_tap、sim_right_click）需要輔助功能權限。

1. 打開 系統設置 > 隱私與安全 > 輔助功能。
2. 啟用實際使用的MCP客戶端應用和終端，如果列表中顯示運行時進程（node），也一併啟用。
3. 如果應用缺失，點擊+並手動添加。

對於模擬器目標，基於選擇器的操作（sim_tap / sim_right_click 配合id或label）默認在應用內內容中進行搜索。設置all: true可包含模擬器的系統UI。

MCP設置（推薦）

使用安裝腳本直接調用每個客戶端的MCP安裝流程。

bash scripts/install.sh --tool all

客戶端矩陣

針對LLM的設置

如果你是一個LLM代理，要設置此MCP服務器，以下是你需要的所有內容：

快速開始（一條命令）

# 將baepsae註冊為所有支持的客戶端的MCP服務器
bash scripts/install.sh --tool all

如果你是通過npm安裝而不是克隆倉庫，使用npx：

# Claude Code
claude mcp add baepsae -- npx -y mcp-baepsae@latest

# Codex CLI
codex mcp add baepsae -- npx -y mcp-baepsae@latest

自動化標誌

# 預覽命令而不執行
bash scripts/install.sh --tool all --dry-run

# 驗證環境和依賴項
bash scripts/install.sh --tool all --doctor

# 從所有客戶端取消註冊
bash scripts/install.sh --tool all --uninstall

運行時選項

安裝程序通過--runtime支持多個運行時：

手動設置（備用方案）

當你不想運行scripts/install.sh時使用此方法。

使用npx（推薦給npm用戶）

# Claude Code
claude mcp add baepsae -- npx -y mcp-baepsae@latest

# Codex CLI
codex mcp add baepsae -- npx -y mcp-baepsae@latest

# Gemini CLI
gemini mcp add --scope user --transport stdio baepsae npx -y mcp-baepsae@latest

使用本地構建

# Claude Code（項目）
claude mcp add --scope project --env="BAEPSAE_NATIVE_PATH=/ABS/PATH/native/.build/release/baepsae-native" baepsae -- node /ABS/PATH/dist/index.js

# Codex CLI
codex mcp add baepsae --env BAEPSAE_NATIVE_PATH=/ABS/PATH/native/.build/release/baepsae-native -- node /ABS/PATH/dist/index.js

# Gemini CLI
gemini mcp add --scope user --transport stdio -e BAEPSAE_NATIVE_PATH=/ABS/PATH/native/.build/release/baepsae-native baepsae node /ABS/PATH/dist/index.js

項目結構

• MCP服務器入口點：src/index.ts
• 工具模塊：src/tools/（信息、模擬器、UI、輸入、媒體、系統）
• 共享實用工具：src/utils.ts，src/types.ts
• 原生二進制文件入口點：native/Sources/main.swift
• 原生命令處理程序：native/Sources/Commands/
• 原生二進制文件輸出：native/.build/release/baepsae-native
• TS測試：tests/mcp.contract.test.mjs，tests/unit.test.mjs，tests/mcp.real.test.mjs
• Swift測試：native/Tests/BaepsaeNativeTests/

命令

npm run build       # 構建TypeScript + 原生Swift二進制文件
npm test            # 契約/集成測試
npm run test:real   # 真實模擬器冒煙測試（需要已啟動的模擬器）
npm run verify      # test + test:real
npm run setup:mcp   # scripts/install.sh的別名

MCP工具狀態

共實現了47個端到端工具。

顯式目標作用域工具（30個，推薦）

優先使用這些工具以避免模擬器/macOS目標的歧義。

僅適用於iOS模擬器（11個）

list_simulators，screenshot，record_video，stream_video，open_url，install_app，launch_app，terminate_app，uninstall_app，button，gesture

僅適用於macOS / 系統（4個）

list_apps，menu_action，get_focused_app，clipboard

實用工具（2個）

baepsae_help，baepsae_version

🔧 技術細節

• 本項目使用Swift原生橋接（baepsae-native）與macOS特定框架（AppKit、CoreGraphics、輔助功能）交互，實現與iOS模擬器和macOS應用的自動化操作。
• TypeScript MCP層依賴xcrun simctl，這是Xcode命令行工具的一部分，確保了在macOS上的兼容性。
• 項目結構清晰，各個模塊分工明確，便於開發和維護。

📄 許可證

文檔中未提及許可證相關信息。

🛠️ 故障排除

• Claude設置時出現Invalid environment variable format錯誤：
  • 使用當前腳本（scripts/install.sh）或claude mcp add --env="KEY=value" ...格式。
• 出現Missing native binary錯誤：
  • 運行npm run build，並確認native/.build/release/baepsae-native存在。
• OpenCode未顯示baepsae：
  • 重新運行bash scripts/install.sh --tool opencode --skip-install --skip-build，並檢查~/.config/opencode/opencode.json。
• Copilot未自動註冊：
  • Copilot MCP流程是交互式/基於會話的。使用--interactive重新運行安裝程序。
• 真實冒煙測試被跳過：
  • 先啟動一個iOS模擬器，然後運行npm run test:real。