@recapt/mcp 0.0.2-beta

package/dist/tools/detectRegressions.d.ts

@@ -0,0 +1,6 @@
+/**
+ * detect_regressions tool
+ *
+ * Detect behavioral regressions by comparing recent data against baselines.
+ */
+export declare function registerDetectRegressions(server: any): void;

package/dist/tools/detectRegressions.js

@@ -0,0 +1,46 @@
+/**
+ * detect_regressions tool
+ *
+ * Detect behavioral regressions by comparing recent data against baselines.
+ */
+import { z } from "zod";
+import { apiGet, isApiConfigured } from "../api/client.js";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerDetectRegressions(server) {
+    server.registerTool("detect_regressions", {
+        description: "Detect behavioral regressions by comparing recent data (last 24h by default) against " +
+            "rolling 7-day baselines. Returns pages where frustration, confusion, or rage click rate " +
+            "have deviated significantly from normal levels, with z-scores indicating severity. " +
+            "Critical (z>3) means an extreme deviation, high (z>2) is notable, medium (z>1.5) is worth monitoring. " +
+            "Use this to catch deployments or changes that degraded user experience.",
+        inputSchema: z.object({
+            window_hours: z
+                .number()
+                .optional()
+                .default(24)
+                .describe("How many recent hours to compare against baseline (default 24)"),
+        }),
+    }, async ({ window_hours }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiGet("/regressions", {
+            window_hours: window_hours ?? 24,
+        });
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
+}

package/dist/tools/discoverPersonas.d.ts

@@ -0,0 +1,6 @@
+/**
+ * discover_personas tool
+ *
+ * Discover behavioral personas - groups of users who behave similarly.
+ */
+export declare function registerDiscoverPersonas(server: any): void;

package/dist/tools/discoverPersonas.js

@@ -0,0 +1,50 @@
+/**
+ * discover_personas tool
+ *
+ * Discover behavioral personas - groups of users who behave similarly.
+ */
+import { z } from "zod";
+import { apiGet, isApiConfigured } from "../api/client.js";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerDiscoverPersonas(server) {
+    server.registerTool("discover_personas", {
+        description: "Discover behavioral personas - groups of users who behave similarly " +
+            "(e.g. confident completers, frustrated battlers, lost explorers). " +
+            "Returns rich profiles with descriptions, risk factors, and recommended interventions. " +
+            "Uses K-means clustering on behavioral embeddings. Optionally scope to a specific page.",
+        inputSchema: z.object({
+            page_path: z
+                .string()
+                .optional()
+                .describe("Scope persona discovery to a specific page"),
+            num_personas: z
+                .number()
+                .optional()
+                .default(4)
+                .describe("Number of personas to discover (default 4, max 8)"),
+        }),
+    }, async ({ page_path, num_personas, }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiGet("/personas", {
+            page_path,
+            num_personas: num_personas ?? 4,
+        });
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
+}

package/dist/tools/getActionableIssues.d.ts

@@ -0,0 +1,7 @@
+/**
+ * get_actionable_issues tool
+ *
+ * Returns UX issues with element context for investigation.
+ * Thin proxy to external-api /actionable-issues endpoint.
+ */
+export declare function registerGetActionableIssues(server: any): void;

package/dist/tools/getActionableIssues.js

@@ -0,0 +1,55 @@
+/**
+ * get_actionable_issues tool
+ *
+ * Returns UX issues with element context for investigation.
+ * Thin proxy to external-api /actionable-issues endpoint.
+ */
+import { z } from "zod";
+import { apiGet, isApiConfigured } from "../api/client.js";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerGetActionableIssues(server) {
+    server.registerTool("get_actionable_issues", {
+        description: "Get UX issues with element context. Returns detected issues (rage clicks, dead clicks, " +
+            "errors, etc.) along with the most affected elements on each page. " +
+            "Use this when you want to understand and fix specific UX problems.",
+        inputSchema: z.object({
+            page_path: z
+                .string()
+                .optional()
+                .describe("Filter to a specific page path (e.g., /checkout)"),
+            severity: z
+                .enum(["critical", "high", "medium", "low", "info"])
+                .optional()
+                .describe("Minimum severity level to include"),
+            limit: z
+                .number()
+                .optional()
+                .default(10)
+                .describe("Maximum number of issues to return (default: 10)"),
+        }),
+    }, async ({ page_path, severity, limit, }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiGet("/actionable-issues", {
+            page_path,
+            severity,
+            limit: limit ?? 10,
+        });
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
+}

package/dist/tools/getAnomalies.d.ts

@@ -0,0 +1,6 @@
+/**
+ * get_anomalies tool
+ *
+ * Detects anomalous sessions and frustration spikes.
+ */
+export declare function registerGetAnomalies(server: any): void;

package/dist/tools/getAnomalies.js

@@ -0,0 +1,53 @@
+/**
+ * get_anomalies tool
+ *
+ * Detects anomalous sessions and frustration spikes.
+ */
+import { z } from "zod";
+import { apiGet, isApiConfigured } from "../api/client.js";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerGetAnomalies(server) {
+    server.registerTool("get_anomalies", {
+        description: "Detect anomalous sessions and frustration spikes. Finds sessions that deviate from normal behavior patterns.",
+        inputSchema: z.object({
+            threshold: z
+                .number()
+                .optional()
+                .default(0.35)
+                .describe("Anomaly threshold (0-1, default: 0.35)"),
+            days: z
+                .number()
+                .optional()
+                .default(7)
+                .describe("Days to analyze for frustration spikes (default: 7)"),
+            page_path: z
+                .string()
+                .optional()
+                .describe("Optional: filter to a specific page"),
+        }),
+    }, async ({ threshold, days, page_path, }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiGet("/anomalies", {
+            threshold: threshold ?? 0.35,
+            days: days ?? 7,
+            page_path,
+        });
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
+}

package/dist/tools/getConsoleErrors.d.ts

@@ -0,0 +1,6 @@
+/**
+ * get_console_errors tool
+ *
+ * Query JavaScript console errors and warnings from user sessions.
+ */
+export declare function registerGetConsoleErrors(server: any): void;

package/dist/tools/getConsoleErrors.js

@@ -0,0 +1,61 @@
+/**
+ * get_console_errors tool
+ *
+ * Query JavaScript console errors and warnings from user sessions.
+ */
+import { z } from "zod";
+import { apiGet, isApiConfigured } from "../api/client.js";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerGetConsoleErrors(server) {
+    server.registerTool("get_console_errors", {
+        description: "Query JavaScript console errors and warnings from user sessions. " +
+            "Use this when you suspect page unresponsiveness, broken buttons, or rendering issues. " +
+            "Returns the most common errors grouped by message, with session impact counts. " +
+            "High rage clicks on root/body elements often correlate with JS errors.",
+        inputSchema: z.object({
+            page_path: z
+                .string()
+                .optional()
+                .describe("Filter errors to a specific page path"),
+            session_id: z
+                .string()
+                .optional()
+                .describe("Filter errors to a specific session"),
+            severity: z
+                .enum(["error", "warn", "all"])
+                .optional()
+                .default("error")
+                .describe('Filter by severity: "error" (default), "warn", or "all"'),
+            limit: z
+                .number()
+                .optional()
+                .default(200)
+                .describe("Max log documents to scan (default 200)"),
+        }),
+    }, async ({ page_path, session_id, severity, limit, }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiGet("/console-errors", {
+            page_path,
+            session_id,
+            severity: severity ?? "error",
+            limit: limit ?? 200,
+        });
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
+}

package/dist/tools/getDeadClicks.d.ts

@@ -0,0 +1,6 @@
+/**
+ * get_dead_clicks tool
+ *
+ * Find buttons and links that users click but nothing happens (dead clicks).
+ */
+export declare function registerGetDeadClicks(server: any): void;

package/dist/tools/getDeadClicks.js

@@ -0,0 +1,42 @@
+/**
+ * get_dead_clicks tool
+ *
+ * Find buttons and links that users click but nothing happens (dead clicks).
+ */
+import { z } from "zod";
+import { apiGet, isApiConfigured } from "../api/client.js";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerGetDeadClicks(server) {
+    server.registerTool("get_dead_clicks", {
+        description: "Find buttons and links that users click but nothing happens (dead clicks). " +
+            "These are interactive elements where the click produced no visible DOM change. " +
+            "Use this to identify BROKEN or UNRESPONSIVE UI elements that frustrate users.",
+        inputSchema: z.object({
+            page_path: z
+                .string()
+                .describe("Page path to check for dead clicks (required)"),
+        }),
+    }, async ({ page_path }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiGet("/dead-clicks", {
+            page_path,
+        });
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
+}

package/dist/tools/getDomains.d.ts

@@ -0,0 +1,6 @@
+/**
+ * get_domains tool
+ *
+ * Returns the list of domains configured for the organization.
+ */
+export declare function registerGetDomains(server: any): void;

package/dist/tools/getDomains.js

@@ -0,0 +1,34 @@
+/**
+ * get_domains tool
+ *
+ * Returns the list of domains configured for the organization.
+ */
+import { z } from "zod";
+import { apiGet, isApiConfigured } from "../api/client.js";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerGetDomains(server) {
+    server.registerTool("get_domains", {
+        description: "Get the list of domains configured for the organization. Domains represent different websites or applications being tracked.",
+        inputSchema: z.object({}),
+    }, async () => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiGet("/domains");
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
+}

package/dist/tools/getElementFriction.d.ts

@@ -0,0 +1,6 @@
+/**
+ * get_element_friction tool
+ *
+ * Returns per-element friction data for a specific page.
+ */
+export declare function registerGetElementFriction(server: any): void;

package/dist/tools/getElementFriction.js

@@ -0,0 +1,45 @@
+/**
+ * get_element_friction tool
+ *
+ * Returns per-element friction data for a specific page.
+ */
+import { z } from "zod";
+import { apiGet, isApiConfigured } from "../api/client.js";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerGetElementFriction(server) {
+    server.registerTool("get_element_friction", {
+        description: "Get per-element friction data for a page. Shows which elements cause user frustration, with click counts and dominant frustration signals.",
+        inputSchema: z.object({
+            page_path: z
+                .string()
+                .describe("Page path to analyze (e.g., /checkout)"),
+            selector_filter: z
+                .string()
+                .optional()
+                .describe("Optional: filter elements by selector substring"),
+        }),
+    }, async ({ page_path, selector_filter, }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiGet("/elements", {
+            page_path,
+            selector_filter,
+        });
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
+}

package/dist/tools/getFlowFriction.d.ts

@@ -0,0 +1,7 @@
+/**
+ * get_flow_friction tool
+ *
+ * Discovers high-friction user flows by analyzing navigation patterns
+ * and behavioral data. Thin proxy to external-api /flow-friction endpoint.
+ */
+export declare function registerGetFlowFriction(server: any): void;

package/dist/tools/getFlowFriction.js

@@ -0,0 +1,57 @@
+/**
+ * get_flow_friction tool
+ *
+ * Discovers high-friction user flows by analyzing navigation patterns
+ * and behavioral data. Thin proxy to external-api /flow-friction endpoint.
+ */
+import { z } from "zod";
+import { apiGet, isApiConfigured } from "../api/client.js";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerGetFlowFriction(server) {
+    server.registerTool("get_flow_friction", {
+        description: "Discover user flows with behavioral metrics. Returns navigation transitions " +
+            "with frustration, confusion, and health scores for each page in the flow. " +
+            "Also flags backtrack hotspots (pages users return to) and dropoff pages. " +
+            "Use this to find which flows need optimization.",
+        inputSchema: z.object({
+            page_path: z
+                .string()
+                .optional()
+                .describe("Focus on flows involving this page (e.g., /checkout)"),
+            days: z
+                .number()
+                .optional()
+                .default(7)
+                .describe("Number of days to analyze (default: 7)"),
+            limit: z
+                .number()
+                .optional()
+                .default(10)
+                .describe("Maximum number of flows to return (default: 10)"),
+        }),
+    }, async ({ page_path, days, limit, }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiGet("/flow-friction", {
+            page_path,
+            days: days ?? 7,
+            limit: limit ?? 10,
+        });
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
+}

package/dist/tools/getFormFriction.d.ts

@@ -0,0 +1,6 @@
+/**
+ * get_form_friction tool
+ *
+ * Analyze which form fields cause friction.
+ */
+export declare function registerGetFormFriction(server: any): void;

package/dist/tools/getFormFriction.js

@@ -0,0 +1,42 @@
+/**
+ * get_form_friction tool
+ *
+ * Analyze which form fields cause friction.
+ */
+import { z } from "zod";
+import { apiGet, isApiConfigured } from "../api/client.js";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerGetFormFriction(server) {
+    server.registerTool("get_form_friction", {
+        description: "Analyze which form fields cause friction on a page. " +
+            "Returns per-field metrics including dwell time, correction rate, and abandonment rate. " +
+            "Use this to identify problematic form fields in checkout, signup, or other forms.",
+        inputSchema: z.object({
+            page_path: z
+                .string()
+                .describe("Page path containing the form to analyze (required)"),
+        }),
+    }, async ({ page_path }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiGet("/forms/friction", {
+            page_path,
+        });
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
+}

package/dist/tools/getIssues.d.ts

@@ -0,0 +1,6 @@
+/**
+ * get_issues tool
+ *
+ * Returns detected UX issues.
+ */
+export declare function registerGetIssues(server: any): void;

package/dist/tools/getIssues.js

@@ -0,0 +1,82 @@
+/**
+ * get_issues tool
+ *
+ * Returns detected UX issues.
+ */
+import { z } from "zod";
+import { apiGet, isApiConfigured } from "../api/client.js";
+const VALID_CATEGORIES = [
+    "code_error",
+    "dead_click",
+    "rage_click",
+    "ux_friction",
+    "performance",
+    "form_issue",
+    "behavioral_anomaly",
+    "structural_issue",
+];
+const VALID_SEVERITIES = ["critical", "high", "medium", "low", "info"];
+const VALID_STATUSES = [
+    "pending",
+    "active",
+    "escalated",
+    "resolved",
+    "dismissed",
+    "expired",
+];
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerGetIssues(server) {
+    server.registerTool("get_issues", {
+        description: "Get detected UX issues. Issues are automatically detected from session recordings and include rage clicks, dead clicks, form issues, and behavioral anomalies.",
+        inputSchema: z.object({
+            page_path: z
+                .string()
+                .optional()
+                .describe("Filter issues to a specific page path"),
+            category: z
+                .enum(VALID_CATEGORIES)
+                .optional()
+                .describe("Filter by issue category"),
+            severity: z
+                .enum(VALID_SEVERITIES)
+                .optional()
+                .describe("Filter by severity level"),
+            status: z
+                .enum(VALID_STATUSES)
+                .optional()
+                .default("active")
+                .describe("Filter by status (default: active)"),
+            limit: z
+                .number()
+                .optional()
+                .default(20)
+                .describe("Maximum number of issues to return (default: 20)"),
+        }),
+    }, async ({ page_path, category, severity, status, limit, }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiGet("/issues", {
+            page_path,
+            category,
+            severity,
+            status: status ?? "active",
+            limit: limit ?? 20,
+        });
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
+}

package/dist/tools/getJourneyPatterns.d.ts

@@ -0,0 +1,7 @@
+/**
+ * get_journey_patterns tool
+ *
+ * Discovers navigation patterns across sessions.
+ * Thin proxy to external-api /flows/patterns endpoint.
+ */
+export declare function registerGetJourneyPatterns(server: any): void;