mcp-baepsae 3.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jay Choi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README-KR.md

@@ -0,0 +1,191 @@
+# mcp-baepsae
+
+<p align="center">
+  <img src="assets/baepsae.png" width="300" alt="baepsae">
+</p>
+
+> **뱁새** (붉은머리오목눈이) — 한국의 작은 새. 동글동글 통통한 몸에 삐약삐약 부지런히 돌아다니는 모습이 특징입니다. 황새를 따라가다 가랑이가 찢어질 뻔해도 포기하지 않는 근성의 아이콘. 이 프로젝트도 작지만 부지런히 시뮬레이터를 쪼아댑니다.
+
+TypeScript MCP 레이어와 Swift 네이티브 브리지를 사용하는 iOS 시뮬레이터 및 macOS 앱 자동화용 로컬 MCP 서버입니다.
+
+영문 문서는 `README.md`를 참고하세요.
+
+## 목차
+
+- [사전 요구 사항](#사전-요구-사항)
+- [설치](#설치)
+- [MCP 설정 (권장)](#mcp-설정-권장)
+- [클라이언트 매트릭스](#클라이언트-매트릭스)
+- [For LLM](#for-llm)
+- [수동 설정 (대안)](#수동-설정-대안)
+- [프로젝트 구조](#프로젝트-구조)
+- [명령어](#명령어)
+- [MCP 도구 구현 상태](#mcp-도구-구현-상태)
+- [트러블슈팅](#트러블슈팅)
+
+## 사전 요구 사항
+
+- macOS 14+
+- Xcode + iOS Simulator
+- Node.js 18+
+- Swift 6+
+
+## 설치
+
+### 옵션 A) 로컬 저장소 빌드 사용 (권장)
+
+```bash
+git clone <your-repo-url>
+cd mcp-baepsae
+npm install
+npm run build
+```
+
+### 옵션 B) 전역 CLI 설치
+
+```bash
+npm install -g .
+```
+
+## MCP 설정 (권장)
+
+`scripts/install.sh`를 사용하면 각 AI 클라이언트의 MCP 설치 절차를 직접 호출합니다.
+
+```bash
+bash scripts/install.sh --tool all
+```
+
+## 클라이언트 매트릭스
+
+| 클라이언트 | 설치 경로 | 스크립트 타깃 | 비고 |
+|---|---|---|---|
+| Claude Code | `claude mcp add` | `--tool claude-code` | `--claude-scope`로 다중 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와 동일 레지스트리 |
+| OpenCode | 전역 설정(`~/.config/opencode/opencode.json`) | `--tool opencode` | 설치 스크립트가 자동 갱신 |
+| Gemini | `gemini mcp add` | `--tool gemini` | user scope 설치 |
+| Google Antigravity | Gemini 호환 MCP 흐름 | `--tool antigravity` | Gemini MCP 명령 경로 사용 |
+| GitHub Copilot | `copilot` 또는 `gh copilot` 세션 | `--tool copilot` | interactive/session 기반 |
+
+## For LLM
+
+LLM 에이전트가 이 저장소를 설치부터 설정까지 자동으로 구성할 때:
+
+```bash
+bash scripts/install.sh --tool all
+```
+
+자동화에 유용한 옵션:
+
+```bash
+# 실제 실행 없이 명령만 출력
+bash scripts/install.sh --tool all --dry-run
+
+# 환경/의존성 점검만 수행
+bash scripts/install.sh --tool all --doctor
+
+# MCP 등록 제거
+bash scripts/install.sh --tool all --uninstall
+```
+
+## 수동 설정 (대안)
+
+`scripts/install.sh`를 사용하지 않을 때:
+
+```bash
+# 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
+```
+
+## 프로젝트 구조
+
+- MCP 서버: `src/index.ts`
+- 네이티브 바이너리 프로젝트: `native/`
+- 네이티브 바이너리 출력: `native/.build/release/baepsae-native`
+- 테스트: `tests/mcp.contract.test.mjs`, `tests/mcp.real.test.mjs`
+
+## 명령어
+
+```bash
+npm run build       # TypeScript + Swift 네이티브 빌드
+npm test            # 계약/통합 테스트
+npm run test:real   # 실제 시뮬레이터 스모크 테스트 (부팅된 시뮬레이터 필요)
+npm run verify      # test + test:real
+npm run setup:mcp   # scripts/install.sh 실행 alias
+```
+
+## MCP 도구 구현 상태
+
+총 32개 도구가 end-to-end 구현 완료되었습니다.
+
+### iOS 시뮬레이터 전용 (11개)
+
+| 도구 | 설명 |
+|---|---|
+| `list_simulators` | iOS 시뮬레이터 목록 조회 |
+| `screenshot` | 시뮬레이터 스크린샷 캡처 |
+| `record_video` | 시뮬레이터 화면 녹화 |
+| `stream_video` | 비디오 프레임 스트리밍 |
+| `open_url` | 시뮬레이터에서 URL 열기 (Safari/딥링크) |
+| `install_app` | .app/.ipa 설치 |
+| `launch_app` | Bundle ID로 앱 실행 |
+| `terminate_app` | 실행 중인 앱 종료 |
+| `uninstall_app` | 앱 제거 |
+| `button` | 하드웨어 버튼 (home/lock/side/siri/apple-pay) |
+| `gesture` | 프리셋 제스처 (scroll/swipe-edge) |
+
+### macOS 전용 (4개)
+
+| 도구 | 설명 |
+|---|---|
+| `list_apps` | 실행 중인 macOS 앱 목록 조회 |
+| `scroll` | 스크롤 휠 이벤트 |
+| `menu_action` | 메뉴 바 액션 실행 |
+| `get_focused_app` | 포커스된 앱 정보 조회 |
+
+### 공통 — iOS 시뮬레이터 + macOS (15개)
+
+| 도구 | 설명 |
+|---|---|
+| `describe_ui` | 접근성 트리 조회 (페이지네이션, 필터, 서브트리, 요약 지원) |
+| `search_ui` | UI 요소 검색 (텍스트/ID/라벨) |
+| `tap` | 좌표 또는 ID/라벨로 탭 (더블클릭 지원) |
+| `type_text` | 텍스트 입력 |
+| `swipe` | 스와이프 제스처 |
+| `key` | HID 키코드 입력 |
+| `key_sequence` | 연속 키코드 입력 |
+| `key_combo` | 수정키 + 키 조합 |
+| `touch` | 터치 다운/업 이벤트 |
+| `right_click` | 우클릭 (ID/라벨 또는 좌표) |
+| `drag_drop` | 드래그 앤 드롭 |
+| `clipboard` | 클립보드 읽기/쓰기 |
+| `list_windows` | 앱 윈도우 목록 |
+| `activate_app` | 앱을 포그라운드로 전환 |
+| `screenshot_app` | 앱 윈도우 스크린샷 |
+
+### 유틸리티 (2개)
+
+| 도구 | 설명 |
+|---|---|
+| `baepsae_help` | 도움말 표시 |
+| `baepsae_version` | 버전 정보 표시 |
+
+## 트러블슈팅
+
+- Claude 설정 중 `Invalid environment variable format` 오류:
+  - 최신 `scripts/install.sh`를 사용하거나 `--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/session 기반이므로 `--interactive` 옵션으로 다시 실행하세요.
+- 실사용 스모크 테스트가 skip 되는 경우:
+  - iOS 시뮬레이터를 먼저 부팅한 뒤 `npm run test:real`을 실행하세요.

package/README.md

@@ -0,0 +1,228 @@
+# mcp-baepsae
+
+<p align="center">
+  <img src="assets/baepsae.png" width="300" alt="baepsae">
+</p>
+
+> **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.
+
+Local MCP server for iOS Simulator and macOS app automation with a TypeScript MCP layer and a Swift native bridge.
+
+한국어 문서는 `README-KR.md`를 참고하세요.
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Install](#install)
+- [MCP Setup (Recommended)](#mcp-setup-recommended)
+- [Client Matrix](#client-matrix)
+- [For LLM](#for-llm)
+- [Manual Setup (Fallback)](#manual-setup-fallback)
+- [Project Structure](#project-structure)
+- [Commands](#commands)
+- [MCP Tool Status](#mcp-tool-status)
+- [Troubleshooting](#troubleshooting)
+
+## Prerequisites
+
+- macOS 14+
+- Xcode + iOS Simulator
+- Node.js 18+
+- Swift 6+
+
+## Permissions
+
+**Accessibility permission is required** for UI automation features (`describe_ui`, `tap` by ID).
+
+1. Open **System Settings** > **Privacy & Security** > **Accessibility**.
+2. Enable your terminal (Terminal, iTerm2, VSCode) or command runner (`node`, `openclaw`).
+3. If the app is missing, click `+` and add it manually.
+
+## Install
+
+### Option A) Local repository build (recommended)
+
+```bash
+git clone <your-repo-url>
+cd mcp-baepsae
+npm install
+npm run build
+```
+
+### Option B) Global CLI install
+
+```bash
+npm install -g .
+```
+
+## MCP Setup (Recommended)
+
+Use the installer script that calls each client's MCP install flow directly.
+
+```bash
+bash scripts/install.sh --tool all
+```
+
+## Client Matrix
+
+| Client | Install Path | Script Target | Notes |
+|---|---|---|---|
+| Claude Code | `claude mcp add` | `--tool claude-code` | Supports multi-scope via `--claude-scope` |
+| Claude Desktop | `claude mcp add --scope user` | `--tool claude-desktop` | User-level registration |
+| Codex CLI | `codex mcp add` | `--tool codex-cli` | Also works for Codex Desktop settings |
+| Codex Desktop | Codex CLI MCP config | `--tool codex-desktop` | Uses same MCP registry as CLI |
+| OpenCode | Global config (`~/.config/opencode/opencode.json`) | `--tool opencode` | Auto-updated by installer |
+| Gemini | `gemini mcp add` | `--tool gemini` | User scope setup |
+| Google Antigravity | Gemini-compatible MCP flow | `--tool antigravity` | Uses Gemini MCP command path |
+| GitHub Copilot | `copilot` or `gh copilot` session | `--tool copilot` | Interactive/session-based setup |
+
+## For LLM
+
+If an LLM agent is provisioning this repository end-to-end:
+
+```bash
+bash scripts/install.sh --tool all
+```
+
+Useful automation flags:
+
+```bash
+# Dry run (print only)
+bash scripts/install.sh --tool all --dry-run
+
+# Health check only
+bash scripts/install.sh --tool all --doctor
+
+# Remove MCP registrations
+bash scripts/install.sh --tool all --uninstall
+```
+
+## Manual Setup (Fallback)
+
+Use this when you do not want to run `scripts/install.sh`.
+
+```bash
+# 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
+```
+
+## Project Structure
+
+- MCP server: `src/index.ts`
+- Native binary project: `native/`
+- Native binary output: `native/.build/release/baepsae-native`
+- Tests: `tests/mcp.contract.test.mjs`, `tests/mcp.real.test.mjs`
+
+## Commands
+
+```bash
+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 verify      # test + test:real
+npm run setup:mcp   # Alias for scripts/install.sh
+```
+
+## MCP Tool Status
+
+32 tools implemented end-to-end, organized by platform:
+
+### iOS Simulator Only (11)
+
+| Tool | Description |
+|---|---|
+| `list_simulators` | List available iOS simulators |
+| `screenshot` | Capture simulator screen |
+| `record_video` | Record simulator screen |
+| `stream_video` | Stream video frames |
+| `open_url` | Open URL in simulator (Safari/Deep Link) |
+| `install_app` | Install .app or .ipa |
+| `launch_app` | Launch app by Bundle ID |
+| `terminate_app` | Terminate running app |
+| `uninstall_app` | Uninstall app |
+| `button` | Hardware buttons (home, lock, side, siri, apple-pay) |
+| `gesture` | Preset gestures (scroll, swipe-edge) |
+
+### macOS Only (4)
+
+| Tool | Description |
+|---|---|
+| `list_apps` | List running macOS apps |
+| `scroll` | Scroll wheel events |
+| `menu_action` | Execute menu bar actions |
+| `get_focused_app` | Get focused app info |
+
+### Cross-Platform — iOS Simulator + macOS (15)
+
+| Tool | Description |
+|---|---|
+| `describe_ui` | Accessibility tree (pagination, filter, subtree, summary) |
+| `search_ui` | Search UI elements by text/ID/label |
+| `tap` | Tap by coordinates or element ID/label (supports double-click) |
+| `type_text` | Type text input |
+| `swipe` | Swipe gesture |
+| `key` | HID keycode input |
+| `key_sequence` | Sequential keycode input |
+| `key_combo` | Modifier + key combination |
+| `touch` | Touch down/up events |
+| `right_click` | Right-click by ID/label or coordinates |
+| `drag_drop` | Drag and drop |
+| `clipboard` | Read/write clipboard |
+| `list_windows` | List app windows |
+| `activate_app` | Bring app to foreground |
+| `screenshot_app` | Capture app window screenshot |
+
+### Utility (2)
+
+| Tool | Description |
+|---|---|
+| `baepsae_help` | Show help info |
+| `baepsae_version` | Show version info |
+
+## Usage Examples
+
+**Open a URL (iOS Simulator):**
+```javascript
+// Open Naver Mobile
+open_url({ udid: "...", url: "https://m.naver.com" })
+```
+
+**Manage Apps (iOS Simulator):**
+```javascript
+// 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 App Automation:**
+```javascript
+// List running macOS apps
+list_apps({})
+
+// Take screenshot of a macOS app
+screenshot_app({ bundleId: "com.apple.Safari" })
+```
+
+## Troubleshooting
+
+- `Invalid environment variable format` on Claude setup:
+  - Use current script (`scripts/install.sh`) or `claude mcp add --env="KEY=value" ...` format.
+- `Missing native binary` error:
+  - Run `npm run build` and confirm `native/.build/release/baepsae-native` exists.
+- OpenCode does not show `baepsae`:
+  - Re-run `bash scripts/install.sh --tool opencode --skip-install --skip-build` and check `~/.config/opencode/opencode.json`.
+- Copilot not auto-registered:
+  - Copilot MCP flow is interactive/session-based. Re-run installer with `--interactive`.
+- Real smoke test skipped:
+  - Boot an iOS simulator first, then run `npm run test:real`.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}