@browserstack/mcp-server 1.2.14 → 1.2.15-beta.2

package/dist/tools/percy-mcp/intelligence/get-ai-analysis.d.ts

@@ -0,0 +1,15 @@
+/**
+ * percy_get_ai_analysis — Get AI-powered visual diff analysis.
+ *
+ * Two modes:
+ *   1. Single comparison (comparison_id) — regions, diff ratios, bug flags
+ *   2. Build aggregate (build_id) — overall AI metrics and job status
+ */
+import { BrowserStackConfig } from "../../../lib/types.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+interface GetAiAnalysisArgs {
+    comparison_id?: string;
+    build_id?: string;
+}
+export declare function percyGetAiAnalysis(args: GetAiAnalysisArgs, config: BrowserStackConfig): Promise<CallToolResult>;
+export {};

package/dist/tools/percy-mcp/intelligence/get-ai-analysis.js

@@ -0,0 +1,166 @@
+/**
+ * percy_get_ai_analysis — Get AI-powered visual diff analysis.
+ *
+ * Two modes:
+ *   1. Single comparison (comparison_id) — regions, diff ratios, bug flags
+ *   2. Build aggregate (build_id) — overall AI metrics and job status
+ */
+import { PercyClient } from "../../../lib/percy-api/client.js";
+function pct(value) {
+    if (value == null)
+        return "N/A";
+    return `${(value * 100).toFixed(1)}%`;
+}
+function na(value) {
+    if (value == null || value === "")
+        return "N/A";
+    return String(value);
+}
+// ---------------------------------------------------------------------------
+// Single-comparison AI analysis
+// ---------------------------------------------------------------------------
+async function analyzeComparison(comparisonId, client) {
+    const includes = [
+        "head-screenshot.image",
+        "base-screenshot.image",
+        "diff-image",
+        "ai-diff-image",
+        "browser.browser-family",
+        "comparison-tag",
+    ];
+    const response = await client.get(`/comparisons/${comparisonId}`, undefined, includes);
+    const comparison = response.data;
+    if (!comparison) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `_Comparison ${comparisonId} not found._`,
+                },
+            ],
+        };
+    }
+    const lines = [];
+    lines.push(`## AI Analysis — Comparison #${comparisonId}`);
+    lines.push("");
+    // Diff ratios
+    const aiDiff = comparison.aiDiffRatio;
+    const rawDiff = comparison.diffRatio;
+    if (aiDiff != null || rawDiff != null) {
+        lines.push(`**AI Diff Ratio:** ${pct(aiDiff)} (raw: ${pct(rawDiff)})`);
+    }
+    // AI processing state
+    if (comparison.aiProcessingState &&
+        comparison.aiProcessingState !== "completed") {
+        lines.push(`> ⚠ AI processing state: ${comparison.aiProcessingState}. Results may be incomplete.`);
+        lines.push("");
+    }
+    // Bug count from regions
+    const regions = comparison.appliedRegions ?? [];
+    const bugCount = regions.filter((r) => r.isBug === true || r.classification === "bug" || r.type === "bug").length;
+    if (bugCount > 0) {
+        lines.push(`**Potential Bugs:** ${bugCount}`);
+    }
+    // Regions
+    if (regions.length > 0) {
+        lines.push("");
+        lines.push(`### Regions (${regions.length}):`);
+        for (let i = 0; i < regions.length; i++) {
+            const region = regions[i];
+            const label = na(region.label ?? region.name);
+            const type = region.type ?? region.changeType ?? "unknown";
+            const desc = region.description ?? "";
+            const ignored = region.ignored === true || region.state === "ignored";
+            let line;
+            if (ignored) {
+                line = `${i + 1}. ~~${label}~~ (ignored by AI)`;
+            }
+            else {
+                line = `${i + 1}. **${label}** (${type})`;
+            }
+            if (desc)
+                line += `\n   ${desc}`;
+            lines.push(line);
+        }
+    }
+    else {
+        lines.push("");
+        lines.push("_No AI regions detected for this comparison._");
+    }
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+    };
+}
+// ---------------------------------------------------------------------------
+// Build-aggregate AI analysis
+// ---------------------------------------------------------------------------
+async function analyzeBuild(buildId, client) {
+    const response = await client.get(`/builds/${buildId}`, { "include-metadata": "true" });
+    const build = response.data;
+    if (!build) {
+        return {
+            content: [{ type: "text", text: `_Build ${buildId} not found._` }],
+        };
+    }
+    const ai = build.aiDetails;
+    if (!ai) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "AI analysis is not enabled for this project.",
+                },
+            ],
+        };
+    }
+    const lines = [];
+    lines.push(`## AI Analysis — Build #${build.buildNumber ?? buildId}`);
+    lines.push("");
+    if (ai.comparisonsAnalyzed != null) {
+        lines.push(`- Comparisons analyzed: ${ai.comparisonsAnalyzed}`);
+    }
+    if (ai.potentialBugs != null) {
+        lines.push(`- Potential bugs: ${ai.potentialBugs}`);
+    }
+    if (ai.totalAiDiffs != null) {
+        lines.push(`- Total AI visual diffs: ${ai.totalAiDiffs}`);
+    }
+    if (ai.diffReduction != null) {
+        lines.push(`- Diff reduction: ${ai.diffReduction} diffs filtered`);
+    }
+    else if (ai.originalDiffPercent != null && ai.aiDiffPercent != null) {
+        lines.push(`- Diff reduction: ${pct(ai.originalDiffPercent)} → ${pct(ai.aiDiffPercent)}`);
+    }
+    const jobsCompleted = ai.aiJobsCompleted != null ? (ai.aiJobsCompleted ? "yes" : "no") : "N/A";
+    lines.push(`- AI jobs completed: ${jobsCompleted}`);
+    const summaryStatus = na(ai.summaryStatus ?? ai.aiSummaryStatus);
+    lines.push(`- Summary status: ${summaryStatus}`);
+    // Warning if AI is still processing
+    if (ai.aiJobsCompleted === false || ai.summaryStatus === "processing") {
+        lines.push("");
+        lines.push("> ⚠ AI analysis is still in progress. Some metrics may be incomplete. Re-run for final results.");
+    }
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+    };
+}
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+export async function percyGetAiAnalysis(args, config) {
+    if (!args.comparison_id && !args.build_id) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "_Error: Provide either `comparison_id` or `build_id` for AI analysis._",
+                },
+            ],
+        };
+    }
+    const client = new PercyClient(config, { scope: "project" });
+    if (args.comparison_id) {
+        return analyzeComparison(args.comparison_id, client);
+    }
+    return analyzeBuild(args.build_id, client);
+}

