@browserstack/mcp-server 1.2.3 → 1.2.4

package/dist/tools/review-agent-utils/build-counts.js

@@ -0,0 +1,44 @@
+// Utility for fetching the count of Percy builds and orgId.
+export async function getPercyBuildCount(percyToken) {
+    const apiUrl = `https://percy.io/api/v1/builds`;
+    const response = await fetch(apiUrl, {
+        headers: {
+            Authorization: `Token token=${percyToken}`,
+            "Content-Type": "application/json",
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to fetch Percy builds: ${response.statusText}`);
+    }
+    const data = await response.json();
+    const builds = data.data ?? [];
+    const included = data.included ?? [];
+    let isFirstBuild = false;
+    let lastBuildId;
+    let orgId;
+    let browserIds = [];
+    if (builds.length === 0) {
+        return {
+            noBuilds: true,
+            isFirstBuild: false,
+            lastBuildId: undefined,
+            orgId,
+            browserIds: [],
+        };
+    }
+    else {
+        isFirstBuild = builds.length === 1;
+        lastBuildId = builds[0].id;
+    }
+    // Extract browserIds from the latest build if available
+    browserIds =
+        builds[0]?.relationships?.browsers?.data
+            ?.map((b) => b.id)
+            ?.filter((id) => typeof id === "string") ?? [];
+    // Extract orgId from the `included` projects block
+    const project = included.find((item) => item.type === "projects");
+    if (project?.relationships?.organization?.data?.id) {
+        orgId = project.relationships.organization.data.id;
+    }
+    return { noBuilds: false, isFirstBuild, lastBuildId, orgId, browserIds };
+}

package/dist/tools/review-agent-utils/percy-approve-reject.d.ts

@@ -0,0 +1,6 @@
+import { BrowserStackConfig } from "../../lib/types.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare function approveOrDeclinePercyBuild(args: {
+    buildId: string;
+    action: "approve" | "unapprove" | "reject";
+}, config: BrowserStackConfig): Promise<CallToolResult>;

package/dist/tools/review-agent-utils/percy-approve-reject.js

@@ -0,0 +1,39 @@
+import { getBrowserStackAuth } from "../../lib/get-auth.js";
+export async function approveOrDeclinePercyBuild(args, config) {
+    const { buildId, action } = args;
+    // Get Basic Auth credentials
+    const authString = getBrowserStackAuth(config);
+    const auth = Buffer.from(authString).toString("base64");
+    // Prepare request body
+    const body = {
+        data: {
+            type: "reviews",
+            attributes: { action },
+            relationships: {
+                build: { data: { type: "builds", id: buildId } },
+            },
+        },
+    };
+    // Send request to Percy API
+    const response = await fetch("https://percy.io/api/v1/reviews", {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Basic ${auth}`,
+        },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`Percy build ${action} failed: ${response.status} ${errorText}`);
+    }
+    const result = await response.json();
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Percy build ${buildId} was ${result.data.attributes["review-state"]} by ${result.data.attributes["action-performed-by"].user_name}`,
+            },
+        ],
+    };
+}

package/dist/tools/review-agent-utils/percy-diffs.d.ts

@@ -0,0 +1,9 @@
+export interface PercySnapshotDiff {
+    id: string;
+    name: string | null;
+    title: string;
+    description: string | null;
+    coordinates: any;
+}
+export declare function getPercySnapshotDiff(snapshotId: string, percyToken: string): Promise<PercySnapshotDiff[]>;
+export declare function getPercySnapshotDiffs(snapshotIds: string[], percyToken: string): Promise<PercySnapshotDiff[]>;

package/dist/tools/review-agent-utils/percy-diffs.js

@@ -0,0 +1,35 @@
+export async function getPercySnapshotDiff(snapshotId, percyToken) {
+    const apiUrl = `https://percy.io/api/v1/snapshots/${snapshotId}`;
+    const response = await fetch(apiUrl, {
+        headers: {
+            Authorization: `Token token=${percyToken}`,
+            "Content-Type": "application/json",
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to fetch Percy snapshot ${snapshotId}: ${response.statusText}`);
+    }
+    const data = await response.json();
+    const pageUrl = data.data.attributes?.name || null;
+    const changes = [];
+    const comparisons = data.included?.filter((item) => item.type === "comparisons") ?? [];
+    for (const comparison of comparisons) {
+        const appliedRegions = comparison.attributes?.["applied-regions"] ?? [];
+        for (const region of appliedRegions) {
+            if (region.ignored)
+                continue;
+            changes.push({
+                id: String(region.id),
+                name: pageUrl,
+                title: region.change_title,
+                description: region.change_description ?? null,
+                coordinates: region.coordinates ?? null,
+            });
+        }
+    }
+    return changes;
+}
+export async function getPercySnapshotDiffs(snapshotIds, percyToken) {
+    const allDiffs = await Promise.all(snapshotIds.map((id) => getPercySnapshotDiff(id, percyToken)));
+    return allDiffs.flat();
+}

package/dist/tools/review-agent-utils/percy-snapshots.d.ts

@@ -0,0 +1,11 @@
+import { BrowserStackConfig } from "../../lib/types.js";
+export declare function getChangedPercySnapshotIds(buildId: string, config: BrowserStackConfig, orgId: string | undefined, browserIds: string[]): Promise<string[]>;
+export declare function constructPercyBuildItemsUrl({ buildId, orgId, category, subcategories, browserIds, widths, groupSnapshotsBy, }: {
+    buildId: string;
+    orgId: string;
+    category?: string[];
+    subcategories?: string[];
+    browserIds?: string[];
+    widths?: string[];
+    groupSnapshotsBy?: string;
+}): string;

package/dist/tools/review-agent-utils/percy-snapshots.js

@@ -0,0 +1,58 @@
+import { getBrowserStackAuth } from "../../lib/get-auth.js";
+import { sanitizeUrlParam } from "../../lib/utils.js";
+// Utility for fetching only the IDs of changed Percy snapshots for a given build.
+export async function getChangedPercySnapshotIds(buildId, config, orgId, browserIds) {
+    if (!buildId || !orgId) {
+        throw new Error("Failed to fetch AI Summary: Missing build ID or organization ID");
+    }
+    const urlStr = constructPercyBuildItemsUrl({
+        buildId,
+        orgId,
+        category: ["changed"],
+        subcategories: ["unreviewed", "approved", "changes_requested"],
+        groupSnapshotsBy: "similar_diff",
+        browserIds,
+        widths: ["375", "1280", "1920"],
+    });
+    const authString = getBrowserStackAuth(config);
+    const auth = Buffer.from(authString).toString("base64");
+    const response = await fetch(urlStr, {
+        headers: {
+            Authorization: `Basic ${auth}`,
+            "Content-Type": "application/json",
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to fetch changed Percy snapshots: ${response.status} ${response.statusText}`);
+    }
+    const responseData = await response.json();
+    const buildItems = responseData.data ?? [];
+    if (buildItems.length === 0) {
+        return [];
+    }
+    const snapshotIds = buildItems
+        .flatMap((item) => item.attributes?.["snapshot-ids"] ?? [])
+        .map((id) => String(id));
+    return snapshotIds;
+}
+export function constructPercyBuildItemsUrl({ buildId, orgId, category = [], subcategories = [], browserIds = [], widths = [], groupSnapshotsBy, }) {
+    const url = new URL("https://percy.io/api/v1/build-items");
+    url.searchParams.set("filter[build-id]", sanitizeUrlParam(buildId));
+    url.searchParams.set("filter[organization-id]", sanitizeUrlParam(orgId));
+    if (category && category.length > 0) {
+        category.forEach((cat) => url.searchParams.append("filter[category][]", sanitizeUrlParam(cat)));
+    }
+    if (subcategories && subcategories.length > 0) {
+        subcategories.forEach((sub) => url.searchParams.append("filter[subcategories][]", sanitizeUrlParam(sub)));
+    }
+    if (browserIds && browserIds.length > 0) {
+        browserIds.forEach((id) => url.searchParams.append("filter[browser_ids][]", sanitizeUrlParam(id)));
+    }
+    if (widths && widths.length > 0) {
+        widths.forEach((w) => url.searchParams.append("filter[widths][]", sanitizeUrlParam(w)));
+    }
+    if (groupSnapshotsBy) {
+        url.searchParams.set("filter[group_snapshots_by]", sanitizeUrlParam(groupSnapshotsBy));
+    }
+    return url.toString();
+}

package/dist/tools/review-agent.d.ts

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

package/dist/tools/review-agent.js

@@ -0,0 +1,56 @@
+import { getBrowserStackAuth } from "../lib/get-auth.js";
+import { getPercyBuildCount } from "./review-agent-utils/build-counts.js";
+import { getChangedPercySnapshotIds } from "./review-agent-utils/percy-snapshots.js";
+import { PercyIntegrationTypeEnum } from "./sdk-utils/common/types.js";
+import { fetchPercyToken } from "./sdk-utils/percy-web/fetchPercyToken.js";
+import { getPercySnapshotDiffs, } from "./review-agent-utils/percy-diffs.js";
+export async function fetchPercyChanges(args, config) {
+    const { project_name } = args;
+    const authorization = getBrowserStackAuth(config);
+    // Get Percy token for the project
+    const percyToken = await fetchPercyToken(project_name, authorization, {
+        type: PercyIntegrationTypeEnum.WEB,
+    });
+    // Get build info (noBuilds, isFirstBuild, lastBuildId)
+    const { noBuilds, isFirstBuild, lastBuildId, orgId, browserIds } = await getPercyBuildCount(percyToken);
+    if (noBuilds) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "No Percy builds found. Please run your first Percy scan to start visual testing.",
+                },
+            ],
+        };
+    }
+    if (isFirstBuild || !lastBuildId) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "This is the first Percy build. No baseline exists to compare changes.",
+                },
+            ],
+        };
+    }
+    // Get snapshot IDs for the latest build
+    const snapshotIds = await getChangedPercySnapshotIds(lastBuildId, config, orgId, browserIds);
+    // Fetch all diffs concurrently and flatten results
+    const allDiffs = await getPercySnapshotDiffs(snapshotIds, percyToken);
+    if (allDiffs.length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "AI Summary is not yet available for this build/framework. There may still be visual changes—please review the build on the dashboard.",
+                },
+            ],
+        };
+    }
+    return {
+        content: allDiffs.map((diff) => ({
+            type: "text",
+            text: `${diff.name} → ${diff.title}: ${diff.description ?? ""}`,
+        })),
+    };
+}

