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)

Tool	Description
start_session	Open browser, navigate to URL, return page snapshot with screenshot + Web Vitals + a11y score. Supports device emulation.
step	Execute an action (click, type, scroll, etc.) with smart selector fallback. Record persona thoughts and friction.
end_session	Close session, compute friction score and emotional arc, return full report (markdown or HTML).
get_page_state	Get current page state and screenshot without performing any action.

v0.3 Session Tools (new capabilities)

Tool	Description
accessibility_audit	Run WCAG 2.0 A/AA/AAA audit using axe-core. Returns score, violations, and fix links.
inspect_storage	Inspect cookies, localStorage, sessionStorage. Detects tracking cookies.
export_har	Export all network activity as HAR 1.2 log for analysis.
compare_screenshots	Pixel-level visual diff between two screenshots with overlay image.
create_persona	Build a custom persona with any trait combination.

Quick Tools (stateless)

Tool	Description
quick_scan	Fast single-page scan with screenshot and element extraction.
list_personas	Browse all 8 built-in personas with full trait definitions.
list_devices	Browse all 10 device emulation profiles.

Auto Tools (heuristic walker)

Tool	Description
auto_walk	Fast automated walk with heuristic navigation — no AI reasoning.
compare_personas_auto	Run 2-5 personas on the same URL and compare experiences.

8 Built-in Personas

Name	Description	Tech	Patience	Device
Alex	The First-Timer — never used SaaS before	Novice	Moderate	Mobile
Morgan	The Power User — developer, expects excellence	Expert	Low	Desktop
Patricia	The Senior Explorer — 68, low vision	Basic	High	Desktop
Jordan	The Busy Executive — 10 seconds to impress	Intermediate	Very Low	Mobile
Sam	The Accessibility Tester — screen reader user	Advanced	Moderate	Desktop
Riley	The Skeptical Evaluator — looking for red flags	Intermediate	Moderate	Desktop
Casey	The International User — potential language barriers	Basic	High	Mobile
Taylor	The Return Visitor — knows the app, wants efficiency	Advanced	Moderate	Desktop

10 Device Profiles

Key	Device	Viewport	Scale
iphone-14-pro	iPhone 14 Pro	393×852	3x
iphone-se	iPhone SE	375×667	2x
pixel-7	Pixel 7	412×915	2.625x
samsung-galaxy-s23	Galaxy S23	393×851	3x
galaxy-fold	Galaxy Fold	280×653	3x
ipad-pro-12-9	iPad Pro 12.9"	1024×1366	2x
ipad-mini	iPad Mini	768×1024	2x
macbook-pro-14	MacBook Pro 14"	1512×982	2x
desktop-1080p	Desktop 1080p	1920×1080	1x
desktop-1440p	Desktop 1440p	2560×1440	1x

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