userflow-mcp 0.2.0

package/dist/walker/action-planner.js

@@ -0,0 +1,236 @@
+import { getDiscoveryProbability } from "../personas/engine.js";
+import { randomUUID } from "node:crypto";
+/**
+ * Score how relevant an element is to the persona's goals.
+ * Returns 0-100 relevance score.
+ */
+function scoreElementRelevance(element, goals) {
+    const elementText = `${element.text} ${element.ariaLabel ?? ""} ${element.placeholder ?? ""} ${element.href ?? ""}`.toLowerCase();
+    let score = 0;
+    for (const goal of goals) {
+        const goalWords = goal.toLowerCase().split(/\s+/);
+        for (const word of goalWords) {
+            if (word.length > 2 && elementText.includes(word)) {
+                score += 20;
+            }
+        }
+    }
+    // Boost for common action patterns
+    const ctaPatterns = ["sign up", "get started", "try", "start", "create", "login", "log in", "register", "submit", "continue", "next", "buy", "purchase", "subscribe", "pricing", "plans"];
+    for (const pattern of ctaPatterns) {
+        if (elementText.includes(pattern)) {
+            score += 15;
+            break;
+        }
+    }
+    // Boost for prominent elements (buttons > links)
+    if (element.tagName === "button" || element.type === "submit")
+        score += 10;
+    if (element.tagName === "a" && element.href)
+        score += 5;
+    return Math.min(100, score);
+}
+/**
+ * Determine what emotional state this persona would feel on this page.
+ */
+export function assessEmotion(persona, page, previousSteps, frictionPoints) {
+    const stepCount = previousSteps.length;
+    const recentFriction = frictionPoints.filter((f) => f.severity === "high" || f.severity === "critical");
+    const prevEmotion = previousSteps[previousSteps.length - 1]?.emotionalState ?? "curious";
+    // First page — usually curious
+    if (stepCount === 0)
+        return "curious";
+    // High friction → frustrated or confused
+    if (recentFriction.length >= 2)
+        return "frustrated";
+    if (recentFriction.length === 1)
+        return "confused";
+    // Error messages on page → anxious
+    if (page.errorMessages.length > 0)
+        return "anxious";
+    // Too many steps without progress → bored or frustrated
+    const patienceMap = { very_low: 3, low: 5, moderate: 8, high: 12, very_high: 18 };
+    const patienceThreshold = patienceMap[persona.traits.patience] ?? 8;
+    if (stepCount > patienceThreshold * 0.7)
+        return "frustrated";
+    if (stepCount > patienceThreshold * 0.5)
+        return "bored";
+    // Page loads fast and has clear content → confident
+    if (page.loadTimeMs < 2000 && page.headings.length > 0 && page.buttons.length > 0)
+        return "confident";
+    // Default: carry forward or neutral
+    if (prevEmotion === "frustrated" && recentFriction.length === 0)
+        return "neutral";
+    return prevEmotion === "curious" ? "neutral" : prevEmotion;
+}
+/**
+ * Detect friction points on the current page for this persona.
+ */
+export function detectFriction(persona, page, stepIndex) {
+    const frictionPoints = [];
+    const createFriction = (severity, description, suggestion) => {
+        frictionPoints.push({
+            id: randomUUID(),
+            severity,
+            description,
+            location: page.url,
+            suggestion,
+            stepIndex,
+        });
+    };
+    // Slow load time
+    if (page.loadTimeMs > 5000) {
+        createFriction("high", `Page took ${(page.loadTimeMs / 1000).toFixed(1)}s to load`, "Optimize page load performance — aim for under 3 seconds");
+    }
+    else if (page.loadTimeMs > 3000) {
+        createFriction("medium", `Page took ${(page.loadTimeMs / 1000).toFixed(1)}s to load`, "Consider lazy loading or code splitting to improve load time");
+    }
+    // No clear headings
+    if (page.headings.length === 0) {
+        createFriction("medium", "No headings found — page purpose is unclear", "Add a clear H1 heading that explains what this page is about");
+    }
+    // Too many interactive elements (cognitive overload)
+    const interactiveCount = page.interactiveElements.length;
+    if (interactiveCount > 20 && persona.traits.techLiteracy === "novice") {
+        createFriction("high", `Page has ${interactiveCount} interactive elements — overwhelming for this user`, "Simplify the page or use progressive disclosure to reduce cognitive load");
+    }
+    else if (interactiveCount > 30) {
+        createFriction("medium", `Page has ${interactiveCount} interactive elements — high cognitive load`, "Consider grouping related actions or using progressive disclosure");
+    }
+    // Error messages visible
+    if (page.errorMessages.length > 0) {
+        createFriction("high", `Error messages visible: "${page.errorMessages[0]}"`, "Ensure error messages are clear, actionable, and help the user recover");
+    }
+    // Too many form fields at once
+    if (page.formFields.length > 6 && persona.traits.patience !== "very_high") {
+        createFriction("high", `Form has ${page.formFields.length} fields — likely to cause abandonment`, "Break the form into smaller steps or make non-essential fields optional");
+    }
+    else if (page.formFields.length > 4) {
+        createFriction("low", `Form has ${page.formFields.length} fields`, "Consider which fields are truly required at this stage");
+    }
+    // No clear CTA
+    if (page.buttons.length === 0 && page.links.length > 0) {
+        createFriction("medium", "No buttons found — unclear what action to take", "Add a prominent call-to-action button");
+    }
+    // Empty state (no content)
+    if (page.mainText.trim().length < 50 && page.buttons.length === 0 && page.links.length < 3) {
+        createFriction("critical", "Page appears empty — no guidance for the user", "Add an empty state with clear next steps or a getting-started guide");
+    }
+    // Accessibility friction for users with needs
+    if (persona.traits.accessibilityNeeds.includes("screen_reader")) {
+        const unlabeledButtons = page.buttons.filter((b) => !b.ariaLabel && !b.text.trim());
+        if (unlabeledButtons.length > 0) {
+            createFriction("critical", `${unlabeledButtons.length} buttons have no accessible label`, "Add aria-label or visible text to all interactive elements");
+        }
+        const unlabeledInputs = page.formFields.filter((f) => !f.ariaLabel && !f.placeholder);
+        if (unlabeledInputs.length > 0) {
+            createFriction("high", `${unlabeledInputs.length} form fields have no label or placeholder`, "Add labels to all form fields for screen reader accessibility");
+        }
+    }
+    if (persona.traits.accessibilityNeeds.includes("low_vision") && page.formFields.length > 0) {
+        createFriction("low", "Verify form field labels have sufficient size and contrast for low-vision users", "Ensure text is at least 16px and has 4.5:1 contrast ratio");
+    }
+    return frictionPoints;
+}
+/**
+ * Plan the next action for a persona on the current page.
+ * Uses heuristic scoring based on persona goals and traits.
+ */
+export function planNextAction(persona, page, previousSteps) {
+    const discoveryProb = getDiscoveryProbability(persona);
+    const stepCount = previousSteps.length;
+    // If this is the first step, the action is just "read" — absorb the page
+    if (stepCount === 0) {
+        return {
+            type: "read",
+            reasoning: `${persona.name} is seeing this page for the first time and taking a moment to understand what it is.`,
+        };
+    }
+    // Check if we're stuck in a loop (same URL visited 3+ times)
+    const recentUrls = previousSteps.slice(-5).map((s) => s.page.url);
+    const currentUrlCount = recentUrls.filter((u) => u === page.url).length;
+    if (currentUrlCount >= 2) {
+        return {
+            type: "give_up",
+            reasoning: `${persona.name} is going in circles and getting frustrated — they've been on this same page multiple times.`,
+        };
+    }
+    // Score all interactive elements
+    const allElements = [...page.buttons, ...page.links, ...page.formFields];
+    const scoredElements = allElements
+        .filter((el) => el.isVisible)
+        .map((el) => ({
+        element: el,
+        score: scoreElementRelevance(el, persona.goals),
+    }))
+        .sort((a, b) => b.score - a.score);
+    // Apply discovery probability — low-tech users may not find non-obvious elements
+    const discoverable = scoredElements.filter((item) => {
+        if (item.score > 30)
+            return true; // Obvious elements always found
+        return Math.random() < discoveryProb;
+    });
+    // If there are form fields, try to fill them (users expect to fill forms)
+    const emptyFormField = page.formFields.find((f) => f.isVisible);
+    if (emptyFormField && page.formFields.length <= 6) {
+        const fieldType = emptyFormField.type ?? "text";
+        const fillValue = generateFieldValue(fieldType, emptyFormField.placeholder);
+        return {
+            type: "type",
+            target: emptyFormField.selector,
+            value: fillValue,
+            reasoning: `${persona.name} sees a form field (${emptyFormField.placeholder ?? emptyFormField.ariaLabel ?? fieldType}) and fills it in.`,
+        };
+    }
+    // Click the highest-scored discoverable element
+    if (discoverable.length > 0) {
+        const bestMatch = discoverable[0];
+        const elementDesc = bestMatch.element.text || bestMatch.element.ariaLabel || bestMatch.element.selector;
+        return {
+            type: "click",
+            target: bestMatch.element.selector,
+            reasoning: `${persona.name} clicks "${elementDesc}" — it looks like the most relevant action for their goal.`,
+        };
+    }
+    // Nothing relevant found — scroll to discover more
+    if (stepCount < 3) {
+        return {
+            type: "scroll",
+            reasoning: `${persona.name} doesn't see anything obvious to do, so they scroll down to see more content.`,
+        };
+    }
+    // Give up
+    return {
+        type: "give_up",
+        reasoning: `${persona.name} can't figure out what to do next and gives up. The page doesn't provide clear guidance.`,
+    };
+}
+/**
+ * Generate a plausible fill value for a form field type.
+ */
+function generateFieldValue(fieldType, placeholder) {
+    const typeValues = {
+        email: "testuser@example.com",
+        password: "SecurePass123!",
+        tel: "555-0123",
+        number: "42",
+        url: "https://example.com",
+        search: "test search",
+        text: "Test User",
+    };
+    if (placeholder) {
+        const lower = placeholder.toLowerCase();
+        if (lower.includes("name"))
+            return "Alex Johnson";
+        if (lower.includes("email"))
+            return "testuser@example.com";
+        if (lower.includes("phone"))
+            return "555-0123";
+        if (lower.includes("company") || lower.includes("organization"))
+            return "Acme Corp";
+        if (lower.includes("url") || lower.includes("website"))
+            return "https://example.com";
+    }
+    return typeValues[fieldType] ?? "test input";
+}
+//# sourceMappingURL=action-planner.js.map

