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

package/dist/tools/percy-mcp/v2/get-comparison.js

@@ -0,0 +1,94 @@
+import { percyGet } from "../../../lib/percy-api/percy-auth.js";
+export async function percyGetComparison(args, config) {
+    const response = await percyGet(`/comparisons/${args.comparison_id}`, config, {
+        include: [
+            "head-screenshot.image",
+            "base-screenshot.image",
+            "diff-image",
+            "ai-diff-image",
+            "browser.browser-family",
+            "comparison-tag",
+        ].join(","),
+    });
+    const comp = response?.data || {};
+    const attrs = comp.attributes || {};
+    const included = response?.included || [];
+    const ai = attrs["ai-details"] || {};
+    // Resolve browser name
+    const browserId = comp.relationships?.browser?.data?.id;
+    const browser = included.find((i) => i.type === "browsers" && i.id === browserId);
+    const familyId = browser?.relationships?.["browser-family"]?.data?.id;
+    const family = included.find((i) => i.type === "browser-families" && i.id === familyId);
+    const browserName = `${family?.attributes?.name || "?"} ${browser?.attributes?.version || ""}`;
+    let output = `## Comparison #${args.comparison_id}\n\n`;
+    output += `| Field | Value |\n|---|---|\n`;
+    output += `| **Browser** | ${browserName} |\n`;
+    output += `| **Width** | ${attrs.width || "?"}px |\n`;
+    output += `| **State** | ${attrs.state || "?"} |\n`;
+    output += `| **Diff ratio** | ${attrs["diff-ratio"] != null ? (attrs["diff-ratio"] * 100).toFixed(2) + "%" : "—"} |\n`;
+    output += `| **AI diff ratio** | ${attrs["ai-diff-ratio"] != null ? (attrs["ai-diff-ratio"] * 100).toFixed(2) + "%" : "—"} |\n`;
+    output += `| **AI state** | ${attrs["ai-processing-state"] || "—"} |\n`;
+    output += `| **Potential bugs** | ${ai["total-potential-bugs"] ?? "—"} |\n`;
+    output += `| **AI visual diffs** | ${ai["total-ai-visual-diffs"] ?? "—"} |\n`;
+    output += `| **Diffs reduced** | ${ai["total-diffs-reduced-capped"] ?? "—"} |\n`;
+    // AI regions (the detailed change descriptions)
+    const regions = attrs["applied-regions"];
+    if (Array.isArray(regions) && regions.length > 0) {
+        output += `\n### AI Detected Changes (${regions.length})\n\n`;
+        regions.forEach((r, i) => {
+            const ignored = r.ignored ? " ~~ignored~~" : "";
+            output += `${i + 1}. **${r.change_title || r.change_type || "Change"}** (${r.change_type || "?"})${ignored}\n`;
+            if (r.change_description)
+                output += `   ${r.change_description}\n`;
+            if (r.change_reason)
+                output += `   *Reason: ${r.change_reason}*\n`;
+            if (r.coordinates) {
+                const c = r.coordinates;
+                output += `   Region: (${c.x || c.left || 0}, ${c.y || c.top || 0}) → (${c.x2 || c.right || c.x + c.width || 0}, ${c.y2 || c.bottom || c.y + c.height || 0})\n`;
+            }
+            output += "\n";
+        });
+    }
+    // Image URLs
+    const resolveImageUrl = (relName) => {
+        const screenshotId = comp.relationships?.[relName]?.data?.id;
+        if (!screenshotId)
+            return null;
+        // Direct image relationship
+        const directImage = included.find((i) => i.type === "images" && i.id === screenshotId);
+        if (directImage?.attributes?.url)
+            return directImage.attributes.url;
+        // Screenshot → image relationship
+        const screenshot = included.find((i) => i.type === "screenshots" && i.id === screenshotId);
+        const imageId = screenshot?.relationships?.image?.data?.id;
+        if (imageId) {
+            const image = included.find((i) => i.type === "images" && i.id === imageId);
+            return image?.attributes?.url || null;
+        }
+        return null;
+    };
+    output += `### Images\n\n`;
+    const headUrl = resolveImageUrl("head-screenshot");
+    const baseUrl = resolveImageUrl("base-screenshot");
+    const diffUrl = resolveImageUrl("diff-image");
+    const aiDiffUrl = resolveImageUrl("ai-diff-image");
+    if (headUrl)
+        output += `**Head:** ${headUrl}\n`;
+    if (baseUrl)
+        output += `**Base:** ${baseUrl}\n`;
+    if (diffUrl)
+        output += `**Diff:** ${diffUrl}\n`;
+    if (aiDiffUrl)
+        output += `**AI Diff:** ${aiDiffUrl}\n`;
+    if (!headUrl && !baseUrl && !diffUrl)
+        output += `No images available.\n`;
+    // Error info
+    if (attrs["error-buckets-exists"]) {
+        output += `\n### Errors\n\n`;
+        const assetFailures = attrs["asset-failure-category-counts"];
+        if (assetFailures) {
+            output += `**Asset failures:** ${JSON.stringify(assetFailures)}\n`;
+        }
+    }
+    return { content: [{ type: "text", text: output }] };
+}

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

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

