@recapt/mcp 0.0.19-beta → 0.0.20-beta

package/dist/tools/analyzeFlow.js

@@ -1,68 +0,0 @@
-/**
- * analyze_flow tool
- *
- * Analyzes user navigation flows between pages.
- * Thin proxy to external-api /flows/analyze endpoint.
- */
-import { z } from "zod";
-import { apiPost, isApiConfigured } from "../api/client.js";
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function registerAnalyzeFlow(server) {
-    server.registerTool("analyze_flow", {
-        description: "Analyze user navigation flows between pages. Returns paths with steps, " +
-            "behavioral metrics (frustration, confusion), success rates, and bottlenecks. " +
-            "Use this to understand how users navigate between specific pages.",
-        inputSchema: z.object({
-            start_page: z
-                .string()
-                .optional()
-                .describe("Starting page path (e.g., /pricing). Partial match supported."),
-            end_page: z
-                .string()
-                .optional()
-                .describe("Ending page path (e.g., /checkout). Partial match supported."),
-            days: z
-                .number()
-                .optional()
-                .default(7)
-                .describe("Number of days to analyze (default: 7)"),
-        }),
-    }, async ({ start_page, end_page, days, }) => {
-        if (!isApiConfigured()) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({ error: "API not configured" }),
-                    },
-                ],
-                isError: true,
-            };
-        }
-        if (!start_page && !end_page) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({
-                            error: "At least one of start_page or end_page is required",
-                        }),
-                    },
-                ],
-                isError: true,
-            };
-        }
-        const { data, error } = await apiPost("/flows/analyze", {
-            start_page,
-            end_page,
-            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/analyzeFunnel.d.ts

@@ -1,7 +0,0 @@
-/**
- * analyze_funnel tool
- *
- * Analyzes conversion funnels through a defined sequence of pages.
- * Thin proxy to external-api /flows/funnel endpoint.
- */
-export declare function registerAnalyzeFunnel(server: any): void;

package/dist/tools/analyzeFunnel.js

@@ -1,63 +0,0 @@
-/**
- * analyze_funnel tool
- *
- * Analyzes conversion funnels through a defined sequence of pages.
- * Thin proxy to external-api /flows/funnel endpoint.
- */
-import { z } from "zod";
-import { apiPost, isApiConfigured } from "../api/client.js";
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function registerAnalyzeFunnel(server) {
-    server.registerTool("analyze_funnel", {
-        description: "Analyze a conversion funnel through a sequence of pages. Returns per-step metrics " +
-            "(entered, converted, dropped, dwell time, frustration, confusion) and dropoff analysis " +
-            'showing where users exit. Supports wildcards: "/checkout*" matches all checkout pages.',
-        inputSchema: z.object({
-            steps: z
-                .array(z.string())
-                .min(2)
-                .describe('Ordered page paths forming the funnel (e.g., ["/cart", "/checkout", "/payment"])'),
-            days: z
-                .number()
-                .optional()
-                .default(7)
-                .describe("Number of days to analyze (default: 7)"),
-        }),
-    }, async ({ steps, days }) => {
-        if (!isApiConfigured()) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({ error: "API not configured" }),
-                    },
-                ],
-                isError: true,
-            };
-        }
-        if (!steps || steps.length < 2) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({
-                            error: "At least 2 steps are required for funnel analysis",
-                        }),
-                    },
-                ],
-                isError: true,
-            };
-        }
-        const { data, error } = await apiPost("/flows/funnel", {
-            steps,
-            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/catalog/callTool.d.ts

@@ -1,22 +0,0 @@
-/**
- * Call Tool — Universal tool proxy for executing any tool by name.
- *
- * This tool allows the agent to invoke ANY tool by name without having
- * all tool descriptions in context. The agent discovers tools via search_tools,
- * then calls them through this proxy.
- *
- * Benefits:
- * - Minimal context: Only ~10 tools have descriptions in the prompt
- * - All 40+ analysis tools accessible on-demand
- * - Scales to any number of tools without context bloat
- */
-export type ToolHandler = (args: Record<string, unknown>) => Promise<{
-    content: Array<{
-        type: string;
-        text: string;
-    }>;
-    isError?: boolean;
-}>;
-export declare function registerToolHandler(name: string, handler: ToolHandler): void;
-export declare function getToolHandler(name: string): ToolHandler | undefined;
-export declare function registerCallTool(server: any): void;

package/dist/tools/catalog/callTool.js

@@ -1,92 +0,0 @@
-/**
- * Call Tool — Universal tool proxy for executing any tool by name.
- *
- * This tool allows the agent to invoke ANY tool by name without having
- * all tool descriptions in context. The agent discovers tools via search_tools,
- * then calls them through this proxy.
- *
- * Benefits:
- * - Minimal context: Only ~10 tools have descriptions in the prompt
- * - All 40+ analysis tools accessible on-demand
- * - Scales to any number of tools without context bloat
- */
-import { z } from "zod";
-import { getToolByName } from "./searchTools.js";
-const toolRegistry = new Map();
-export function registerToolHandler(name, handler) {
-    toolRegistry.set(name, handler);
-}
-export function getToolHandler(name) {
-    return toolRegistry.get(name);
-}
-const callToolSchema = z.object({
-    tool_name: z
-        .string()
-        .describe("The exact name of the tool to call (e.g., 'get_page_metrics', 'analyze_flow', 'compare_cohorts')"),
-    arguments: z
-        .record(z.string(), z.unknown())
-        .describe("The arguments to pass to the tool as a JSON object. Check the tool description from search_tools for required parameters."),
-});
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function registerCallTool(server) {
-    server.registerTool("call_tool", {
-        description: "Execute any analysis tool by name. Use search_tools first to discover available tools, " +
-            "then call them through this proxy. Pass the exact tool name and arguments as a JSON object. " +
-            "Example: call_tool({ tool_name: 'get_page_metrics', arguments: { page_path: '/checkout' } })",
-        inputSchema: callToolSchema,
-    }, async ({ tool_name, arguments: args }) => {
-        const handler = toolRegistry.get(tool_name);
-        if (!handler) {
-            const catalogEntry = getToolByName(tool_name);
-            if (catalogEntry) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({
-                                error: `Tool "${tool_name}" exists in catalog but is not registered. This may be a server configuration issue.`,
-                                tool_info: {
-                                    name: catalogEntry.name,
-                                    description: catalogEntry.description,
-                                    category: catalogEntry.category,
-                                },
-                            }),
-                        },
-                    ],
-                    isError: true,
-                };
-            }
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({
-                            error: `Unknown tool: ${tool_name}`,
-                            hint: "Use search_tools to discover available tools first.",
-                        }),
-                    },
-                ],
-                isError: true,
-            };
-        }
-        try {
-            return await handler(args);
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({
-                            error: `Tool execution failed: ${message}`,
-                            tool_name,
-                            arguments: args,
-                        }),
-                    },
-                ],
-                isError: true,
-            };
-        }
-    });
-}