package/dist/tools/percy-mcp/intelligence/get-ai-quota.d.ts

@@ -0,0 +1,9 @@
+/**
+ * percy_get_ai_quota — Check Percy AI quota status.
+ *
+ * Since there is no direct quota endpoint, derives AI quota info
+ * from the latest build's AI details.
+ */
+import { BrowserStackConfig } from "../../../lib/types.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare function percyGetAiQuota(_args: Record<string, never>, config: BrowserStackConfig): Promise<CallToolResult>;

package/dist/tools/percy-mcp/intelligence/get-ai-quota.js

@@ -0,0 +1,73 @@
+/**
+ * percy_get_ai_quota — Check Percy AI quota status.
+ *
+ * Since there is no direct quota endpoint, derives AI quota info
+ * from the latest build's AI details.
+ */
+import { PercyClient } from "../../../lib/percy-api/client.js";
+export async function percyGetAiQuota(_args, config) {
+    const client = new PercyClient(config, { scope: "project" });
+    // Fetch the latest build to extract AI details
+    const response = await client.get("/builds", {
+        "page[limit]": "1",
+        "include-metadata": "true",
+    });
+    const builds = Array.isArray(response.data) ? response.data : [];
+    if (builds.length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "AI quota information unavailable. No builds found for this project.",
+                },
+            ],
+        };
+    }
+    const build = builds[0];
+    const ai = build.aiDetails;
+    if (!ai) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "AI quota information unavailable. Ensure AI is enabled on your Percy project.",
+                },
+            ],
+        };
+    }
+    const lines = [];
+    lines.push("## Percy AI Quota Status");
+    lines.push("");
+    // Quota / regeneration info
+    const used = ai.regenerationsUsed ?? ai.quotaUsed;
+    const total = ai.regenerationsTotal ?? ai.quotaTotal ?? ai.dailyQuota;
+    const plan = ai.planType ?? ai.plan ?? ai.tier;
+    if (used != null && total != null) {
+        lines.push(`**Daily Regenerations:** ${used} / ${total} used`);
+    }
+    else if (total != null) {
+        lines.push(`**Daily Regeneration Limit:** ${total}`);
+    }
+    else {
+        lines.push("**Daily Regenerations:** Quota details not available in build metadata.");
+    }
+    if (plan) {
+        lines.push(`**Plan:** ${plan}`);
+    }
+    // Additional AI stats from the latest build
+    if (ai.comparisonsAnalyzed != null) {
+        lines.push("");
+        lines.push("### Latest Build AI Stats");
+        lines.push(`- Build #${build.buildNumber ?? build.id}`);
+        lines.push(`- Comparisons analyzed: ${ai.comparisonsAnalyzed}`);
+        if (ai.potentialBugs != null) {
+            lines.push(`- Potential bugs detected: ${ai.potentialBugs}`);
+        }
+        if (ai.aiJobsCompleted != null) {
+            lines.push(`- AI jobs completed: ${ai.aiJobsCompleted ? "yes" : "no"}`);
+        }
+    }
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+    };
+}

