mcp-baepsae 5.0.0 → 6.1.1

package/README-KR.md

@@ -53,13 +53,36 @@ Swift 네이티브 브리지(`baepsae-native`)는 iOS 시뮬레이터 및 macOS
 
 ## 권한
 
-**접근성(Accessibility) 권한이 필요합니다.** UI 조회/입력 자동화 도구(`sim_*` / `mac_*` 스코프 도구, 예: `sim_describe_ui`, `mac_tap`, `sim_right_click`)를 사용할 때 필수입니다.
+**접근성(Accessibility) 권한이 필요합니다.** UI 조회/입력 자동화 도구(예: `analyze_ui`, `tap`, `right_click`)를 사용할 때 필수입니다.
+
+중요한 점은, 보통 권한 대상이 **자동화 대상 앱**이 아니라 **automation host / runtime process** 쪽이라는 것입니다.
+
+### 보통 어떤 프로세스에 권한이 필요한가?
+
+- **네이티브 바이너리를 직접 실행하는 경우**
+  - 예: `baepsae-native ...`
+  - 보통 `baepsae-native` 바이너리 자체와, 이를 실행한 터미널/셸 앱이 관련됩니다
+- **Node / npx 런타임으로 실행하는 경우**
+  - 예: `node dist/index.js`, `npx -y mcp-baepsae@latest`
+  - 보통 런타임 프로세스(`node`)와, 이를 실행한 터미널 또는 MCP client 앱이 관련됩니다
+- **Desktop / CLI MCP client를 통해 실행하는 경우**
+  - 예: Claude Code, Codex CLI/Desktop, Gemini CLI
+  - launch path 에 따라 MCP client 앱, 터미널 host, runtime process 중 여러 항목이 관련될 수 있습니다
+
+### 권장 설정 순서
 
 1. **시스템 설정** > **개인정보 보호 및 보안** > **손쉬운 사용(Accessibility)** 로 이동합니다.
-2. 사용 중인 터미널/실행기(Terminal, iTerm2, VSCode, `node`, `openclaw`)를 허용합니다.
-3. 목록에 없으면 `+` 버튼으로 수동 추가합니다.
+2. 실제로 사용하는 터미널 또는 MCP client 앱을 허용합니다.
+3. 목록에 보이면 런타임 프로세스(`node`, `bun` 등)도 허용합니다.
+4. 네이티브 바이너리를 직접 실행하는 경우 `baepsae-native` 항목도 별도로 확인합니다.
+5. 목록에 없으면 `+` 버튼으로 수동 추가합니다.
+
+### 중요
+
+권한을 켠 뒤에도 macOS가 즉시 반영하지 않는 경우가 있습니다.  
+오류가 계속되면 `mcp-baepsae` 를 시작한 터미널, MCP client, 또는 runtime process 를 종료 후 다시 실행하세요.
 
-시뮬레이터 타깃에서 선택자 기반 액션(`sim_tap`/`sim_right_click`의 `id`/`label`)은 기본적으로 **앱 내부 콘텐츠**를 탐색합니다. Simulator 크롬/시스템 UI까지 포함하려면 `all: true`를 사용하세요.
+시뮬레이터 타깃에서 선택자 기반 액션(`tap`/`right_click`의 `id`/`label`)은 기본적으로 **앱 내부 콘텐츠**를 탐색합니다. Simulator 크롬/시스템 UI까지 포함하려면 `all: true`를 사용하세요.
 
 ## 설치
 
@@ -74,6 +97,8 @@ npm install -g mcp-baepsae
 ```
 
 > macOS에서는 설치 시 Swift 네이티브 바이너리가 자동 빌드됩니다. Swift가 없어도 simctl 기반 기능은 정상 작동합니다.
+>
+> UI 조회/입력 자동화를 바로 사용할 계획이라면, 실제로 서버를 실행할 터미널 / MCP client / runtime process 에 먼저 접근성 권한을 부여해두는 것이 좋습니다.
 
 ### 옵션 B) 소스에서 빌드
 
@@ -109,6 +134,8 @@ bash scripts/install.sh --tool all
 
 LLM 에이전트가 이 MCP 서버를 설정할 때 필요한 모든 정보입니다.
 
+> UI 자동화 도구를 사용하기 전에, 접근성 권한은 보통 **자동화 대상 앱**이 아니라 **host/runtime process** (`node`, terminal, MCP client) 에 필요하다는 점을 먼저 확인하세요.
+
 ### 빠른 시작 (한 줄)
 
 ```bash