package/dist/tools/catalog/index.d.ts

@@ -1,11 +0,0 @@
-/**
- * Tool Catalog — Registry and discovery for MCP tools.
- *
- * Exports:
- * - searchTools: Find tools by natural language query
- * - registerSearchTools: Register the search_tools MCP tool
- * - registerCallTool: Register the call_tool MCP tool
- * - registerToolHandler: Register a tool handler for call_tool to invoke
- */
-export { searchTools, getToolByName, getAllTools, registerSearchTools, type ToolEntry, } from "./searchTools.js";
-export { registerCallTool, registerToolHandler, getToolHandler, type ToolHandler, } from "./callTool.js";

package/dist/tools/catalog/index.js

@@ -1,11 +0,0 @@
-/**
- * Tool Catalog — Registry and discovery for MCP tools.
- *
- * Exports:
- * - searchTools: Find tools by natural language query
- * - registerSearchTools: Register the search_tools MCP tool
- * - registerCallTool: Register the call_tool MCP tool
- * - registerToolHandler: Register a tool handler for call_tool to invoke
- */
-export { searchTools, getToolByName, getAllTools, registerSearchTools, } from "./searchTools.js";
-export { registerCallTool, registerToolHandler, getToolHandler, } from "./callTool.js";

package/dist/tools/catalog/searchTools.d.ts

