@recapt/mcp 0.0.2-beta

package/dist/tools/getJourneyPatterns.js

@@ -0,0 +1,50 @@
+/**
+ * get_journey_patterns tool
+ *
+ * Discovers navigation patterns across sessions.
+ * Thin proxy to external-api /flows/patterns endpoint.
+ */
+import { z } from "zod";
+import { apiGet, isApiConfigured } from "../api/client.js";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerGetJourneyPatterns(server) {
+    server.registerTool("get_journey_patterns", {
+        description: "Discover navigation patterns across sessions. Returns top page transitions, " +
+            "backtrack hotspots (pages users return to), and dropoff pages (where sessions end). " +
+            "Use this to understand organic user navigation.",
+        inputSchema: z.object({
+            page_path: z
+                .string()
+                .optional()
+                .describe("Filter to transitions involving this page (e.g., /pricing)"),
+            days: z
+                .number()
+                .optional()
+                .default(7)
+                .describe("Number of days to analyze (default: 7)"),
+        }),
+    }, async ({ page_path, days }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiGet("/flows/patterns", {
+            page_path,
+            days: days ?? 7,
+        });
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
+}

package/dist/tools/getPageMetrics.d.ts

@@ -0,0 +1,6 @@
+/**
+ * get_page_metrics tool
+ *
+ * Returns aggregated behavioral metrics for a specific page or all pages.
+ */
+export declare function registerGetPageMetrics(server: any): void;

package/dist/tools/getPageMetrics.js

@@ -0,0 +1,47 @@
+/**
+ * get_page_metrics tool
+ *
+ * Returns aggregated behavioral metrics for a specific page or all pages.
+ */
+import { z } from "zod";
+import { apiGet, isApiConfigured } from "../api/client.js";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerGetPageMetrics(server) {
+    server.registerTool("get_page_metrics", {
+        description: "Get aggregated behavioral metrics for a page. Returns frustration, confusion, confidence, energy scores, and health score. If page_path is omitted, returns metrics for all pages.",
+        inputSchema: z.object({
+            page_path: z
+                .string()
+                .optional()
+                .describe("Page path to get metrics for (e.g., /checkout). Omit to get all pages."),
+            days: z
+                .number()
+                .optional()
+                .default(7)
+                .describe("Number of days to look back (default: 7)"),
+        }),
+    }, async ({ page_path, days }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiGet("/pages", {
+            page_path,
+            days,
+        });
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
+}

package/dist/tools/getPageTrends.d.ts

@@ -0,0 +1,6 @@
+/**
+ * get_page_trends tool
+ *
+ * Returns daily behavioral trends for a page.
+ */
+export declare function registerGetPageTrends(server: any): void;

package/dist/tools/getPageTrends.js

@@ -0,0 +1,46 @@
+/**
+ * get_page_trends tool
+ *
+ * Returns daily behavioral trends for a page.
+ */
+import { z } from "zod";
+import { apiGet, isApiConfigured } from "../api/client.js";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerGetPageTrends(server) {
+    server.registerTool("get_page_trends", {
+        description: "Get daily behavioral trends for a page. Shows how frustration, confusion, and confidence change over time.",
+        inputSchema: z.object({
+            page_path: z
+                .string()
+                .describe("Page path to analyze (e.g., /checkout)"),
+            days: z
+                .number()
+                .optional()
+                .default(14)
+                .describe("Number of days to look back (default: 14)"),
+        }),
+    }, async ({ page_path, days }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiGet("/trends", {
+            page_path,
+            days: days ?? 14,
+        });
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
+}

package/dist/tools/getSessionDetails.d.ts

@@ -0,0 +1,6 @@
+/**
+ * get_session_details tool
+ *
+ * Returns behavioral timeline for one or more sessions.
+ */
+export declare function registerGetSessionDetails(server: any): void;

package/dist/tools/getSessionDetails.js

@@ -0,0 +1,70 @@
+/**
+ * get_session_details tool
+ *
+ * Returns behavioral timeline for one or more sessions.
+ */
+import { z } from "zod";
+import { apiGet, apiPost, isApiConfigured } from "../api/client.js";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerGetSessionDetails(server) {
+    server.registerTool("get_session_details", {
+        description: "Get behavioral timeline for one or more sessions. Shows how frustration, confusion, and confidence evolved over time. Accepts a single session_id or an array of session_ids (max 20).",
+        inputSchema: z.object({
+            session_id: z
+                .string()
+                .optional()
+                .describe("Single session ID to get details for"),
+            session_ids: z
+                .array(z.string())
+                .max(20)
+                .optional()
+                .describe("Array of session IDs to get details for (max 20)"),
+        }),
+    }, async ({ session_id, session_ids, }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        if (!session_id && (!session_ids || session_ids.length === 0)) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "Either session_id or session_ids must be provided",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        if (session_id && !session_ids) {
+            const { data, error } = await apiGet(`/sessions/${session_id}`);
+            if (error) {
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ error }) }],
+                    isError: true,
+                };
+            }
+            return { content: [{ type: "text", text: JSON.stringify(data) }] };
+        }
+        const ids = session_ids ?? [session_id];
+        const { data, error } = await apiPost("/sessions/details", {
+            session_ids: ids,
+        });
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
+}

package/dist/tools/getUxHealthReport.d.ts

@@ -0,0 +1,7 @@
+/**
+ * get_ux_health_report tool
+ *
+ * Returns a comprehensive UX health report for the website or a specific page.
+ * Thin proxy to external-api /health-report endpoint.
+ */
+export declare function registerGetUxHealthReport(server: any): void;

package/dist/tools/getUxHealthReport.js

@@ -0,0 +1,50 @@
+/**
+ * get_ux_health_report tool
+ *
+ * Returns a comprehensive UX health report for the website or a specific page.
+ * Thin proxy to external-api /health-report endpoint.
+ */
+import { z } from "zod";
+import { apiGet, isApiConfigured } from "../api/client.js";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerGetUxHealthReport(server) {
+    server.registerTool("get_ux_health_report", {
+        description: "Get a comprehensive UX health report combining page metrics, issues, and anomalies. " +
+            "Returns overall health score, per-page breakdown, active issues, and frustration spikes. " +
+            "Use this as a starting point to understand overall UX state before diving deeper.",
+        inputSchema: z.object({
+            page_path: z
+                .string()
+                .optional()
+                .describe("Focus on a specific page (omit for site-wide report)"),
+            days: z
+                .number()
+                .optional()
+                .default(7)
+                .describe("Number of days to analyze (default: 7)"),
+        }),
+    }, async ({ page_path, days }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiGet("/health-report", {
+            page_path,
+            days: days ?? 7,
+        });
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
+}

package/dist/tools/listPages.d.ts

@@ -0,0 +1,6 @@
+/**
+ * list_pages tool
+ *
+ * List all tracked pages with basic metrics.
+ */
+export declare function registerListPages(server: any): void;

package/dist/tools/listPages.js

@@ -0,0 +1,50 @@
+/**
+ * list_pages tool
+ *
+ * List all tracked pages with basic metrics.
+ */
+import { z } from "zod";
+import { apiGet, isApiConfigured } from "../api/client.js";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerListPages(server) {
+    server.registerTool("list_pages", {
+        description: "List all tracked pages with basic metrics. " +
+            "Returns page paths sorted by session count with frustration and health grade. " +
+            "Use this to discover what pages are being tracked before diving into specific pages.",
+        inputSchema: z.object({
+            days: z
+                .number()
+                .optional()
+                .default(7)
+                .describe("Number of days to look back (default 7)"),
+            limit: z
+                .number()
+                .optional()
+                .default(50)
+                .describe("Maximum number of pages to return (default 50)"),
+        }),
+    }, async ({ days, limit }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiGet("/pages/list", {
+            days: days ?? 7,
+            limit: limit ?? 50,
+        });
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
+}

package/dist/tools/listSessions.d.ts

@@ -0,0 +1,7 @@
+/**
+ * list_sessions tool
+ *
+ * Lists and filters recorded sessions.
+ * Thin proxy to external-api /sessions endpoint.
+ */
+export declare function registerListSessions(server: any): void;

package/dist/tools/listSessions.js

@@ -0,0 +1,67 @@
+/**
+ * list_sessions tool
+ *
+ * Lists and filters recorded sessions.
+ * Thin proxy to external-api /sessions endpoint.
+ */
+import { z } from "zod";
+import { apiGet, isApiConfigured } from "../api/client.js";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerListSessions(server) {
+    server.registerTool("list_sessions", {
+        description: "List and filter recorded sessions. Returns session metadata including status, " +
+            "duration, device, browser, and domains. Use to find sessions for a domain, " +
+            "check for active sessions, or browse by device type.",
+        inputSchema: z.object({
+            domain: z
+                .string()
+                .optional()
+                .describe("Filter by domain name (partial match supported)"),
+            status: z
+                .enum(["active", "terminated", "all"])
+                .optional()
+                .default("all")
+                .describe("Filter by session status"),
+            device: z
+                .enum(["desktop", "mobile", "tablet"])
+                .optional()
+                .describe("Filter by device type"),
+            days: z
+                .number()
+                .optional()
+                .default(7)
+                .describe("Number of days to look back (default: 7)"),
+            limit: z
+                .number()
+                .optional()
+                .default(20)
+                .describe("Maximum sessions to return (default: 20, max: 200)"),
+        }),
+    }, async ({ domain, status, device, days, limit, }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiGet("/sessions", {
+            domain,
+            status: status === "all" ? undefined : status,
+            device,
+            days: days ?? 7,
+            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/memory.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Memory management tools for MCP sessions.
+ *
+ * Provides working memory for AI agents to store intermediate results
+ * and query across stored data without re-fetching.
+ */
+export declare function registerMemoryTools(server: any): void;

package/dist/tools/memory.js

@@ -0,0 +1,119 @@
+/**
+ * Memory management tools for MCP sessions.
+ *
+ * Provides working memory for AI agents to store intermediate results
+ * and query across stored data without re-fetching.
+ */
+import { z } from "zod";
+const memoryStore = new Map();
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerMemoryTools(server) {
+    server.registerTool("memory_save", {
+        description: "Save a value to working memory for later retrieval. " +
+            "Use this to store intermediate results from tool calls that you want to reference later.",
+        inputSchema: z.object({
+            key: z.string().describe("Unique key to store the value under"),
+            value: z.string().describe("Value to store (will be stored as string)"),
+            annotation: z
+                .string()
+                .optional()
+                .describe("Optional note about what this data represents"),
+        }),
+    }, async ({ key, value, annotation, }) => {
+        memoryStore.set(key, {
+            key,
+            value,
+            timestamp: Date.now(),
+            annotation,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ success: true, key, size: value.length }),
+                },
+            ],
+        };
+    });
+    server.registerTool("memory_recall", {
+        description: "Retrieve a value from working memory by key. " +
+            "Use this to access data you previously stored with memory_save.",
+        inputSchema: z.object({
+            key: z.string().describe("Key to retrieve"),
+        }),
+    }, async ({ key }) => {
+        const entry = memoryStore.get(key);
+        if (!entry) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: `Key "${key}" not found in memory`,
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: entry.value,
+                },
+            ],
+        };
+    });
+    server.registerTool("memory_list", {
+        description: "List all keys currently stored in working memory. " +
+            "Returns key names, sizes, timestamps, and annotations.",
+        inputSchema: z.object({}),
+    }, async () => {
+        const entries = [...memoryStore.values()].map((entry) => ({
+            key: entry.key,
+            size: entry.value.length,
+            timestamp: new Date(entry.timestamp).toISOString(),
+            annotation: entry.annotation,
+        }));
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ count: entries.length, entries }),
+                },
+            ],
+        };
+    });
+    server.registerTool("memory_delete", {
+        description: "Delete a value from working memory by key.",
+        inputSchema: z.object({
+            key: z.string().describe("Key to delete"),
+        }),
+    }, async ({ key }) => {
+        const existed = memoryStore.delete(key);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ success: true, deleted: existed }),
+                },
+            ],
+        };
+    });
+    server.registerTool("memory_clear", {
+        description: "Clear all values from working memory. Use with caution.",
+        inputSchema: z.object({}),
+    }, async () => {
+        const count = memoryStore.size;
+        memoryStore.clear();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ success: true, cleared: count }),
+                },
+            ],
+        };
+    });
+}