package/dist/walker/action-planner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-planner.js","sourceRoot":"","sources":["../../src/walker/action-planner.ts"],"names":[],"mappings":"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"}

package/dist/walker/flow-walker.d.ts

@@ -0,0 +1,10 @@
+import type { Persona, UserSession } from "../types.js";
+/**
+ * Walk through a web application as a specific persona (legacy heuristic walker).
+ * Autonomously navigates, interacts, and records observations.
+ * Used by the `auto_walk` tool as a fast fallback.
+ */
+export declare function walkFlow(startUrl: string, persona: Persona, options?: {
+    readonly maxSteps?: number;
+}): Promise<UserSession>;
+//# sourceMappingURL=flow-walker.d.ts.map

package/dist/walker/flow-walker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-walker.d.ts","sourceRoot":"","sources":["../../src/walker/flow-walker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAYxD;;;;GAIG;AACH,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACvC,OAAO,CAAC,WAAW,CAAC,CAiEtB"}

package/dist/walker/flow-walker.js

@@ -0,0 +1,107 @@
+import { getBrowser } from "../utils/browser.js";
+import { extractPageSnapshot } from "../utils/page-snapshot.js";
+import { executeAction } from "../utils/actions.js";
+import { getMaxSteps, getViewport } from "../personas/engine.js";
+import { planNextAction, assessEmotion, detectFriction } from "./action-planner.js";
+import { SessionRecorder } from "./session-recorder.js";
+const NAVIGATION_TIMEOUT = 30_000;
+const DEFAULT_SCALE_FACTOR = 2;
+/**
+ * Walk through a web application as a specific persona (legacy heuristic walker).
+ * Autonomously navigates, interacts, and records observations.
+ * Used by the `auto_walk` tool as a fast fallback.
+ */
+export async function walkFlow(startUrl, persona, options) {
+    const maxSteps = options?.maxSteps ?? getMaxSteps(persona);
+    const viewport = getViewport(persona);
+    const recorder = new SessionRecorder(persona, startUrl);
+    const browser = await getBrowser();
+    const page = await browser.newPage();
+    await page.setViewport({ width: viewport.width, height: viewport.height, deviceScaleFactor: DEFAULT_SCALE_FACTOR });
+    let goalAchieved = false;
+    let goalAchievedStep;
+    try {
+        await page.goto(startUrl, { waitUntil: "networkidle2", timeout: NAVIGATION_TIMEOUT });
+        for (let step = 0; step < maxSteps; step++) {
+            const stepStart = Date.now();
+            const snapshot = await extractPageSnapshot(page);
+            const friction = detectFriction(persona, snapshot, step);
+            const action = planNextAction(persona, snapshot, recorder.getSteps());
+            const emotion = assessEmotion(persona, snapshot, recorder.getSteps(), friction);
+            const thought = generateThought(persona, snapshot, action, emotion, step);
+            recorder.recordStep({
+                page: snapshot,
+                action,
+                thought,
+                emotionalState: emotion,
+                frictionPoints: friction,
+                timeSpentMs: Date.now() - stepStart,
+            });
+            if (action.type === "give_up") {
+                break;
+            }
+            const result = await executeAction(page, { type: action.type, target: action.target, value: action.value });
+            if (!result.success) {
+                const failSnapshot = await extractPageSnapshot(page);
+                recorder.recordStep({
+                    page: failSnapshot,
+                    action: { type: "give_up", reasoning: `${persona.name}'s intended action failed — this would confuse a real user.` },
+                    thought: `"That didn't work... I clicked something and nothing happened. This is broken."`,
+                    emotionalState: "frustrated",
+                    frictionPoints: [{
+                            id: `friction-fail-${step}`,
+                            severity: "high",
+                            description: `Action failed: tried to ${action.type} on ${action.target ?? "element"} but it didn't respond`,
+                            location: failSnapshot.url,
+                            suggestion: "Ensure all interactive elements respond to user interaction and provide visual feedback",
+                            stepIndex: step + 1,
+                        }],
+                    timeSpentMs: Date.now() - stepStart,
+                });
+                break;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 500));
+        }
+    }
+    finally {
+        try {
+            if (!page.isClosed())
+                await page.close();
+        }
+        catch { /* ignore */ }
+    }
+    return recorder.finalize(goalAchieved, goalAchievedStep);
+}
+function generateThought(persona, page, action, emotion, stepIndex) {
+    if (stepIndex === 0) {
+        if (page.headings.length > 0) {
+            return `"${page.headings[0]}... okay, let me see what this is about."`;
+        }
+        return `"Hmm, I'm not immediately sure what this site does. Let me look around."`;
+    }
+    if (emotion === "frustrated") {
+        const reasons = [
+            `"I've been trying to figure this out and it's not obvious what I should do next."`,
+            `"Why is this so complicated? I just want to ${persona.goals[0] ?? 'get something done'}."`,
+            `"I'm about to give up. Nothing here is clicking."`,
+        ];
+        return reasons[stepIndex % reasons.length];
+    }
+    if (emotion === "confused") {
+        if (page.errorMessages.length > 0)
+            return `"Something went wrong... '${page.errorMessages[0]}' — what does that mean?"`;
+        return `"I'm not sure what I'm supposed to do here. The page doesn't guide me."`;
+    }
+    if (emotion === "delighted")
+        return `"Oh nice, this is exactly what I was looking for!"`;
+    if (action.type === "give_up")
+        return `"I can't figure this out. A real person would leave at this point."`;
+    if (action.type === "click")
+        return `"Let me try clicking that — it looks like it might help me ${persona.goals[0] ?? 'move forward'}."`;
+    if (action.type === "type")
+        return `"Alright, filling in this form field..."`;
+    if (action.type === "scroll")
+        return `"Let me scroll down to see if there's more content below."`;
+    return `"Okay, let me see what's here..."`;
+}
+//# sourceMappingURL=flow-walker.js.map

