@recapt/mcp 0.0.18-beta → 0.0.20-beta

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;

package/dist/tools/detectDrift.js

@@ -1,55 +0,0 @@
-/**
- * detect_drift tool
- *
- * Detect behavioral drift over time.
- */
-import { z } from "zod";
-import { apiGet, isApiConfigured } from "../api/client.js";
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function registerDetectDrift(server) {
-    server.registerTool("detect_drift", {
-        description: "Detect behavioral drift over time by analyzing how user behavior patterns change. " +
-            "Splits data into time windows and measures centroid shift between consecutive periods. " +
-            "Use this for long-term monitoring to detect gradual UX degradation.",
-        inputSchema: z.object({
-            page_path: z
-                .string()
-                .optional()
-                .describe("Scope drift detection to a specific page"),
-            days: z
-                .number()
-                .optional()
-                .default(30)
-                .describe("Number of days to analyze (default 30)"),
-            window_size: z
-                .number()
-                .optional()
-                .default(7)
-                .describe("Size of each time window in days (default 7)"),
-        }),
-    }, async ({ page_path, days, window_size, }) => {
-        if (!isApiConfigured()) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({ error: "API not configured" }),
-                    },
-                ],
-                isError: true,
-            };
-        }
-        const { data, error } = await apiGet("/drift", {
-            page_path,
-            days: days ?? 30,
-            window_size: window_size ?? 7,
-        });
-        if (error) {
-            return {
-                content: [{ type: "text", text: JSON.stringify({ error }) }],
-                isError: true,
-            };
-        }
-        return { content: [{ type: "text", text: JSON.stringify(data) }] };
-    });
-}

package/dist/tools/detectRegressions.d.ts

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

package/dist/tools/detectRegressions.js

@@ -1,63 +0,0 @@
-/**
- * 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 against rolling 7-day baselines. " +
-            "By default analyzes top 50 pages by traffic. Use sort_by='low_traffic' to check low-traffic " +
-            "pages that might otherwise be missed. Use offset/limit to paginate through all pages. " +
-            "Returns pages where frustration, confusion, or rage click rate have deviated significantly.",
-        inputSchema: z.object({
-            window_hours: z
-                .number()
-                .optional()
-                .default(24)
-                .describe("How many recent hours to compare against baseline (default 24)"),
-            limit: z
-                .number()
-                .optional()
-                .default(50)
-                .describe("Number of pages to check per request (default 50, max 100)"),
-            offset: z
-                .number()
-                .optional()
-                .default(0)
-                .describe("Skip this many pages for pagination (default 0)"),
-            sort_by: z
-                .enum(["traffic", "low_traffic"])
-                .optional()
-                .default("traffic")
-                .describe("Sort order: 'traffic' (default) or 'low_traffic' to check overlooked pages"),
-        }),
-    }, async ({ window_hours, limit, offset, sort_by, }) => {
-        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,
-            limit: limit ?? 50,
-            offset: offset ?? 0,
-            sort_by: sort_by ?? "traffic",
-        });
-        if (error) {
-            return {
-                content: [{ type: "text", text: JSON.stringify({ error }) }],
-                isError: true,
-            };
-        }
-        return { content: [{ type: "text", text: JSON.stringify(data) }] };
-    });
-}

package/dist/tools/diagnostic.d.ts

@@ -1,6 +0,0 @@
-/**
- * Diagnostic tools for self-improvement workflow.
- *
- * Provides comprehensive site diagnostics, issue investigation, and validation.
- */
-export declare function registerDiagnosticTools(server: any): void;

package/dist/tools/diagnostic.js

@@ -1,109 +0,0 @@
-/**
- * Diagnostic tools for self-improvement workflow.
- *
- * Provides comprehensive site diagnostics, issue investigation, and validation.
- */
-import { z } from "zod";
-import { apiGet, apiPost, isApiConfigured } from "../api/client.js";
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function registerDiagnosticTools(server) {
-    server.registerTool("run_full_diagnostic", {
-        description: "Get a quick site health overview with prioritized issues and problem pages. " +
-            "This is a lightweight entry point — it does NOT include regression detection. " +
-            "For a complete analysis, call detect_regressions separately after this. " +
-            "Returns: health score, top issues, pages needing attention, and investigation order.",
-        inputSchema: z.object({
-            days: z
-                .number()
-                .optional()
-                .default(7)
-                .describe("Number of days to analyze (default: 7)"),
-        }),
-    }, async ({ days }) => {
-        if (!isApiConfigured()) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({ error: "API not configured" }),
-                    },
-                ],
-                isError: true,
-            };
-        }
-        const { data, error } = await apiGet("/diagnostic/full", { days: days ?? 7 });
-        if (error) {
-            return {
-                content: [{ type: "text", text: JSON.stringify({ error }) }],
-                isError: true,
-            };
-        }
-        return { content: [{ type: "text", text: JSON.stringify(data) }] };
-    });
-    server.registerTool("investigate_issue", {
-        description: "Deep-dive into a specific issue. Returns affected sessions, element friction data, " +
-            "related console errors, similar issues, and page context. Use after identifying an " +
-            "issue to understand root cause. NOTE: Free tier users get issue summary and page " +
-            "context only. Detailed investigation data (affected sessions, element friction, " +
-            "related errors) requires a paid plan (Starter+).",
-        inputSchema: z.object({
-            issue_id: z.string().describe("The ID of the issue to investigate"),
-            days: z
-                .number()
-                .optional()
-                .default(7)
-                .describe("Number of days to look back (default: 7)"),
-        }),
-    }, async ({ issue_id, days }) => {
-        if (!isApiConfigured()) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({ error: "API not configured" }),
-                    },
-                ],
-                isError: true,
-            };
-        }
-        const { data, error } = await apiGet(`/issues/${issue_id}/investigate`, { days: days ?? 7 });
-        if (error) {
-            return {
-                content: [{ type: "text", text: JSON.stringify({ error }) }],
-                isError: true,
-            };
-        }
-        return { content: [{ type: "text", text: JSON.stringify(data) }] };
-    });
-    server.registerTool("validate_issue", {
-        description: "Check if an issue is still actively occurring. Returns staleness info and recommendation (investigate, dismiss_stale, or monitor). Use to filter out stale issues before proposing fixes.",
-        inputSchema: z.object({
-            issue_id: z.string().describe("The ID of the issue to validate"),
-            lookback_days: z
-                .number()
-                .optional()
-                .default(3)
-                .describe("Number of days to look back for recent occurrences (default: 3)"),
-        }),
-    }, async ({ issue_id, lookback_days, }) => {
-        if (!isApiConfigured()) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({ error: "API not configured" }),
-                    },
-                ],
-                isError: true,
-            };
-        }
-        const { data, error } = await apiPost(`/issues/${issue_id}/validate`, { lookback_days: lookback_days ?? 3 });
-        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

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