package/dist/tools/run-percy-scan.d.ts

@@ -0,0 +1,8 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { PercyIntegrationTypeEnum } from "./sdk-utils/common/types.js";
+import { BrowserStackConfig } from "../lib/types.js";
+export declare function runPercyScan(args: {
+    projectName: string;
+    integrationType: PercyIntegrationTypeEnum;
+    instruction?: string;
+}, config: BrowserStackConfig): Promise<CallToolResult>;

package/dist/tools/run-percy-scan.js

@@ -0,0 +1,37 @@
+import { getBrowserStackAuth } from "../lib/get-auth.js";
+import { fetchPercyToken } from "./sdk-utils/percy-web/fetchPercyToken.js";
+export async function runPercyScan(args, config) {
+    const { projectName, integrationType, instruction } = args;
+    const authorization = getBrowserStackAuth(config);
+    const percyToken = await fetchPercyToken(projectName, authorization, {
+        type: integrationType,
+    });
+    const steps = [generatePercyTokenInstructions(percyToken)];
+    if (instruction) {
+        steps.push(`Use the provided test command with Percy:\n${instruction}`, `If this command fails or is incorrect, fall back to the default approach below.`);
+    }
+    steps.push(`Attempt to infer the project's test command from context (high confidence commands first):
+    - Java → mvn test
+    - Python → pytest
+    - Node.js → npm test or yarn test
+    - Cypress → cypress run
+    or from package.json scripts`, `Wrap the inferred command with Percy:\nnpx percy exec -- <test command>`, `If the test command cannot be inferred confidently, ask the user directly for the correct test command.`);
+    const instructionContext = steps
+        .map((step, index) => `${index + 1}. ${step}`)
+        .join("\n\n");
+    return {
+        content: [
+            {
+                type: "text",
+                text: instructionContext,
+            },
+        ],
+    };
+}
+function generatePercyTokenInstructions(percyToken) {
+    return `Set the environment variable for your project:
+
+export PERCY_TOKEN="${percyToken}"
+
+(For Windows: use 'setx PERCY_TOKEN "${percyToken}"' or 'set PERCY_TOKEN=${percyToken}' as appropriate.)`;
+}