package/dist/walker/flow-walker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-walker.js","sourceRoot":"","sources":["../../src/walker/flow-walker.ts"],"names":[],"mappings":"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"}

package/dist/walker/session-recorder.d.ts

@@ -0,0 +1,28 @@
+import type { SessionStep, StepAction, PageSnapshot, FrictionPoint, EmotionalState, UserSession, Persona } from "../types.js";
+/**
+ * Mutable session builder that accumulates steps during a flow walk.
+ * Finalized into an immutable UserSession at the end.
+ */
+export declare class SessionRecorder {
+    private readonly persona;
+    private readonly startUrl;
+    private readonly steps;
+    private readonly startedAt;
+    constructor(persona: Persona, startUrl: string);
+    recordStep(params: {
+        readonly page: PageSnapshot;
+        readonly action: StepAction;
+        readonly thought?: string;
+        readonly emotionalState?: EmotionalState;
+        readonly frictionPoints?: readonly FrictionPoint[];
+        readonly timeSpentMs: number;
+    }): SessionStep;
+    getSteps(): readonly SessionStep[];
+    getStepCount(): number;
+    getLastStep(): SessionStep | undefined;
+    /**
+     * Finalize the session into an immutable UserSession with computed summary.
+     */
+    finalize(goalAchieved: boolean, goalAchievedStep?: number): UserSession;
+}
+//# sourceMappingURL=session-recorder.d.ts.map

