{
  "markdown": "# mcp-baepsae\n\n<p align=\"center\">\n  <img src=\"assets/baepsae.png\" width=\"300\" alt=\"baepsae\">\n</p>\n\n> **Baepsae** (Vinous-throated Parrotbill) — A tiny Korean bird. Round, chubby, and constantly hopping around chirping. Known for its grit — even when a little bird tries to keep up with a stork, it never gives up. This project is small too, but it pecks away at your simulators tirelessly.\n\nLocal MCP server for iOS Simulator and macOS app automation with a TypeScript MCP layer and a Swift native bridge.\n\n한국어 문서는 [README-KR.md](./README-KR.md)를 참고하세요.\n\n## Table of Contents\n\n- [Prerequisites](#prerequisites)\n- [Platform Support](#platform-support)\n- [Install](#install)\n- [Permissions](#permissions)\n- [MCP Setup (Recommended)](#mcp-setup-recommended)\n- [Client Matrix](#client-matrix)\n- [For LLM](#for-llm)\n- [Manual Setup (Fallback)](#manual-setup-fallback)\n- [Project Structure](#project-structure)\n- [Commands](#commands)\n- [MCP Tool Status](#mcp-tool-status)\n- [Usage Examples](#usage-examples)\n- [Troubleshooting](#troubleshooting)\n\n## Prerequisites\n\n- macOS 14+\n- Xcode + iOS Simulator\n- Node.js 18+\n- Swift 6+\n\n## Platform Support\n\n| Platform | Supported | Notes |\n|---|---|---|\n| macOS | Yes | Primary platform. Required for iOS Simulator and Accessibility APIs. |\n| Linux | No | Native binary depends on AppKit, CoreGraphics, and Accessibility frameworks. |\n| Windows | No | Native binary depends on AppKit, CoreGraphics, and Accessibility frameworks. |\n\n**Why macOS only?**\n\nThe Swift native bridge (`baepsae-native`) uses macOS-specific frameworks (AppKit, CoreGraphics, Accessibility) to interact with iOS Simulator and macOS applications. These frameworks are not available on Linux or Windows. The TypeScript MCP layer also relies on `xcrun simctl`, which is part of Xcode Command Line Tools and only available on macOS.\n\n**Requirements summary:**\n\n- **macOS 14 or later** -- required for iOS Simulator automation and Accessibility API access.\n- **Xcode or Xcode Command Line Tools** -- required for Swift 6+ compilation of the native binary and `xcrun simctl` commands.\n- **Node.js >= 18.0.0** -- required to run the TypeScript MCP server.\n\n## Permissions\n\n**Accessibility permission is required** for UI inspection and input automation features (use unified generic tools such as `analyze_ui`, `tap`, `right_click`).\n\nThe important detail is that permission usually needs to be granted to the **automation host / runtime process**, not to the target app you are automating.\n\n### Which process usually needs permission?\n\n- **Direct native binary invocation**\n  - Example: `baepsae-native ...`\n  - Most relevant entry: the `baepsae-native` binary itself, plus the terminal/shell app that launched it\n- **Node / npx MCP runtime**\n  - Example: `node dist/index.js`, `npx -y mcp-baepsae@latest`\n  - Most relevant entry: the runtime process (`node`), plus the terminal or MCP client app that launched it\n- **Desktop / CLI MCP clients**\n  - Example: Claude Code, Codex CLI/Desktop, Gemini CLI\n  - Relevant entries can include the MCP client app, the terminal host, and the runtime process depending on launch path\n\n### Recommended setup flow\n\n1. Open **System Settings** > **Privacy & Security** > **Accessibility**.\n2. Enable the terminal or MCP client app you actually use.\n3. Enable the runtime process if listed (`node`, `bun`, etc.).\n4. For direct native invocation, also enable the `baepsae-native` binary entry if it appears separately.\n5. If an entry is missing, click `+` and add it manually.\n\n### Important note\n\nAfter granting permission, the launching process may need to be restarted before macOS applies the change.  \nIf the error persists, quit and relaunch the terminal, MCP client, or runtime process that started `mcp-baepsae`.\n\nFor simulator targets, selector-based actions (`tap` / `right_click` with `id` or `label`) search **in-app content** by default. Set `all: true` to include Simulator chrome UI.\n\n## Install\n\n### Option A) npm (easiest)\n\n```bash\n# Run directly without installing\nnpx mcp-baepsae@latest\n\n# Or install globally\nnpm install -g mcp-baepsae\n```\n\n> On macOS, the Swift native binary is built automatically during install. If Swift is not available, the server still works with simctl-based features.\n>\n> If you plan to use UI inspection or input automation right away, grant Accessibility permission to the terminal / MCP client / runtime process you will actually launch the server with.\n\n### Option B) From source\n\n```bash\ngit clone https://github.com/oozoofrog/mcp-baepsae.git\ncd mcp-baepsae\nnpm install\nnpm run build\n```\n\n## MCP Setup (Recommended)\n\nUse the installer script that calls each client's MCP install flow directly.\n\n```bash\nbash scripts/install.sh --tool all\n```\n\n## Client Matrix\n\n| Client | Install Path | Script Target | Notes |\n|---|---|---|---|\n| Claude Code | `claude mcp add` | `--tool claude-code` | Supports multi-scope via `--claude-scope` |\n| Claude Desktop | `claude mcp add --scope user` | `--tool claude-desktop` | User-level registration |\n| Codex CLI | `codex mcp add` | `--tool codex-cli` | Also works for Codex Desktop settings |\n| Codex Desktop | Codex CLI MCP config | `--tool codex-desktop` | Uses same MCP registry as CLI |\n| OpenCode | Global config (`~/.config/opencode/opencode.json`) | `--tool opencode` | Auto-updated by installer |\n| Gemini | `gemini mcp add` | `--tool gemini` | User scope setup |\n| Google Antigravity | Gemini-compatible MCP flow | `--tool antigravity` | Uses Gemini MCP command path |\n| GitHub Copilot | `copilot` or `gh copilot` session | `--tool copilot` | Interactive/session-based setup |\n\n## For LLM\n\nIf you are an LLM agent setting up this MCP server, here is everything you need:\n\n> Before trying UI automation tools, remember that Accessibility permission usually belongs to the **host/runtime process** (`node`, terminal, MCP client), not the target app under automation.\n\n### Quick start (one command)\n\n```bash\n# Register baepsae as an MCP server for all supported clients\nbash scripts/install.sh --tool all\n```\n\nIf you installed via npm instead of cloning the repo, use npx:\n\n```bash\n# Claude Code\nclaude mcp add baepsae -- npx -y mcp-baepsae@latest\n\n# Codex CLI\ncodex mcp add baepsae -- npx -y mcp-baepsae@latest\n```\n\n### Automation flags\n\n```bash\n# Preview commands without executing\nbash scripts/install.sh --tool all --dry-run\n\n# Verify environment and dependencies\nbash scripts/install.sh --tool all --doctor\n\n# Unregister from all clients\nbash scripts/install.sh --tool all --uninstall\n```\n\n### Runtime options\n\nThe installer supports multiple runtimes via `--runtime`:\n\n| Flag | Command | When to use |\n|---|---|---|\n| `--runtime node` (default) | `node dist/index.js` | Local source build |\n| `--runtime npx` | `npx -y mcp-baepsae@latest` | npm registry, no global install |\n| `--runtime bunx` | `bunx mcp-baepsae@latest` | Bun users |\n| `--runtime global` | `mcp-baepsae` | After `npm install -g mcp-baepsae` |\n\n## Manual Setup (Fallback)\n\nUse this when you do not want to run `scripts/install.sh`.\n\n### Using npx (recommended for npm users)\n\n```bash\n# Claude Code\nclaude mcp add baepsae -- npx -y mcp-baepsae@latest\n\n# Codex CLI\ncodex mcp add baepsae -- npx -y mcp-baepsae@latest\n\n# Gemini CLI\ngemini mcp add --scope user --transport stdio baepsae npx -y mcp-baepsae@latest\n```\n\nWhen using `npx`, the relevant Accessibility entry is commonly the spawned `node` runtime plus the terminal / MCP client that launched it.\n\n### Using local build\n\n```bash\n# Claude Code (project)\nclaude mcp add --scope project --env=\"BAEPSAE_NATIVE_PATH=/ABS/PATH/native/.build/release/baepsae-native\" baepsae -- node /ABS/PATH/dist/index.js\n\n# Codex CLI\ncodex mcp add baepsae --env BAEPSAE_NATIVE_PATH=/ABS/PATH/native/.build/release/baepsae-native -- node /ABS/PATH/dist/index.js\n\n# Gemini CLI\ngemini mcp add --scope user --transport stdio -e BAEPSAE_NATIVE_PATH=/ABS/PATH/native/.build/release/baepsae-native baepsae node /ABS/PATH/dist/index.js\n```\n\nWhen using a local build, check permission on both the runtime (`node`) and the app that launched it.  \nIf you invoke `baepsae-native` directly for debugging, check permission on the native binary entry itself as well.\n\n## Project Structure\n\n- MCP server entry point: `src/index.ts`\n- Tool modules: `src/tools/` (info, simulator, ui, input, media, system)\n- Shared utilities: `src/utils.ts`, `src/types.ts`\n- Native binary entry point: `native/Sources/main.swift`\n- Native command handlers: `native/Sources/Commands/`\n- Native binary output: `native/.build/release/baepsae-native`\n- TS tests: `tests/mcp.contract.test.mjs`, `tests/unit.test.mjs`, `tests/mcp.real.test.mjs`\n- Swift tests: `native/Tests/BaepsaeNativeTests/`\n\n## Commands\n\n```bash\nnpm run build       # Build TypeScript + native Swift binary\nnpm test            # Contract/integration tests\nnpm run test:real   # Real simulator smoke test (requires booted simulator)\nnpm run test:real:preflight  # Environment diagnostics only\nnpm run test:real:sim        # iOS simulator phases only (skips Phase 4)\nnpm run test:real:mac        # macOS Safari phase only\nnpm run verify      # test + test:real\nnpm run setup:mcp   # Alias for scripts/install.sh\n```\n\n## MCP Tool Status\n\n43 tools implemented end-to-end.\n\n### Official public MCP surface: unified generic tools\n\nThe public API surface is intentionally single-scheme: use unified generic tools with a target argument, rather than `sim_*` / `mac_*` names.\n\n| Category | Tools |\n|---|---|\n| 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` |\n| Input | `key`, `key_sequence`, `key_combo`, `touch`, `input_source`, `list_input_sources` |\n| Workflow | `run_steps` |\n| System | `list_windows`, `activate_app`, `screenshot_app`, `right_click`, `focus_window`, `context_menu_action`, `watch_notification` |\n| Simulator-only | `list_simulators`, `screenshot`, `record_video`, `stream_video`, `open_url`, `install_app`, `launch_app`, `terminate_app`, `uninstall_app`, `button`, `gesture` |\n| macOS/system | `list_apps`, `menu_action`, `get_focused_app`, `clipboard` |\n| Utility | `baepsae_help`, `baepsae_version`, `doctor` |\n\nTarget routing is explicit in the arguments: `udid` for simulator, `bundleId` / `appName` for macOS.\n\n### `type_text` policy\n\n`type_text` accepts exactly one input source: `text`, `stdinText`, or `file`.\n\n- `method: \"auto\"` resolves to:\n  - `paste` for simulator targets\n  - `keyboard` for macOS targets\n- `method: \"paste\"` uses the simulator pasteboard for simulator targets and a temporary host clipboard replace/restore flow for macOS targets.\n- `method: \"keyboard\"` always types character-by-character.\n\nWhen `paste` is used, simulator targets update the simulator pasteboard without touching the host clipboard, while macOS targets temporarily overwrite the host clipboard and restore it after submission. Successful responses report the input source, target kind, requested method, used method, paste transport, and any auto fallback that was applied.\n\n### `tap_tab` policy\n\n`tap_tab` is **semantic-first, geometry-last**.\n\n- First it tries actionable descendants exposed under the tab bar.\n- If SwiftUI/Simulator does not expose real tab button descendants, it can use a **semantic proxy row** (for example, app-provided top navigation buttons that map cleanly to the same tabs).\n- Only if neither semantic path exists does it fall back to tab-bar geometry.\n\nThis matters because SwiftUI `TabView` in Simulator may expose the tab bar as a generic `AXGroup text=\"Tab Bar\"` without actionable child buttons.\n\n## Usage Examples\n\n**Switch tabs by index with semantic-first fallback:**\n```javascript\n// Prefer this when your app exposes a real tab bar but individual tab buttons\n// are not consistently addressable via query_ui/tap selectors.\ntap_tab({ udid: \"...\", index: 1, tabCount: 3 })\n```\n\n**Unified simulator app accessibility quickstart (inside app UI):**\n```javascript\n// 1) Launch your app in the target simulator\nlaunch_app({ udid: \"...\", bundleId: \"com.example.app\" })\n\n// 2) Inspect or search accessibility tree (in-app content scope by default)\nanalyze_ui({ udid: \"...\" })\nquery_ui({ udid: \"...\", query: \"Login\" })\n\n// 3) Interact by accessibility identifier/label\ntap({ udid: \"...\", id: \"login-button\" })\n\n// Optional: include Simulator chrome/system UI in selector lookup\ntap({ udid: \"...\", label: \"Home\", all: true })\n```\n\n**Open a URL (iOS Simulator):**\n```javascript\n// Open Naver Mobile\nopen_url({ udid: \"...\", url: \"https://m.naver.com\" })\n```\n\n**Manage Apps (iOS Simulator):**\n```javascript\n// Install an app\ninstall_app({ udid: \"...\", path: \"/path/to/App.app\" })\n\n// Launch Safari\nlaunch_app({ udid: \"...\", bundleId: \"com.apple.mobilesafari\" })\n\n// Terminate Safari\nterminate_app({ udid: \"...\", bundleId: \"com.apple.mobilesafari\" })\n```\n\n**macOS App Automation:**\n```javascript\n// List running macOS apps\nlist_apps({})\n\n// Take screenshot of a macOS app\nscreenshot_app({ bundleId: \"com.apple.Safari\" })\n```\n\n## Troubleshooting\n\n### Accessibility permission checklist\n\n- The permission target is usually the **automation host/runtime process**, not the target app.\n- Run `doctor` first to inspect host process, parent process, native binary, booted simulator availability, and accessibility readiness in one place.\n- Check the error message for:\n  - **current host process**\n  - **parent process**\n  - **inferred launch mode**\n- If you launched through `npx` / `node`, grant permission to the runtime and the launching terminal / MCP client.\n- If you launched `baepsae-native` directly, grant permission to the native binary entry and the launching terminal / shell app.\n- After changing permission, restart the launching process before retrying.\n\n- `Invalid environment variable format` on Claude setup:\n  - Use current script (`scripts/install.sh`) or `claude mcp add --env=\"KEY=value\" ...` format.\n- `Missing native binary` error:\n  - Run `npm run build` and confirm `native/.build/release/baepsae-native` exists.\n- Accessibility permission error is ambiguous:\n  - Current versions include host/parent process diagnostics and inferred launch mode in the error text so you can see which executable path likely needs permission.\n- Real smoke test diagnostics:\n  - Run `npm run test:real:preflight` to print environment and capability diagnostics without executing the full suite.\n  - Run `npm run test:real:sim` to focus on simulator-capability coverage, or `npm run test:real:mac` for the macOS Safari subset.\n- Multiple Simulator windows are open and selectors hit the wrong device:\n  - Current versions scope simulator selectors to the target `udid` window first.\n  - If you intentionally need Simulator chrome/system UI, use `all: true`.\n- OpenCode does not show `baepsae`:\n  - Re-run `bash scripts/install.sh --tool opencode --skip-install --skip-build` and check `~/.config/opencode/opencode.json`.\n- Copilot not auto-registered:\n  - Copilot MCP flow is interactive/session-based. Re-run installer with `--interactive`.\n- Real smoke test skipped:\n  - Boot an iOS simulator first, then run `npm run test:real`.\n",
  "bytes": 15192,
  "sha": "31c98396bb9069be18e51086415e7bea8fbf970d84be7b313b296258c599f4cf",
  "repo_slug": "oozoofrog/mcp-baepsae",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_oozoofrog_baepsae_422c8862/readme"
}