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

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

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

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

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

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