@recapt/mcp 0.0.4-beta → 0.0.6-beta

package/dist/index.js

@@ -3,62 +3,216 @@
  * MCP Server entry point.
  *
  * Exposes recapt behavioral intelligence as tools for AI coding agents.
- * Acts as a thin proxy to external-api query endpoints.
+ * Uses a search_tools + call_tool pattern to minimize context while
+ * providing access to 40+ analysis tools.
+ *
+ * Exposed tools (10):
+ * - search_tools: Discover tools by intent
+ * - call_tool: Execute discovered tools
+ * - get_domains: List tracked domains
+ * - run_full_diagnostic: Self-healing entry point
+ * - triage_sessions: Find sessions needing attention
+ * - memory_save, memory_recall, memory_list, memory_delete, memory_clear
+ *
+ * Hidden tools (38): Accessible via call_tool after discovery with search_tools
  */
 import "dotenv/config";
 // @ts-ignore - MCP SDK types are complex
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 // @ts-ignore - MCP SDK types are complex
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { isApiConfigured, getApiUrl } from "./api/client.js";
-import { registerGetPageMetrics } from "./tools/getPageMetrics.js";
-import { registerGetElementFriction } from "./tools/getElementFriction.js";
-import { registerSearchSessions } from "./tools/searchSessions.js";
-import { registerGetIssues } from "./tools/getIssues.js";
-import { registerGetSessionDetails } from "./tools/getSessionDetails.js";
-import { registerGetPageTrends } from "./tools/getPageTrends.js";
-import { registerGetAnomalies } from "./tools/getAnomalies.js";
+import { isApiConfigured, getApiUrl, apiGet, apiPost, apiPatch, apiDelete, } from "./api/client.js";
+import { registerSearchTools, registerCallTool, registerToolHandler, } from "./tools/catalog/index.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Exposed Tools - Registered directly with the MCP server
+// ─────────────────────────────────────────────────────────────────────────────
 import { registerGetDomains } from "./tools/getDomains.js";
-import { registerGetActionableIssues } from "./tools/getActionableIssues.js";
-import { registerGetUxHealthReport } from "./tools/getUxHealthReport.js";
-import { registerAnalyzeFlow } from "./tools/analyzeFlow.js";
-import { registerAnalyzeFunnel } from "./tools/analyzeFunnel.js";
-import { registerGetFlowFriction } from "./tools/getFlowFriction.js";
-import { registerGetJourneyPatterns } from "./tools/getJourneyPatterns.js";
-import { registerGetDeadClicks } from "./tools/getDeadClicks.js";
-import { registerGetConsoleErrors } from "./tools/getConsoleErrors.js";
-import { registerCompareCohorts } from "./tools/compareCohorts.js";
-import { registerDetectRegressions } from "./tools/detectRegressions.js";
-import { registerDiscoverPersonas } from "./tools/discoverPersonas.js";
-import { registerGetFormFriction } from "./tools/getFormFriction.js";
-import { registerScanSite } from "./tools/scanSite.js";
-import { registerListPages } from "./tools/listPages.js";
-import { registerComparePeriods } from "./tools/comparePeriods.js";
-import { registerDetectDrift } from "./tools/detectDrift.js";
-import { registerPredictOutcomes } from "./tools/predictOutcomes.js";
 import { registerMemoryTools } from "./tools/memory.js";
-import { registerListSessions } from "./tools/listSessions.js";
 import { registerTriageSessions } from "./tools/triageSessions.js";
 import { registerDiagnosticTools } from "./tools/diagnostic.js";
