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

package/dist/tools/percy-mcp/v2/figma-baseline.d.ts

@@ -0,0 +1,7 @@
+import { BrowserStackConfig } from "../../../lib/types.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare function percyFigmaBaseline(args: {
+    project_slug: string;
+    branch: string;
+    build_id: string;
+}, config: BrowserStackConfig): Promise<CallToolResult>;

package/dist/tools/percy-mcp/v2/figma-baseline.js

@@ -0,0 +1,18 @@
+import { percyPost } from "../../../lib/percy-api/percy-auth.js";
+export async function percyFigmaBaseline(args, config) {
+    await percyPost("/design/figma/update-baseline", config, {
+        data: {
+            attributes: {
+                "project-slug": args.project_slug,
+                branch: args.branch,
+                "build-id": args.build_id,
+            },
+        },
+    });
+    let output = `## Figma Baseline Updated\n\n`;
+    output += `**Project:** ${args.project_slug}\n`;
+    output += `**Branch:** ${args.branch}\n`;
+    output += `**Build:** ${args.build_id}\n`;
+    output += `Baseline has been updated from the latest Figma designs.\n`;
+    return { content: [{ type: "text", text: output }] };
+}

package/dist/tools/percy-mcp/v2/figma-build.d.ts

@@ -0,0 +1,7 @@
+import { BrowserStackConfig } from "../../../lib/types.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare function percyFigmaBuild(args: {
+    project_slug: string;
+    branch: string;
+    figma_url: string;
+}, config: BrowserStackConfig): Promise<CallToolResult>;

package/dist/tools/percy-mcp/v2/figma-build.js

@@ -0,0 +1,39 @@
+import { percyPost } from "../../../lib/percy-api/percy-auth.js";
+export async function percyFigmaBuild(args, config) {
+    // Step 1: Fetch design from Figma URL
+    const fetchResult = await percyPost("/design/figma/fetch-design", config, {
+        data: { attributes: { "figma-url": args.figma_url } },
+    });
+    const nodes = fetchResult?.data?.attributes?.nodes || fetchResult?.nodes || [];
+    if (!nodes.length && !fetchResult?.data) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `No design nodes found at ${args.figma_url}. Check the Figma URL and ensure it points to a frame or component.`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    // Step 2: Create build from design data
+    const figmaData = Array.isArray(nodes) ? nodes : [nodes];
+    const buildResult = await percyPost("/design/figma/create-build", config, {
+        data: {
+            attributes: {
+                branch: args.branch,
+                "project-slug": args.project_slug,
+                "figma-url": args.figma_url,
+                "figma-data": figmaData,
+            },
+        },
+    });
+    const buildId = buildResult?.data?.id || "unknown";
+    let output = `## Figma Build Created\n\n`;
+    output += `**Build ID:** ${buildId}\n`;
+    output += `**Project:** ${args.project_slug}\n`;
+    output += `**Branch:** ${args.branch}\n`;
+    output += `**Figma URL:** ${args.figma_url}\n`;
+    output += `**Design nodes:** ${figmaData.length}\n`;
+    return { content: [{ type: "text", text: output }] };
+}

package/dist/tools/percy-mcp/v2/figma-link.d.ts

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

package/dist/tools/percy-mcp/v2/figma-link.js

@@ -0,0 +1,27 @@
+import { percyGet } from "../../../lib/percy-api/percy-auth.js";
+export async function percyFigmaLink(args, config) {
+    const params = {};
+    if (args.snapshot_id)
+        params.snapshot_id = args.snapshot_id;
+    if (args.comparison_id)
+        params.comparison_id = args.comparison_id;
+    const result = await percyGet("/design/figma/figma-link", config, params);
+    const link = result?.data?.attributes?.["figma-url"] || result?.figma_url || null;
+    if (!link) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "No Figma link found for this snapshot/comparison.",
+                },
+            ],
+        };
+    }
+    let output = `## Figma Link\n\n`;
+    output += `**Link:** ${link}\n`;
+    if (args.snapshot_id)
+        output += `**Snapshot:** ${args.snapshot_id}\n`;
+    if (args.comparison_id)
+        output += `**Comparison:** ${args.comparison_id}\n`;
+    return { content: [{ type: "text", text: output }] };
+}

package/dist/tools/percy-mcp/v2/get-ai-summary.d.ts

@@ -0,0 +1,5 @@
+import { BrowserStackConfig } from "../../../lib/types.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare function percyGetAiSummary(args: {
+    build_id: string;
+}, config: BrowserStackConfig): Promise<CallToolResult>;

package/dist/tools/percy-mcp/v2/get-ai-summary.js