package/dist/tools/sdk-utils/{commands.d.ts → bstack/commands.d.ts}

@@ -1,3 +1,3 @@
-import { SDKSupportedLanguage } from "./types.js";
+import { SDKSupportedLanguage } from "../common/types.js";
 export declare function getSDKPrefixCommand(language: SDKSupportedLanguage, framework: string, username: string, accessKey: string): string;
 export declare function getJavaFrameworkForMaven(framework: string): string;

package/dist/tools/sdk-utils/bstack/commands.js

@@ -0,0 +1,88 @@
+// Constants
+const MAVEN_ARCHETYPE_GROUP_ID = "com.browserstack";
+const MAVEN_ARCHETYPE_ARTIFACT_ID = "browserstack-sdk-archetype-integrate";
+const MAVEN_ARCHETYPE_VERSION = "1.0";
+// Mapping of test frameworks to their corresponding Maven archetype framework names
+const JAVA_FRAMEWORK_MAP = {
+    testng: "testng",
+    junit5: "junit5",
+    junit4: "junit4",
+    cucumber: "cucumber-testng",
+};
+// Template for Node.js SDK setup instructions
+const NODEJS_SDK_INSTRUCTIONS = (username, accessKey) => `---STEP---
+Install BrowserStack Node SDK using command:
+\`\`\`bash
+npm i -D browserstack-node-sdk@latest
+\`\`\`
+---STEP---
+Run the following command to setup browserstack sdk:
+\`\`\`bash
+npx setup --username ${username} --key ${accessKey}
+\`\`\``;
+// Template for Gradle setup instructions (platform-independent)
+const GRADLE_SETUP_INSTRUCTIONS = `
+**For Gradle setup:**
+1. Add browserstack-java-sdk to dependencies:
+   compileOnly 'com.browserstack:browserstack-java-sdk:latest.release'
+
+2. Add browserstackSDK path variable:
+   def browserstackSDKArtifact = configurations.compileClasspath.resolvedConfiguration.resolvedArtifacts.find { it.name == 'browserstack-java-sdk' }
+
+3. Add javaagent to gradle tasks:
+   jvmArgs "-javaagent:\${browserstackSDKArtifact.file}"
+`;
+// Generates Maven archetype command for Windows platform
+function getMavenCommandForWindows(framework, mavenFramework) {
+    return (`mvn archetype:generate -B ` +
+        `-DarchetypeGroupId="${MAVEN_ARCHETYPE_GROUP_ID}" ` +
+        `-DarchetypeArtifactId="${MAVEN_ARCHETYPE_ARTIFACT_ID}" ` +
+        `-DarchetypeVersion="${MAVEN_ARCHETYPE_VERSION}" ` +
+        `-DgroupId="${MAVEN_ARCHETYPE_GROUP_ID}" ` +
+        `-DartifactId="${MAVEN_ARCHETYPE_ARTIFACT_ID}" ` +
+        `-Dversion="${MAVEN_ARCHETYPE_VERSION}" ` +
+        `-DBROWSERSTACK_USERNAME="${process.env.BROWSERSTACK_USERNAME}" ` +
+        `-DBROWSERSTACK_ACCESS_KEY="${process.env.BROWSERSTACK_ACCESS_KEY}" ` +
+        `-DBROWSERSTACK_FRAMEWORK="${mavenFramework}"`);
+}
+// Generates Maven archetype command for Unix-like platforms (macOS/Linux)
+function getMavenCommandForUnix(username, accessKey, mavenFramework) {
+    return `mvn archetype:generate -B -DarchetypeGroupId=${MAVEN_ARCHETYPE_GROUP_ID} \\
+-DarchetypeArtifactId=${MAVEN_ARCHETYPE_ARTIFACT_ID} -DarchetypeVersion=${MAVEN_ARCHETYPE_VERSION} \\
+-DgroupId=${MAVEN_ARCHETYPE_GROUP_ID} -DartifactId=${MAVEN_ARCHETYPE_ARTIFACT_ID} -Dversion=${MAVEN_ARCHETYPE_VERSION} \\
+-DBROWSERSTACK_USERNAME="${username}" \\
+-DBROWSERSTACK_ACCESS_KEY="${accessKey}" \\
+-DBROWSERSTACK_FRAMEWORK="${mavenFramework}"`;
+}
+// Generates Java SDK setup instructions with Maven/Gradle options
+function getJavaSDKInstructions(framework, username, accessKey) {
+    const mavenFramework = getJavaFrameworkForMaven(framework);
+    const isWindows = process.platform === "win32";
+    const platformLabel = isWindows ? "Windows" : "macOS/Linux";
+    const mavenCommand = isWindows
+        ? getMavenCommandForWindows(framework, mavenFramework)
+        : getMavenCommandForUnix(username, accessKey, mavenFramework);
+    return `---STEP---
+Install BrowserStack Java SDK
+
+**Maven command for ${framework} (${platformLabel}):**
+Run the command, it is required to generate the browserstack-sdk-archetype-integrate project:
+${mavenCommand}
+
+Alternative setup for Gradle users:
+${GRADLE_SETUP_INSTRUCTIONS}`;
+}
+// Main function to get SDK setup commands based on language and framework
+export function getSDKPrefixCommand(language, framework, username, accessKey) {
+    switch (language) {
+        case "nodejs":
+            return NODEJS_SDK_INSTRUCTIONS(username, accessKey);
+        case "java":
+            return getJavaSDKInstructions(framework, username, accessKey);
+        default:
+            return "";
+    }
+}
+export function getJavaFrameworkForMaven(framework) {
+    return JAVA_FRAMEWORK_MAP[framework] || framework;
+}