-import { registerTriageTools } from "./tools/triage.js";
-import { registerRemediationTools } from "./tools/remediation.js";
-import { registerKnowledgeTools } from "./tools/knowledge.js";
-async function main() {
-    console.error("[MCP] Starting recapt behavioral intelligence server...");
-    if (!isApiConfigured()) {
-        console.error("[MCP] ERROR: RECAPT_SECRET_KEY environment variable is required");
-        process.exit(1);
-    }
-    console.error(`[MCP] API URL: ${getApiUrl()}`);
-    const server = new McpServer({
-        name: "recapt",
-        version: "1.0.0",
-    }, {
-        capabilities: { logging: {} },
-        instructions: `# Recapt Behavioral Intelligence
+// ─────────────────────────────────────────────────────────────────────────────
+// Hidden Tool Handlers - Registered with call_tool registry
+// ─────────────────────────────────────────────────────────────────────────────
+function createApiHandler(method, endpoint, buildParams) {
+    return async (args) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const url = typeof endpoint === "function" ? endpoint(args) : endpoint;
+        const params = buildParams ? buildParams(args) : args;
+        let result;
+        switch (method) {
+            case "GET":
+                result = await apiGet(url, params);
+                break;
+            case "POST":
+                result = await apiPost(url, params);
+                break;
+            case "PATCH":
+                result = await apiPatch(url, params);
+                break;
+            case "DELETE":
+                result = await apiDelete(url);
+                break;
+        }
+        if (result.error) {
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({ error: result.error }) },
+                ],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(result.data) }] };
+    };
+}
+function registerHiddenTools() {
+    // Page Analysis
+    registerToolHandler("get_page_metrics", createApiHandler("GET", "/pages"));
+    registerToolHandler("get_element_friction", createApiHandler("GET", "/elements"));
+    registerToolHandler("get_page_trends", createApiHandler("GET", "/trends"));
+    registerToolHandler("get_dead_clicks", createApiHandler("GET", "/dead-clicks"));
+    registerToolHandler("get_console_errors", createApiHandler("GET", "/console-errors"));
+    registerToolHandler("get_form_friction", createApiHandler("GET", "/forms/friction"));
+    registerToolHandler("list_pages", createApiHandler("GET", "/pages/list"));
+    registerToolHandler("scan_site", createApiHandler("GET", "/site/overview", (args) => ({
+        top_n: args.top_n ?? 10,
+        offset: args.offset ?? 0,
+    })));
+    registerToolHandler("get_ux_health_report", createApiHandler("GET", "/health-report"));
+    // Flow Analysis
+    registerToolHandler("analyze_flow", createApiHandler("POST", "/flows/analyze"));
+    registerToolHandler("analyze_funnel", createApiHandler("POST", "/flows/funnel"));
+    registerToolHandler("get_flow_friction", createApiHandler("GET", "/flow-friction"));
+    registerToolHandler("get_journey_patterns", createApiHandler("GET", "/flows/patterns"));
+    // Issue Detection
+    registerToolHandler("get_issues", createApiHandler("GET", "/issues"));
+    registerToolHandler("get_actionable_issues", createApiHandler("GET", "/actionable-issues"));
+    registerToolHandler("get_anomalies", createApiHandler("GET", "/anomalies"));
+    registerToolHandler("detect_regressions", createApiHandler("GET", "/regressions"));
+    registerToolHandler("detect_drift", createApiHandler("GET", "/drift"));
+    // Comparison & Segmentation
+    registerToolHandler("compare_cohorts", createApiHandler("POST", "/cohorts/compare"));
+    registerToolHandler("compare_periods", createApiHandler("POST", "/pages/compare-periods"));
+    registerToolHandler("discover_personas", createApiHandler("GET", "/personas"));
+    // Session Analysis
+    registerToolHandler("search_sessions", createApiHandler("POST", "/sessions/search"));
+    registerToolHandler("list_sessions", createApiHandler("GET", "/sessions"));
+    registerToolHandler("get_session_details", async (args) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { session_id, session_ids } = args;
+        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) }] };
+    });
+    registerToolHandler("predict_outcomes", createApiHandler("POST", "/predict"));
+    // Diagnostic (investigate_issue and validate_issue - run_full_diagnostic is exposed)
+    registerToolHandler("investigate_issue", createApiHandler("GET", (args) => `/issues/${args.issue_id}/investigate`, (args) => ({ days: args.days ?? 7 })));
+    registerToolHandler("validate_issue", createApiHandler("POST", (args) => `/issues/${args.issue_id}/validate`, (args) => ({ lookback_days: args.lookback_days ?? 3 })));
+    // Triage
+    registerToolHandler("dismiss_issue", createApiHandler("POST", (args) => `/issues/${args.issue_id}/dismiss`, (args) => ({
+        reason: args.reason,
+        explanation: args.explanation,
+        create_knowledge: args.create_knowledge ?? true,
+    })));
+    registerToolHandler("mark_intended_behavior", createApiHandler("POST", (args) => `/issues/${args.issue_id}/mark-intended`, (args) => ({ explanation: args.explanation })));
+    registerToolHandler("get_issue_history", createApiHandler("GET", (args) => `/issues/${args.issue_id}/history`));
+    // Remediation
+    registerToolHandler("propose_fix", createApiHandler("POST", "/remediations"));
+    registerToolHandler("list_pending_fixes", createApiHandler("GET", "/remediations/pending"));
+    registerToolHandler("list_remediations", createApiHandler("GET", "/remediations"));
+    registerToolHandler("confirm_deployment", createApiHandler("PATCH", (args) => `/remediations/${args.remediation_id}/deploy`, () => ({})));
+    registerToolHandler("evaluate_fix", createApiHandler("POST", (args) => `/remediations/${args.remediation_id}/evaluate`, (args) => ({ min_hours: args.min_hours ?? 24 })));
+    registerToolHandler("get_fix_history", createApiHandler("GET", (args) => `/remediations/history/${args.issue_id}`));
+    // Knowledge
+    registerToolHandler("get_site_knowledge", createApiHandler("GET", "/knowledge"));
+    registerToolHandler("add_site_knowledge", createApiHandler("POST", "/knowledge", (args) => ({
+        ...args,
+        source: "agent",
+    })));
+    registerToolHandler("delete_site_knowledge", createApiHandler("DELETE", (args) => `/knowledge/${args.knowledge_id}`));
+    registerToolHandler("get_similar_fixes", createApiHandler("GET", "/knowledge/similar-fixes"));
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Server Instructions
+// ─────────────────────────────────────────────────────────────────────────────
+const SERVER_INSTRUCTIONS = `# Recapt Behavioral Intelligence
 
 This server provides behavioral data from session recordings. Use these tools to understand user behavior, identify UX issues, and find friction points.
 
+## Tool Discovery Pattern
+
+You have access to 40+ analysis tools. Most are hidden to reduce context size. Use this pattern:
+
+1. **search_tools(query)** — Describe what you need in natural language
+2. **call_tool(tool_name, arguments)** — Execute the discovered tool
+
+Example:
+\`\`\`
+search_tools({ query: "analyze user navigation between pages" })
+→ Returns: analyze_flow, analyze_funnel, get_journey_patterns...
+
+call_tool({ tool_name: "analyze_flow", arguments: { start_page: "/pricing", end_page: "/checkout" } })
+→ Returns: flow analysis with paths, bottlenecks, friction scores
+\`\`\`
+
+## Always-Available Tools
+
+These tools are always visible (no search needed):
+- **get_domains** — List tracked domains (good starting point)
+- **run_full_diagnostic** — Comprehensive site analysis with prioritized issues
+- **triage_sessions** — Find sessions needing attention
+- **memory_*** — Store/retrieve intermediate results
+
 ## Metric Interpretation
 
 All behavioral scores are 0-1 where higher = more of that signal:
@@ -69,232 +223,51 @@ All behavioral scores are 0-1 where higher = more of that signal:
 - **drop_off_rate** > 0.3: Major leak point in a flow
 - **spike_ratio** > 2: Critical frustration spike, likely recent regression
 
-## Tool Orchestration Strategies
-
-### Starting point - understand the landscape
-1. Use \`scan_site\` or \`list_pages\` to see all tracked pages with health grades
-2. Use \`get_ux_health_report\` for a comprehensive overview combining metrics, issues, and anomalies
-3. Use \`get_domains\` to see which domains are being tracked
-
-### Diagnosing a problematic page
-1. Start with \`get_page_metrics\` to see overall behavioral scores
-2. If frustration high → \`get_element_friction\` to find specific problematic elements
-3. If confusion high → \`get_dead_clicks\` to find misleading UI elements users click expecting action
-4. Check \`get_console_errors\` for JS errors that may cause unresponsiveness
-5. Use \`get_form_friction\` if the page has forms to find problematic fields
-
-### Understanding user flows
-1. \`get_journey_patterns\` for organic navigation discovery (where do users go?)
-2. \`analyze_flow\` between specific pages to see paths, bottlenecks, and friction
-3. \`analyze_funnel\` for conversion analysis through defined steps (cart → checkout → payment)
-4. \`get_flow_friction\` to automatically discover high-friction flows
-
-### Finding issues to fix
-1. \`get_issues\` for auto-detected problems (rage clicks, dead clicks, errors)
-2. \`get_actionable_issues\` for issues with element context
-3. \`detect_regressions\` to find recent degradations (compare last 24h vs baseline)
-4. \`get_anomalies\` for unusual sessions and frustration spikes
-
-### Comparing segments
-1. \`compare_cohorts\` to understand differences (mobile vs desktop, completed vs abandoned)
-2. \`compare_periods\` to measure impact of changes (before vs after deployment)
-3. \`discover_personas\` to find behavioral user segments
-
-### Deep-diving a session
-1. \`search_sessions\` with natural language to find relevant sessions
-2. \`list_sessions\` to browse by domain, status, or device
-3. \`get_session_details\` for behavioral timeline of a specific session
-
-### Monitoring over time
-1. \`get_page_trends\` for daily behavioral trends on a page
-2. \`detect_drift\` for gradual behavioral changes over weeks
-3. \`detect_regressions\` for sudden changes (deployment impact)
-
 ## Reasoning Tips
 
-- High rage clicks on body/root elements often indicate JS errors preventing interaction - check \`get_console_errors\`
-- Backtrack hotspots (pages users return to repeatedly) suggest confusion or errors on subsequent pages
-- Drop-off pages may be intentional exits (thank you page) or problems - check if it's a terminal page
-- Compare frustration across device types with \`compare_cohorts\` - mobile often has different issues
-- When frustration spikes recently, use \`detect_regressions\` to correlate with deployments
-- Low confidence + high confusion = users don't understand what to do next
-- High frustration + low confusion = users know what to do but can't (broken UI, errors)
+- High rage clicks on body/root elements often indicate JS errors - search "console errors"
+- Backtrack hotspots suggest confusion on subsequent pages
+- Low confidence + high confusion = users don't understand what to do
+- High frustration + low confusion = users know what to do but can't (broken UI)
 - Use \`memory_save\` to store intermediate results when doing multi-step analysis
 
-## Available Tools
-
-### Site Overview
-- \`get_domains\`: List configured domains
-- \`scan_site\`: Quick health scan of top pages
-- \`list_pages\`: List all tracked pages with metrics
-- \`get_ux_health_report\`: Comprehensive health report
-
-### Page Analysis
-- \`get_page_metrics\`: Behavioral metrics for a page
-- \`get_element_friction\`: Per-element friction data
-- \`get_page_trends\`: Daily trends over time
-- \`get_dead_clicks\`: Unresponsive elements users click
-- \`get_console_errors\`: JavaScript errors
-- \`get_form_friction\`: Form field friction analysis
-
-### Flow Analysis
-- \`analyze_flow\`: Navigation between specific pages
-- \`analyze_funnel\`: Conversion through page sequence
-- \`get_flow_friction\`: Discover high-friction flows
-- \`get_journey_patterns\`: Navigation patterns and hotspots
-
-### Issue Detection
-- \`get_issues\`: Auto-detected UX issues
-- \`get_actionable_issues\`: Issues with element context
-- \`get_anomalies\`: Unusual sessions and spikes
-- \`detect_regressions\`: Recent degradations
-
-### Comparison & Segmentation
-- \`compare_cohorts\`: Compare user segments
-- \`compare_periods\`: Compare time periods
-- \`discover_personas\`: Behavioral clustering
-- \`detect_drift\`: Long-term behavioral changes
-
-### Session Analysis
-- \`search_sessions\`: Natural language session search
-- \`list_sessions\`: Filter sessions by criteria
-- \`get_session_details\`: Session behavioral timeline
-- \`predict_outcomes\`: Predict session outcomes
-- \`triage_sessions\`: Auto-triage sessions with compromised UX
-
-### Session Triage
-Use \`triage_sessions\` to automatically identify sessions that need attention:
-- Surfaces sessions with user comments (direct feedback)
-- Flags high-frustration sessions with rage clicks
-- Includes console errors as evidence
-- Returns replay URLs for quick investigation
-
-Severity levels:
-- **critical**: triage_score >= 0.7 OR has comment + high frustration
-- **high**: triage_score >= 0.5
-- **medium**: triage_score >= 0.3
-- **low**: triage_score < 0.3
-
-When triaging, prioritize:
-1. Sessions with user comments (explicit feedback is gold)
-2. Critical severity with rage clicks (users actively struggling)
-3. Sessions with console errors + high frustration (likely bugs)
-
-### Working Memory
-- \`memory_save\`, \`memory_recall\`, \`memory_list\`, \`memory_delete\`, \`memory_clear\`: Store and retrieve intermediate results
-
-## Self-Healing Workflow
-
-When asked to "fix all issues", "heal the site", or "improve my site via recapt":
-
-### 1. Full Diagnostic
-- Call \`run_full_diagnostic\` to get prioritized issue list with severity scores
-- Call \`get_site_knowledge\` to load known false positives and intended behaviors
-- Review the \`recommended_investigation_order\` to prioritize your work
-
-### 2. Triage Each Issue
-For each issue in priority order, determine if it's actionable:
-- Call \`validate_issue\` to check if still occurring (not stale)
-- Check against site knowledge for known false positives
-- If recommendation is "dismiss_stale", consider dismissing
-- If uncertain, call \`investigate_issue\` for deep context
-- **Always ask user to confirm** if behavior is intended when unclear
-
-### 3. Propose Fixes
-For confirmed issues:
-- Analyze root cause from evidence and element context
-- Call \`get_similar_fixes\` to see what worked before for similar issues
-- Call \`get_fix_history\` to see past attempts on this specific issue
-- Call \`propose_fix\` with detailed diagnosis and code suggestion
-- Explain confidence level and reasoning to user
-- **Ask for confirmation when confidence < 0.7**
-
-### 4. Track Deployments
-- Show user all pending fixes with \`list_pending_fixes\`
-- When user confirms "I have deployed this fix", call \`confirm_deployment\`
-- Explain that evaluation will happen after 24-48 hours of data collection
-
-### 5. Evaluate Results
-- After deployment window (24-48h), call \`evaluate_fix\`
-- If outcome is "success": celebrate, the issue will be auto-resolved
-- If outcome is "partial": discuss with user whether to iterate
-- If outcome is "failed": analyze why, propose alternative approach
-- Store learnings with \`add_site_knowledge\` for future reference
-
-### Evaluation Thresholds
-- **Success**: frustration decreased >15% OR health score increased >10 points
-- **Partial**: frustration decreased 5-15% OR health score increased 3-10 points
-- **Failed**: no improvement or regression
-
-### Asking for Confirmation
-Always ask user before:
-- Dismissing an issue as false positive
-- Marking behavior as intended
-- When confidence in fix is <0.7
-- Before evaluating (ensure they've actually deployed)
-
-### Self-Healing Tools
-
-#### Diagnostic
-- \`run_full_diagnostic\`: Comprehensive site analysis with prioritized issues
-- \`investigate_issue\`: Deep-dive into specific issue with sessions and errors
-- \`validate_issue\`: Check if issue is still occurring (not stale)
-
-#### Triage
-- \`dismiss_issue\`: Mark issue as false positive with reason
-- \`mark_intended_behavior\`: Flag behavior as by design
-- \`get_issue_history\`: View past occurrences and fix attempts
-
-#### Remediation
-- \`propose_fix\`: Create remediation record with baseline metrics
-- \`list_pending_fixes\`: Show fixes awaiting deployment
-- \`list_remediations\`: Browse all remediation records
-- \`confirm_deployment\`: Mark fix as deployed, start evaluation timer
-- \`evaluate_fix\`: Compare post-deploy metrics to baseline
-- \`get_fix_history\`: View all fix attempts for an issue
-
-#### Knowledge
-- \`get_site_knowledge\`: Retrieve learned patterns and false positives
-- \`add_site_knowledge\`: Store new learning for future reference
-- \`delete_site_knowledge\`: Remove outdated knowledge
-- \`get_similar_fixes\`: Find past fixes for similar issues`,
+## Installable Skills
+
+For guided workflows (self-healing, deep-dive analysis, regression hunting), install recapt skills:
+\`\`\`bash
+npx @recapt/mcp skill list
+npx @recapt/mcp skill install self-healing
+\`\`\`
+Skills provide step-by-step guidance for complex multi-tool workflows.`;
+// ─────────────────────────────────────────────────────────────────────────────
+// Main
+// ─────────────────────────────────────────────────────────────────────────────
+async function main() {
+    console.error("[MCP] Starting recapt behavioral intelligence server...");
+    if (!isApiConfigured()) {
+        console.error("[MCP] ERROR: RECAPT_SECRET_KEY environment variable is required");
+        process.exit(1);
+    }
+    console.error(`[MCP] API URL: ${getApiUrl()}`);
+    const server = new McpServer({
+        name: "recapt",
+        version: "1.0.0",
+    }, {
+        capabilities: { logging: {} },
+        instructions: SERVER_INSTRUCTIONS,
     });
+    // Register hidden tool handlers first (for call_tool to use)
+    registerHiddenTools();
+    // Register exposed tools
+    registerSearchTools(server);
+    registerCallTool(server);
     registerGetDomains(server);
-    registerGetPageMetrics(server);
-    registerGetElementFriction(server);
-    registerSearchSessions(server);
-    registerGetIssues(server);
-    registerGetSessionDetails(server);
-    registerGetPageTrends(server);
-    registerGetAnomalies(server);
-    registerGetActionableIssues(server);
-    registerGetUxHealthReport(server);
-    registerAnalyzeFlow(server);
-    registerAnalyzeFunnel(server);
-    registerGetFlowFriction(server);
-    registerGetJourneyPatterns(server);
-    registerGetDeadClicks(server);
-    registerGetConsoleErrors(server);
-    registerCompareCohorts(server);
-    registerDetectRegressions(server);
-    registerDiscoverPersonas(server);
-    registerGetFormFriction(server);
-    registerScanSite(server);
-    registerListPages(server);
-    registerComparePeriods(server);
-    registerDetectDrift(server);
-    registerPredictOutcomes(server);
-    registerMemoryTools(server);
-    registerListSessions(server);
+    registerDiagnosticTools(server); // Includes run_full_diagnostic
     registerTriageSessions(server);
-    // Self-healing tools
-    registerDiagnosticTools(server);
-    registerTriageTools(server);
-    registerRemediationTools(server);
-    registerKnowledgeTools(server);
+    registerMemoryTools(server);
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error("[MCP] Server running on stdio");
+    console.error("[MCP] Server running on stdio (10 exposed tools, 38 hidden)");
 }
 main().catch((err) => {
     console.error("[MCP] Fatal error:", err);

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

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

@@ -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";