mcp-baepsae: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

mcp-baepsae is a local MCP (Model Context Protocol) server for iOS Simulator and macOS app automation. It has two layers:

• TypeScript MCP layer (src/) — exposes 32 MCP tools, validates inputs via Zod, spawns child processes. Entry point is src/index.ts; tools are registered in src/tools/*.ts modules.
• Swift native bridge (native/) — a CLI binary (baepsae-native) that uses AppKit/CoreGraphics/Accessibility APIs for UI automation. Entry point is native/Sources/main.swift; command handlers are in native/Sources/Commands/*.swift.

The TS layer is the MCP surface; it delegates to either the native binary or xcrun simctl depending on the command.

Build & Test Commands

npm run build          # TypeScript (tsc) + Swift (release) build
npm run build:ts       # TypeScript only
npm run build:native   # Swift only: swift build --package-path native -c release
npm test               # Build + contract tests (no simulator needed)
npm run test:real      # Build + real simulator smoke tests (requires booted simulator)
npm run test:e2e       # Build sample app + real tests
npm run verify         # test + test:real

Single test file: node --test tests/mcp.contract.test.mjs

Architecture

TypeScript MCP layer (src/)

• src/index.ts — Entry point: --version flag, MCP server setup, imports and calls registerXxxTools() from each tool module
• src/types.ts — Shared TypeScript interfaces (ToolTextResult, CommandExecutionOptions, etc.)
• src/utils.ts — Shared utilities and constants:
  • resolveNativeBinary() — finds the native binary (env override BAEPSAE_NATIVE_PATH → bundled → release → debug fallback)
  • executeCommand() — process spawn with timeout, SIGINT→SIGTERM escalation, stdout/stderr capture
  • runNative() / runSimctl() — bridge MCP tools to native CLI or xcrun simctl
  • toToolResult() — normalizes output into { content: text[], isError: boolean } shape
• src/tools/ — Tool registration modules, each exports a registerXxxTools(server) function:
  • info.ts — baepsae_help, baepsae_version, list_apps, get_focused_app
  • simulator.ts — list_simulators, open_url, install_app, launch_app, terminate_app, uninstall_app
  • ui.ts — analyze_ui, query_ui, tap, type_text, swipe, scroll, drag_drop
  • input.ts — key, key_sequence, key_combo, button, touch, gesture
  • media.ts — stream_video, record_video, screenshot
  • system.ts — list_windows, activate_app, screenshot_app, right_click, menu_action, clipboard