# Marionette MCP Spike — Usage Guide

**Issue:** #533  
**Purpose:** Document how to run the Marionette MCP spike for auth flows.

## Prerequisites

1. **Marionette MCP server** — Install globally:
   ```bash
   dart pub global activate marionette_mcp
   ```

2. **Add Marionette to Cursor** — In `.cursor/mcp.json` or global config:
   ```json
   {
     "mcpServers": {
       "marionette": {
         "command": "marionette_mcp",
         "args": []
       }
     }
   }
   ```

3. **Run app in debug mode** — The app must be running with VM Service:
   ```bash
   cd apps/mobile && flutter run -d <device_id>
   ```

4. **Get VM Service URI** — From the `flutter run` output, copy the `ws://127.0.0.1:XXXX/ws` URI (often shown in the DevTools link).

## Spike flows (AI agent prompts)

Use these prompts with the Marionette MCP connected to the running app.

### Client — Login

> Connect to the app using the VM Service URI. Navigate to the Get Started screen, tap "Sign In", enter legendary@krowd.com and Demo2026!, then tap "Sign In". Verify we land on the home screen.

### Client — Sign up

> Connect to the app. Tap "Create Account", fill in Company, Email, Password (and confirm) with new credentials, then tap "Create Account". Verify we land on the home screen.

### Staff — Login

> Connect to the app. Tap "Log In", enter phone number 5557654321, tap "Send Code", enter OTP 123456, tap "Continue". Verify we reach the staff home screen.
> (Firebase test phone: +1 555-765-4321 / OTP 123456)

### Staff — Sign up

> Connect to the app. Tap "Sign Up", enter a NEW phone number (Firebase test phone), tap "Send Code", enter OTP, tap "Continue". Verify we reach Profile Setup or staff home.

## Limitations observed (from spike)

- **Debug only** — Marionette needs the Dart VM Service; does not work with release builds.
- **Non-deterministic** — LLM-driven actions can vary in behavior and timing.
- **Latency** — Each step involves API roundtrips (~45s+ for full flow vs ~5s for Maestro).
- **Best use** — Exploratory testing, live debugging, smoke checks during development.