@@ -167,6 +194,8 @@ codex mcp add baepsae -- npx -y mcp-baepsae@latest
 gemini mcp add --scope user --transport stdio baepsae npx -y mcp-baepsae@latest
 ```
 
+`npx` 경로에서는 보통 spawn된 `node` 런타임과, 이를 실행한 터미널 / MCP client 가 관련 권한 대상입니다.
+
 ### 로컬 빌드 사용
 
 ```bash
@@ -180,6 +209,9 @@ codex mcp add baepsae --env BAEPSAE_NATIVE_PATH=/ABS/PATH/native/.build/release/
 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` 를 직접 호출한다면 native binary 항목도 별도로 확인하세요.
+
 ## 프로젝트 구조
 
 - MCP 서버 진입점: `src/index.ts`
@@ -197,47 +229,44 @@ gemini mcp add --scope user --transport stdio -e BAEPSAE_NATIVE_PATH=/ABS/PATH/n
 npm run build       # TypeScript + Swift 네이티브 빌드
 npm test            # 계약/통합 테스트
 npm run test:real   # 실제 시뮬레이터 스모크 테스트 (부팅된 시뮬레이터 필요)
+npm run test:real:preflight  # 환경 진단만 출력
+npm run test:real:sim        # iOS 시뮬레이터 단계만 실행 (Phase 4 제외)
+npm run test:real:mac        # macOS Safari 단계만 실행
 npm run verify      # test + test:real
 npm run setup:mcp   # scripts/install.sh 실행 alias
 ```
 
 ## MCP 도구 구현 상태
 
-총 47개 도구가 end-to-end 구현 완료되었습니다.
+총 35개 도구가 end-to-end 구현 완료되었습니다.
 
-### 타깃 분리 스코프 도구 (30개, 권장)
+### 공식 공개 MCP 표면: unified generic tools
 
-시뮬레이터/맥 타깃 혼동을 줄이려면 아래 `sim_*` / `mac_*` 도구를 우선 사용하세요.
+공개 API 표면은 단일 스킴으로 정리되어 있으며, `sim_*` / `mac_*` 이름 대신 target 인자를 받는 unified generic tools 를 사용합니다.
 
-| 시뮬레이터 스코프 | macOS 스코프 |
+| 분류 | 도구 |
 |---|---|
-| `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` |
+| UI | `analyze_ui`, `query_ui`, `tap`, `tap_tab`, `type_text`, `swipe`, `scroll`, `drag_drop` |
+| Input | `key`, `key_sequence`, `key_combo`, `touch` |
+| Workflow | `run_steps` |
+| System | `list_windows`, `activate_app`, `screenshot_app`, `right_click` |
+| iOS 시뮬레이터 전용 | `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` |
 
-### iOS 시뮬레이터 전용 (11개)
+대상 라우팅은 인자로 명시합니다: simulator 는 `udid`, macOS 는 `bundleId` / `appName`.
 
-`list_simulators`, `screenshot`, `record_video`, `stream_video`, `open_url`, `install_app`, `launch_app`, `terminate_app`, `uninstall_app`, `button`, `gesture`
+### `type_text` 정책
 
-### macOS / 시스템 전용 (4개)
+`type_text`는 다음 입력 소스 중 정확히 하나만 받습니다: `text`, `stdinText`, `file`.
 
-`list_apps`, `menu_action`, `get_focused_app`, `clipboard`
+- `method: "auto"`는 다음처럼 해석됩니다.
+  - 시뮬레이터 대상: `paste`
+  - macOS 대상: `keyboard`
+- `method: "paste"`는 시뮬레이터 대상에서는 simulator pasteboard를, macOS 대상에서는 host clipboard를 잠시 바꿨다가 복원하는 경로를 사용합니다.
+- `method: "keyboard"`는 항상 문자 단위 타이핑을 사용합니다.
 
-### 유틸리티 (2개)
-
-`baepsae_help`, `baepsae_version`
+`paste`를 사용하면 시뮬레이터 대상은 host clipboard를 건드리지 않고 simulator pasteboard를 갱신하며, macOS 대상은 host clipboard를 잠시 덮어쓴 뒤 복원합니다. 성공 응답에는 입력 소스, 대상 종류, 요청한 method, 실제 사용한 method, paste transport, auto fallback이 함께 보고됩니다.
 
 ## 사용 예시
 
@@ -247,22 +276,39 @@ npm run setup:mcp   # scripts/install.sh 실행 alias
 launch_app({ udid: "...", bundleId: "com.example.app" })
 
 // 2) 접근성 트리 조회/검색 (기본: 앱 내부 콘텐츠 스코프)
