baepsae

mcp-baepsae

Baepsae（Vinous-throated Parrotbill）— 韓国の小さな鳥です。丸くてぷっくりしていて、さえずりながら絶えず飛び跳ねています。その根性で知られており、小さな鳥がコウノトリに追いつこうとしても、決して諦めません。このプロジェクトも小さいですが、あなたのシミュレータをつつき続けます。

TypeScript の MCP レイヤーと Swift ネイティブブリッジによる、iOS Simulator および macOS アプリの自動化のためのローカル MCP サーバーです。

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

目次

• 前提条件
• プラットフォームサポート
• インストール
• 権限
• MCP のセットアップ（推奨）
• クライアント対応表
• LLM 向け
• 手動セットアップ（フォールバック）
• プロジェクト構成
• コマンド
• MCP ツールのステータス
• 使用例
• トラブルシューティング

前提条件

• macOS 14+
• Xcode + iOS Simulator
• Node.js 18+
• Swift 6+

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

プラットフォーム	サポート	備考
macOS	はい	主要なプラットフォームです。iOS Simulator およびアクセシビリティ API に必要です。
Linux	いいえ	ネイティブバイナリは AppKit、CoreGraphics、およびアクセシビリティフレームワークに依存しています。
Windows	いいえ	ネイティブバイナリは AppKit、CoreGraphics、およびアクセシビリティフレームワークに依存しています。

なぜ macOS 専用なのか？

Swift ネイティブブリッジ（baepsae-native）は、iOS Simulator および macOS アプリケーションとやり取りするために macOS 固有のフレームワーク（AppKit、CoreGraphics、アクセシビリティ）を使用します。これらのフレームワークは Linux や Windows では利用できません。TypeScript の MCP レイヤーも xcrun simctl に依存しており、これは Xcode Command Line Tools の一部で、macOS でのみ利用できます。

要件のまとめ:

• macOS 14 以降 -- iOS Simulator の自動化およびアクセシビリティ API へのアクセスに必要です。
• Xcode または Xcode Command Line Tools -- ネイティブバイナリの Swift 6+ でのコンパイル、および xcrun simctl コマンドに必要です。
• Node.js >= 18.0.0 -- TypeScript の MCP サーバーを実行するために必要です。

権限

UI の検査および入力自動化の機能（analyze_ui、tap、right_click などの統合された汎用ツール）には、アクセシビリティ権限が必要です。

重要な点は、権限は通常、自動化の対象アプリではなく、自動化のホスト / ランタイムプロセスに付与する必要があるということです。

通常どのプロセスに権限が必要か？

• ネイティブバイナリを直接起動する場合
  • 例: baepsae-native ...
  • 最も関連する項目: baepsae-native バイナリ自体、およびそれを起動したターミナル / シェルアプリ
• Node / npx MCP ランタイム
  • 例: node dist/index.js、npx -y mcp-baepsae@latest
  • 最も関連する項目: ランタイムプロセス（node）、およびそれを起動したターミナルまたは MCP クライアントアプリ
• デスクトップ / CLI MCP クライアント
  • 例: Claude Code、Codex CLI/Desktop、Gemini CLI
  • 起動経路に応じて、MCP クライアントアプリ、ターミナルホスト、およびランタイムプロセスが関連する項目に含まれることがあります

推奨されるセットアップ手順

1. システム設定 > プライバシーとセキュリティ > アクセシビリティを開きます。
2. 実際に使用するターミナルまたは MCP クライアントアプリを有効にします。
3. 一覧に表示されていれば、ランタイムプロセス（node、bun など）を有効にします。
4. ネイティブを直接起動する場合は、baepsae-native バイナリの項目が別途表示されていれば、それも有効にします。
5. 項目が存在しない場合は、+ をクリックして手動で追加します。

重要な注意

権限を付与した後、macOS が変更を適用する前に、起動元のプロセスを再起動する必要がある場合があります。
エラーが解消しない場合は、mcp-baepsae を起動したターミナル、MCP クライアント、またはランタイムプロセスを終了して再起動してください。

シミュレータを対象とする場合、セレクタベースのアクション（id または label を指定した tap / right_click）は、デフォルトでアプリ内のコンテンツを検索します。Simulator のクローム UI を含めるには all: true を設定してください。

インストール

オプション A) npm (最も簡単)

# Run directly without installing
npx mcp-baepsae@latest

# Or install globally
npm install -g mcp-baepsae

macOS では、Swift ネイティブバイナリはインストール時に自動的にビルドされます。Swift が利用できない場合でも、サーバーは simctl ベースの機能で動作します。