package/dist/tools/percy-mcp/v2/get-devices.js

@@ -0,0 +1,33 @@
+import { percyGet } from "../../../lib/percy-api/percy-auth.js";
+export async function percyGetDevices(args, config) {
+    // Get browser families
+    const families = await percyGet("/browser-families", config);
+    const familyList = families?.data || [];
+    let output = `## Percy Browsers & Devices\n\n`;
+    output += `### Browser Families\n\n`;
+    output += `| Name | Slug | ID |\n|---|---|---|\n`;
+    familyList.forEach((f) => {
+        output += `| ${f.attributes?.name || "?"} | ${f.attributes?.slug || "?"} | ${f.id} |\n`;
+    });
+    // Get device details if build_id provided
+    if (args.build_id) {
+        try {
+            const devices = await percyGet("/discovery/device-details", config, {
+                build_id: args.build_id,
+            });
+            const deviceList = devices?.data || devices || [];
+            if (Array.isArray(deviceList) && deviceList.length) {
+                output += `\n### Devices for Build ${args.build_id}\n\n`;
+                output += `| Device | Width | Height |\n|---|---|---|\n`;
+                deviceList.forEach((d) => {
+                    const attrs = d.attributes || d;
+                    output += `| ${attrs.name || "?"} | ${attrs.width || "?"} | ${attrs.height || "?"} |\n`;
+                });
+            }
+        }
+        catch {
+            /* device details may not be available */
+        }
+    }
+    return { content: [{ type: "text", text: output }] };
+}

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

@@ -0,0 +1,7 @@
+import { BrowserStackConfig } from "../../../lib/types.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare function percyGetInsights(args: {
+    org_slug: string;
+    period?: string;
+    product?: string;
+}, config: BrowserStackConfig): Promise<CallToolResult>;

package/dist/tools/percy-mcp/v2/get-insights.js

@@ -0,0 +1,52 @@
+import { percyGet } from "../../../lib/percy-api/percy-auth.js";
+export async function percyGetInsights(args, config) {
+    const params = {
+        organization_id: args.org_slug,
+        period: args.period || "last_30_days",
+        product: args.product || "web",
+    };
+    const response = await percyGet("/insights/metrics", config, params);
+    const data = response?.data?.attributes || response?.data || {};
+    let output = `## Percy Testing Insights — ${args.org_slug}\n\n`;
+    output += `**Period:** ${params.period}\n**Product:** ${params.product}\n\n`;
+    // Review efficiency
+    const review = data.reviewEfficiency || data["review-efficiency"] || {};
+    if (review) {
+        output += `### Review Efficiency\n`;
+        output += `| Metric | Value |\n|---|---|\n`;
+        if (review.meaningfulReviewTimeRatio != null)
+            output += `| Meaningful review ratio | ${(review.meaningfulReviewTimeRatio * 100).toFixed(0)}% |\n`;
+        if (review.totalReviews != null)
+            output += `| Total reviews | ${review.totalReviews} |\n`;
+        if (review.noisyReviews != null)
+            output += `| Noisy reviews | ${review.noisyReviews} |\n`;
+        if (review.medianReviewTimeSeconds != null)
+            output += `| Median review time | ${review.medianReviewTimeSeconds}s |\n`;
+        output += "\n";
+    }
+    // ROI
+    const roi = data.roiTimeSavings || data["roi-time-savings"] || {};
+    if (roi) {
+        output += `### ROI & Time Savings\n`;
+        output += `| Metric | Value |\n|---|---|\n`;
+        if (roi.totalTimeSaved != null)
+            output += `| Total time saved | ${roi.totalTimeSaved} min |\n`;
+        if (roi.noDiffPercentage != null)
+            output += `| No-diff percentage | ${(roi.noDiffPercentage * 100).toFixed(0)}% |\n`;
+        if (roi.buildsCount != null)
+            output += `| Builds | ${roi.buildsCount} |\n`;
+        output += "\n";
+    }
+    // Coverage
+    const coverage = data.coverage || {};
+    if (coverage) {
+        output += `### Coverage\n`;
+        output += `| Metric | Value |\n|---|---|\n`;
+        if (coverage.coveragePercentage != null)
+            output += `| Coverage | ${coverage.coveragePercentage.toFixed(0)}% |\n`;
+        if (coverage.activeSnapshotsCount != null)
+            output += `| Active snapshots | ${coverage.activeSnapshotsCount} |\n`;
+        output += "\n";
+    }
+    return { content: [{ type: "text", text: output }] };
+}

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

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

