Metadata-Version: 2.4
Name: watchr-mcp
Version: 0.2.0
Summary: iOS Simulator QA agent — MCP server for Claude Code
License: MIT
Requires-Python: <3.14,>=3.11
Requires-Dist: fb-idb>=1.1.7
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp[cli]>=1.2.0
Description-Content-Type: text/markdown

# Watchr — iOS QA Agent

AI-powered mobile app testing for iOS Simulator. Tell Claude Code what to test in plain English — it drives the simulator, finds bugs, checks accessibility, and catches crashes automatically.

## Install (one time)

```bash
# 1. Install idb-companion (needed to control the iOS Simulator)
brew install idb-companion

# 2. Add watchr to Claude Code
claude mcp add --scope user watchr -- uvx --python 3.12 --upgrade watchr-mcp
```

That's it. Two commands. No repo to clone, no paths to manage. `uvx` downloads everything automatically. The `--scope user` flag makes watchr available in every project.

> If you're missing anything, watchr will tell you exactly what to install when it starts.

## Usage

Go to your app's project directory, open Claude Code, and type:

```bash
cd ~/Projects/my-ios-app
claude
```

Then tell it what to test:

```
Boot the simulator, launch com.yourapp.bundleid, and test the sign-up flow
```

Claude Code will:
- Boot the simulator
- Launch your app
- Navigate the flow you described
- Take screenshots at each step
- Report any bugs, crashes, or issues it finds

> **Note:** Your simulator needs to be booted and your app installed on it. If not:
> ```bash
> xcrun simctl boot "iPhone 16 Pro"
> open -a Simulator
> xcrun simctl install booted /path/to/YourApp.app
> ```

## Example Prompts

```
"Test the sign-up flow end to end and report any bugs"

"Go to settings, verify all options are visible, check accessibility"

"Run monkey testing on the home screen for 30 seconds"

"Save a baseline screenshot of the landing page, then compare after my changes"

"Navigate to the payment screen and check if the app crashes"
```

## What It Can Do

| Capability | Description |
|-----------|-------------|
| **Navigate any flow** | Describe a user journey in English — it taps, swipes, types, and scrolls through it |
| **Crash Detection** | Checks if the app is still alive after every action, reads crash logs |
| **Accessibility Audit** | Finds missing labels, small touch targets, unlabeled buttons |
| **Visual Regression** | Saves golden screenshots, diffs against them to catch UI changes |
| **Performance Timing** | Measures screen load times, flags slow screens (>3s) |
| **Monkey Testing** | Random taps and swipes to find crashes scripted tests would miss |
| **Text Verification** | Asserts specific text is on screen, like Playwright's `expect` |

## Troubleshooting

| Problem | Fix |
|---------|-----|
| `idb` commands fail | Run `idb connect UDID` with your simulator's UDID from `xcrun simctl list` |
| MCP server won't start | Run `uvx watchr-mcp` in terminal to see errors |
| Screenshots are blank | Make sure the Simulator app is open and visible |
| "No booted simulator found" | Boot one with `xcrun simctl boot "iPhone 16 Pro"` |
| App not launching | Verify the bundle ID with `xcrun simctl listapps booted` |

## Update

Watchr updates automatically — `uvx` fetches the latest version from PyPI each time Claude Code starts the server.

To force an update:
```bash
uvx --upgrade watchr-mcp
```