@@ -1,22 +0,0 @@
-/**
- * Search Tools — Semantic and keyword search over the tool catalog.
- *
- * Allows the agent to discover specialized tools by describing what
- * it needs in natural language. Uses pre-computed embeddings for
- * fast, accurate matching with fallback to keyword search.
- */
-export interface ToolEntry {
-    name: string;
-    description: string;
-    category: string;
-    parameters: Record<string, {
-        type: string;
-        required?: boolean;
-        description?: string;
-    }>;
-    embedding: number[];
-}
-export declare function searchTools(query: string, limit?: number, queryEmbedding?: number[]): Promise<ToolEntry[]>;
-export declare function getToolByName(name: string): ToolEntry | undefined;
-export declare function getAllTools(): ToolEntry[];
-export declare function registerSearchTools(server: any): void;

package/dist/tools/catalog/searchTools.js

@@ -1,194 +0,0 @@
-/**
- * Search Tools — Semantic and keyword search over the tool catalog.
- *
- * Allows the agent to discover specialized tools by describing what
- * it needs in natural language. Uses pre-computed embeddings for
- * fast, accurate matching with fallback to keyword search.
- */
-import { z } from "zod";
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-let _catalog = null;
-function loadCatalog() {
-    if (_catalog)
-        return _catalog;
-    try {
-        const catalogPath = join(__dirname, "toolCatalog.json");
-        const raw = readFileSync(catalogPath, "utf-8");
-        _catalog = JSON.parse(raw);
-        return _catalog;
-    }
-    catch {
-        console.warn("[searchTools] Failed to load toolCatalog.json, using empty catalog");
-        _catalog = [];
-        return _catalog;
-    }
-}
-function cosineSimilarity(a, b) {
-    if (a.length === 0 || b.length === 0 || a.length !== b.length)
-        return 0;
-    let dot = 0;
-    for (let i = 0; i < a.length; i++) {
-        dot += a[i] * b[i];
-    }
-    return dot;
-}
-function searchByKeyword(query, limit) {
-    const catalog = loadCatalog();
-    const normalizedQuery = query.toLowerCase();
-    // Extract words, keeping short ones that might be meaningful (e.g., "ux", "js")
-    const queryWords = normalizedQuery
-        .split(/[\s_-]+/)
-        .filter((w) => w.length >= 2);
-    // Also check for the full query as a phrase
-    const queryPhrases = [normalizedQuery];
-    // Common synonyms and related terms
-    const synonyms = {
-        error: ["console", "js", "javascript", "bug", "crash", "exception"],
-        page: ["pages", "route", "url", "path"],
-        user: ["users", "session", "visitor"],
-        click: ["clicks", "tap", "press", "rage"],
-        form: ["forms", "input", "field", "submit"],
-        flow: ["flows", "journey", "funnel", "navigation", "path"],
-        issue: ["issues", "problem", "bug", "friction"],
-        fix: ["fixes", "remediation", "repair", "resolve"],
-        compare: ["comparison", "diff", "versus", "cohort"],
-        health: ["score", "metrics", "ux"],
-        dead: ["unresponsive", "broken", "stuck"],
-        rage: ["angry", "frustrated", "frustration"],
-    };
-    // Expand query words with synonyms
-    const expandedWords = new Set(queryWords);
-    for (const word of queryWords) {
-        if (synonyms[word]) {
-            synonyms[word].forEach((syn) => expandedWords.add(syn));
-        }
-        // Also check if query word is a synonym value
-        for (const [key, values] of Object.entries(synonyms)) {
-            if (values.includes(word)) {
-                expandedWords.add(key);
-            }
-        }
-    }
-    return catalog
-        .map((tool) => {
-        const toolName = tool.name.toLowerCase().replace(/_/g, " ");
-        const toolNameParts = tool.name.toLowerCase().split("_");
-        const text = `${toolName} ${tool.description} ${tool.category}`.toLowerCase();
-        let score = 0;
-        // Phrase match in description (highest value)
-        for (const phrase of queryPhrases) {
-            if (phrase.length > 3 && text.includes(phrase))
-                score += 5;
-        }
-        // Word matches
-        for (const word of expandedWords) {
-            // Exact word in tool name parts (e.g., "page" matches "get_page_metrics")
-            if (toolNameParts.includes(word))
-                score += 4;
-            // Word appears in tool name
-            if (toolName.includes(word))
-                score += 3;
-            // Category match
-            if (tool.category.toLowerCase() === word)
-                score += 2;
-            // Word in description
-            if (text.includes(word))
-                score += 1;
-        }
-        return { tool, score };
-    })
-        .filter((s) => s.score > 0)
-        .sort((a, b) => b.score - a.score)
-        .slice(0, limit)
-        .map((s) => s.tool);
-}
-async function searchBySemantic(query, limit, queryEmbedding) {
-    const catalog = loadCatalog();
-    return catalog
-        .filter((t) => t.embedding && t.embedding.length > 0)
-        .map((tool) => ({
-        tool,
-        score: cosineSimilarity(queryEmbedding, tool.embedding),
-    }))
-        .sort((a, b) => b.score - a.score)
-        .slice(0, limit)
-        .map((s) => s.tool);
-}
-export async function searchTools(query, limit = 5, queryEmbedding) {
-    if (queryEmbedding && queryEmbedding.length > 0) {
-        return searchBySemantic(query, limit, queryEmbedding);
-    }
-    return searchByKeyword(query, limit);
-}
-export function getToolByName(name) {
-    return loadCatalog().find((t) => t.name === name);
-}
-export function getAllTools() {
-    return loadCatalog();
-}
-const DEFAULT_TOOL_LIMIT = 5;
-const searchToolsSchema = z.object({
-    query: z
-        .string()
-        .describe("Natural language description of what data or analysis capability you need. " +
-        "Describe what you want to learn or investigate."),
-    limit: z
-        .number()
-        .optional()
-        .describe("Maximum number of tools to return (default 5)"),
-});
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function registerSearchTools(server) {
-    server.registerTool("search_tools", {
-        description: "Discover analysis tools by describing what data or capability you need. " +
-            "You have access to 40+ specialized tools covering sessions, pages, behaviors, journeys, " +
-            "forms, errors, performance, cohorts, issues, and remediation. Keyword search matches your intent to " +
-            "relevant tools. Returns tool names, descriptions, categories, and parameters. " +
-            "Use call_tool to execute discovered tools.",
-        inputSchema: searchToolsSchema,
-    }, async ({ query, limit }) => {
-        const searchLimit = limit ?? DEFAULT_TOOL_LIMIT;
-        const matches = await searchTools(query, searchLimit);
-        if (matches.length === 0) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({
-                            tools: [],
-                            message: "No matching tools found. Try rephrasing your query or use broader terms like 'page', 'session', 'issue', 'flow', or 'form'.",
-                        }),
-                    },
-                ],
-            };
-        }
-        const tools = matches.map((tool) => ({
-            name: tool.name,
-            description: tool.description.length > 250
-                ? tool.description.slice(0, 250) + "..."
-                : tool.description,
-            category: tool.category,
-            parameters: Object.entries(tool.parameters).map(([name, prop]) => ({
-                name,
-                type: prop.type,
-                required: prop.required ?? false,
-                description: prop.description,
-            })),
-        }));
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify({
-                        tools,
-                        usage: "Use call_tool with the tool name and arguments to execute. Example: call_tool({ tool_name: 'get_page_metrics', arguments: { page_path: '/checkout' } })",
-                    }),
-                },
-            ],
-        };
-    });
-}