package/dist/tools/percy-mcp/intelligence/get-build-summary.d.ts

@@ -0,0 +1,11 @@
+/**
+ * percy_get_build_summary — Get AI-generated natural language summary
+ * of all visual changes in a Percy build.
+ */
+import { BrowserStackConfig } from "../../../lib/types.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+interface GetBuildSummaryArgs {
+    build_id: string;
+}
+export declare function percyGetBuildSummary(args: GetBuildSummaryArgs, config: BrowserStackConfig): Promise<CallToolResult>;
+export {};

package/dist/tools/percy-mcp/intelligence/get-build-summary.js

@@ -0,0 +1,78 @@
+/**
+ * percy_get_build_summary — Get AI-generated natural language summary
+ * of all visual changes in a Percy build.
+ */
+import { PercyClient } from "../../../lib/percy-api/client.js";
+export async function percyGetBuildSummary(args, config) {
+    const client = new PercyClient(config, { scope: "project" });
+    const response = await client.get(`/builds/${args.build_id}`, { "include-metadata": "true" }, [
+        "build-summary",
+    ]);
+    const build = response.data;
+    if (!build) {
+        return {
+            content: [{ type: "text", text: `_Build ${args.build_id} not found._` }],
+        };
+    }
+    // Check for build summary in relationships or top-level
+    const summary = build.buildSummary?.content ??
+        build.buildSummary?.summary ??
+        build.summary ??
+        null;
+    if (summary && typeof summary === "string") {
+        const lines = [];
+        lines.push(`## Build Summary — Build #${build.buildNumber ?? args.build_id}`);
+        lines.push("");
+        // The summary may be a JSON string or plain text
+        let parsedSummary;
+        try {
+            const parsed = JSON.parse(summary);
+            // If it parsed as an object, format its contents
+            if (typeof parsed === "object" && parsed !== null) {
+                parsedSummary = Object.entries(parsed)
+                    .map(([key, value]) => `**${key}:** ${value}`)
+                    .join("\n");
+            }
+            else {
+                parsedSummary = String(parsed);
+            }
+        }
+        catch {
+            // Plain text — use as-is
+            parsedSummary = summary;
+        }
+        lines.push(parsedSummary);
+        return {
+            content: [{ type: "text", text: lines.join("\n") }],
+        };
+    }
+    // No summary — check AI details for reason
+    const ai = build.aiDetails;
+    if (ai) {
+        const status = ai.summaryStatus ?? ai.aiSummaryStatus;
+        if (status === "processing") {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Build summary is being generated. Try again in a minute.",
+                    },
+                ],
+            };
+        }
+        if (status === "skipped") {
+            const reason = ai.summaryReason ?? ai.summarySkipReason ?? "unknown reason";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Build summary unavailable. Reason: ${reason}`,
+                    },
+                ],
+            };
+        }
+    }
+    return {
+        content: [{ type: "text", text: "No build summary available." }],
+    };
+}

package/dist/tools/percy-mcp/intelligence/get-rca.d.ts

@@ -0,0 +1,6 @@
+import { BrowserStackConfig } from "../../../lib/types.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare function percyGetRca(args: {
+    comparison_id: string;
+    trigger_if_missing?: boolean;
+}, config: BrowserStackConfig): Promise<CallToolResult>;

package/dist/tools/percy-mcp/intelligence/get-rca.js

@@ -0,0 +1,153 @@
+import { PercyClient } from "../../../lib/percy-api/client.js";
+import { pollUntil } from "../../../lib/percy-api/polling.js";
+export async function percyGetRca(args, config) {
+    const client = new PercyClient(config);
+    const triggerIfMissing = args.trigger_if_missing !== false; // default true
+    // Step 1: Check existing RCA status
+    // GET /rca?comparison_id={id}
+    // Response has: status (pending/finished/failed), diffNodes (when finished)
+    let rcaData;
+    try {
+        rcaData = await client.get("/rca", { comparison_id: args.comparison_id });
+    }
+    catch (e) {
+        // 404 means RCA not started
+        if (e.statusCode === 404 && triggerIfMissing) {
+            // Step 2: Trigger RCA
+            try {
+                await client.post("/rca", {
+                    data: {
+                        type: "rca",
+                        attributes: { "comparison-id": args.comparison_id },
+                    },
+                });
+            }
+            catch (triggerError) {
+                if (triggerError.statusCode === 422) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: "RCA requires DOM metadata. This comparison type does not support RCA.",
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                throw triggerError;
+            }
+            rcaData = { status: "pending" };
+        }
+        else if (e.statusCode === 404) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "RCA not yet triggered for this comparison. Set trigger_if_missing=true to start it.",
+                    },
+                ],
+            };
+        }
+        else {
+            throw e;
+        }
+    }
+    // Step 3: Poll if pending
+    if (rcaData?.status === "pending") {
+        const result = await pollUntil(async () => {
+            const data = await client.get("/rca", {
+                comparison_id: args.comparison_id,
+            });
+            if (data?.status === "finished")
+                return { done: true, result: data };
+            if (data?.status === "failed")
+                return { done: true, result: data };
+            return { done: false };
+        }, { initialDelayMs: 500, maxDelayMs: 5000, maxTimeoutMs: 120000 });
+        if (!result) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "RCA analysis timed out after 2 minutes. The analysis may still be processing — try again later.",
+                    },
+                ],
+            };
+        }
+        rcaData = result;
+    }
+    if (rcaData?.status === "failed") {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "RCA analysis failed. The comparison may not have sufficient DOM metadata.",
+                },
+            ],
+            isError: true,
+        };
+    }
+    // Step 4: Format diff nodes
+    const diffNodes = rcaData?.diffNodes || rcaData?.diff_nodes || {};
+    const commonDiffs = diffNodes.common_diffs || [];
+    const extraBase = diffNodes.extra_base || [];
+    const extraHead = diffNodes.extra_head || [];
+    let output = `## Root Cause Analysis — Comparison #${args.comparison_id}\n\n`;
+    output += `**Status:** ${rcaData?.status || "unknown"}\n\n`;
+    if (commonDiffs.length > 0) {
+        output += `### Changed Elements (${commonDiffs.length})\n\n`;
+        commonDiffs.forEach((diff, i) => {
+            const base = diff.base || {};
+            const head = diff.head || {};
+            const tag = head.tagName || base.tagName || "unknown";
+            const xpath = head.xpath || base.xpath || "";
+            const diffType = head.diff_type === 1
+                ? "DIFF"
+                : head.diff_type === 2
+                    ? "IGNORED"
+                    : "unknown";
+            output += `${i + 1}. **${tag}** (${diffType})\n`;
+            if (xpath)
+                output += `   XPath: \`${xpath}\`\n`;
+            // Show attribute differences
+            const baseAttrs = base.attributes || {};
+            const headAttrs = head.attributes || {};
+            const allKeys = new Set([
+                ...Object.keys(baseAttrs),
+                ...Object.keys(headAttrs),
+            ]);
+            for (const key of allKeys) {
+                if (JSON.stringify(baseAttrs[key]) !== JSON.stringify(headAttrs[key])) {
+                    output += `   ${key}: \`${baseAttrs[key] ?? "N/A"}\` → \`${headAttrs[key] ?? "N/A"}\`\n`;
+                }
+            }
+            output += "\n";
+        });
+    }
+    if (extraBase.length > 0) {
+        output += `### Removed Elements (${extraBase.length})\n\n`;
+        extraBase.forEach((node, i) => {
+            const detail = node.node_detail || node;
+            output += `${i + 1}. **${detail.tagName || "unknown"}** — removed from head\n`;
+            if (detail.xpath)
+                output += `   XPath: \`${detail.xpath}\`\n`;
+            output += "\n";
+        });
+    }
+    if (extraHead.length > 0) {
+        output += `### Added Elements (${extraHead.length})\n\n`;
+        extraHead.forEach((node, i) => {
+            const detail = node.node_detail || node;
+            output += `${i + 1}. **${detail.tagName || "unknown"}** — added in head\n`;
+            if (detail.xpath)
+                output += `   XPath: \`${detail.xpath}\`\n`;
+            output += "\n";
+        });
+    }
+    if (commonDiffs.length === 0 &&
+        extraBase.length === 0 &&
+        extraHead.length === 0) {
+        output += "No DOM differences found.\n";
+    }
+    return { content: [{ type: "text", text: output }] };
+}