package/dist/walker/session-recorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-recorder.d.ts","sourceRoot":"","sources":["../../src/walker/session-recorder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAkB,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAG9I;;;GAGG;AACH,qBAAa,eAAe;IAKxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAL3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAGhB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM;IAKnC,UAAU,CAAC,MAAM,EAAE;QACjB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;QAC5B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;QAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;QACzC,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;QACnD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;KAC9B,GAAG,WAAW;IAef,QAAQ,IAAI,SAAS,WAAW,EAAE;IAIlC,YAAY,IAAI,MAAM;IAItB,WAAW,IAAI,WAAW,GAAG,SAAS;IAItC;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,WAAW;CAwDxE"}

package/dist/walker/session-recorder.js

@@ -0,0 +1,90 @@
+import { randomUUID } from "node:crypto";
+/**
+ * Mutable session builder that accumulates steps during a flow walk.
+ * Finalized into an immutable UserSession at the end.
+ */
+export class SessionRecorder {
+    persona;
+    startUrl;
+    steps = [];
+    startedAt;
+    constructor(persona, startUrl) {
+        this.persona = persona;
+        this.startUrl = startUrl;
+        this.startedAt = new Date().toISOString();
+    }
+    recordStep(params) {
+        const step = {
+            index: this.steps.length,
+            timestamp: new Date().toISOString(),
+            page: params.page,
+            action: params.action,
+            thought: params.thought ?? "",
+            emotionalState: params.emotionalState ?? "neutral",
+            frictionPoints: [...(params.frictionPoints ?? [])],
+            timeSpentMs: params.timeSpentMs,
+        };
+        this.steps.push(step);
+        return step;
+    }
+    getSteps() {
+        return [...this.steps];
+    }
+    getStepCount() {
+        return this.steps.length;
+    }
+    getLastStep() {
+        return this.steps[this.steps.length - 1];
+    }
+    /**
+     * Finalize the session into an immutable UserSession with computed summary.
+     */
+    finalize(goalAchieved, goalAchievedStep) {
+        const completedAt = new Date().toISOString();
+        const allFriction = this.steps.flatMap((s) => s.frictionPoints);
+        const totalTimeMs = this.steps.reduce((sum, s) => sum + s.timeSpentMs, 0);
+        // Friction score: weighted sum of friction points normalized to 0-10
+        const frictionWeights = { low: 1, medium: 2, high: 4, critical: 7 };
+        const rawFriction = allFriction.reduce((sum, f) => sum + (frictionWeights[f.severity] ?? 1), 0);
+        const frictionScore = Math.min(10, rawFriction / Math.max(1, this.steps.length) * 2);
+        // Emotional journey
+        const emotionalJourney = this.steps.map((s) => s.emotionalState);
+        // Drop-off risk analysis
+        const highFrictionSteps = this.steps.filter((s) => s.frictionPoints.some((f) => f.severity === "high" || f.severity === "critical"));
+        const dropOffRisk = highFrictionSteps.length > 0
+            ? `High risk at step${highFrictionSteps.length > 1 ? "s" : ""} ${highFrictionSteps.map((s) => s.index).join(", ")} — ${highFrictionSteps[0].frictionPoints[0]?.description ?? "friction detected"}`
+            : frictionScore > 5 ? "Moderate risk — cumulative friction may cause abandonment"
+                : "Low risk — flow is relatively smooth";
+        // Top friction points (sorted by severity)
+        const severityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+        const topFrictionPoints = [...allFriction]
+            .sort((a, b) => (severityOrder[a.severity] ?? 3) - (severityOrder[b.severity] ?? 3))
+            .slice(0, 5);
+        // Generate recommendations from friction points
+        const recommendations = topFrictionPoints.map((f) => f.suggestion);
+        if (!goalAchieved) {
+            recommendations.push("User could not complete their goal — review the entire flow for blockers");
+        }
+        const summary = {
+            totalSteps: this.steps.length,
+            totalTimeMs,
+            frictionScore: Math.round(frictionScore * 10) / 10,
+            dropOffRisk,
+            emotionalJourney,
+            topFrictionPoints,
+            recommendations,
+            goalAchieved,
+            goalAchievedStep,
+        };
+        return {
+            id: randomUUID(),
+            persona: this.persona,
+            startUrl: this.startUrl,
+            startedAt: this.startedAt,
+            completedAt,
+            steps: [...this.steps],
+            summary,
+        };
+    }
+}
+//# sourceMappingURL=session-recorder.js.map

package/dist/walker/session-recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-recorder.js","sourceRoot":"","sources":["../../src/walker/session-recorder.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "userflow-mcp",
+  "version": "0.2.0",
+  "mcpName": "io.github.prembobby39-gif/userflow-mcp",
+  "description": "UserFlow MCP — Simulates real users navigating your app with different personas and delivers qualitative UX feedback. Free for Pro plan users.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "userflow-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist/**/*",
+    "!dist/__tests__/**"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepare": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "claude-code",
+    "user-testing",
+    "ux-feedback",
+    "persona-testing",
+    "user-flow",
+    "user-simulation",
+    "usability-testing",
+    "puppeteer",
+    "developer-tools",
+    "ux-review",
+    "friction-detection",
+    "onboarding-testing",
+    "cognitive-load",
+    "user-experience",
+    "synthetic-users",
+    "flow-analysis",
+    "userflow"
+  ],
+  "homepage": "https://github.com/prembobby39-gif/userflow-mcp",
+  "bugs": {
+    "url": "https://github.com/prembobby39-gif/userflow-mcp/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/prembobby39-gif/userflow-mcp.git"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.28.0",
+    "puppeteer-core": "^24.0.0",
+    "typescript": "^5.9.3",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^4.1.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.1"
+  }
+}