package/dist/tools/predictOutcomes.d.ts

@@ -0,0 +1,6 @@
+/**
+ * predict_outcomes tool
+ *
+ * Predict session outcomes based on behavioral features.
+ */
+export declare function registerPredictOutcomes(server: any): void;

package/dist/tools/predictOutcomes.js

@@ -0,0 +1,66 @@
+/**
+ * predict_outcomes tool
+ *
+ * Predict session outcomes based on behavioral features.
+ */
+import { z } from "zod";
+import { apiPost, isApiConfigured } from "../api/client.js";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerPredictOutcomes(server) {
+    server.registerTool("predict_outcomes", {
+        description: "Predict session outcomes based on early behavioral signals. " +
+            "Provide either a session_id to analyze an existing session, or behavioral_features " +
+            "to predict outcomes for hypothetical scenarios. " +
+            "Returns predicted outcome (COMPLETED, STRUGGLED, BLOCKED, DISENGAGED) with confidence.",
+        inputSchema: z.object({
+            session_id: z
+                .string()
+                .optional()
+                .describe("Session ID to analyze and predict outcome for"),
+            behavioral_features: z
+                .object({
+                frustration: z.number().describe("Frustration score (0-1)"),
+                confusion: z.number().describe("Confusion score (0-1)"),
+                confidence: z.number().describe("Confidence score (0-1)"),
+            })
+                .optional()
+                .describe("Behavioral features to use for prediction"),
+        }),
+    }, async ({ session_id, behavioral_features, }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        if (!session_id && !behavioral_features) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "Either session_id or behavioral_features is required",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiPost("/predict", {
+            session_id,
+            behavioral_features,
+        });
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
+}

package/dist/tools/scanSite.d.ts

@@ -0,0 +1,6 @@
+/**
+ * scan_site tool
+ *
+ * One-shot site health scan across all pages.
+ */
+export declare function registerScanSite(server: any): void;