UI インスペクションや入力自動化をすぐに使用する予定がある場合は、実際にサーバーを起動するターミナル / MCP クライアント / ランタイムプロセスにアクセシビリティ権限を付与してください。

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

クライアント一覧

クライアント	インストールパス	スクリプトターゲット	備考
Claude Code	claude mcp add	--tool claude-code	--claude-scope によるマルチスコープをサポート
Claude Desktop	claude mcp add --scope user	--tool claude-desktop	ユーザーレベルの登録
Codex CLI	codex mcp add	--tool codex-cli	Codex Desktop の設定でも動作します
Codex Desktop	Codex CLI MCP 設定	--tool codex-desktop	CLI と同じ MCP レジストリを使用
OpenCode	グローバル設定 (~/.config/opencode/opencode.json)	--tool opencode	インストーラーにより自動更新
Gemini	gemini mcp add	--tool gemini	ユーザースコープのセットアップ
Google Antigravity	Gemini 互換の MCP フロー	--tool antigravity	Gemini MCP コマンドパスを使用
GitHub Copilot	copilot または gh copilot セッション	--tool copilot	対話型/セッションベースのセットアップ

LLM 向け

この MCP サーバーをセットアップする LLM エージェントの場合、必要なものはすべてここにあります:

UI 自動化ツールを試す前に、アクセシビリティ権限は通常、自動化対象のアプリではなく ホスト/ランタイムプロセス (node、ターミナル、MCP クライアント) に属することを覚えておいてください。

クイックスタート (1 コマンド)

# Register baepsae as an MCP server for all supported clients
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

自動化フラグ

# Preview commands without executing
bash scripts/install.sh --tool all --dry-run

# Verify environment and dependencies
bash scripts/install.sh --tool all --doctor

# Unregister from all clients
bash scripts/install.sh --tool all --uninstall

ランタイムオプション

インストーラーは --runtime を介して複数のランタイムをサポートしています:

フラグ	コマンド	使用する場合
--runtime node (デフォルト)	node dist/index.js	ローカルソースビルド
--runtime npx	npx -y mcp-baepsae@latest	npm レジストリ、グローバルインストールなし
--runtime bunx	bunx mcp-baepsae@latest	Bun ユーザー
--runtime global	mcp-baepsae	npm install -g mcp-baepsae の実行後

手動セットアップ (フォールバック)

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

npx を使用する場合、該当するアクセシビリティのエントリは通常、起動された node ランタイムとそれを起動したターミナル / MCP クライアントです。

ローカルビルドを使用する場合

# Claude Code (project)
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

ローカルビルドを使用する場合は、ランタイム (node) とそれを起動したアプリの両方で権限を確認してください。
デバッグのために baepsae-native を直接呼び出す場合は、ネイティブバイナリのエントリ自体でも権限を確認してください。

プロジェクト構造

• MCP サーバーのエントリポイント: src/index.ts
• ツールモジュール: src/tools/ (info, simulator, ui, input, media, system)
• 共有ユーティリティ: 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       # Build TypeScript + native Swift binary
npm test            # Contract/integration tests
npm run test:real   # Real simulator smoke test (requires booted simulator)
npm run test:real:preflight  # Environment diagnostics only
npm run test:real:sim        # iOS simulator phases only (skips Phase 4)
npm run test:real:mac        # macOS Safari phase only
npm run verify      # test + test:real
npm run setup:mcp   # Alias for scripts/install.sh

MCP ツールのステータス

43 個のツールがエンドツーエンドで実装されています。

公式の公開 MCP サーフェス: 統合された汎用ツール

公開 API サーフェスは意図的に単一スキームです。sim_* / mac_* という名前ではなく、target 引数を伴う統合された汎用ツールを使用してください。

カテゴリ	ツール
UI	analyze_ui、query_ui、tap、tap_tab、type_text、swipe、scroll、drag_drop、wait_for_ui、detect_dialog、read_ui_value、set_ui_value、read_ui_param、hit_test、enumerate_ui
入力	key、key_sequence、key_combo、touch、input_source、list_input_sources
ワークフロー	run_steps
システム	list_windows、activate_app、screenshot_app、right_click、focus_window、context_menu_action、watch_notification
シミュレータ専用	list_simulators、screenshot、record_video、stream_video、open_url、install_app、launch_app、terminate_app、uninstall_app、button、gesture
macOS／システム	list_apps、menu_action、get_focused_app、clipboard
ユーティリティ	baepsae_help、baepsae_version、doctor

ターゲットのルーティングは引数で明示されます。シミュレータには udid、macOS には bundleId / appName を使用します。