package/dist/tools/compareCohorts.d.ts

@@ -1,6 +0,0 @@
-/**
- * compare_cohorts tool
- *
- * Compare two user cohorts side by side.
- */
-export declare function registerCompareCohorts(server: any): void;

package/dist/tools/compareCohorts.js

@@ -1,84 +0,0 @@
-/**
- * compare_cohorts tool
- *
- * Compare two user cohorts side by side.
- */
-import { z } from "zod";
-import { apiPost, isApiConfigured } from "../api/client.js";
-const cohortFilterSchema = z.object({
-    device: z
-        .enum(["desktop", "tablet", "mobile"])
-        .optional()
-        .describe("Filter by device type"),
-    outcome: z
-        .enum(["COMPLETED", "STRUGGLED", "BLOCKED", "DISENGAGED"])
-        .optional()
-        .describe("Filter by session outcome"),
-    pattern: z.string().optional().describe("Filter by behavioral pattern"),
-    page_path: z.string().optional().describe("Filter by page path"),
-    has_friction: z
-        .boolean()
-        .optional()
-        .describe("Filter for sessions with friction"),
-    has_rage_clicks: z
-        .boolean()
-        .optional()
-        .describe("Filter for sessions with rage clicks"),
-});
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function registerCompareCohorts(server) {
-    server.registerTool("compare_cohorts", {
-        description: "Compare two user cohorts side by side. Each cohort is defined by filter criteria: " +
-            "device (desktop/tablet/mobile), outcome (COMPLETED/STRUGGLED/BLOCKED/DISENGAGED), " +
-            "pattern, has_friction, has_rage_clicks, or page_path. " +
-            "Returns behavioral metrics for each cohort and statistically significant differences. " +
-            'Use this to answer "how do mobile users differ from desktop?", "what distinguishes ' +
-            'users who complete vs abandon?", or "do form users struggle more than non-form users?"',
-        inputSchema: z.object({
-            cohort_a: cohortFilterSchema.describe('Filters for cohort A, e.g. {"device": "mobile"} or {"outcome": "COMPLETED"}'),
-            cohort_b: cohortFilterSchema.describe('Filters for cohort B, e.g. {"device": "desktop"} or {"outcome": "BLOCKED"}'),
-            cohort_a_label: z
-                .string()
-                .optional()
-                .describe("Human label for cohort A"),
-            cohort_b_label: z
-                .string()
-                .optional()
-                .describe("Human label for cohort B"),
-            page_path: z
-                .string()
-                .optional()
-                .describe("Scope comparison to a specific page"),
-            date_from: z.string().optional().describe("Start date (ISO format)"),
-            date_to: z.string().optional().describe("End date (ISO format)"),
-        }),
-    }, async ({ cohort_a, cohort_b, cohort_a_label, cohort_b_label, page_path, date_from, date_to, }) => {
-        if (!isApiConfigured()) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({ error: "API not configured" }),
-                    },
-                ],
-                isError: true,
-            };
-        }
-        const { data, error } = await apiPost("/cohorts/compare", {
-            cohort_a,
-            cohort_b,
-            cohort_a_label,
-            cohort_b_label,
-            page_path,
-            date_from,
-            date_to,
-        });
-        if (error) {
-            return {
-                content: [{ type: "text", text: JSON.stringify({ error }) }],
-                isError: true,
-            };
-        }
-        return { content: [{ type: "text", text: JSON.stringify(data) }] };
-    });
-}

