@recapt/mcp 0.0.4-beta → 0.0.6-beta

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,194 @@
+/**
+ * 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' } })",
+                    }),
+                },
+            ],
+        };
+    });
+}