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

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

@@ -1,94 +0,0 @@
-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

@@ -1,5 +0,0 @@
-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

@@ -1,33 +0,0 @@
-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

@@ -1,7 +0,0 @@
-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

@@ -1,52 +0,0 @@
-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

@@ -1,6 +0,0 @@
-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

@@ -1,41 +0,0 @@
-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

@@ -1,5 +0,0 @@
-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

@@ -1,96 +0,0 @@
-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

@@ -1,5 +0,0 @@
-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

@@ -1,20 +0,0 @@
-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

@@ -1,6 +0,0 @@
-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

@@ -1,36 +0,0 @@
-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

@@ -1,35 +0,0 @@
-/**
- * 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;