-sim_describe_ui({ udid: "..." })
-sim_search_ui({ udid: "...", query: "로그인" })
+analyze_ui({ udid: "..." })
+query_ui({ udid: "...", query: "로그인" })
 
 // 3) 접근성 ID/라벨로 상호작용
-sim_tap({ udid: "...", id: "login-button" })
+tap({ udid: "...", id: "login-button" })
 
 // 선택: Simulator 크롬/시스템 UI까지 탐색하려면
-sim_tap({ udid: "...", label: "Home", all: true })
+tap({ udid: "...", label: "Home", all: true })
 ```
 
 ## 트러블슈팅
 
+### 접근성 권한 체크리스트
+
+- 권한 대상은 보통 **target app** 이 아니라 **automation host/runtime process** 입니다.
+- 먼저 `doctor` 를 실행해서 host process, parent process, native binary, booted simulator availability, accessibility readiness 를 한 번에 확인하세요.
+- 오류 메시지에서 다음 항목을 먼저 확인하세요.
+  - **current host process**
+  - **parent process**
+  - **inferred launch mode**
+- `npx` / `node` 경유 실행이라면 런타임과 이를 실행한 터미널 / MCP client 에 권한을 줍니다.
+- `baepsae-native` 직접 실행이라면 native binary 항목과 이를 실행한 터미널 / 셸 앱을 확인합니다.
+- 권한 변경 후에는 launching process 를 재시작한 뒤 다시 시도하세요.
+
 - Claude 설정 중 `Invalid environment variable format` 오류:
   - 최신 `scripts/install.sh`를 사용하거나 `--env="KEY=value"` 형식을 사용하세요.
 - `Missing native binary` 오류:
   - `npm run build` 실행 후 `native/.build/release/baepsae-native` 파일 존재 여부를 확인하세요.
+- 접근성 권한 오류가 모호한 경우:
+  - 현재 버전은 오류 메시지에 host / parent process 진단 정보와 inferred launch mode 를 함께 보여주므로 어떤 실행 파일에 권한을 줘야 할지 추적할 수 있습니다.
+- 실제 스모크 테스트 진단:
+  - `npm run test:real:preflight`로 전체 스위트를 돌리지 않고 환경/기능(capability) 진단만 출력할 수 있습니다.
+  - `npm run test:real:sim`으로 시뮬레이터 중심 범위만, `npm run test:real:mac`으로 macOS Safari 범위만 실행할 수 있습니다.
 - OpenCode에서 `baepsae`가 보이지 않는 경우:
   - `bash scripts/install.sh --tool opencode --skip-install --skip-build`를 다시 실행하고 `~/.config/opencode/opencode.json`을 확인하세요.
 - Copilot 자동 등록이 안 되는 경우:

package/README.md

@@ -53,13 +53,36 @@ The Swift native bridge (`baepsae-native`) uses macOS-specific frameworks (AppKi
 
 ## Permissions
 
-**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`).
+**Accessibility permission is required** for UI inspection and input automation features (use unified generic tools such as `analyze_ui`, `tap`, `right_click`).
+
+The important detail is that permission usually needs to be granted to the **automation host / runtime process**, not to the target app you are automating.
+
+### Which process usually needs permission?
+
+- **Direct native binary invocation**
+  - Example: `baepsae-native ...`
+  - Most relevant entry: the `baepsae-native` binary itself, plus the terminal/shell app that launched it
+- **Node / npx MCP runtime**
+  - Example: `node dist/index.js`, `npx -y mcp-baepsae@latest`
+  - Most relevant entry: the runtime process (`node`), plus the terminal or MCP client app that launched it
+- **Desktop / CLI MCP clients**
+  - Example: Claude Code, Codex CLI/Desktop, Gemini CLI
+  - Relevant entries can include the MCP client app, the terminal host, and the runtime process depending on launch path
+
+### Recommended setup flow
 
 1. Open **System Settings** > **Privacy & Security** > **Accessibility**.
-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.
+2. Enable the terminal or MCP client app you actually use.
+3. Enable the runtime process if listed (`node`, `bun`, etc.).
+4. For direct native invocation, also enable the `baepsae-native` binary entry if it appears separately.
+5. If an entry is missing, click `+` and add it manually.
+
+### Important note
+
+After granting permission, the launching process may need to be restarted before macOS applies the change.  
+If the error persists, quit and relaunch the terminal, MCP client, or runtime process that started `mcp-baepsae`.
 
-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.
+For 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.
 
 ## Install
 