type_text ポリシー

type_text は入力ソースを 1 つだけ受け付けます。text、stdinText、または file です。

• method: "auto" は次のように解決されます:
  • シミュレータターゲットには paste
  • macOS ターゲットには keyboard
• method: "paste" は、シミュレータターゲットではシミュレータのペーストボードを使用し、macOS ターゲットではホストのクリップボードを一時的に置き換えて復元するフローを使用します。
• method: "keyboard" は常に 1 文字ずつ入力します。

paste を使用する場合、シミュレータターゲットはホストのクリップボードに触れることなくシミュレータのペーストボードを更新し、macOS ターゲットはホストのクリップボードを一時的に上書きし、送信後に復元します。成功時のレスポンスは、入力ソース、ターゲットの種類、要求されたメソッド、使用されたメソッド、ペーストのトランスポート、および適用された自動フォールバックを報告します。

tap_tab ポリシー

tap_tab はセマンティック優先、ジオメトリ最後です。

• まず、タブバーの下に公開されている操作可能な子孫要素を試します。
• SwiftUI／シミュレータが実際のタブボタンの子孫要素を公開しない場合、セマンティックプロキシ行（たとえば、同じタブにきれいに対応するアプリ提供の上部ナビゲーションボタン）を使用できます。
• どちらのセマンティックパスも存在しない場合にのみ、タブバーのジオメトリにフォールバックします。

これは重要です。シミュレータの SwiftUI TabView では、タブバーが操作可能な子ボタンを持たない汎用の AXGroup text="Tab Bar" として公開されることがあるためです。

使用例

セマンティック優先のフォールバックを使用してインデックスでタブを切り替える:

// Prefer this when your app exposes a real tab bar but individual tab buttons
// are not consistently addressable via query_ui/tap selectors.
tap_tab({ udid: "...", index: 1, tabCount: 3 })

統合シミュレータアプリのアクセシビリティクイックスタート（アプリ UI 内）:

// 1) Launch your app in the target simulator
launch_app({ udid: "...", bundleId: "com.example.app" })

// 2) Inspect or search accessibility tree (in-app content scope by default)
analyze_ui({ udid: "..." })
query_ui({ udid: "...", query: "Login" })

// 3) Interact by accessibility identifier/label
tap({ udid: "...", id: "login-button" })

// Optional: include Simulator chrome/system UI in selector lookup
tap({ udid: "...", label: "Home", all: true })

URL を開く（iOS シミュレータ）:

// Open Naver Mobile
open_url({ udid: "...", url: "https://m.naver.com" })

アプリを管理する（iOS シミュレータ）:

// Install an app
install_app({ udid: "...", path: "/path/to/App.app" })

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

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

macOS アプリの自動化:

// List running macOS apps
list_apps({})

// Take screenshot of a macOS app
screenshot_app({ bundleId: "com.apple.Safari" })

トラブルシューティング

アクセシビリティ権限チェックリスト

• 権限の対象は通常、自動化ホスト/ランタイムプロセスであり、対象アプリではありません。

• まず doctor を実行して、ホストプロセス、親プロセス、ネイティブバイナリ、起動済みシミュレータの可用性、アクセシビリティの準備状態を一箇所で確認します。

• エラーメッセージで以下を確認します:

  • 現在のホストプロセス
  • 親プロセス
  • 推定された起動モード

• npx / node 経由で起動した場合は、ランタイムと起動元のターミナル / MCP クライアントに権限を付与します。

• baepsae-native を直接起動した場合は、ネイティブバイナリのエントリと起動元のターミナル / シェルアプリに権限を付与します。

• 権限を変更した後は、再試行する前に起動プロセスを再起動します。

• 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 が存在することを確認します。

• アクセシビリティ権限エラーが曖昧:

  • 現在のバージョンでは、エラーテキストにホスト/親プロセスの診断情報と推定された起動モードが含まれるため、どの実行ファイルパスに権限が必要そうかを確認できます。

• 実際のスモークテストの診断:

  • npm run test:real:preflight を実行すると、フルスイートを実行せずに環境と機能の診断情報を出力します。
  • npm run test:real:sim を実行するとシミュレータ機能のカバレッジに集中でき、npm run test:real:mac は macOS Safari のサブセット向けです。

• 複数の Simulator ウィンドウが開いていて、セレクタが誤ったデバイスにヒットする:

  • 現在のバージョンでは、シミュレータのセレクタはまず対象の udid ウィンドウにスコープされます。
  • Simulator のクローム/システム UI が意図的に必要な場合は、all: true を使用します。

• 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 を実行します。