package/dist/tools/comparePeriods.d.ts

@@ -1,6 +0,0 @@
-/**
- * compare_periods tool
- *
- * Compare metrics between two time periods for a page.
- */
-export declare function registerComparePeriods(server: any): void;

package/dist/tools/comparePeriods.js

@@ -1,54 +0,0 @@
-/**
- * compare_periods tool
- *
- * Compare metrics between two time periods for a page.
- */
-import { z } from "zod";
-import { apiPost, isApiConfigured } from "../api/client.js";
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function registerComparePeriods(server) {
-    server.registerTool("compare_periods", {
-        description: "Compare behavioral metrics between two time periods for a specific page. " +
-            "Returns metrics for each period and the deltas between them. " +
-            "Use this to measure the impact of changes or compare week-over-week performance.",
-        inputSchema: z.object({
-            page_path: z.string().describe("Page path to compare"),
-            period_a: z
-                .object({
-                from: z.string().describe("Start date for period A (ISO format)"),
-                to: z.string().describe("End date for period A (ISO format)"),
-            })
-                .describe("First time period"),
-            period_b: z
-                .object({
-                from: z.string().describe("Start date for period B (ISO format)"),
-                to: z.string().describe("End date for period B (ISO format)"),
-            })
-                .describe("Second time period"),
-        }),
-    }, async ({ page_path, period_a, period_b, }) => {
-        if (!isApiConfigured()) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({ error: "API not configured" }),
-                    },
-                ],
-                isError: true,
-            };
-        }
-        const { data, error } = await apiPost("/pages/compare-periods", {
-            page_path,
-            period_a,
-            period_b,
-        });
-        if (error) {
-            return {
-                content: [{ type: "text", text: JSON.stringify({ error }) }],
-                isError: true,
-            };
-        }
-        return { content: [{ type: "text", text: JSON.stringify(data) }] };
-    });
-}

package/dist/tools/detectDrift.d.ts

@@ -1,6 +0,0 @@
-/**
- * detect_drift tool
- *
- * Detect behavioral drift over time.
- */
-export declare function registerDetectDrift(server: any): void;