package/dist/tools/sdk-utils/bstack/configUtils.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Utilities for generating BrowserStack configuration files.
+ */
+export declare function generateBrowserStackYMLInstructions(desiredPlatforms: string[], enablePercy: boolean | undefined, projectName: string): string;

package/dist/tools/sdk-utils/bstack/configUtils.js

@@ -0,0 +1,66 @@
+/**
+ * Utilities for generating BrowserStack configuration files.
+ */
+export function generateBrowserStackYMLInstructions(desiredPlatforms, enablePercy = false, projectName) {
+    let ymlContent = `
+# ======================
+# BrowserStack Reporting
+# ======================
+# A single name for your project to organize all your tests. This is required for Percy.
+projectName: ${projectName}
+# TODO: Replace these sample values with your actual project details
+buildName: Sample-Build
+
+# =======================================
+# Platforms (Browsers / Devices to test)
+# =======================================
+# Platforms object contains all the browser / device combinations you want to test on.
+# Generate this on the basis of the following platforms requested by the user:
+# Requested platforms: ${desiredPlatforms}
+platforms:
+  - os: Windows
+    osVersion: 11
+    browserName: chrome
+    browserVersion: latest
+  
+# =======================
+# Parallels per Platform
+# =======================
+# The number of parallel threads to be used for each platform set.
+# BrowserStack's SDK runner will select the best strategy based on the configured value
+#
+# Example 1 - If you have configured 3 platforms and set \`parallelsPerPlatform\` as 2, a total of 6 (2 * 3) parallel threads will be used on BrowserStack
+#
+# Example 2 - If you have configured 1 platform and set \`parallelsPerPlatform\` as 5, a total of 5 (1 * 5) parallel threads will be used on BrowserStack
+parallelsPerPlatform: 1
+
+# =================
+# Local Testing
+# =================
+# Set to true to test local
+browserstackLocal: true
+
+# ===================
+# Debugging features
+# ===================
+debug: true # Visual logs, text logs, etc.
+testObservability: true # For Test Observability`;
+    if (enablePercy) {
+        ymlContent += `
+
+# =====================
+# Percy Visual Testing
+# =====================
+# Set percy to true to enable visual testing.
+# Set percyCaptureMode to 'manual' to control when screenshots are taken.
+percy: true
+percyCaptureMode: manual`;
+    }
+    return `
+---STEP---
+Create a browserstack.yml file in the project root. The file should be in the following format:
+
+\`\`\`yaml${ymlContent}
+\`\`\`
+\n`;
+}

