@recapt/mcp 0.0.2-beta

package/dist/tools/scanSite.js

@@ -0,0 +1,51 @@
+/**
+ * scan_site tool
+ *
+ * One-shot site health scan across all pages.
+ */
+import { z } from "zod";
+import { apiGet, isApiConfigured } from "../api/client.js";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerScanSite(server) {
+    server.registerTool("scan_site", {
+        description: "One-shot site health scan. Lists all pages and computes aggregate metrics " +
+            "for the top-N pages (default 10) sorted by session count. Returns a ranked " +
+            "table with frustration and health grade per page. " +
+            "Use this as the FIRST tool when the user asks a broad question without naming a specific page.",
+        inputSchema: z.object({
+            top_n: z
+                .number()
+                .optional()
+                .default(10)
+                .describe("Number of top pages to analyze (default 10)"),
+            offset: z
+                .number()
+                .optional()
+                .default(0)
+                .describe("Skip first N pages for pagination (default 0)"),
+        }),
+    }, async ({ top_n, offset }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiGet("/site/overview", {
+            top_n: top_n ?? 10,
+            offset: offset ?? 0,
+        });
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
+}

package/dist/tools/searchSessions.d.ts

@@ -0,0 +1,6 @@
+/**
+ * search_sessions tool
+ *
+ * Search sessions by natural language query using vector search.
+ */
+export declare function registerSearchSessions(server: any): void;

package/dist/tools/searchSessions.js

@@ -0,0 +1,51 @@
+/**
+ * search_sessions tool
+ *
+ * Search sessions by natural language query using vector search.
+ */
+import { z } from "zod";
+import { apiPost, isApiConfigured } from "../api/client.js";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerSearchSessions(server) {
+    server.registerTool("search_sessions", {
+        description: 'Search sessions by natural language query. Examples: "frustrated users on checkout", "rage clicks on pricing page", "confused users who abandoned cart".',
+        inputSchema: z.object({
+            query: z
+                .string()
+                .describe("Natural language search query describing the sessions you want to find"),
+            page_path: z
+                .string()
+                .optional()
+                .describe("Optional: filter to a specific page path"),
+            limit: z
+                .number()
+                .optional()
+                .default(10)
+                .describe("Maximum number of sessions to return (default: 10)"),
+        }),
+    }, async ({ query, page_path, limit, }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiPost("/sessions/search", {
+            query,
+            page_path,
+            limit: limit ?? 10,
+        });
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
+}

package/dist/tools/triageSessions.d.ts

@@ -0,0 +1,8 @@
+/**
+ * triage_sessions tool
+ *
+ * Automatically triages sessions to find compromised user experiences.
+ * Analyzes user comments, frustration signals, rage clicks, and console errors.
+ * Thin proxy to external-api /sessions/triage endpoint.
+ */
+export declare function registerTriageSessions(server: any): void;

package/dist/tools/triageSessions.js

@@ -0,0 +1,195 @@
+/**
+ * triage_sessions tool
+ *
+ * Automatically triages sessions to find compromised user experiences.
+ * Analyzes user comments, frustration signals, rage clicks, and console errors.
+ * Thin proxy to external-api /sessions/triage endpoint.
+ */
+import { z } from "zod";
+import { apiGet, isApiConfigured } from "../api/client.js";
+function formatDuration(seconds) {
+    if (!seconds)
+        return "unknown";
+    if (seconds < 60)
+        return `${seconds}s`;
+    if (seconds < 3600)
+        return `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
+    const hours = Math.floor(seconds / 3600);
+    const mins = Math.floor((seconds % 3600) / 60);
+    return `${hours}h ${mins}m`;
+}
+function getActionReason(session) {
+    const reasons = [];
+    if (session.user_comments.length > 0) {
+        reasons.push(`USER FEEDBACK: ${session.user_comments.length} comment(s) - "${session.user_comments[0].text.slice(0, 100)}${session.user_comments[0].text.length > 100 ? "..." : ""}"`);
+    }
+    if (session.behavioral_signals.frustration >= 0.5) {
+        reasons.push(`HIGH FRUSTRATION: ${(session.behavioral_signals.frustration * 100).toFixed(0)}%`);
+    }
+    else if (session.behavioral_signals.frustration >= 0.3) {
+        reasons.push(`MODERATE FRUSTRATION: ${(session.behavioral_signals.frustration * 100).toFixed(0)}%`);
+    }
+    if (session.behavioral_signals.has_rage_clicks) {
+        reasons.push("RAGE CLICKS detected");
+    }
+    if (session.console_errors.length > 0) {
+        const errorCount = session.console_errors.reduce((sum, e) => sum + e.count, 0);
+        reasons.push(`JS ERRORS: ${errorCount} error(s) - "${session.console_errors[0].message.slice(0, 80)}..."`);
+    }
+    if (!session.behavioral_signals.has_behavioral_data) {
+        reasons.push("NOTE: No behavioral analysis data available for this session");
+    }
+    if (reasons.length === 0) {
+        reasons.push("Low severity - no major issues detected");
+    }
+    return reasons.join("\n  - ");
+}
+function formatTriageOutput(data) {
+    const lines = [];
+    // Summary
+    lines.push("# SESSION TRIAGE RESULTS\n");
+    lines.push(`Total sessions analyzed: ${data.summary.total_sessions}`);
+    lines.push(`Sessions with issues: ${data.summary.flagged_sessions}`);
+    lines.push(`Sessions with user comments: ${data.summary.sessions_with_comments}`);
+    if (data.sessions.length === 0) {
+        lines.push("\nNo sessions require attention.");
+        return lines.join("\n");
+    }
+    // Group by severity
+    const critical = data.sessions.filter((s) => s.severity === "critical");
+    const high = data.sessions.filter((s) => s.severity === "high");
+    const medium = data.sessions.filter((s) => s.severity === "medium");
+    const low = data.sessions.filter((s) => s.severity === "low");
+    lines.push("\n## PRIORITY SUMMARY");
+    lines.push(`- CRITICAL: ${critical.length} session(s) - investigate immediately`);
+    lines.push(`- HIGH: ${high.length} session(s) - investigate soon`);
+    lines.push(`- MEDIUM: ${medium.length} session(s) - review when possible`);
+    lines.push(`- LOW: ${low.length} session(s) - likely okay`);
+    // Action recommendations
+    lines.push("\n## RECOMMENDED ACTIONS\n");
+    if (critical.length > 0) {
+        lines.push("### CRITICAL - Investigate Immediately\n");
+        for (const s of critical) {
+            lines.push(`**Session ${s.session_id.slice(-8)}** (${formatDuration(s.duration_seconds)}, ${s.device})`);
+            lines.push(`  Replay: ${s.replay_url}`);
+            lines.push(`  Score: ${(s.triage_score * 100).toFixed(0)}%`);
+            lines.push(`  Why: ${getActionReason(s)}`);
+            if (s.pages_visited.length > 0) {
+                lines.push(`  Pages: ${s.pages_visited.slice(0, 3).join(", ")}${s.pages_visited.length > 3 ? ` (+${s.pages_visited.length - 3} more)` : ""}`);
+            }
+            lines.push("");
+        }
+    }
+    if (high.length > 0) {
+        lines.push("### HIGH - Investigate Soon\n");
+        for (const s of high) {
+            lines.push(`**Session ${s.session_id.slice(-8)}** (${formatDuration(s.duration_seconds)}, ${s.device})`);
+            lines.push(`  Replay: ${s.replay_url}`);
+            lines.push(`  Score: ${(s.triage_score * 100).toFixed(0)}%`);
+            lines.push(`  Why: ${getActionReason(s)}`);
+            if (s.pages_visited.length > 0) {
+                lines.push(`  Pages: ${s.pages_visited.slice(0, 3).join(", ")}${s.pages_visited.length > 3 ? ` (+${s.pages_visited.length - 3} more)` : ""}`);
+            }
+            lines.push("");
+        }
+    }
+    if (medium.length > 0) {
+        lines.push("### MEDIUM - Review When Possible\n");
+        for (const s of medium) {
+            lines.push(`- Session ${s.session_id.slice(-8)} (${formatDuration(s.duration_seconds)}): ${getActionReason(s).split("\n")[0]}`);
+            lines.push(`  ${s.replay_url}`);
+        }
+        lines.push("");
+    }
+    if (low.length > 0) {
+        lines.push("### LOW - Likely Okay\n");
+        lines.push(`${low.length} session(s) with minor or no issues detected.`);
+        if (low.length <= 3) {
+            for (const s of low) {
+                lines.push(`- Session ${s.session_id.slice(-8)}: ${s.replay_url}`);
+            }
+        }
+        lines.push("");
+    }
+    // Raw data for reference (compact)
+    lines.push("\n## RAW DATA (for detailed analysis)\n");
+    lines.push("```json");
+    lines.push(JSON.stringify({
+        summary: data.summary,
+        sessions: data.sessions.map((s) => ({
+            id: s.session_id,
+            severity: s.severity,
+            score: s.triage_score,
+            url: s.replay_url,
+            comments: s.user_comments.length,
+            frustration: s.behavioral_signals.frustration,
+            rage_clicks: s.behavioral_signals.has_rage_clicks,
+            errors: s.console_errors.length,
+            has_data: s.behavioral_signals.has_behavioral_data,
+        })),
+    }, null, 2));
+    lines.push("```");
+    return lines.join("\n");
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerTriageSessions(server) {
+    server.registerTool("triage_sessions", {
+        description: "Automatically triage sessions to find compromised user experiences. " +
+            "Analyzes user comments, frustration signals, rage clicks, and console errors. " +
+            "Returns flagged sessions with evidence and replay links. Use this to identify " +
+            "sessions that need attention without manually reviewing every recording. " +
+            "Can triage specific sessions by ID(s) or scan for problematic sessions.",
+        inputSchema: z.object({
+            session_ids: z
+                .array(z.string())
+                .optional()
+                .describe("Triage specific sessions by ID. If provided, other filters are ignored."),
+            days: z
+                .number()
+                .optional()
+                .default(7)
+                .describe("Lookback period in days (default: 7). Ignored if session_ids is provided."),
+            page_path: z
+                .string()
+                .optional()
+                .describe("Filter to sessions that visited a specific page"),
+            min_severity: z
+                .enum(["critical", "high", "medium", "low"])
+                .optional()
+                .describe("Minimum severity to include in results"),
+            limit: z
+                .number()
+                .optional()
+                .default(20)
+                .describe("Maximum sessions to return (default: 20, max: 100)"),
+        }),
+    }, async ({ session_ids, days, page_path, min_severity, limit, }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiGet("/sessions/triage", {
+            session_ids: session_ids?.join(","),
+            days: session_ids?.length ? undefined : (days ?? 7),
+            page_path: session_ids?.length ? undefined : page_path,
+            min_severity,
+            limit: session_ids?.length ? session_ids.length : (limit ?? 20),
+        });
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        // Format output for better LLM comprehension
+        const formattedOutput = formatTriageOutput(data);
+        return { content: [{ type: "text", text: formattedOutput }] };
+    });
+}

package/dist/utils/orgContext.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Organization context for the MCP server.
+ * Reads RECAPT_ORG_ID from environment and validates it.
+ */
+export declare function getOrgId(): string;
+export declare function hasOrgId(): boolean;

package/dist/utils/orgContext.js

@@ -0,0 +1,22 @@
+/**
+ * Organization context for the MCP server.
+ * Reads RECAPT_ORG_ID from environment and validates it.
+ */
+let cachedOrgId = null;
+export function getOrgId() {
+    if (cachedOrgId)
+        return cachedOrgId;
+    const orgId = process.env.RECAPT_ORG_ID;
+    if (!orgId) {
+        throw new Error('RECAPT_ORG_ID environment variable is required. ' +
+            'Set it to the MongoDB ObjectId of the organization to query.');
+    }
+    if (!/^[a-f0-9]{24}$/i.test(orgId)) {
+        throw new Error(`RECAPT_ORG_ID must be a valid 24-character MongoDB ObjectId. Got: ${orgId}`);
+    }
+    cachedOrgId = orgId;
+    return orgId;
+}
+export function hasOrgId() {
+    return !!process.env.RECAPT_ORG_ID;
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@recapt/mcp",
+  "version": "0.0.2-beta",
+  "description": "MCP exposing recapt behavioral intelligence to AI coding agents",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf ./dist",
+    "dev": "tsx --watch src/index.ts",
+    "start": "node dist/index.js",
+    "prettify": "prettier --write .",
+    "type-check": "tsc --noEmit"
+  },
+  "bin": {
+    "recapt-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+
+  "author": "Recapt",
+  "license": "ISC",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "peerDependencies": {
+    "@types/node": "^24.3.1",
+    "dotenv": "^17.2.2",
+    "prettier": "^3.8.1",
+    "rimraf": "^6.0.1",
+    "tsx": "^4.16.5",
+    "typescript": "5.9.3"
+  }
+}