package/dist/tools/percy-mcp/v2/get-projects.js

@@ -0,0 +1,41 @@
+import { percyGet } from "../../../lib/percy-api/percy-auth.js";
+import { setOrg } from "../../../lib/percy-api/percy-session.js";
+export async function percyGetProjectsV2(args, config) {
+    const params = {};
+    if (args.search)
+        params["filter[search]"] = args.search;
+    params["page[limit]"] = String(args.limit || 20);
+    const response = await percyGet("/projects", config, params);
+    const projects = response?.data || [];
+    if (projects.length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "No projects found. Use `percy_create_project` to create one.",
+                },
+            ],
+        };
+    }
+    // Extract org slug from the first project's full-slug
+    const firstSlug = projects[0]?.attributes?.["full-slug"] || "";
+    const orgSlug = firstSlug.split("/")[0] || "";
+    if (orgSlug)
+        setOrg({ slug: orgSlug });
+    let output = `## Percy Projects (${projects.length})\n\n`;
+    output += `| # | Name | ID | Type | Slug (for builds) |\n|---|---|---|---|---|\n`;
+    projects.forEach((p, i) => {
+        const name = p.attributes?.name || "?";
+        const type = p.attributes?.type || "?";
+        const fullSlug = p.attributes?.["full-slug"] || p.attributes?.slug || "?";
+        output += `| ${i + 1} | ${name} | ${p.id} | ${type} | \`${fullSlug}\` |\n`;
+    });
+    if (orgSlug) {
+        output += `\n**Organization:** ${orgSlug}\n`;
+    }
+    output += `\n### Usage\n\n`;
+    output += `- \`percy_get_builds\` with project_slug "${firstSlug}" — List builds for a project\n`;
+    output += `- \`percy_create_project\` with name "my-project" — Create new project & activate token\n`;
+    output += `- \`percy_create_build\` with project_name "my-project" — Create a build\n`;
+    return { content: [{ type: "text", text: output }] };
+}

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

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

package/dist/tools/percy-mcp/v2/get-snapshot.js

