@recapt/mcp 0.0.14-beta → 0.0.15-beta

package/dist/tools/diagnostic.js

@@ -41,7 +41,11 @@ export function registerDiagnosticTools(server) {
         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.",
+        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

package/dist/tools/healingRun.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Healing Run tools for tracking self-healing workflow executions.
+ *
+ * Provides run registration, phase updates, action recording, and run listing.
+ */
+export declare function registerHealingRunTools(server: any): void;

package/dist/tools/healingRun.js

@@ -0,0 +1,313 @@
+/**
+ * Healing Run tools for tracking self-healing workflow executions.
+ *
+ * Provides run registration, phase updates, action recording, and run listing.
+ */
+import { z } from "zod";
+import { apiGet, apiPost, apiPatch, isApiConfigured } from "../api/client.js";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerHealingRunTools(server) {
+    server.registerTool("start_healing_run", {
+        description: "Register the start of a self-healing workflow run. Call this at the beginning of a healing session to track the run and its outcomes. Returns a run ID to use for subsequent updates.",
+        inputSchema: z.object({
+            trigger_type: z
+                .enum(["github_actions", "cron", "manual", "api"])
+                .describe("What triggered this healing run"),
+            trigger_metadata: z
+                .record(z.unknown())
+                .optional()
+                .describe("Additional metadata about the trigger (e.g., GitHub run ID, branch, actor)"),
+            phases: z
+                .array(z.object({
+                name: z.string(),
+                status: z
+                    .enum(["pending", "running", "completed", "skipped", "failed"])
+                    .default("pending"),
+            }))
+                .optional()
+                .describe("Initial phases to track (e.g., diagnose, investigate, fix)"),
+        }),
+    }, async ({ trigger_type, trigger_metadata, phases, }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiPost("/healing-runs", {
+            trigger_type,
+            trigger_metadata,
+            phases,
+        });
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
+    server.registerTool("update_healing_run", {
+        description: "Update a healing run's status, phases, or summary. Use to track progress through the workflow phases and record final outcomes.",
+        inputSchema: z.object({
+            run_id: z.string().describe("The ID of the healing run to update"),
+            status: z
+                .enum(["running", "completed", "failed", "cancelled"])
+                .optional()
+                .describe("New status for the run"),
+            phases: z
+                .array(z.object({
+                name: z.string(),
+                status: z.enum([
+                    "pending",
+                    "running",
+                    "completed",
+                    "skipped",
+                    "failed",
+                ]),
+                startedAt: z.string().nullable().optional(),
+                completedAt: z.string().nullable().optional(),
+                output: z.record(z.unknown()).optional(),
+            }))
+                .optional()
+                .describe("Updated phases array"),
+            summary: z
+                .object({
+                issuesFound: z.number().optional(),
+                issuesFixed: z.number().optional(),
+                issuesDeferred: z.number().optional(),
+                issuesDismissed: z.number().optional(),
+                prsCreated: z.number().optional(),
+            })
+                .optional()
+                .describe("Updated summary counts"),
+            completed_at: z
+                .string()
+                .optional()
+                .describe("ISO timestamp when the run completed"),
+            duration_ms: z
+                .number()
+                .optional()
+                .describe("Total duration of the run in milliseconds"),
+        }),
+    }, async ({ run_id, status, phases, summary, completed_at, duration_ms, }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiPatch(`/healing-runs/${run_id}`, {
+            status,
+            phases,
+            summary,
+            completed_at,
+            duration_ms,
+        });
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
+    server.registerTool("record_healing_action", {
+        description: "Record an action taken during a healing run. Use to track what was done for each issue: code fixes, deferrals, dismissals, etc. " +
+            "IMPORTANT: When recording code_fix actions, the code_changes.diff field must contain ACTUAL SOURCE CODE in unified diff format, " +
+            "not a description of what changed. Include the literal code lines with proper +/- prefixes.",
+        inputSchema: z.object({
+            run_id: z.string().describe("The ID of the healing run"),
+            issue_id: z
+                .string()
+                .optional()
+                .describe("The ID of the issue this action relates to (if any)"),
+            action_type: z
+                .enum([
+                "code_fix",
+                "needs_more_data",
+                "dismissed",
+                "marked_intended",
+                "knowledge_added",
+            ])
+                .describe("Type of action taken"),
+            hypothesis: z.string().describe("AI's reasoning for this action"),
+            expected_improvement: z
+                .string()
+                .describe("What improvement is expected from this action"),
+            code_changes: z
+                .array(z.object({
+                file: z.string().describe("Path to the changed file"),
+                diff: z
+                    .string()
+                    .describe("CRITICAL: Must be actual source code in unified diff format, NOT a description of changes. " +
+                    "This field must contain the literal code lines that were changed.\n\n" +
+                    "FORMAT REQUIREMENTS:\n" +
+                    "1. Start with @@ header: @@ -oldStart,oldCount +newStart,newCount @@\n" +
+                    "2. Context lines (unchanged): prefix with single space ' '\n" +
+                    "3. Removed lines: prefix with minus '-'\n" +
+                    "4. Added lines: prefix with plus '+'\n" +
+                    "5. Include 5 lines of context before and after the change\n\n" +
+                    "CORRECT EXAMPLE:\n" +
+                    "@@ -35,7 +35,9 @@\n" +
+                    " import { Spinner } from '@chakra-ui/react';\n" +
+                    " \n" +
+                    " export function FilterDropdown({ filters }) {\n" +
+                    "-  const [isOpen, setIsOpen] = useState(false);\n" +
+                    "+  const [isOpen, setIsOpen] = useState(false);\n" +
+                    "+  const [isLoading, setIsLoading] = useState(false);\n" +
+                    "   const handleClick = () => {\n" +
+                    " \n\n" +
+                    "WRONG (do NOT do this):\n" +
+                    "- 'Added isLoading state to provide feedback'\n" +
+                    "- 'Changed the button to show a spinner'\n" +
+                    "- Any prose description instead of actual code"),
+                startLine: z
+                    .number()
+                    .describe("Line number in the original file where the first line of the diff begins (the first context line)"),
+                linesAdded: z
+                    .number()
+                    .default(0)
+                    .describe("Count of lines added (lines starting with '+')"),
+                linesRemoved: z
+                    .number()
+                    .default(0)
+                    .describe("Count of lines removed (lines starting with '-')"),
+            }))
+                .optional()
+                .describe("Array of code changes. Each diff MUST contain actual source code lines, not descriptions."),
+            pr_url: z
+                .string()
+                .optional()
+                .describe("GitHub PR URL if a PR was created"),
+            pr_number: z.number().optional().describe("GitHub PR number"),
+            remediation_id: z
+                .string()
+                .optional()
+                .describe("ID of the associated remediation record (if any)"),
+            deferral_reason: z
+                .string()
+                .optional()
+                .describe("Explanation for why the issue was deferred (for needs_more_data actions)"),
+            dismissal_reason: z
+                .string()
+                .optional()
+                .describe("Explanation for why the issue was dismissed (for dismissed/marked_intended actions)"),
+        }),
+    }, async ({ run_id, issue_id, action_type, hypothesis, expected_improvement, code_changes, pr_url, pr_number, remediation_id, deferral_reason, dismissal_reason, }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiPost(`/healing-runs/${run_id}/actions`, {
+            issue_id,
+            action_type,
+            hypothesis,
+            expected_improvement,
+            code_changes,
+            pr_url,
+            pr_number,
+            remediation_id,
+            deferral_reason,
+            dismissal_reason,
+        });
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
+    server.registerTool("get_healing_run", {
+        description: "Get details of a specific healing run including all actions taken. Use to review what happened during a run.",
+        inputSchema: z.object({
+            run_id: z.string().describe("The ID of the healing run to retrieve"),
+        }),
+    }, async ({ run_id }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiGet(`/healing-runs/${run_id}`);
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
+    server.registerTool("list_healing_runs", {
+        description: "List recent healing runs with optional filters. Use to review past runs and their outcomes.",
+        inputSchema: z.object({
+            status: z
+                .enum(["running", "completed", "failed", "cancelled"])
+                .optional()
+                .describe("Filter by run status"),
+            trigger_type: z
+                .enum(["github_actions", "cron", "manual", "api"])
+                .optional()
+                .describe("Filter by trigger type"),
+            limit: z
+                .number()
+                .optional()
+                .default(20)
+                .describe("Maximum number of results (default: 20)"),
+            offset: z
+                .number()
+                .optional()
+                .default(0)
+                .describe("Offset for pagination"),
+        }),
+    }, async ({ status, trigger_type, limit, offset, }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiGet("/healing-runs", {
+            status,
+            trigger_type,
+            limit: limit ?? 20,
+            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/triageSessions.js

@@ -138,7 +138,9 @@ export function registerTriageSessions(server) {
             "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.",
+            "Can triage specific sessions by ID(s) or scan for problematic sessions. " +
+            "NOTE: Session replay URLs require a paid plan (Starter+). Free tier users " +
+            "can see session summaries and triage scores but not watch replays.",
         inputSchema: z.object({
             session_ids: z
                 .array(z.string())

package/dist/tools/upgradeOptions.d.ts

@@ -0,0 +1,7 @@
+/**
+ * get_upgrade_options tool
+ *
+ * Provides upgrade information for AI agents to communicate upgrade paths to users.
+ * Part of the "Diagnose Free, Solve Paid" pattern.
+ */
+export declare function registerGetUpgradeOptions(server: any): void;

package/dist/tools/upgradeOptions.js

@@ -0,0 +1,67 @@
+/**
+ * get_upgrade_options tool
+ *
+ * Provides upgrade information for AI agents to communicate upgrade paths to users.
+ * Part of the "Diagnose Free, Solve Paid" pattern.
+ */
+import { z } from "zod";
+import { apiGet, isApiConfigured } from "../api/client.js";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerGetUpgradeOptions(server) {
+    server.registerTool("get_upgrade_options", {
+        description: "Get available upgrade options for the current plan. Use this when a user hits a " +
+            "feature limit or when you need to explain what's available on higher tiers. " +
+            "Returns the current plan, available upgrades with their features and benefits, " +
+            "and a direct link to the billing page. Use this to help users understand the " +
+            "value of upgrading when they encounter gated features.",
+        inputSchema: z.object({}),
+    }, async () => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { data, error } = await apiGet("/upgrade-options");
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        // Format output for better LLM comprehension
+        const output = formatUpgradeOptions(data);
+        return { content: [{ type: "text", text: output }] };
+    });
+}
+function formatUpgradeOptions(data) {
+    const lines = [];
+    lines.push("# UPGRADE OPTIONS\n");
+    lines.push(`**Current Plan:** ${data.currentPlan.name} (${data.currentPlan.tag})\n`);
+    if (data.availableUpgrades.length === 0) {
+        lines.push("You're on the highest tier! No upgrades available.");
+        return lines.join("\n");
+    }
+    lines.push("## Available Upgrades\n");
+    for (const upgrade of data.availableUpgrades) {
+        lines.push(`### ${upgrade.name}\n`);
+        lines.push("**Features:**");
+        for (const feature of upgrade.features) {
+            lines.push(`- ${feature}`);
+        }
+        lines.push("");
+        lines.push("**Benefits:**");
+        for (const benefit of upgrade.benefits) {
+            lines.push(`- ${benefit}`);
+        }
+        lines.push("");
+    }
+    lines.push("---");
+    lines.push(`**Upgrade now:** ${data.upgradeUrl}`);
+    return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recapt/mcp",
-  "version": "0.0.14-beta",
+  "version": "0.0.15-beta",
   "description": "MCP exposing recapt behavioral intelligence to AI coding agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",