@@ -74,6 +97,8 @@ npm install -g mcp-baepsae
 ```
 
 > On macOS, the Swift native binary is built automatically during install. If Swift is not available, the server still works with simctl-based features.
+>
+> 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.
 
 ### Option B) From source
 
@@ -109,6 +134,8 @@ bash scripts/install.sh --tool all
 
 If you are an LLM agent setting up this MCP server, here is everything you need:
 
+> 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.
+
 ### Quick start (one command)
 
 ```bash
@@ -167,6 +194,8 @@ codex mcp add baepsae -- npx -y mcp-baepsae@latest
 gemini mcp add --scope user --transport stdio baepsae npx -y mcp-baepsae@latest
 ```
 
+When using `npx`, the relevant Accessibility entry is commonly the spawned `node` runtime plus the terminal / MCP client that launched it.
+
 ### Using local build
 
 ```bash
@@ -180,6 +209,9 @@ codex mcp add baepsae --env BAEPSAE_NATIVE_PATH=/ABS/PATH/native/.build/release/
 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
 ```
 
+When using a local build, check permission on both the runtime (`node`) and the app that launched it.  
+If you invoke `baepsae-native` directly for debugging, check permission on the native binary entry itself as well.
+
 ## Project Structure
 
 - MCP server entry point: `src/index.ts`
@@ -197,64 +229,61 @@ gemini mcp add --scope user --transport stdio -e BAEPSAE_NATIVE_PATH=/ABS/PATH/n
 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 Tool Status
 
-47 tools implemented end-to-end.
+35 tools implemented end-to-end.
 
-### Explicit target-scoped tools (30, recommended)
+### Official public MCP surface: unified generic tools
 
-Use these first to avoid simulator/macOS target ambiguity.
+The public API surface is intentionally single-scheme: use unified generic tools with a target argument, rather than `sim_*` / `mac_*` names.
 
-| Simulator-scoped | macOS-scoped |
+| Category | Tools |
 |---|---|
-| `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` |
+| UI | `analyze_ui`, `query_ui`, `tap`, `tap_tab`, `type_text`, `swipe`, `scroll`, `drag_drop` |
+| Input | `key`, `key_sequence`, `key_combo`, `touch` |
+| Workflow | `run_steps` |
+| System | `list_windows`, `activate_app`, `screenshot_app`, `right_click` |
+| Simulator-only | `list_simulators`, `screenshot`, `record_video`, `stream_video`, `open_url`, `install_app`, `launch_app`, `terminate_app`, `uninstall_app`, `button`, `gesture` |
+| macOS/system | `list_apps`, `menu_action`, `get_focused_app`, `clipboard` |
+| Utility | `baepsae_help`, `baepsae_version`, `doctor` |
 
-### iOS Simulator Only (11)
+Target routing is explicit in the arguments: `udid` for simulator, `bundleId` / `appName` for macOS.
 
-`list_simulators`, `screenshot`, `record_video`, `stream_video`, `open_url`, `install_app`, `launch_app`, `terminate_app`, `uninstall_app`, `button`, `gesture`
+### `type_text` policy
 
-### macOS / System Only (4)
+`type_text` accepts exactly one input source: `text`, `stdinText`, or `file`.
 
-`list_apps`, `menu_action`, `get_focused_app`, `clipboard`
+- `method: "auto"` resolves to:
+  - `paste` for simulator targets
+  - `keyboard` for macOS targets
+- `method: "paste"` uses the simulator pasteboard for simulator targets and a temporary host clipboard replace/restore flow for macOS targets.
+- `method: "keyboard"` always types character-by-character.
 
-### Utility (2)
-
-`baepsae_help`, `baepsae_version`
+When `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.
 
 ## Usage Examples
 
-**Simulator app accessibility quickstart (inside app UI):**
+**Unified 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" })
+analyze_ui({ udid: "..." })
+query_ui({ udid: "...", query: "Login" })
 
 // 3) Interact by accessibility identifier/label
-sim_tap({ udid: "...", id: "login-button" })
+tap({ udid: "...", id: "login-button" })
 
 // Optional: include Simulator chrome/system UI in selector lookup
-sim_tap({ udid: "...", label: "Home", all: true })
+tap({ udid: "...", label: "Home", all: true })
 ```
 
 **Open a URL (iOS Simulator):**
@@ -281,15 +310,32 @@ terminate_app({ udid: "...", bundleId: "com.apple.mobilesafari" })
 list_apps({})
 
 // Take screenshot of a macOS app
-mac_screenshot_app({ bundleId: "com.apple.Safari" })
+screenshot_app({ bundleId: "com.apple.Safari" })
 ```
 
 ## Troubleshooting
 
