MCP Baepsae

🚀 mcp-baepsae

ベプセ（ベプセカワセミ）は、小さな韓国の鳥です。丸くてぽっちゃりしており、いつもチュンチュンと鳴きながら飛び回っています。小さな鳥がコウノトリに追いつこうとしても、決して諦めない粘り強さで知られています。このプロジェクトも小さいですが、シミュレーターに対して粘り強くアクセスします。

iOSシミュレーターとmacOSアプリの自動化を行うためのローカルMCPサーバーで、TypeScriptのMCPレイヤーとSwiftのネイティブブリッジを備えています。

韓国語のドキュメントはREADME-KR.mdを参照してください。

🚀 クイックスタート

📋 前提条件

• macOS 14以上
• Xcode + iOSシミュレーター
• Node.js 18以上
• Swift 6以上

📱 プラットフォームサポート

なぜmacOSのみですか？

Swiftのネイティブブリッジ (baepsae-native) は、iOSシミュレーターとmacOSアプリケーションとやり取りするために、macOS固有のフレームワーク（AppKit、CoreGraphics、アクセシビリティ）を使用しています。これらのフレームワークはLinuxやWindowsでは利用できません。TypeScriptのMCPレイヤーも、Xcodeコマンドラインツールの一部であり、macOSでのみ利用可能な xcrun simctl に依存しています。

要件の概要:

• 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. アプリがリストにない場合は、+ をクリックして手動で追加します。

シミュレーターターゲットの場合、セレクターベースのアクション（id または label を指定した sim_tap / sim_right_click）はデフォルトでアプリ内のコンテンツを検索します。all: true を設定すると、シミュレーターのクロームUIも含まれます。

📦 インストール

オプション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

✨ MCPセットアップ（推奨）

各クライアントのMCPインストールフローを直接呼び出すインストーラースクリプトを使用します。

bash scripts/install.sh --tool all

📊 クライアントマトリックス

🤖 LLM向け

LLMエージェントでこのMCPサーバーをセットアップする場合、必要な情報は次の通りです。

🚀 クイックスタート（1コマンド）

# すべてのサポートされているクライアントに対して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
• ツールモジュール: mcp.contract.test.mjs, tests/unit.test.mjs, tests/mcp.real.test.mjs
• Swiftテスト: native/Tests/BaepsaeNativeTests/

💻 コマンド

npm run build       # TypeScript + ネイティブSwiftバイナリをビルド
npm test            # コントラクト/統合テスト

共通コマンド（13セット）

iOSシミュレーターのみ（11個）

list_simulators, screenshot, record_video, stream_video, open_url, install_app, launch_app, terminate_app, sim_describe_ui, sim_search_ui, sim_tap

💻 使用例

基本的な使用法

アクセシビリティツリーの検索

// アクセシビリティツリーを検索する（デフォルトではアプリ内コンテンツのスコープ）
sim_describe_ui({ udid: "..." })
sim_search_ui({ udid: "...", query: "Login" })

アクセシビリティ識別子/ラベルによる操作

// アクセシビリティ識別子でタップ操作
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" })

🐞 トラブルシューティング

• 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 を実行してください。