# 👻 phantom-touch

> An MCP server for iOS simulator automation — with clipboard-based text input that works with React Native.

**phantom-touch** gives AI agents full control over iOS simulators: screenshots, element inspection, gestures, app management, and most importantly — **reliable text input into React Native forms**.

## Quick Start

### Claude Desktop / Cursor

Add to your MCP configuration:

```json
{
  "mcpServers": {
    "phantom-touch": {
      "command": "npx",
      "args": ["-y", "phantom-touch"]
    }
  }
}
```

That's it. No cloning, no building — just `npx`.

## The Problem

Every existing iOS MCP tool fails at filling React Native `TextInput` components because:
- HID keyboard events don't trigger `onChangeText`
- WebDriverAgent `setValue` gets overwritten by React state

## The Solution

`phantom-touch` uses a **clipboard + paste** strategy:
1. `simctl pbcopy` → set simulator clipboard
2. `idb tap` → focus the field
3. `Cmd+V` → paste triggers `onChangeText` ✅

## 16 MCP Tools

| Module | Tools |
|--------|-------|
| **Simulator** | `pt_list_simulators`, `pt_boot_simulator`, `pt_shutdown_simulator` |
| **App** | `pt_launch_app`, `pt_terminate_app`, `pt_list_apps`, `pt_open_url` |
| **Screen** | `pt_screenshot`, `pt_list_elements`, `pt_get_screen_size` |
| **Gesture** | `pt_tap`, `pt_swipe` |
| **Input** ⭐ | `pt_type_text`, `pt_press_button`, `pt_set_clipboard`, `pt_get_clipboard` |

## Prerequisites

- macOS with Xcode installed
- iOS Simulator
- [IDB](https://fbidb.io/) (iOS Development Bridge): `brew install idb-companion`
- Node.js 18+

## Usage Examples

Once configured, ask your AI agent:

- *"Take a screenshot of the simulator"*
- *"List all UI elements on screen"*
- *"Tap the Create Account button at (200, 500)"*
- *"Type 'hello@example.com' into the email field at (200, 450)"*
- *"Open the deep link myapp://login"*

## Text Input Strategies

### `paste` (default, recommended)
Uses clipboard + Cmd+V. Works with React Native controlled TextInput.

```
pt_type_text(text: "Hello", x: 200, y: 400, strategy: "paste")
```

### `keyboard`
Uses HID keyboard events. Faster but may fail with React Native.

```
pt_type_text(text: "Hello", x: 200, y: 400, strategy: "keyboard")
```

## Development

```bash
git clone https://github.com/hieudtr8/phantom-touch.git
cd phantom-touch
npm install
npm run build
npm run dev   # Run in dev mode with tsx
```

## License

MIT