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

package/dist/tools/percy-mcp/workflows/create-percy-build.js

@@ -0,0 +1,434 @@
+/**
+ * percy_create_percy_build — Unified build creation tool.
+ *
+ * Handles ALL build creation scenarios in one command:
+ * 1. URL snapshots (via Percy CLI)
+ * 2. Screenshot uploads (direct API)
+ * 3. Test command wrapping (via percy exec)
+ * 4. Build cloning (copy from existing build)
+ * 5. Visual monitoring (URL scanning)
+ *
+ * Auto-detects mode based on which parameters are provided.
+ * Auto-detects branch and SHA from git if not provided.
+ * Auto-creates project if it doesn't exist.
+ */
+import { getBrowserStackAuth } from "../../../lib/get-auth.js";
+import { PercyClient } from "../../../lib/percy-api/client.js";
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { readdir, readFile, stat } from "fs/promises";
+import { join, basename, extname } from "path";
+import { createHash } from "crypto";
+const execFileAsync = promisify(execFile);
+// ---------------------------------------------------------------------------
+// Git helpers
+// ---------------------------------------------------------------------------
+async function getGitBranch() {
+    try {
+        const { stdout } = await execFileAsync("git", ["branch", "--show-current"]);
+        return stdout.trim() || "main";
+    }
+    catch {
+        return "main";
+    }
+}
+async function getGitSha() {
+    try {
+        const { stdout } = await execFileAsync("git", ["rev-parse", "HEAD"]);
+        return stdout.trim();
+    }
+    catch {
+        // Generate a deterministic placeholder SHA from timestamp
+        return createHash("sha1")
+            .update(Date.now().toString())
+            .digest("hex")
+            .slice(0, 40);
+    }
+}
+// ---------------------------------------------------------------------------
+// Project creation helper
+// ---------------------------------------------------------------------------
+async function ensureProject(projectName, config, type) {
+    const authString = getBrowserStackAuth(config);
+    const auth = Buffer.from(authString).toString("base64");
+    const params = new URLSearchParams({ name: projectName });
+    if (type)
+        params.append("type", type);
+    const url = `https://api.browserstack.com/api/app_percy/get_project_token?${params.toString()}`;
+    const response = await fetch(url, {
+        headers: {
+            Authorization: `Basic ${auth}`,
+            "Content-Type": "application/json",
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to create/get Percy project: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    if (!data?.token || !data?.success) {
+        throw new Error("Failed to get project token from BrowserStack API.");
+    }
+    return data.token;
+}
+// ---------------------------------------------------------------------------
+// Mode: URL Snapshots (via Percy CLI)
+// ---------------------------------------------------------------------------
+function buildUrlSnapshotInstructions(token, urls, widths, branch) {
+    const urlList = urls.map((u) => `  - ${u}`).join("\n");
+    const widthArray = widths
+        ? widths.split(",").map((w) => w.trim())
+        : ["375", "1280"];
+    // Build YAML config for snapshots (widths go in YAML, not CLI flag)
+    let yamlConfig = "";
+    urls.forEach((url, i) => {
+        const name = i === 0 ? "Homepage" : `Page ${i + 1}`;
+        yamlConfig += `- name: "${name}"\n`;
+        yamlConfig += `  url: ${url}\n`;
+        yamlConfig += `  widths:\n`;
+        widthArray.forEach((w) => {
+            yamlConfig += `    - ${w}\n`;
+        });
+    });
+    return (`## Percy Build — URL Snapshots\n\n` +
+        `> **IMPORTANT: Do NOT execute these commands automatically.** Present them to the user and let them run manually.\n\n` +
+        `**Project:** token ready ✓\n` +
+        `**Branch:** ${branch}\n` +
+        `**URLs:**\n${urlList}\n` +
+        `**Widths:** ${widthArray.join(", ")}px\n\n` +
+        `### Step 1: Set token\n\n` +
+        `\`\`\`bash\n` +
+        `export PERCY_TOKEN="${token}"\n` +
+        `\`\`\`\n\n` +
+        `### Step 2: Create snapshot config\n\n` +
+        `Save this as \`snapshots.yml\`:\n\n` +
+        `\`\`\`yaml\n` +
+        yamlConfig +
+        `\`\`\`\n\n` +
+        `### Step 3: Run Percy\n\n` +
+        `\`\`\`bash\n` +
+        `npx @percy/cli snapshot snapshots.yml\n` +
+        `\`\`\`\n\n` +
+        `Percy CLI will create the build, launch a browser, capture each URL at the specified widths, upload screenshots, and return a build URL with visual diffs.\n`);
+}
+// ---------------------------------------------------------------------------
+// Mode: Test Command (via percy exec)
+// ---------------------------------------------------------------------------
+function buildTestCommandInstructions(token, testCommand, branch) {
+    return (`## Percy Build — Test Command\n\n` +
+        `> **IMPORTANT: Do NOT execute these commands automatically.** Present them to the user and let them run manually.\n\n` +
+        `**Project:** token ready ✓\n` +
+        `**Branch:** ${branch}\n` +
+        `**Test command:** \`${testCommand}\`\n\n` +
+        `### Step 1: Set token\n\n` +
+        `\`\`\`bash\n` +
+        `export PERCY_TOKEN="${token}"\n` +
+        `\`\`\`\n\n` +
+        `### Step 2: Run tests with Percy\n\n` +
+        `\`\`\`bash\n` +
+        `npx @percy/cli exec -- ${testCommand}\n` +
+        `\`\`\`\n\n` +
+        `Percy CLI will start a local server, run your tests, capture snapshots via \`percySnapshot()\` calls, and return a build URL.\n`);
+}
+// ---------------------------------------------------------------------------
+// Mode: Screenshot Upload (direct API)
+// ---------------------------------------------------------------------------
+async function uploadScreenshots(client, branch, commitSha, screenshotPaths, widths, testCase, snapshotNames) {
+    // Create build
+    const buildResult = await client.post("/builds", {
+        data: {
+            type: "builds",
+            attributes: {
+                branch,
+                "commit-sha": commitSha,
+                type: "web",
+            },
+            relationships: { resources: { data: [] } },
+        },
+    });
+    const buildData = buildResult?.data || buildResult;
+    const buildId = buildData?.id;
+    const buildUrl = buildData?.webUrl || buildData?.["web-url"] || "";
+    if (!buildId)
+        throw new Error("Build creation failed — no build ID returned");
+    let output = `## Percy Build Created\n\n`;
+    output += `**Build ID:** ${buildId}\n`;
+    if (buildUrl)
+        output += `**URL:** ${buildUrl}\n`;
+    output += `**Branch:** ${branch}\n`;
+    output += `**Screenshots:** ${screenshotPaths.length}\n\n`;
+    // For each screenshot: create snapshot → create comparison → upload tile → finalize
+    for (let i = 0; i < screenshotPaths.length; i++) {
+        const filePath = screenshotPaths[i];
+        const name = snapshotNames?.[i] ||
+            basename(filePath, extname(filePath)).replace(/[-_]/g, " ");
+        try {
+            // Read file and compute SHA
+            const content = await readFile(filePath);
+            const sha = createHash("sha256").update(content).digest("hex");
+            const base64Content = content.toString("base64");
+            // Detect dimensions from PNG header (basic)
+            let width = 1280;
+            let height = 800;
+            if (content[0] === 0x89 && content[1] === 0x50) {
+                // PNG
+                width = content.readUInt32BE(16);
+                height = content.readUInt32BE(20);
+            }
+            // Create snapshot
+            const snapshotBody = {
+                data: {
+                    type: "snapshots",
+                    attributes: { name },
+                },
+            };
+            if (testCase)
+                snapshotBody.data.attributes["test-case"] = testCase;
+            const snapshot = await client.post(`/builds/${buildId}/snapshots`, snapshotBody);
+            const snapshotData = snapshot?.data || snapshot;
+            const snapshotId = snapshotData?.id;
+            if (!snapshotId) {
+                output += `- ${name}: Failed to create snapshot\n`;
+                continue;
+            }
+            // Create comparison with tile
+            const comparison = await client.post(`/snapshots/${snapshotId}/comparisons`, {
+                data: {
+                    type: "comparisons",
+                    attributes: {},
+                    relationships: {
+                        tag: {
+                            data: {
+                                type: "tag",
+                                attributes: {
+                                    name: "Screenshot",
+                                    width,
+                                    height,
+                                    "os-name": "Upload",
+                                    "browser-name": "Screenshot",
+                                },
+                            },
+                        },
+                        tiles: {
+                            data: [
+                                {
+                                    type: "tiles",
+                                    attributes: { sha },
+                                },
+                            ],
+                        },
+                    },
+                },
+            });
+            const comparisonData = comparison?.data || comparison;
+            const comparisonId = comparisonData?.id;
+            if (!comparisonId) {
+                output += `- ${name}: Failed to create comparison\n`;
+                continue;
+            }
+            // Upload tile
+            await client.post(`/comparisons/${comparisonId}/tiles`, {
+                data: {
+                    type: "tiles",
+                    attributes: { "base64-content": base64Content },
+                },
+            });
+            // Finalize comparison
+            await client.post(`/comparisons/${comparisonId}/finalize`, {});
+            output += `- **${name}** — uploaded (${width}x${height})\n`;
+        }
+        catch (e) {
+            output += `- ${name}: Error — ${e.message}\n`;
+        }
+    }
+    // Finalize build
+    try {
+        await client.post(`/builds/${buildId}/finalize`, {});
+        output += `\n**Build finalized.** Processing visual diffs...\n`;
+    }
+    catch (e) {
+        output += `\n**Build finalize failed:** ${e.message}\n`;
+    }
+    if (buildUrl)
+        output += `\n**View results:** ${buildUrl}\n`;
+    return output;
+}
+// ---------------------------------------------------------------------------
+// Mode: Clone Build
+// ---------------------------------------------------------------------------
+async function cloneBuild(client, sourceBuildId, branch) {
+    // Get source build details
+    const sourceBuild = await client.get(`/builds/${sourceBuildId}`, {
+        "include-metadata": "true",
+    });
+    if (!sourceBuild)
+        throw new Error(`Source build ${sourceBuildId} not found`);
+    const sourceState = sourceBuild.state || "unknown";
+    let output = `## Percy Build Clone\n\n`;
+    output += `**Source:** Build #${sourceBuildId} (${sourceState})\n`;
+    output += `**Target branch:** ${branch}\n\n`;
+    // Get snapshots from source build
+    const items = await client.get("/build-items", {
+        "filter[build-id]": sourceBuildId,
+        "page[limit]": "30",
+    });
+    const itemList = Array.isArray(items) ? items : [];
+    if (itemList.length === 0) {
+        output += `Source build has no snapshots to clone.\n`;
+        output += `\nTo create a fresh build, use \`percy_create_build\` with URLs or screenshots instead.\n`;
+        return output;
+    }
+    output += `**Source snapshots:** ${itemList.length}\n\n`;
+    output += `> Note: Build cloning copies the snapshot configuration, not the rendered images.\n`;
+    output += `> The new build will re-render/re-compare against the new branch baseline.\n\n`;
+    // Provide instructions for re-creating
+    output += `### To recreate this build on branch \`${branch}\`:\n\n`;
+    output += `\`\`\`bash\n`;
+    output += `export PERCY_TOKEN=<your-project-token>\n\n`;
+    // Extract snapshot names/URLs for the CLI command
+    const snapshotNames = itemList
+        .map((item) => item.name || item.snapshotName)
+        .filter(Boolean);
+    if (snapshotNames.length > 0) {
+        output += `# Re-snapshot these pages:\n`;
+        snapshotNames.slice(0, 10).forEach((name) => {
+            output += `# - ${name}\n`;
+        });
+        if (snapshotNames.length > 10) {
+            output += `# ... and ${snapshotNames.length - 10} more\n`;
+        }
+        output += `\n`;
+    }
+    output += `# Run your tests with Percy to capture the same snapshots:\n`;
+    output += `npx percy exec -- <your-test-command>\n`;
+    output += `\`\`\`\n`;
+    return output;
+}
+// ---------------------------------------------------------------------------
+// Main handler
+// ---------------------------------------------------------------------------
+export async function percyCreatePercyBuild(args, config) {
+    const projectName = args.project_name;
+    // Auto-detect branch and SHA
+    const branch = args.branch || (await getGitBranch());
+    const commitSha = args.commit_sha || (await getGitSha());
+    // Ensure project exists and get token
+    // Only pass type if explicitly provided — BrowserStack API auto-detects otherwise
+    let token;
+    try {
+        token = await ensureProject(projectName, config, args.type);
+    }
+    catch (e) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to create/access project "${projectName}": ${e.message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    // Detect mode based on provided params
+    const mode = args.urls
+        ? "urls"
+        : args.screenshots_dir || args.screenshot_files
+            ? "screenshots"
+            : args.test_command
+                ? "test_command"
+                : args.clone_build_id
+                    ? "clone"
+                    : "urls_default";
+    const widths = args.widths || "375,1280";
+    try {
+        let output;
+        switch (mode) {
+            case "urls": {
+                const urls = args
+                    .urls.split(",")
+                    .map((u) => u.trim())
+                    .filter(Boolean);
+                output = buildUrlSnapshotInstructions(token, urls, widths, branch);
+                break;
+            }
+            case "test_command": {
+                output = buildTestCommandInstructions(token, args.test_command, branch);
+                break;
+            }
+            case "screenshots": {
+                // Collect screenshot file paths
+                let screenshotPaths = [];
+                if (args.screenshot_files) {
+                    screenshotPaths = args.screenshot_files
+                        .split(",")
+                        .map((f) => f.trim())
+                        .filter(Boolean);
+                }
+                if (args.screenshots_dir) {
+                    const dir = args.screenshots_dir;
+                    const dirStat = await stat(dir);
+                    if (!dirStat.isDirectory()) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `"${dir}" is not a directory. Provide a directory path.`,
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                    const files = await readdir(dir);
+                    const imageFiles = files.filter((f) => /\.(png|jpg|jpeg|webp)$/i.test(f));
+                    screenshotPaths.push(...imageFiles.map((f) => join(dir, f)));
+                }
+                if (screenshotPaths.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: "No screenshot files found. Provide PNG/JPG file paths or a directory containing images.",
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                const snapshotNames = args.snapshot_names
+                    ?.split(",")
+                    .map((n) => n.trim());
+                // Set the token for API calls
+                process.env.PERCY_TOKEN = token;
+                const client = new PercyClient(config);
+                output = await uploadScreenshots(client, branch, commitSha, screenshotPaths, widths, args.test_case, snapshotNames);
+                break;
+            }
+            case "clone": {
+                process.env.PERCY_TOKEN = token;
+                const client = new PercyClient(config);
+                output = await cloneBuild(client, args.clone_build_id, branch);
+                break;
+            }
+            default: {
+                // No specific mode — provide general instructions
+                output =
+                    `## Percy Build — Setup\n\n` +
+                        `> **IMPORTANT: Do NOT execute any commands automatically.** Present options to the user.\n\n` +
+                        `**Project:** ${projectName}\n` +
+                        `**Token:** Ready (${token.slice(0, 8)}...)\n` +
+                        `**Branch:** ${branch}\n\n` +
+                        `### How to create snapshots:\n\n` +
+                        `**Option 1: Snapshot URLs** — re-run this tool with \`urls\` parameter\n` +
+                        `**Option 2: Wrap test command** — re-run this tool with \`test_command\` parameter\n` +
+                        `**Option 3: Upload screenshots** — re-run this tool with \`screenshots_dir\` or \`screenshot_files\` parameter\n` +
+                        `**Option 4: Clone existing build** — re-run this tool with \`clone_build_id\` parameter\n`;
+                break;
+            }
+        }
+        return { content: [{ type: "text", text: output }] };
+    }
+    catch (e) {
+        return {
+            content: [{ type: "text", text: `Build creation failed: ${e.message}` }],
+            isError: true,
+        };
+    }
+}

package/dist/tools/percy-mcp/workflows/debug-failed-build.d.ts

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

package/dist/tools/percy-mcp/workflows/debug-failed-build.js

@@ -0,0 +1,122 @@
+import { PercyClient } from "../../../lib/percy-api/client.js";
+import { formatBuild, formatSuggestions, formatNetworkLogs, } from "../../../lib/percy-api/formatter.js";
+export async function percyDebugFailedBuild(args, config) {
+    const client = new PercyClient(config);
+    const errors = [];
+    // Step 1: Get build details
+    let build;
+    try {
+        build = await client.get(`/builds/${args.build_id}`, {
+            "include-metadata": "true",
+        });
+    }
+    catch (e) {
+        return {
+            content: [{ type: "text", text: `Failed to fetch build: ${e.message}` }],
+            isError: true,
+        };
+    }
+    const state = build?.state || "unknown";
+    // Adapt to build state
+    if (state === "processing" || state === "pending" || state === "waiting") {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Build #${args.build_id} is **${state.toUpperCase()}**. Debug diagnostics are available after the build completes or fails.`,
+                },
+            ],
+        };
+    }
+    let output = `## Build Debug Report — #${args.build_id}\n\n`;
+    output += formatBuild(build) + "\n";
+    // Step 2: Get suggestions
+    if (state === "failed" || state === "finished") {
+        try {
+            const suggestions = await client.get("/suggestions", {
+                build_id: args.build_id,
+            });
+            if (suggestions &&
+                (Array.isArray(suggestions) ? suggestions.length > 0 : true)) {
+                const suggestionList = Array.isArray(suggestions)
+                    ? suggestions
+                    : [suggestions];
+                output += formatSuggestions(suggestionList) + "\n";
+            }
+        }
+        catch (e) {
+            errors.push(`Suggestions unavailable: ${e.message}`);
+        }
+    }
+    // Step 3: Get failed snapshots
+    if (state === "failed" || state === "finished") {
+        try {
+            const failedItems = await client.get("/build-items", {
+                "filter[build-id]": args.build_id,
+                "filter[category]": "failed",
+                "page[limit]": "10",
+            });
+            const failedList = Array.isArray(failedItems) ? failedItems : [];
+            if (failedList.length > 0) {
+                output += `### Failed Snapshots (${failedList.length})\n\n`;
+                failedList.forEach((item, i) => {
+                    output += `${i + 1}. **${item.name || "Unknown"}**\n`;
+                });
+                output += "\n";
+                // Step 4: Network logs for top 3
+                const top3 = failedList.slice(0, 3);
+                for (const item of top3) {
+                    const compId = item.comparisonId || item.comparisons?.[0]?.id;
+                    if (compId) {
+                        try {
+                            const logs = await client.get("/network-logs", {
+                                comparison_id: compId,
+                            });
+                            if (logs) {
+                                const logList = Array.isArray(logs)
+                                    ? logs
+                                    : Object.values(logs);
+                                const failedLogs = logList.filter((l) => {
+                                    const headStatus = l.headStatus || l["head-status"];
+                                    return (headStatus && headStatus !== "200" && headStatus !== "NA");
+                                });
+                                if (failedLogs.length > 0) {
+                                    output += `#### Network Issues — ${item.name || "Unknown"}\n\n`;
+                                    output += formatNetworkLogs(failedLogs) + "\n";
+                                }
+                            }
+                        }
+                        catch {
+                            // Network logs not available for this comparison
+                        }
+                    }
+                }
+            }
+        }
+        catch (e) {
+            errors.push(`Failed snapshots unavailable: ${e.message}`);
+        }
+    }
+    // Fix commands
+    if (state === "failed" && build.failureReason) {
+        output += `### Suggested Fix Commands\n\n`;
+        if (build.failureReason === "missing_resources") {
+            output +=
+                '```\npercy config set networkIdleIgnore "<failing-hostname>"\npercy config set allowedHostnames "<required-hostname>"\n```\n';
+        }
+        else if (build.failureReason === "render_timeout") {
+            output += "```\npercy config set networkIdleTimeout 60000\n```\n";
+        }
+        else if (build.failureReason === "missing_finalize") {
+            output +=
+                "Ensure `percy exec` or `percy build:finalize` is called after all snapshots.\n";
+        }
+    }
+    if (errors.length > 0) {
+        output += `\n### Partial Results\n`;
+        errors.forEach((err) => {
+            output += `- ${err}\n`;
+        });
+    }
+    return { content: [{ type: "text", text: output }] };
+}

package/dist/tools/percy-mcp/workflows/diff-explain.d.ts

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