# @plaintest/mcp-connect

[![npm version](https://img.shields.io/npm/v/@plaintest/mcp-connect.svg)](https://www.npmjs.com/package/@plaintest/mcp-connect)
[![npm downloads](https://img.shields.io/npm/dm/@plaintest/mcp-connect.svg)](https://www.npmjs.com/package/@plaintest/mcp-connect)
[![npm downloads total](https://img.shields.io/npm/dt/@plaintest/mcp-connect.svg)](https://www.npmjs.com/package/@plaintest/mcp-connect)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub stars](https://img.shields.io/github/stars/plaintest/mcp-connect.svg?style=social)](https://github.com/plaintest/mcp-connect)
[![GitHub issues](https://img.shields.io/github/issues/plaintest/mcp-connect.svg)](https://github.com/plaintest/mcp-connect/issues)
[![Node.js Version](https://img.shields.io/node/v/@plaintest/mcp-connect.svg)](https://nodejs.org)

A Model Context Protocol (MCP) server that enables AI assistants to control iOS Simulators and automate browsers. Combines the power of `xcrun simctl`, `fb-idb`, and Puppeteer into a single unified server.

## Features

### iOS Simulator Tools
- **Screenshots**: Capture screenshots in various formats (PNG, JPEG, TIFF, BMP, GIF)
- **Device Management**: List simulators, get info about booted devices
- **Gestures**: Tap, swipe with duration control (requires fb-idb)
- **Input**: Type text into focused fields, press system buttons
- **Navigation**: Open URLs and deep links
- **UI Inspection**: Get accessibility tree (requires fb-idb)
- **Reset**: Erase simulator to factory settings

### Browser Automation Tools
- **Launch & Control**: Launch Chrome/Chromium, navigate to URLs
- **Screenshots**: Capture full page or element-specific screenshots
- **DOM Interaction**: Click elements, type text, query elements
- **Inspection**: Get DOM tree, element info, page info
- **JavaScript**: Execute arbitrary JavaScript in page context
- **Metro Bundler**: Quick shortcuts for React Native development

## Prerequisites

- **macOS** with Xcode and iOS Simulator
- **Node.js** >= 18
- **Chrome/Chromium** for browser automation
- **fb-idb** (optional, for enhanced iOS gestures)

## Installation

### Option 1: Quick Install (Recommended)

Run the installer for your MCP client:

```bash
# For Claude Code
npx @plaintest/mcp-connect install claude

# For Cursor
npx @plaintest/mcp-connect install cursor

# For Windsurf
npx @plaintest/mcp-connect install windsurf

# For Cline (VS Code)
npx @plaintest/mcp-connect install cline

# For GitHub Copilot (VS Code)
npx @plaintest/mcp-connect install copilot

# Install for all clients at once
npx @plaintest/mcp-connect install --all
```

Restart your editor and the tools will be available.

### Option 2: Global Install

Install globally to have `mcp-connect` available as a command:

```bash
npm install -g @plaintest/mcp-connect
```

Then configure your MCP client manually:

```json
{
  "mcpServers": {
    "mcp-connect": {
      "command": "mcp-connect"
    }
  }
}
```

### Option 3: Manual Configuration

If you prefer not to install globally, configure your MCP client to use npx:

```json
{
  "mcpServers": {
    "mcp-connect": {
      "command": "npx",
      "args": ["-y", "@plaintest/mcp-connect"]
    }
  }
}
```

**Config file locations:**
- **Claude Code**: Uses `claude mcp add` command (automatic with install)
- **Cursor**: `~/.cursor/mcp.json`
- **Windsurf**: `~/.codeium/windsurf/mcp_config.json`
- **Cline**: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
- **Copilot**: `~/Library/Application Support/Code/User/settings.json` (under `github.copilot.chat.experimental.mcp.servers`)

## CLI Commands

```bash
npx @plaintest/mcp-connect install <client>    # Install config for a client
npx @plaintest/mcp-connect uninstall <client>  # Remove config from a client
npx @plaintest/mcp-connect list                # List supported clients
npx @plaintest/mcp-connect status              # Show installation status
npx @plaintest/mcp-connect help                # Show help
```

## Tool Filtering

By default, mcp-connect auto-detects which tools to enable based on your system:
- **iOS Simulator tools**: enabled if Xcode/xcrun is installed
- **Browser tools**: enabled if Chrome/Chromium is found

This reduces context usage and prevents confusion by only exposing relevant tools.

### Override Auto-detection

To manually control which tools are enabled, use the `--only` flag:

```bash
npx @plaintest/mcp-connect --only=browser     # Browser tools only
npx @plaintest/mcp-connect --only=simulator   # iOS Simulator tools only
npx @plaintest/mcp-connect --only=all         # Force all tools
```

To use filtering with an MCP client, update your config:

```json
{
  "mcpServers": {
    "mcp-connect": {
      "command": "npx",
      "args": ["-y", "@plaintest/mcp-connect", "--only=browser"]
    }
  }
}
```

## Available Tools

### iOS Simulator Tools (10)

| Tool | Description |
|------|-------------|
| `capture_simulator_screenshot` | Capture screenshot with format/mask options |
| `list_simulators` | List all simulators (booted or all) |
| `get_simulator_info` | Get info about currently booted simulator |
| `tap_screen` | Tap at coordinates (x, y) |
| `swipe` | Swipe from (x1, y1) to (x2, y2) with duration |
| `simulator_type_text` | Type text into focused input field |
| `press_button` | Press system button (home, lock, siri, volume) |
| `open_url` | Open URL or deep link in simulator |
| `erase_simulator` | Reset simulator to factory settings |
| `get_ui_tree` | Get accessibility tree (requires fb-idb) |

### Browser Automation Tools (14)

| Tool | Description |
|------|-------------|
| `launch_browser` | Launch Chrome/Chromium instance |
| `navigate` | Navigate to URL |
| `capture_screenshot` | Capture page or element screenshot |
| `click_element` | Click element by CSS selector |
| `type_text` | Type into input field |
| `get_page_info` | Get URL, title, viewport info |
| `get_dom_tree` | Get HTML structure with depth control |
| `evaluate_javascript` | Execute JS in page context |
| `query_elements` | Find elements by CSS selector |
| `get_element_info` | Get element position, styles, content |
| `close_browser` | Close browser and cleanup |
| `open_metro_bundler` | Open React Native Metro bundler UI |
| `get_metro_logs` | Extract logs from Metro UI |
| `reload_metro` | Trigger Metro reload |

## Examples

### Take iOS Simulator Screenshot

```
AI: Use capture_simulator_screenshot to take a screenshot
```

### Navigate and Interact with Browser

```
AI: Launch browser and navigate to http://localhost:8081
AI: Click the element with selector ".reload-button"
AI: Capture a screenshot
```

### iOS Gesture Automation

```
AI: Tap the screen at coordinates (200, 400)
AI: Swipe from (200, 600) to (200, 200) over 0.3 seconds
AI: Type "Hello World" into the focused input
```

## Setup for Tap/Swipe Gestures

For `tap_screen` and `swipe` to work reliably, install fb-idb:

```bash
brew tap facebook/fb
brew install idb-companion
```

Without fb-idb:
- Tap falls back to AppleScript (less reliable)
- Swipe is not available

## Troubleshooting

### Chrome not found

Install Google Chrome or set a custom path:
- The server looks for Chrome at standard macOS locations
- Chromium and Chrome Canary are also supported

### Simulator not detected

1. Open Xcode > Open Developer Tool > Simulator
2. Boot a simulator
3. Verify: `xcrun simctl list devices booted`

### fb-idb not working

```bash
# Reinstall
brew uninstall idb-companion
brew tap facebook/fb
brew install idb-companion

# Verify
which idb
```

### Permission denied for gestures

Grant Accessibility permissions:
1. System Settings > Privacy & Security > Accessibility
2. Add Terminal (or your shell app)
3. Restart your editor

## Development

```bash
# Clone the repository
git clone https://github.com/plaintest/mcp-connect.git
cd mcp-connect

# Install dependencies
npm install

# Build
npm run build

# Run locally
node dist/index.js

# Watch mode
npm run dev
```

## License

MIT License - see [LICENSE](LICENSE) for details.

## Author

George Al-Haddad - [Plaintest](https://github.com/plaintest)