UserFlow MCP

Simulates real users navigating your app and delivers qualitative UX feedback. Built as an MCP server for Claude Code.

UserFlow puts itself in your user's shoes. It clicks through your app as different personas (a first-time user, a busy executive, a senior citizen, an accessibility-dependent user) and tells you where they'd get confused, frustrated, or give up. Now with auto-friction detection, Core Web Vitals, WCAG accessibility auditing, network monitoring, device emulation, and rich HTML reports with dev recommendations.

Free for Claude Pro users. No API keys, no external services. Just install and go.

Quick Start

# Install globally
npm install -g userflow-mcp

# Or use directly with npx
npx -y userflow-mcp

Add to Claude Code

In your Claude Code MCP settings:

{
  "mcpServers": {
    "userflow": {
      "command": "npx",
      "args": ["-y", "userflow-mcp"]
    }
  }
}

Then in Claude Code:

→ "Start a user flow session on https://myapp.com as Alex"
→ "Quick scan https://myapp.com"
→ "Run an accessibility audit on this page"
→ "Compare Alex and Morgan on https://myapp.com"

What You Get

Persona-Driven UX Feedback

Step 1: Landing Page (3.2s)
  🔍 curious
  > "Hmm, 'Supercharge your workflow' — but what does this product actually do?"
  ⚠️ MEDIUM: Value prop unclear — heading doesn't explain the product
     → Rewrite heading to describe what the product does, not how it makes you feel

Step 2: Signup (12.1s)
  😐 neutral
  > "Alright, let me sign up and see..."
  🛑 HIGH: Form asks for company size during signup — feels invasive
     → Remove non-essential fields from signup, ask later during onboarding

Auto-Friction Detection

Friction is automatically detected from page metrics on every step — no manual annotation needed:

• Performance: LCP > 2.5s, CLS > 0.1, FCP > 3s

• Accessibility: Critical/serious axe-core violations, score < 50

• Console: JS errors, uncaught exceptions

• Network: Failed requests, pages > 5MB transfer

• Content: Missing headings, 50+ interactive elements (cognitive overload), visible error messages

Core Web Vitals & Performance

| Metric | Value   | Rating |
|--------|---------|--------|
| LCP    | 1840ms  | 🟢 good |
| CLS    | 0.042   | 🟢 good |
| FCP    | 920ms   | — |
| TTFB   | 180ms   | — |
| Resources | 47 files (1,280KB) | — |

Accessibility (axe-core WCAG Audit)

Score: 82/100 | Violations: 5 (0 critical, 2 serious, 2 moderate, 1 minor)
| serious | [color-contrast] Insufficient contrast ratio | 12 nodes |
| serious | [image-alt] Missing alt text on images | 3 nodes |

Rich HTML Reports

The end_session tool generates standalone HTML reports with:

• Executive summary — key metrics at a glance (friction score, goal status, steps, time, pages, a11y score, JS errors, failed requests)

• Site-wide page dashboard — comparison table of all pages with LCP, CLS, a11y, requests, errors

• Emotional journey — color-coded chart with legend, tooltips, and plain English summary

• Step-by-step walkthrough — collapsible steps with embedded screenshots

• Aggregated accessibility — all WCAG violations across the session, sorted by impact, with axe-core help links

• Network overview — total requests, failures, transfer size, resource breakdown, slowest requests

• Dev recommendations — P0/P1/P2 prioritized fixes with code examples (LCP, CLS, contrast, labels, errors, cookies, headings)

• "Idiot summary" — plain English section explaining what's wrong the way a regular user would say it

• Print/PDF optimized — all steps expand, sidebar hides, sections avoid page breaks

14 Tools

Step-by-Step Session Tools (Claude drives the simulation)

v0.3 Session Tools (new capabilities)

Quick Tools (stateless)

Auto Tools (heuristic walker)

8 Built-in Personas

10 Device Profiles

How It Works

1. Puppeteer opens your URL in a real browser

2. Monitors attach before navigation — network requests, console messages, and performance observers start capturing immediately

3. The persona engine creates a user with specific traits (tech literacy, patience, goals, device)

4. Claude drives the simulation step-by-step using the step tool, with smart selector fallback (8 strategies: data-testid → id → aria-label → role-text → input-attr → link-href → text → CSS path)

5. At each step, the system collects:

   • Page snapshot — interactive elements, headings, forms, errors, screenshot

   • Core Web Vitals — LCP, CLS, INP, FCP, TTFB via PerformanceObserver

   • Network summary — request count, failures, transfer size, slow requests

   • Console errors — JS errors, warnings, uncaught exceptions

   • Accessibility — axe-core WCAG audit with violation details (on initial load)

   • Storage — cookies, localStorage, sessionStorage, tracking detection (on initial load)