@@ -0,0 +1,96 @@
+import { percyGet } from "../../../lib/percy-api/percy-auth.js";
+export async function percyGetSnapshot(args, config) {
+    const response = await percyGet(`/snapshots/${args.snapshot_id}`, config, {
+        include: [
+            "comparisons.head-screenshot.image",
+            "comparisons.base-screenshot.image",
+            "comparisons.diff-image",
+            "comparisons.ai-diff-image",
+            "comparisons.browser.browser-family",
+            "comparisons.comparison-tag",
+        ].join(","),
+    });
+    const snap = response?.data || {};
+    const attrs = snap.attributes || {};
+    const included = response?.included || [];
+    let output = `## Snapshot: ${attrs.name || args.snapshot_id}\n\n`;
+    if (attrs["display-name"] && attrs["display-name"] !== attrs.name) {
+        output += `**Display name:** ${attrs["display-name"]}\n`;
+    }
+    output += `| Field | Value |\n|---|---|\n`;
+    output += `| **Review** | ${attrs["review-state"] || "—"} (${attrs["review-state-reason"] || "—"}) |\n`;
+    output += `| **Diff ratio** | ${attrs["diff-ratio"] != null ? (attrs["diff-ratio"] * 100).toFixed(2) + "%" : "—"} |\n`;
+    output += `| **Test case** | ${attrs["test-case-name"] || "none"} |\n`;
+    output += `| **Comments** | ${attrs["total-open-comments"] ?? 0} |\n`;
+    output += `| **Layout** | ${attrs["enable-layout"] ? "enabled" : "disabled"} |\n`;
+    // Comparisons table
+    const comps = included.filter((i) => i.type === "comparisons");
+    const browsers = new Map(included
+        .filter((i) => i.type === "browsers")
+        .map((b) => {
+        const family = included.find((f) => f.type === "browser-families" &&
+            f.id === b.relationships?.["browser-family"]?.data?.id);
+        return [
+            b.id,
+            `${family?.attributes?.name || "?"} ${b.attributes?.version || ""}`,
+        ];
+    }));
+    const images = new Map(included
+        .filter((i) => i.type === "images")
+        .map((img) => [img.id, img.attributes]));
+    if (comps.length > 0) {
+        output += `\n### Comparisons (${comps.length})\n\n`;
+        output += `| Browser | Width | Diff | AI Diff | AI State | Bugs |\n|---|---|---|---|---|---|\n`;
+        comps.forEach((c) => {
+            const ca = c.attributes || {};
+            const browserId = c.relationships?.browser?.data?.id;
+            const browserName = browsers.get(browserId) || "?";
+            const diff = ca["diff-ratio"] != null
+                ? (ca["diff-ratio"] * 100).toFixed(1) + "%"
+                : "—";
+            const aiDiff = ca["ai-diff-ratio"] != null
+                ? (ca["ai-diff-ratio"] * 100).toFixed(1) + "%"
+                : "—";
+            const aiState = ca["ai-processing-state"] || "—";
+            const bugs = ca["ai-details"]?.["total-potential-bugs"] ?? "—";
+            output += `| ${browserName} | ${ca.width || "?"}px | ${diff} | ${aiDiff} | ${aiState} | ${bugs} |\n`;
+        });
+        // Show AI regions for comparisons that have them
+        const compsWithRegions = comps.filter((c) => c.attributes?.["applied-regions"]?.length > 0);
+        if (compsWithRegions.length > 0) {
+            output += `\n### AI Detected Changes\n\n`;
+            for (const c of compsWithRegions) {
+                const regions = c.attributes["applied-regions"];
+                regions.forEach((r) => {
+                    const ignored = r.ignored ? " *(ignored)*" : "";
+                    output += `- **${r.change_title || r.change_type || "Change"}** (${r.change_type || "?"})${ignored}\n`;
+                    if (r.change_description)
+                        output += `  ${r.change_description}\n`;
+                    if (r.change_reason)
+                        output += `  *Reason: ${r.change_reason}*\n`;
+                });
+            }
+        }
+        // Image URLs for first comparison
+        const firstComp = comps[0];
+        const headScreenshotId = firstComp?.relationships?.["head-screenshot"]?.data?.id;
+        const headScreenshot = included.find((i) => i.type === "screenshots" && i.id === headScreenshotId);
+        const headImageId = headScreenshot?.relationships?.image?.data?.id;
+        const headImage = headImageId ? images.get(headImageId) : null;
+        if (headImage?.url) {
+            output += `\n### Images (first comparison)\n\n`;
+            output += `**Head:** ${headImage.url}\n`;
+            const baseScreenshotId = firstComp?.relationships?.["base-screenshot"]?.data?.id;
+            const baseScreenshot = included.find((i) => i.type === "screenshots" && i.id === baseScreenshotId);
+            const baseImageId = baseScreenshot?.relationships?.image?.data?.id;
+            const baseImage = baseImageId ? images.get(baseImageId) : null;
+            if (baseImage?.url)
+                output += `**Base:** ${baseImage.url}\n`;
+            const diffImageId = firstComp?.relationships?.["diff-image"]?.data?.id;
+            const diffImage = diffImageId ? images.get(diffImageId) : null;
+            if (diffImage?.url)
+                output += `**Diff:** ${diffImage.url}\n`;
+        }
+    }
+    return { content: [{ type: "text", text: output }] };
+}

package/dist/tools/percy-mcp/v2/get-test-case-history.d.ts

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

package/dist/tools/percy-mcp/v2/get-test-case-history.js