package/dist/tools/sdk-utils/bstack/constants.d.ts

@@ -0,0 +1,58 @@
+import { ConfigMapping } from "../common/types.js";
+/**
+ * ---------- PYTHON INSTRUCTIONS ----------
+ */
+export declare const pythonInstructions: (username: string, accessKey: string) => {
+    setup: string;
+    run: string;
+};
+export declare const generatePythonFrameworkInstructions: (framework: string) => (username: string, accessKey: string) => {
+    setup: string;
+    run: string;
+};
+export declare const robotInstructions: (username: string, accessKey: string) => {
+    setup: string;
+    run: string;
+};
+export declare const behaveInstructions: (username: string, accessKey: string) => {
+    setup: string;
+    run: string;
+};
+export declare const pytestInstructions: (username: string, accessKey: string) => {
+    setup: string;
+    run: string;
+};
+export declare const javaInstructions: (username: string, accessKey: string) => {
+    setup: string;
+    run: string;
+};
+/**
+ * ---------- CSharp INSTRUCTIONS ----------
+ */
+export declare const csharpCommonInstructions: (username: string, accessKey: string) => {
+    setup: string;
+    run: string;
+};
+export declare const csharpPlaywrightCommonInstructions: (username: string, accessKey: string) => {
+    setup: string;
+    run: string;
+};
+/**
+ * ---------- NODEJS INSTRUCTIONS ----------
+ */
+export declare const nodejsInstructions: (username: string, accessKey: string) => {
+    setup: string;
+    run: string;
+};
+/**
+ * ---------- EXPORT CONFIG ----------
+ */
+export declare const webdriverioInstructions: (username: string, accessKey: string) => {
+    setup: string;
+    run: string;
+};
+export declare const cypressInstructions: (username: string, accessKey: string) => {
+    setup: string;
+    run: string;
+};
+export declare const SUPPORTED_CONFIGURATIONS: ConfigMapping;