6. The feedback generator compiles everything into a structured report with emotional journey, friction scores, Web Vitals, and recommendations

Architecture

src/
├── server.ts                  # MCP tool registrations (14 tools)
├── types.ts                   # Full type system (450+ lines)
├── personas/
│   ├── presets.ts             # 8 built-in personas
│   └── engine.ts              # Persona creation + resolution
├── session/
│   ├── types.ts               # LiveSession with monitors
│   └── session-manager.ts     # Session lifecycle + new audit methods
├── walker/
│   ├── flow-walker.ts         # Autonomous page traversal
│   ├── action-planner.ts      # Heuristic action decisions
│   └── session-recorder.ts    # Journey tracking
├── analysis/
│   ├── friction.ts            # Friction detection + scoring
│   ├── cognitive-load.ts      # Page complexity assessment
│   ├── clarity.ts             # CTA + value prop evaluation
│   └── emotional-arc.ts       # Sentiment tracking
├── feedback/
│   ├── generator.ts           # Markdown report (with Web Vitals, a11y, network)
│   ├── html-report.ts         # Rich standalone HTML report
│   ├── comparison.ts          # Multi-persona comparison
│   └── report.ts              # Legacy report utilities
└── utils/
    ├── browser.ts             # Puppeteer + CDP connection support
    ├── page-snapshot.ts       # Full page state extraction + v0.3 enrichment
    ├── actions.ts             # Action execution with smart selector fallback
    ├── selector-engine.ts     # 8-strategy smart selector generation
    ├── auto-friction.ts       # Auto-detect friction from page metrics
    ├── network-monitor.ts     # Request/response tracking + HAR export
    ├── console-monitor.ts     # Console message + page error capture
    ├── performance.ts         # Core Web Vitals via PerformanceObserver
    ├── accessibility.ts       # axe-core WCAG audit
    ├── device-profiles.ts     # 10 device emulation presets
    ├── storage-inspector.ts   # Cookie/localStorage inspection
    └── screenshot-diff.ts     # Pixel-level visual comparison

Requirements

• Node.js >= 18.0.0

• Google Chrome or Chromium installed

• Claude Code with MCP support

Development

git clone https://github.com/prembobby39-gif/userflow-mcp.git
cd userflow-mcp
npm install
npm run build     # compiles TypeScript to dist/
npm test          # 42 tests
npm start         # run the MCP server

Note for contributors: You must run npm run build after cloning — the dist/ directory is not committed to git. Requires Node.js >= 18 and Google Chrome installed.

Changelog

v0.3.1

• Auto-friction detection — automatically detects friction from page metrics (performance thresholds, a11y violations, console errors, network failures, layout issues, visible errors). Runs on every step and initial page load.

• Executive summary — key metrics at a glance in HTML reports

• Site-wide page dashboard — comparison table showing all pages side-by-side with LCP, CLS, a11y, violations, requests, errors

• Aggregated accessibility section — all violations across the session, sorted by impact, with axe-core help links

• Network overview — total requests, failures, transfer size, resource breakdown, slowest requests

• Dev recommendations — P0/P1/P2 prioritized actionable fixes with code examples

• "Idiot summary" — plain English section explaining what's wrong the way a regular user would say it

• Emotional journey improvements — color legend, descriptive tooltips, plain English summary

• Sidebar navigation — fixed left sidebar with jump links, highlights on scroll

• Collapsed steps — steps start collapsed with expand/collapse all buttons

• Screenshot compression — CSS max-height + object-fit for embedded screenshots

• Print/PDF optimization — all steps expand, sidebar hides, sections avoid page breaks

v0.3.0

• Smart selector engine with 8-strategy fallback chain

• Console capture (JS errors, warnings, uncaught exceptions)

• Network monitoring with HAR 1.2 export

• Accessibility auditing via axe-core (WCAG 2.0 A/AA/AAA)

• Core Web Vitals (LCP, CLS, INP, FCP, TTFB)

• Device emulation (10 profiles: iPhone, Pixel, iPad, Galaxy Fold, desktops)

• Cookie/localStorage/sessionStorage inspection with tracking detection

• Screenshot visual diffing via pixelmatch

• Rich standalone HTML reports with embedded screenshots

• Custom persona creation tool

• 6 new tools, 3 enhanced tools (14 total)

v0.2.1

• CDP connection support for testing logged-in sites (CHROME_CDP_URL, CHROME_WS_ENDPOINT)

v0.2.0

• Thin MCP architecture — Claude drives step-by-step simulation

• 8 built-in personas with full trait system

v0.1.0

• Initial release with autonomous heuristic walker

License

MIT — ARISTONE