Krow-workspace/docs/research/marionette-spike-usage.md

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:

   dart pub global activate marionette_mcp
   

2. Add Marionette to Cursor — In .cursor/mcp.json or global config:

   {
     "mcpServers": {
       "marionette": {
         "command": "marionette_mcp",
         "args": []
       }
     }
   }
   

3. Run app in debug mode — The app must be running with VM Service:

   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.