@recapt/mcp 0.0.3-beta → 0.0.5-beta

package/dist/tools/catalog/callTool.js

@@ -0,0 +1,92 @@
+/**
+ * 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

@@ -0,0 +1,11 @@
+/**
+ * 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

@@ -0,0 +1,11 @@
+/**
+ * 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

@@ -0,0 +1,22 @@
+/**
+ * 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

@@ -0,0 +1,149 @@
+/**
+ * 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 queryWords = query
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((w) => w.length > 2);
+    return catalog
+        .map((tool) => {
+        const text = `${tool.name} ${tool.description} ${tool.category}`.toLowerCase();
+        let score = 0;
+        for (const word of queryWords) {
+            if (text.includes(word))
+                score += 1;
+            if (tool.name.toLowerCase().includes(word))
+                score += 2;
+            if (tool.category.toLowerCase() === 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/diagnostic.d.ts

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

package/dist/tools/diagnostic.js

@@ -0,0 +1,102 @@
+/**
+ * Diagnostic tools for self-healing 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: "Run a comprehensive site diagnostic. Returns prioritized issues, problem pages, regressions, and recommended investigation order. Use this as the first step in a self-healing workflow.",
+        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.",
+        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/knowledge.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Knowledge tools for self-healing workflow.
+ *
+ * Provides site-specific knowledge management for learning from past fixes.
+ */
+export declare function registerKnowledgeTools(server: any): void;

package/dist/tools/knowledge.js

@@ -0,0 +1,186 @@
+/**
+ * Knowledge tools for self-healing workflow.
+ *
+ * Provides site-specific knowledge management for learning from past fixes.
+ */
+import { z } from "zod";
+import { apiGet, apiPost, apiDelete, isApiConfigured } from "../api/client.js";
+const KNOWLEDGE_CATEGORIES = [
+    "false_positive",
+    "intended_behavior",
+    "fix_pattern",
+    "context",
+];
+const ISSUE_CATEGORIES = [
+    "code_error",
+    "dead_click",
+    "rage_click",
+    "ux_friction",
+    "performance",
+    "form_issue",
+    "behavioral_anomaly",
+    "structural_issue",
+];
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerKnowledgeTools(server) {
+    server.registerTool("get_site_knowledge", {
+        description: "Retrieve site-specific learnings including known false positives, intended behaviors, and successful fix patterns. Use at the start of a self-healing workflow to avoid re-flagging known issues.",
+        inputSchema: z.object({
+            category: z
+                .enum(KNOWLEDGE_CATEGORIES)
+                .optional()
+                .describe("Filter by knowledge category"),
+            page_path: z.string().optional().describe("Filter by page path"),
+            issue_category: z
+                .enum(ISSUE_CATEGORIES)
+                .optional()
+                .describe("Filter by issue category"),
+            limit: z
+                .number()
+                .optional()
+                .default(50)
+                .describe("Maximum number of entries to return (default: 50)"),
+        }),
+    }, async ({ category, page_path, issue_category, limit, }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiGet("/knowledge", {
+            category,
+            page_path,
+            issue_category,
+            limit: limit ?? 50,
+        });
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
+    server.registerTool("add_site_knowledge", {
+        description: "Store a site-specific learning. Use to record false positives, intended behaviors, successful fix patterns, or important context about the site.",
+        inputSchema: z.object({
+            category: z
+                .enum(KNOWLEDGE_CATEGORIES)
+                .describe("Category of knowledge: false_positive, intended_behavior, fix_pattern, or context"),
+            subject: z
+                .string()
+                .describe("Unique identifier/title for this knowledge entry"),
+            content: z.string().describe("Detailed description of the learning"),
+            page_path: z
+                .string()
+                .optional()
+                .describe("Associated page path (if applicable)"),
+            element_selector: z
+                .string()
+                .optional()
+                .describe("Associated element selector (if applicable)"),
+            issue_category: z
+                .enum(ISSUE_CATEGORIES)
+                .optional()
+                .describe("Associated issue category (if applicable)"),
+        }),
+    }, async ({ category, subject, content, page_path, element_selector, issue_category, }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiPost("/knowledge", {
+            category,
+            subject,
+            content,
+            page_path,
+            element_selector,
+            issue_category,
+            source: "agent",
+        });
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
+    server.registerTool("delete_site_knowledge", {
+        description: "Delete a site knowledge entry. Use when a learning is no longer valid or was created in error.",
+        inputSchema: z.object({
+            knowledge_id: z
+                .string()
+                .describe("The ID of the knowledge entry to delete"),
+        }),
+    }, async ({ knowledge_id }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiDelete(`/knowledge/${knowledge_id}`);
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
+    server.registerTool("get_similar_fixes", {
+        description: "Find past fixes for similar issues. Returns successful and failed remediation attempts for issues with the same category, page, or element. Use before proposing a fix to learn from past attempts.",
+        inputSchema: z.object({
+            issue_id: z
+                .string()
+                .describe("The ID of the issue to find similar fixes for"),
+            limit: z
+                .number()
+                .optional()
+                .default(5)
+                .describe("Maximum number of similar fixes to return (default: 5)"),
+        }),
+    }, async ({ issue_id, limit }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiGet("/knowledge/similar-fixes", {
+            issue_id,
+            limit: limit ?? 5,
+        });
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
+}

package/dist/tools/remediation.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Remediation tools for self-healing workflow.
+ *
+ * Provides fix proposal, deployment confirmation, evaluation, and history tracking.
+ */
+export declare function registerRemediationTools(server: any): void;