@@ -0,0 +1,109 @@
+import { percyGet } from "../../../lib/percy-api/percy-auth.js";
+export async function percyGetAiSummary(args, config) {
+    // Get build with build-summary include
+    const response = await percyGet(`/builds/${args.build_id}`, config, {
+        include: "build-summary",
+    });
+    const build = response?.data || {};
+    const attrs = build.attributes || {};
+    const buildNum = attrs["build-number"] || args.build_id;
+    const state = attrs.state || "unknown";
+    // Get AI details from build attributes
+    const ai = attrs["ai-details"] || {};
+    const potentialBugs = ai["total-potential-bugs"] ?? 0;
+    const aiVisualDiffs = ai["total-ai-visual-diffs"] ?? 0;
+    const diffsReduced = ai["total-diffs-reduced-capped"] ?? 0;
+    const comparisonsWithAi = ai["total-comparisons-with-ai"] ?? 0;
+    const allCompleted = ai["all-ai-jobs-completed"] ?? false;
+    const summaryStatus = ai["summary-status"];
+    // Get build summary from included data
+    const included = response?.included || [];
+    const summaryObj = included.find((i) => i.type === "build-summaries");
+    const summaryJson = summaryObj?.attributes?.summary;
+    let output = `## Percy Build #${buildNum} — AI Build Summary\n\n`;
+    // Check for actual AI data, not just the toggle flag
+    const hasAiData = (comparisonsWithAi ?? 0) > 0 ||
+        (potentialBugs ?? 0) > 0 ||
+        (aiVisualDiffs ?? 0) > 0 ||
+        summaryStatus === "ok";
+    if (!hasAiData) {
+        output += `No AI analysis data found for this build.\n`;
+        output += `AI may not be enabled, or the build has no visual diffs.\n`;
+        return { content: [{ type: "text", text: output }] };
+    }
+    if (state !== "finished") {
+        output += `Build is **${state}**. AI summary is available after the build finishes.\n`;
+        return { content: [{ type: "text", text: output }] };
+    }
+    // AI stats header
+    output += `**${potentialBugs} potential bug${potentialBugs !== 1 ? "s" : ""}** · **${aiVisualDiffs} AI visual diff${aiVisualDiffs !== 1 ? "s" : ""}**\n\n`;
+    if (diffsReduced > 0) {
+        output += `AI reduced noise by **${diffsReduced}** diff${diffsReduced !== 1 ? "s" : ""}.\n`;
+    }
+    if (comparisonsWithAi > 0) {
+        output += `**${comparisonsWithAi}** comparison${comparisonsWithAi !== 1 ? "s" : ""} analyzed by AI.\n`;
+    }
+    output += `AI jobs: ${allCompleted ? "completed" : "in progress"}\n\n`;
+    // Parse and display the build summary
+    if (summaryJson) {
+        try {
+            const summary = typeof summaryJson === "string" ? JSON.parse(summaryJson) : summaryJson;
+            if (summary.title) {
+                output += `### Summary\n\n`;
+                output += `> ${summary.title}\n\n`;
+            }
+            // Display items (change descriptions with occurrences)
+            const items = summary.items || summary.changes || [];
+            if (items.length > 0) {
+                output += `### Changes\n\n`;
+                items.forEach((item) => {
+                    const title = item.title || item.description || item.name || String(item);
+                    const occurrences = item.occurrences || item.count || item.occurrence_count;
+                    output += `- **${title}**`;
+                    if (occurrences)
+                        output += ` (${occurrences} occurrence${occurrences !== 1 ? "s" : ""})`;
+                    output += "\n";
+                });
+                output += "\n";
+            }
+            // Display snapshots if available
+            const snapshots = summary.snapshots || [];
+            if (snapshots.length > 0) {
+                output += `### Affected Snapshots\n\n`;
+                snapshots.forEach((snap) => {
+                    const name = snap.name || snap.snapshot_name || "Unknown";
+                    const changes = snap.changes || snap.items || [];
+                    output += `**${name}**\n`;
+                    changes.forEach((change) => {
+                        output += `  - ${change.title || change.description || change}\n`;
+                    });
+                });
+                output += "\n";
+            }
+        }
+        catch {
+            // Summary is not valid JSON — show raw
+            output += `### Raw Summary\n\n`;
+            output += `${String(summaryJson).slice(0, 1000)}\n\n`;
+        }
+    }
+    else if (summaryStatus === "processing") {
+        output += `### Summary\n\nAI summary is being generated. Try again in a minute.\n`;
+    }
+    else if (summaryStatus === "skipped") {
+        const reason = ai["summary-reason"] || "unknown";
+        output += `### Summary\n\nAI summary was skipped: ${reason}\n`;
+        if (reason === "too_many_comparisons") {
+            output += `(Build has more than 50 comparisons — summaries are only generated for smaller builds)\n`;
+        }
+    }
+    else {
+        output += `### Summary\n\nNo AI summary available for this build.\n`;
+    }
+    // Build URL
+    const webUrl = attrs["web-url"];
+    if (webUrl) {
+        output += `**View in Percy:** ${webUrl}\n`;
+    }
+    return { content: [{ type: "text", text: output }] };
+}

package/dist/tools/percy-mcp/v2/get-build-detail.d.ts

@@ -0,0 +1,22 @@
+/**
+ * percy_get_build — Unified build details tool.
+ *
+ * detail param routes to different views:
+ * - overview: status, stats, AI metrics, browsers, summary preview
+ * - ai_summary: full AI change descriptions with occurrences
+ * - changes: changed snapshots with diff ratios and bugs
+ * - rca: root cause analysis for a comparison
+ * - logs: failure diagnostics and suggestions
+ * - network: network request logs for a comparison
+ * - snapshots: all snapshots with review states
+ */
+import { BrowserStackConfig } from "../../../lib/types.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+interface GetBuildArgs {
+    build_id: string;
+    detail?: string;
+    comparison_id?: string;
+    snapshot_id?: string;
+}
+export declare function percyGetBuildDetail(args: GetBuildArgs, config: BrowserStackConfig): Promise<CallToolResult>;
+export {};