@@ -0,0 +1,20 @@
+import { percyGet } from "../../../lib/percy-api/percy-auth.js";
+export async function percyGetTestCaseHistory(args, config) {
+    const response = await percyGet("/test-case-histories", config, {
+        test_case_id: args.test_case_id,
+    });
+    const history = response?.data || [];
+    if (!history.length) {
+        return {
+            content: [{ type: "text", text: "No history found for this test case." }],
+        };
+    }
+    let output = `## Test Case History\n\n`;
+    output += `| # | Build | State | Total | Failed | Unreviewed |\n|---|---|---|---|---|---|\n`;
+    history.forEach((entry, i) => {
+        const attrs = entry.attributes || {};
+        const buildId = entry.relationships?.build?.data?.id || "?";
+        output += `| ${i + 1} | #${buildId} | ${attrs["review-state"] ?? "?"} | ${attrs["total-snapshots"] ?? "?"} | ${attrs["failed-snapshots"] ?? "?"} | ${attrs["unreviewed-snapshots"] ?? "?"} |\n`;
+    });
+    return { content: [{ type: "text", text: output }] };
+}

package/dist/tools/percy-mcp/v2/get-test-cases.d.ts

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

package/dist/tools/percy-mcp/v2/get-test-cases.js

@@ -0,0 +1,36 @@
+import { percyGet } from "../../../lib/percy-api/percy-auth.js";
+export async function percyGetTestCases(args, config) {
+    // Get test cases
+    const params = { project_id: args.project_id };
+    const response = await percyGet("/test-cases", config, params);
+    const testCases = response?.data || [];
+    if (!testCases.length) {
+        return {
+            content: [
+                { type: "text", text: "No test cases found for this project." },
+            ],
+        };
+    }
+    let output = `## Test Cases (${testCases.length})\n\n`;
+    output += `| # | Name | ID |\n|---|---|---|\n`;
+    testCases.forEach((tc, i) => {
+        const name = tc.attributes?.name || tc.name || "?";
+        output += `| ${i + 1} | ${name} | ${tc.id} |\n`;
+    });
+    // If build_id provided, get executions
+    if (args.build_id) {
+        const execResponse = await percyGet("/test-case-executions", config, {
+            build_id: args.build_id,
+        });
+        const executions = execResponse?.data || [];
+        if (executions.length) {
+            output += `\n### Executions for Build ${args.build_id}\n\n`;
+            output += `| Test Case | Total | Failed | Unreviewed | State |\n|---|---|---|---|---|\n`;
+            executions.forEach((exec) => {
+                const attrs = exec.attributes || {};
+                output += `| ${attrs["test-case-name"] || exec.id} | ${attrs["total-snapshots"] ?? "?"} | ${attrs["failed-snapshots"] ?? "?"} | ${attrs["unreviewed-snapshots"] ?? "?"} | ${attrs["review-state"] ?? "?"} |\n`;
+            });
+        }
+    }
+    return { content: [{ type: "text", text: output }] };
+}

package/dist/tools/percy-mcp/v2/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Percy MCP Tools v2 — Simplified, production-ready tools.
+ *
+ * Key changes from v1:
+ * - ALL read operations use BrowserStack Basic Auth (not Percy Token)
+ * - Fewer, more powerful tools (quality > quantity)
+ * - Every tool tested against real Percy API
+ *
+ * Tools (21 total):
+ *   percy_create_project       — Create/get a Percy project
+ *   percy_create_build         — Create build (URL snapshot / screenshot upload / test wrap)
+ *   percy_get_projects         — List projects
+ *   percy_get_builds           — List builds with filters
+ *   percy_auth_status          — Check auth
+ *   percy_figma_build          — Create build from Figma designs
+ *   percy_figma_baseline       — Update Figma design baseline
+ *   percy_figma_link           — Get Figma link for snapshot/comparison
+ *   percy_get_insights         — Testing health metrics
+ *   percy_manage_insights_email — Configure insights email recipients
+ *   percy_get_test_cases       — List test cases for a project
+ *   percy_get_test_case_history — Test case execution history
+ *   percy_discover_urls        — Discover URLs from sitemaps
+ *   percy_get_devices          — List browsers/devices/viewports
+ *   percy_manage_domains       — Get/update allowed/error domains
+ *   percy_manage_usage_alerts  — Configure usage alert thresholds
+ *   percy_preview_comparison   — Trigger on-demand diff recomputation
+ *   percy_search_builds        — Advanced build item search
+ *   percy_list_integrations    — List org integrations
+ *   percy_migrate_integrations — Migrate integrations between orgs
+ *   percy_create_app_build     — Create App Percy BYOS build from device screenshots
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BrowserStackConfig } from "../../../lib/types.js";
+export declare function registerPercyMcpToolsV2(server: McpServer, config: BrowserStackConfig): Record<string, any>;
+export default registerPercyMcpToolsV2;