package/dist/tools/percy-mcp/intelligence/suggest-prompt.d.ts

@@ -0,0 +1,15 @@
+/**
+ * percy_suggest_prompt — Get an AI-generated prompt suggestion for diff regions.
+ *
+ * Sends region IDs to the Percy API, polls for the suggestion result,
+ * and returns the generated prompt text.
+ */
+import { BrowserStackConfig } from "../../../lib/types.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+interface SuggestPromptArgs {
+    comparison_id: string;
+    region_ids: string;
+    ignore_change?: boolean;
+}
+export declare function percySuggestPrompt(args: SuggestPromptArgs, config: BrowserStackConfig): Promise<CallToolResult>;
+export {};

package/dist/tools/percy-mcp/intelligence/suggest-prompt.js

@@ -0,0 +1,86 @@
+/**
+ * percy_suggest_prompt — Get an AI-generated prompt suggestion for diff regions.
+ *
+ * Sends region IDs to the Percy API, polls for the suggestion result,
+ * and returns the generated prompt text.
+ */
+import { PercyClient } from "../../../lib/percy-api/client.js";
+import { pollUntil } from "../../../lib/percy-api/polling.js";
+export async function percySuggestPrompt(args, config) {
+    const client = new PercyClient(config);
+    const regionIds = args.region_ids
+        .split(",")
+        .map((id) => id.trim())
+        .filter(Boolean);
+    const regionTypes = regionIds.map(() => "ai_region");
+    const body = {
+        data: {
+            attributes: {
+                "comparison-id": parseInt(args.comparison_id, 10),
+                "region-id": regionIds.map(Number),
+                "region-type": regionTypes,
+                "ignore-change": args.ignore_change !== false,
+            },
+        },
+    };
+    const result = await client.post("/suggest-prompt", body);
+    const identifier = result?.identifier ||
+        result?.id;
+    if (!identifier) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Prompt suggestion initiated but no tracking ID received. Check results manually.",
+                },
+            ],
+        };
+    }
+    const suggestion = await pollUntil(async () => {
+        const status = await client.get("/job_status", {
+            sync: "true",
+            type: "ai",
+            id: String(identifier),
+        });
+        const entry = status?.[String(identifier)];
+        if (entry?.status === true) {
+            return { done: true, result: entry };
+        }
+        if (entry?.error) {
+            return { done: true, result: entry };
+        }
+        return { done: false };
+    }, { initialDelayMs: 1000, maxDelayMs: 3000, maxTimeoutMs: 30000 });
+    if (!suggestion) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Prompt suggestion timed out. The AI is still generating — try again in a moment.",
+                },
+            ],
+        };
+    }
+    if (suggestion.error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Prompt suggestion failed: ${suggestion.error}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const data = suggestion.data;
+    const prompt = data?.generated_prompt ||
+        suggestion.generated_prompt ||
+        "No prompt generated";
+    let output = "## AI Prompt Suggestion\n\n";
+    output += `**Suggested prompt:** ${prompt}\n\n`;
+    output += `**Mode:** ${args.ignore_change !== false ? "ignore" : "show"}\n`;
+    output += `**Regions analyzed:** ${regionIds.length}\n\n`;
+    output +=
+        "Use this prompt with `percy_trigger_ai_recompute` to apply it across all comparisons.\n";
+    return { content: [{ type: "text", text: output }] };
+}

package/dist/tools/percy-mcp/intelligence/trigger-ai-recompute.d.ts

@@ -0,0 +1,16 @@
+/**
+ * percy_trigger_ai_recompute — Re-run Percy AI analysis with a custom prompt.
+ *
+ * Sends a recompute request for a build or single comparison, optionally
+ * with a user-supplied prompt and ignore/unignore mode.
+ */
+import { BrowserStackConfig } from "../../../lib/types.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+interface TriggerAiRecomputeArgs {
+    build_id?: string;
+    comparison_id?: string;
+    prompt?: string;
+    mode?: string;
+}
+export declare function percyTriggerAiRecompute(args: TriggerAiRecomputeArgs, config: BrowserStackConfig): Promise<CallToolResult>;
+export {};