+### Accessibility permission checklist
+
+- The permission target is usually the **automation host/runtime process**, not the target app.
+- Run `doctor` first to inspect host process, parent process, native binary, booted simulator availability, and accessibility readiness in one place.
+- Check the error message for:
+  - **current host process**
+  - **parent process**
+  - **inferred launch mode**
+- If you launched through `npx` / `node`, grant permission to the runtime and the launching terminal / MCP client.
+- If you launched `baepsae-native` directly, grant permission to the native binary entry and the launching terminal / shell app.
+- After changing permission, restart the launching process before retrying.
+
 - `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.
+- Accessibility permission error is ambiguous:
+  - 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.
+- Real smoke test diagnostics:
+  - Run `npm run test:real:preflight` to print environment and capability diagnostics without executing the full suite.
+  - Run `npm run test:real:sim` to focus on simulator-capability coverage, or `npm run test:real:mac` for the macOS Safari subset.
 - 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:

package/dist/backend.d.ts

@@ -0,0 +1,26 @@
+import type { CommandExecutionOptions, ResponseOptions, ToolTextResult } from "./types.js";
+export declare const BACKEND_KINDS: {
+    readonly SIMCTL: "simctl";
+    readonly NATIVE_ACCESSIBILITY: "native_accessibility";
+    readonly SIMULATOR_INPUT: "simulator_input";
+    readonly UTILITY_RUNTIME: "utility/runtime";
+};
+export type BackendKind = typeof BACKEND_KINDS[keyof typeof BACKEND_KINDS];
+export type BackendDomain = "simulator" | "accessibility" | "input" | "utility";
+export type BackendExecutorKind = "native" | "simctl";
+export interface BackendDescriptor {
+    kind: BackendKind;
+    domain: BackendDomain;
+    executorKind: BackendExecutorKind;
+    label: string;
+    summary: string;
+}
+type BackendExecutor = (args: string[], options?: CommandExecutionOptions, responseOptions?: ResponseOptions) => Promise<ToolTextResult>;
+export declare const BACKEND_DOMAIN_TO_KIND: Record<BackendDomain, BackendKind>;
+export declare const BACKENDS: Record<BackendKind, BackendDescriptor>;
+export declare const BACKEND_EXECUTORS: Record<BackendExecutorKind, BackendExecutor>;
+export declare function resolveBackendKind(domain: BackendDomain): BackendKind;
+export declare function getBackendDescriptor(domain: BackendDomain): BackendDescriptor;
+export declare function runBackend(domain: BackendDomain, args: string[], options?: CommandExecutionOptions, responseOptions?: ResponseOptions): Promise<ToolTextResult>;
+export {};
+//# sourceMappingURL=backend.d.ts.map

package/dist/backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE3F,eAAO,MAAM,aAAa;;;;;CAKhB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,OAAO,aAAa,CAAC,MAAM,OAAO,aAAa,CAAC,CAAC;AAC3E,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,eAAe,GAAG,OAAO,GAAG,SAAS,CAAC;AAChF,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEtD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,EAAE,aAAa,CAAC;IACtB,YAAY,EAAE,mBAAmB,CAAC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,KAAK,eAAe,GAAG,CACrB,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE,uBAAuB,EACjC,eAAe,CAAC,EAAE,eAAe,KAC9B,OAAO,CAAC,cAAc,CAAC,CAAC;AAE7B,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,aAAa,EAAE,WAAW,CAKrE,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,WAAW,EAAE,iBAAiB,CA6B3D,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,mBAAmB,EAAE,eAAe,CAG1E,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,aAAa,GAAG,WAAW,CAErE;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,aAAa,GAAG,iBAAiB,CAE7E;AAWD,wBAAsB,UAAU,CAC9B,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE,uBAAuB,EACjC,eAAe,CAAC,EAAE,eAAe,GAChC,OAAO,CAAC,cAAc,CAAC,CAUzB"}

package/dist/backend.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BACKEND_EXECUTORS = exports.BACKENDS = exports.BACKEND_DOMAIN_TO_KIND = exports.BACKEND_KINDS = void 0;
+exports.resolveBackendKind = resolveBackendKind;
+exports.getBackendDescriptor = getBackendDescriptor;
+exports.runBackend = runBackend;
+const utils_js_1 = require("./utils.js");
+exports.BACKEND_KINDS = {
+    SIMCTL: "simctl",
+    NATIVE_ACCESSIBILITY: "native_accessibility",
+    SIMULATOR_INPUT: "simulator_input",
+    UTILITY_RUNTIME: "utility/runtime",
+};
+exports.BACKEND_DOMAIN_TO_KIND = {
+    simulator: exports.BACKEND_KINDS.SIMCTL,
+    accessibility: exports.BACKEND_KINDS.NATIVE_ACCESSIBILITY,
+    input: exports.BACKEND_KINDS.SIMULATOR_INPUT,
+    utility: exports.BACKEND_KINDS.UTILITY_RUNTIME,
+};
+exports.BACKENDS = {
+    [exports.BACKEND_KINDS.SIMCTL]: {
+        kind: exports.BACKEND_KINDS.SIMCTL,
+        domain: "simulator",
+        executorKind: "simctl",
+        label: "simctl",
+        summary: "Direct simulator control via xcrun simctl.",
+    },
+    [exports.BACKEND_KINDS.NATIVE_ACCESSIBILITY]: {
+        kind: exports.BACKEND_KINDS.NATIVE_ACCESSIBILITY,
+        domain: "accessibility",
+        executorKind: "native",
+        label: "native accessibility",
+        summary: "Native accessibility and UI inspection commands.",
+    },
+    [exports.BACKEND_KINDS.SIMULATOR_INPUT]: {
+        kind: exports.BACKEND_KINDS.SIMULATOR_INPUT,
+        domain: "input",
+        executorKind: "native",
+        label: "simulator input",
+        summary: "Native simulator input and HID-style interaction commands.",
+    },
+    [exports.BACKEND_KINDS.UTILITY_RUNTIME]: {
+        kind: exports.BACKEND_KINDS.UTILITY_RUNTIME,
+        domain: "utility",
+        executorKind: "native",
+        label: "utility/runtime",
+        summary: "Native utility and runtime shim commands.",
+    },
+};
+exports.BACKEND_EXECUTORS = {
+    native: utils_js_1.runNative,
+    simctl: utils_js_1.runSimctl,
+};
+function resolveBackendKind(domain) {
+    return exports.BACKEND_DOMAIN_TO_KIND[domain];
+}
+function getBackendDescriptor(domain) {
+    return exports.BACKENDS[resolveBackendKind(domain)];
+}
+function backendMetadata(descriptor) {
+    return {
+        backendDomain: descriptor.domain,
+        backendKind: descriptor.kind,
+        backendExecutor: descriptor.executorKind,
+        backendLabel: descriptor.label,
+    };
+}
+async function runBackend(domain, args, options, responseOptions) {
+    const descriptor = getBackendDescriptor(domain);
+    const executor = exports.BACKEND_EXECUTORS[descriptor.executorKind];
+    return await executor(args, options, {
+        ...responseOptions,
+        metadata: {
+            ...(responseOptions?.metadata ?? {}),
+            ...backendMetadata(descriptor),
+        },
+    });
+}
+//# sourceMappingURL=backend.js.map

package/dist/backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":";;;AAuEA,gDAEC;AAED,oDAEC;AAWD,gCAeC;AAvGD,yCAAkD;AAGrC,QAAA,aAAa,GAAG;IAC3B,MAAM,EAAE,QAAQ;IAChB,oBAAoB,EAAE,sBAAsB;IAC5C,eAAe,EAAE,iBAAiB;IAClC,eAAe,EAAE,iBAAiB;CAC1B,CAAC;AAoBE,QAAA,sBAAsB,GAAuC;IACxE,SAAS,EAAE,qBAAa,CAAC,MAAM;IAC/B,aAAa,EAAE,qBAAa,CAAC,oBAAoB;IACjD,KAAK,EAAE,qBAAa,CAAC,eAAe;IACpC,OAAO,EAAE,qBAAa,CAAC,eAAe;CACvC,CAAC;AAEW,QAAA,QAAQ,GAA2C;IAC9D,CAAC,qBAAa,CAAC,MAAM,CAAC,EAAE;QACtB,IAAI,EAAE,qBAAa,CAAC,MAAM;QAC1B,MAAM,EAAE,WAAW;QACnB,YAAY,EAAE,QAAQ;QACtB,KAAK,EAAE,QAAQ;QACf,OAAO,EAAE,4CAA4C;KACtD;IACD,CAAC,qBAAa,CAAC,oBAAoB,CAAC,EAAE;QACpC,IAAI,EAAE,qBAAa,CAAC,oBAAoB;QACxC,MAAM,EAAE,eAAe;QACvB,YAAY,EAAE,QAAQ;QACtB,KAAK,EAAE,sBAAsB;QAC7B,OAAO,EAAE,kDAAkD;KAC5D;IACD,CAAC,qBAAa,CAAC,eAAe,CAAC,EAAE;QAC/B,IAAI,EAAE,qBAAa,CAAC,eAAe;QACnC,MAAM,EAAE,OAAO;QACf,YAAY,EAAE,QAAQ;QACtB,KAAK,EAAE,iBAAiB;QACxB,OAAO,EAAE,4DAA4D;KACtE;IACD,CAAC,qBAAa,CAAC,eAAe,CAAC,EAAE;QAC/B,IAAI,EAAE,qBAAa,CAAC,eAAe;QACnC,MAAM,EAAE,SAAS;QACjB,YAAY,EAAE,QAAQ;QACtB,KAAK,EAAE,iBAAiB;QACxB,OAAO,EAAE,2CAA2C;KACrD;CACF,CAAC;AAEW,QAAA,iBAAiB,GAAiD;IAC7E,MAAM,EAAE,oBAAS;IACjB,MAAM,EAAE,oBAAS;CAClB,CAAC;AAEF,SAAgB,kBAAkB,CAAC,MAAqB;IACtD,OAAO,8BAAsB,CAAC,MAAM,CAAC,CAAC;AACxC,CAAC;AAED,SAAgB,oBAAoB,CAAC,MAAqB;IACxD,OAAO,gBAAQ,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED,SAAS,eAAe,CAAC,UAA6B;IACpD,OAAO;QACL,aAAa,EAAE,UAAU,CAAC,MAAM;QAChC,WAAW,EAAE,UAAU,CAAC,IAAI;QAC5B,eAAe,EAAE,UAAU,CAAC,YAAY;QACxC,YAAY,EAAE,UAAU,CAAC,KAAK;KAC/B,CAAC;AACJ,CAAC;AAEM,KAAK,UAAU,UAAU,CAC9B,MAAqB,EACrB,IAAc,EACd,OAAiC,EACjC,eAAiC;IAEjC,MAAM,UAAU,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAChD,MAAM,QAAQ,GAAG,yBAAiB,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;IAC5D,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE;QACnC,GAAG,eAAe;QAClB,QAAQ,EAAE;YACR,GAAG,CAAC,eAAe,EAAE,QAAQ,IAAI,EAAE,CAAC;YACpC,GAAG,eAAe,CAAC,UAAU,CAAC;SAC/B;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/index.js

@@ -12,7 +12,7 @@ if (hasVersionFlag(process.argv)) {
     process.exit(0);
 }
 async function main() {
-    const [{ McpServer }, { StdioServerTransport }, { SERVER_NAME, SERVER_VERSION }, { registerInfoTools }, { registerSimulatorTools }, { registerUITools }, { registerInputTools }, { registerMediaTools }, { registerSystemTools }] = await Promise.all([
+    const [{ McpServer }, { StdioServerTransport }, { SERVER_NAME, SERVER_VERSION }, { registerInfoTools }, { registerSimulatorTools }, { registerUITools }, { registerInputTools }, { registerWorkflowTools }, { registerMediaTools }, { registerSystemTools }] = await Promise.all([
         import("@modelcontextprotocol/sdk/server/mcp.js"),
         import("@modelcontextprotocol/sdk/server/stdio.js"),
         import("./utils.js"),
@@ -20,6 +20,7 @@ async function main() {
         import("./tools/simulator.js"),
         import("./tools/ui.js"),
         import("./tools/input.js"),
+        import("./tools/workflow.js"),
         import("./tools/media.js"),
         import("./tools/system.js"),
     ]);
@@ -31,6 +32,7 @@ async function main() {
     registerSimulatorTools(server);
     registerUITools(server);
     registerInputTools(server);
+    registerWorkflowTools(server);
     registerMediaTools(server);
     registerSystemTools(server);
     const transport = new StdioServerTransport();

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAIA,6CAA6D;AAE7D,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC;AAEvD,SAAS,cAAc,CAAC,IAAc;IACpC,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;AACxD,CAAC;AAED,oFAAoF;AACpF,IAAI,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;IACjC,OAAO,CAAC,GAAG,CAAC,GAAG,yBAAY,IAAI,4BAAe,EAAE,CAAC,CAAC;IAClD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,oBAAoB,EAAE,EAAE,EAAE,WAAW,EAAE,cAAc,EAAE,EAAE,EAAE,iBAAiB,EAAE,EAAE,EAAE,sBAAsB,EAAE,EAAE,EAAE,eAAe,EAAE,EAAE,EAAE,kBAAkB,EAAE,EAAE,EAAE,kBAAkB,EAAE,EAAE,EAAE,mBAAmB,EAAE,CAAC,GAC/N,MAAM,OAAO,CAAC,GAAG,CAAC;QAChB,MAAM,CAAC,yCAAyC,CAAC;QACjD,MAAM,CAAC,2CAA2C,CAAC;QACnD,MAAM,CAAC,YAAY,CAAC;QACpB,MAAM,CAAC,iBAAiB,CAAC;QACzB,MAAM,CAAC,sBAAsB,CAAC;QAC9B,MAAM,CAAC,eAAe,CAAC;QACvB,MAAM,CAAC,kBAAkB,CAAC;QAC1B,MAAM,CAAC,kBAAkB,CAAC;QAC1B,MAAM,CAAC,mBAAmB,CAAC;KAC5B,CAAC,CAAC;IAEL,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,cAAc;KACxB,CAA6B,CAAC;IAE/B,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAC1B,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAC/B,eAAe,CAAC,MAAM,CAAC,CAAC;IACxB,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3B,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3B,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAE5B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,qCAAqC,EAAE,KAAK,CAAC,CAAC;IAC5D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAIA,6CAA6D;AAE7D,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC;AAEvD,SAAS,cAAc,CAAC,IAAc;IACpC,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;AACxD,CAAC;AAED,oFAAoF;AACpF,IAAI,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;IACjC,OAAO,CAAC,GAAG,CAAC,GAAG,yBAAY,IAAI,4BAAe,EAAE,CAAC,CAAC;IAClD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,oBAAoB,EAAE,EAAE,EAAE,WAAW,EAAE,cAAc,EAAE,EAAE,EAAE,iBAAiB,EAAE,EAAE,EAAE,sBAAsB,EAAE,EAAE,EAAE,eAAe,EAAE,EAAE,EAAE,kBAAkB,EAAE,EAAE,EAAE,qBAAqB,EAAE,EAAE,EAAE,kBAAkB,EAAE,EAAE,EAAE,mBAAmB,EAAE,CAAC,GAC1P,MAAM,OAAO,CAAC,GAAG,CAAC;QAChB,MAAM,CAAC,yCAAyC,CAAC;QACjD,MAAM,CAAC,2CAA2C,CAAC;QACnD,MAAM,CAAC,YAAY,CAAC;QACpB,MAAM,CAAC,iBAAiB,CAAC;QACzB,MAAM,CAAC,sBAAsB,CAAC;QAC9B,MAAM,CAAC,eAAe,CAAC;QACvB,MAAM,CAAC,kBAAkB,CAAC;QAC1B,MAAM,CAAC,qBAAqB,CAAC;QAC7B,MAAM,CAAC,kBAAkB,CAAC;QAC1B,MAAM,CAAC,mBAAmB,CAAC;KAC5B,CAAC,CAAC;IAEL,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,cAAc;KACxB,CAA6B,CAAC;IAE/B,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAC1B,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAC/B,eAAe,CAAC,MAAM,CAAC,CAAC;IACxB,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3B,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC9B,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3B,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAE5B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,qCAAqC,EAAE,KAAK,CAAC,CAAC;IAC5D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/tool-manifest.d.ts

@@ -0,0 +1,12 @@
+export type ToolCategory = "UI" | "Input" | "Workflow" | "System" | "Simulator-only" | "macOS/system" | "Utility";
+export type ToolManifestEntry = {
+    name: string;
+    category: ToolCategory;
+    summary: string;
+};
+export declare const TOOL_MANIFEST: ToolManifestEntry[];
+export declare const TOOL_CATEGORY_ORDER: ToolCategory[];
+export declare const TOOL_CATEGORY_LABELS_KR: Record<ToolCategory, string>;
+export declare function formatToolManifestMarkdown(): string;
+export declare function formatToolManifestMarkdownKr(): string;
+//# sourceMappingURL=tool-manifest.d.ts.map

package/dist/tool-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-manifest.d.ts","sourceRoot":"","sources":["../src/tool-manifest.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GACpB,IAAI,GACJ,OAAO,GACP,UAAU,GACV,QAAQ,GACR,gBAAgB,GAChB,cAAc,GACd,SAAS,CAAC;AAEd,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,YAAY,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,iBAAiB,EA0C5C,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,YAAY,EAQ7C,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAQhE,CAAC;AAEF,wBAAgB,0BAA0B,IAAI,MAAM,CAQnD;AAED,wBAAgB,4BAA4B,IAAI,MAAM,CAQrD"}