mcp-baepsae 3.1.9 → 4.0.0

package/README-KR.md

@@ -13,7 +13,9 @@ TypeScript MCP 레이어와 Swift 네이티브 브리지를 사용하는 iOS 시
 ## 목차
 
 - [사전 요구 사항](#사전-요구-사항)
+- [플랫폼 지원](#플랫폼-지원)
 - [설치](#설치)
+- [권한](#권한)
 - [MCP 설정 (권장)](#mcp-설정-권장)
 - [클라이언트 매트릭스](#클라이언트-매트릭스)
 - [For LLM](#for-llm)
@@ -21,6 +23,7 @@ TypeScript MCP 레이어와 Swift 네이티브 브리지를 사용하는 iOS 시
 - [프로젝트 구조](#프로젝트-구조)
 - [명령어](#명령어)
 - [MCP 도구 구현 상태](#mcp-도구-구현-상태)
+- [사용 예시](#사용-예시)
 - [트러블슈팅](#트러블슈팅)
 
 ## 사전 요구 사항
@@ -30,13 +33,41 @@ TypeScript MCP 레이어와 Swift 네이티브 브리지를 사용하는 iOS 시
 - Node.js 18+
 - Swift 6+
 
+## 플랫폼 지원
+
+| 플랫폼 | 지원 여부 | 비고 |
+|---|---|---|
+| macOS | 지원 | 기본 플랫폼. iOS 시뮬레이터 및 접근성 API에 필수. |
+| Linux | 미지원 | 네이티브 바이너리가 AppKit, CoreGraphics, Accessibility 프레임워크에 의존. |
+| Windows | 미지원 | 네이티브 바이너리가 AppKit, CoreGraphics, Accessibility 프레임워크에 의존. |
+
+**macOS 전용인 이유**
+
+Swift 네이티브 브리지(`baepsae-native`)는 iOS 시뮬레이터 및 macOS 애플리케이션과 상호작용하기 위해 macOS 전용 프레임워크(AppKit, CoreGraphics, Accessibility)를 사용합니다. 이 프레임워크들은 Linux나 Windows에서 사용할 수 없습니다. TypeScript MCP 레이어 또한 Xcode Command Line Tools에 포함된 `xcrun simctl`에 의존하며, 이는 macOS에서만 사용 가능합니다.
+
+**요구 사항 요약:**
+
+- **macOS 14 이상** -- iOS 시뮬레이터 자동화 및 접근성 API 접근에 필요합니다.
+- **Xcode 또는 Xcode Command Line Tools** -- 네이티브 바이너리의 Swift 6+ 컴파일 및 `xcrun simctl` 명령어 실행에 필요합니다.
+- **Node.js >= 18.0.0** -- TypeScript MCP 서버 실행에 필요합니다.
+
+## 권한
+
+**접근성(Accessibility) 권한이 필요합니다.** UI 조회/입력 자동화 도구(`sim_*` / `mac_*` 스코프 도구, 예: `sim_describe_ui`, `mac_tap`, `sim_right_click`)를 사용할 때 필수입니다.
+
+1. **시스템 설정** > **개인정보 보호 및 보안** > **손쉬운 사용(Accessibility)** 로 이동합니다.
+2. 사용 중인 터미널/실행기(Terminal, iTerm2, VSCode, `node`, `openclaw`)를 허용합니다.
+3. 목록에 없으면 `+` 버튼으로 수동 추가합니다.
+
+시뮬레이터 타깃에서 선택자 기반 액션(`sim_tap`/`sim_right_click`의 `id`/`label`)은 기본적으로 **앱 내부 콘텐츠**를 탐색합니다. Simulator 크롬/시스템 UI까지 포함하려면 `all: true`를 사용하세요.
+
 ## 설치
 
 ### 옵션 A) npm (가장 간편)
 
 ```bash
 # 설치 없이 바로 실행
-npx mcp-baepsae
+npx mcp-baepsae@latest
 
 # 또는 전역 설치
 npm install -g mcp-baepsae
@@ -89,10 +120,10 @@ bash scripts/install.sh --tool all
 
 ```bash
 # Claude Code
-claude mcp add baepsae -- npx -y mcp-baepsae
+claude mcp add baepsae -- npx -y mcp-baepsae@latest
 
 # Codex CLI
-codex mcp add baepsae -- npx -y mcp-baepsae
+codex mcp add baepsae -- npx -y mcp-baepsae@latest
 ```
 
 ### 자동화 옵션
@@ -115,8 +146,8 @@ bash scripts/install.sh --tool all --uninstall
 | 플래그 | 명령어 | 사용 시점 |
 |---|---|---|
 | `--runtime node` (기본값) | `node dist/index.js` | 소스 빌드 |
-| `--runtime npx` | `npx -y mcp-baepsae` | npm 레지스트리, 전역 설치 불필요 |
-| `--runtime bunx` | `bunx mcp-baepsae` | Bun 사용자 |
+| `--runtime npx` | `npx -y mcp-baepsae@latest` | npm 레지스트리, 전역 설치 불필요 |
+| `--runtime bunx` | `bunx mcp-baepsae@latest` | Bun 사용자 |
 | `--runtime global` | `mcp-baepsae` | `npm install -g mcp-baepsae` 이후 |
 
 ## 수동 설정 (대안)
@@ -127,13 +158,13 @@ bash scripts/install.sh --tool all --uninstall
 
 ```bash
 # Claude Code
-claude mcp add baepsae -- npx -y mcp-baepsae
+claude mcp add baepsae -- npx -y mcp-baepsae@latest
 
 # Codex CLI
-codex mcp add baepsae -- npx -y mcp-baepsae
+codex mcp add baepsae -- npx -y mcp-baepsae@latest
 
 # Gemini CLI
-gemini mcp add --scope user --transport stdio baepsae npx -y mcp-baepsae
+gemini mcp add --scope user --transport stdio baepsae npx -y mcp-baepsae@latest
 ```
 
 ### 로컬 빌드 사용
@@ -151,10 +182,14 @@ gemini mcp add --scope user --transport stdio -e BAEPSAE_NATIVE_PATH=/ABS/PATH/n
 
 ## 프로젝트 구조
 
-- MCP 서버: `src/index.ts`
-- 네이티브 바이너리 프로젝트: `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`
-- 테스트: `tests/mcp.contract.test.mjs`, `tests/mcp.real.test.mjs`
+- TS 테스트: `tests/mcp.contract.test.mjs`, `tests/unit.test.mjs`, `tests/mcp.real.test.mjs`
+- Swift 테스트: `native/Tests/BaepsaeNativeTests/`
 
 ## 명령어
 
@@ -168,59 +203,59 @@ npm run setup:mcp   # scripts/install.sh 실행 alias
 
 ## MCP 도구 구현 상태
 
-총 32개 도구가 end-to-end 구현 완료되었습니다.
+총 47개 도구가 end-to-end 구현 완료되었습니다.
 
-### iOS 시뮬레이터 전용 (11개)
+### 타깃 분리 스코프 도구 (30개, 권장)
 
-| 도구 | 설명 |
-|---|---|
-| `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개)
-
-| 도구 | 설명 |
+시뮬레이터/맥 타깃 혼동을 줄이려면 아래 `sim_*` / `mac_*` 도구를 우선 사용하세요.
+
+| 시뮬레이터 스코프 | macOS 스코프 |
 |---|---|
-| `list_apps` | 실행 중인 macOS 앱 목록 조회 |
-| `scroll` | 스크롤 휠 이벤트 |
-| `menu_action` | 메뉴 바 액션 실행 |
-| `get_focused_app` | 포커스된 앱 정보 조회 |
+| `sim_describe_ui` | `mac_describe_ui` |
+| `sim_search_ui` | `mac_search_ui` |
+| `sim_tap` | `mac_tap` |
+| `sim_type_text` | `mac_type_text` |
+| `sim_swipe` | `mac_swipe` |
+| `sim_key` | `mac_key` |
+| `sim_key_sequence` | `mac_key_sequence` |
+| `sim_key_combo` | `mac_key_combo` |
+| `sim_touch` | `mac_touch` |
+| `sim_right_click` | `mac_right_click` |
+| `sim_scroll` | `mac_scroll` |
+| `sim_drag_drop` | `mac_drag_drop` |
+| `sim_list_windows` | `mac_list_windows` |
+| `sim_activate_app` | `mac_activate_app` |
+| `sim_screenshot_app` | `mac_screenshot_app` |
 
-### 공통 — iOS 시뮬레이터 + macOS (15개)
+### iOS 시뮬레이터 전용 (11개)
 
-| 도구 | 설명 |
-|---|---|
-| `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` | 앱 윈도우 스크린샷 |
+`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` | 버전 정보 표시 |
+`baepsae_help`, `baepsae_version`
+
+## 사용 예시
+
+**시뮬레이터 내부 앱 접근성 퀵스타트:**
+```javascript
+// 1) 대상 시뮬레이터에서 앱 실행
+launch_app({ udid: "...", bundleId: "com.example.app" })
+
+// 2) 접근성 트리 조회/검색 (기본: 앱 내부 콘텐츠 스코프)
+sim_describe_ui({ udid: "..." })
+sim_search_ui({ udid: "...", query: "로그인" })
+
+// 3) 접근성 ID/라벨로 상호작용
+sim_tap({ udid: "...", id: "login-button" })
+
+// 선택: Simulator 크롬/시스템 UI까지 탐색하려면
+sim_tap({ udid: "...", label: "Home", all: true })
+```
 
 ## 트러블슈팅
 

package/README.md

@@ -13,7 +13,9 @@ Local MCP server for iOS Simulator and macOS app automation with a TypeScript MC
 ## Table of Contents
 
 - [Prerequisites](#prerequisites)
+- [Platform Support](#platform-support)
 - [Install](#install)
+- [Permissions](#permissions)
 - [MCP Setup (Recommended)](#mcp-setup-recommended)
 - [Client Matrix](#client-matrix)
 - [For LLM](#for-llm)
@@ -21,6 +23,7 @@ Local MCP server for iOS Simulator and macOS app automation with a TypeScript MC
 - [Project Structure](#project-structure)
 - [Commands](#commands)
 - [MCP Tool Status](#mcp-tool-status)
+- [Usage Examples](#usage-examples)
 - [Troubleshooting](#troubleshooting)
 
 ## Prerequisites
@@ -30,21 +33,41 @@ Local MCP server for iOS Simulator and macOS app automation with a TypeScript MC
 - Node.js 18+
 - Swift 6+
 
+## Platform Support
+
+| Platform | Supported | Notes |
+|---|---|---|
+| macOS | Yes | Primary platform. Required for iOS Simulator and Accessibility APIs. |
+| Linux | No | Native binary depends on AppKit, CoreGraphics, and Accessibility frameworks. |
+| Windows | No | Native binary depends on AppKit, CoreGraphics, and Accessibility frameworks. |
+
+**Why macOS only?**
+
+The 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.
+
+**Requirements summary:**
+
+- **macOS 14 or later** -- required for iOS Simulator automation and Accessibility API access.
+- **Xcode or Xcode Command Line Tools** -- required for Swift 6+ compilation of the native binary and `xcrun simctl` commands.
+- **Node.js >= 18.0.0** -- required to run the TypeScript MCP server.
+
 ## Permissions
 
-**Accessibility permission is required** for UI automation features (`describe_ui`, `tap` by ID).
+**Accessibility permission is required** for UI inspection and input automation features (use `sim_*` / `mac_*` scoped tools such as `sim_describe_ui`, `mac_tap`, `sim_right_click`).
 
 1. Open **System Settings** > **Privacy & Security** > **Accessibility**.
-2. Enable your terminal (Terminal, iTerm2, VSCode) or command runner (`node`, `openclaw`).
+2. Enable the MCP client app and terminal you actually use, and also the runtime process (`node`) if listed.
 3. If the app is missing, click `+` and add it manually.
 
+For simulator targets, selector-based actions (`sim_tap` / `sim_right_click` with `id` or `label`) search **in-app content** by default. Set `all: true` to include Simulator chrome UI.
+
 ## Install
 
 ### Option A) npm (easiest)
 
 ```bash
 # Run directly without installing
-npx mcp-baepsae
+npx mcp-baepsae@latest
 
 # Or install globally
 npm install -g mcp-baepsae
@@ -97,10 +120,10 @@ If you installed via npm instead of cloning the repo, use npx:
 
 ```bash
 # Claude Code
-claude mcp add baepsae -- npx -y mcp-baepsae
+claude mcp add baepsae -- npx -y mcp-baepsae@latest
 
 # Codex CLI
-codex mcp add baepsae -- npx -y mcp-baepsae
+codex mcp add baepsae -- npx -y mcp-baepsae@latest
 ```
 
 ### Automation flags
@@ -123,8 +146,8 @@ The installer supports multiple runtimes via `--runtime`:
 | Flag | Command | When to use |
 |---|---|---|
 | `--runtime node` (default) | `node dist/index.js` | Local source build |
-| `--runtime npx` | `npx -y mcp-baepsae` | npm registry, no global install |
-| `--runtime bunx` | `bunx mcp-baepsae` | Bun users |
+| `--runtime npx` | `npx -y mcp-baepsae@latest` | npm registry, no global install |
+| `--runtime bunx` | `bunx mcp-baepsae@latest` | Bun users |
 | `--runtime global` | `mcp-baepsae` | After `npm install -g mcp-baepsae` |
 
 ## Manual Setup (Fallback)
@@ -135,13 +158,13 @@ Use this when you do not want to run `scripts/install.sh`.
 
 ```bash
 # Claude Code
-claude mcp add baepsae -- npx -y mcp-baepsae
+claude mcp add baepsae -- npx -y mcp-baepsae@latest
 
 # Codex CLI
-codex mcp add baepsae -- npx -y mcp-baepsae
+codex mcp add baepsae -- npx -y mcp-baepsae@latest
 
 # Gemini CLI
-gemini mcp add --scope user --transport stdio baepsae npx -y mcp-baepsae
+gemini mcp add --scope user --transport stdio baepsae npx -y mcp-baepsae@latest
 ```
 
 ### Using local build
@@ -159,10 +182,14 @@ gemini mcp add --scope user --transport stdio -e BAEPSAE_NATIVE_PATH=/ABS/PATH/n
 
 ## Project Structure
 
-- MCP server: `src/index.ts`
-- Native binary project: `native/`
+- MCP server entry point: `src/index.ts`
+- Tool modules: `src/tools/` (info, simulator, ui, input, media, system)
+- Shared utilities: `src/utils.ts`, `src/types.ts`
+- Native binary entry point: `native/Sources/main.swift`
+- Native command handlers: `native/Sources/Commands/`
 - Native binary output: `native/.build/release/baepsae-native`
-- Tests: `tests/mcp.contract.test.mjs`, `tests/mcp.real.test.mjs`
+- TS tests: `tests/mcp.contract.test.mjs`, `tests/unit.test.mjs`, `tests/mcp.real.test.mjs`
+- Swift tests: `native/Tests/BaepsaeNativeTests/`
 
 ## Commands
 
@@ -176,62 +203,60 @@ npm run setup:mcp   # Alias for scripts/install.sh
 
 ## MCP Tool Status
 
-32 tools implemented end-to-end, organized by platform:
+47 tools implemented end-to-end.
 
-### iOS Simulator Only (11)
+### Explicit target-scoped tools (30, recommended)
 
-| 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 |
+Use these first to avoid simulator/macOS target ambiguity.
+
+| Simulator-scoped | macOS-scoped |
 |---|---|
-| `list_apps` | List running macOS apps |
-| `scroll` | Scroll wheel events |
-| `menu_action` | Execute menu bar actions |
-| `get_focused_app` | Get focused app info |
+| `sim_describe_ui` | `mac_describe_ui` |
+| `sim_search_ui` | `mac_search_ui` |
+| `sim_tap` | `mac_tap` |
+| `sim_type_text` | `mac_type_text` |
+| `sim_swipe` | `mac_swipe` |
+| `sim_key` | `mac_key` |
+| `sim_key_sequence` | `mac_key_sequence` |
+| `sim_key_combo` | `mac_key_combo` |
+| `sim_touch` | `mac_touch` |
+| `sim_right_click` | `mac_right_click` |
+| `sim_scroll` | `mac_scroll` |
+| `sim_drag_drop` | `mac_drag_drop` |
+| `sim_list_windows` | `mac_list_windows` |
+| `sim_activate_app` | `mac_activate_app` |
+| `sim_screenshot_app` | `mac_screenshot_app` |
 
-### Cross-Platform — iOS Simulator + macOS (15)
+### iOS Simulator Only (11)
 
-| 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 |
+`list_simulators`, `screenshot`, `record_video`, `stream_video`, `open_url`, `install_app`, `launch_app`, `terminate_app`, `uninstall_app`, `button`, `gesture`
+
+### macOS / System Only (4)
+
+`list_apps`, `menu_action`, `get_focused_app`, `clipboard`
 
 ### Utility (2)
 
-| Tool | Description |
-|---|---|
-| `baepsae_help` | Show help info |
-| `baepsae_version` | Show version info |
+`baepsae_help`, `baepsae_version`
 
 ## Usage Examples
 
+**Simulator app accessibility quickstart (inside app UI):**
+```javascript
+// 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)
+sim_describe_ui({ udid: "..." })
+sim_search_ui({ udid: "...", query: "Login" })
+
+// 3) Interact by accessibility identifier/label
+sim_tap({ udid: "...", id: "login-button" })
+
+// Optional: include Simulator chrome/system UI in selector lookup
+sim_tap({ udid: "...", label: "Home", all: true })
+```
+
 **Open a URL (iOS Simulator):**
 ```javascript
 // Open Naver Mobile
@@ -256,7 +281,7 @@ terminate_app({ udid: "...", bundleId: "com.apple.mobilesafari" })
 list_apps({})
 
 // Take screenshot of a macOS app
-screenshot_app({ bundleId: "com.apple.Safari" })
+mac_screenshot_app({ bundleId: "com.apple.Safari" })
 ```
 
 ## Troubleshooting