@browserstack/mcp-server 1.0.13 → 1.0.15

package/dist/tools/applive.js

@@ -1,19 +1,12 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.startAppLiveSession = startAppLiveSession;
-exports.default = addAppLiveTools;
-const zod_1 = require("zod");
-const fs_1 = __importDefault(require("fs"));
-const start_session_1 = require("./applive-utils/start-session");
-const logger_1 = __importDefault(require("../logger"));
-const instrumentation_1 = require("../lib/instrumentation");
+import { z } from "zod";
+import fs from "fs";
+import { startSession } from "./applive-utils/start-session.js";
+import logger from "../logger.js";
+import { trackMCP } from "../lib/instrumentation.js";
 /**
  * Launches an App Live Session on BrowserStack.
  */
-async function startAppLiveSession(args) {
+export async function startAppLiveSession(args) {
     if (!args.desiredPlatform) {
         throw new Error("You must provide a desiredPlatform.");
     }
@@ -31,16 +24,16 @@ async function startAppLiveSession(args) {
     }
     // check if the app path exists && is readable
     try {
-        if (!fs_1.default.existsSync(args.appPath)) {
+        if (!fs.existsSync(args.appPath)) {
             throw new Error("The app path does not exist.");
         }
-        fs_1.default.accessSync(args.appPath, fs_1.default.constants.R_OK);
+        fs.accessSync(args.appPath, fs.constants.R_OK);
     }
     catch (error) {
-        logger_1.default.error("The app path does not exist or is not readable: %s", error);
+        logger.error("The app path does not exist or is not readable: %s", error);
         throw new Error("The app path does not exist or is not readable.");
     }
-    const launchUrl = await (0, start_session_1.startSession)({
+    const launchUrl = await startSession({
         appPath: args.appPath,
         desiredPlatform: args.desiredPlatform,
         desiredPhone: args.desiredPhone,
@@ -55,28 +48,28 @@ async function startAppLiveSession(args) {
         ],
     };
 }
-function addAppLiveTools(server) {
+export default function addAppLiveTools(server) {
     server.tool("runAppLiveSession", "Use this tool when user wants to manually check their app on a particular mobile device using BrowserStack's cloud infrastructure. Can be used to debug crashes, slow performance, etc.", {
-        desiredPhone: zod_1.z
+        desiredPhone: z
             .string()
             .describe("The full name of the device to run the app on. Example: 'iPhone 12 Pro' or 'Samsung Galaxy S20' or 'Google Pixel 6'. Always ask the user for the device they want to use, do not assume it. "),
-        desiredPlatformVersion: zod_1.z
+        desiredPlatformVersion: z
             .string()
             .describe("Specifies the platform version to run the app on. For example, use '12.0' for Android or '16.0' for iOS. If the user says 'latest', 'newest', or similar, normalize it to 'latest'. Likewise, convert terms like 'earliest' or 'oldest' to 'oldest'."),
-        desiredPlatform: zod_1.z
+        desiredPlatform: z
             .enum(["android", "ios"])
             .describe("Which platform to run on, examples: 'android', 'ios'. Set this based on the app path provided."),
-        appPath: zod_1.z
+        appPath: z
             .string()
             .describe("The path to the .ipa or .apk file to install on the device. Always ask the user for the app path, do not assume it."),
     }, async (args) => {
         try {
-            (0, instrumentation_1.trackMCP)("runAppLiveSession", server.server.getClientVersion());
+            trackMCP("runAppLiveSession", server.server.getClientVersion());
             return await startAppLiveSession(args);
         }
         catch (error) {
-            logger_1.default.error("App live session failed: %s", error);
-            (0, instrumentation_1.trackMCP)("runAppLiveSession", server.server.getClientVersion(), error);
+            logger.error("App live session failed: %s", error);
+            trackMCP("runAppLiveSession", server.server.getClientVersion(), error);
             return {
                 content: [
                     {

package/dist/tools/automate-utils/fetch-screenshots.js

@@ -0,0 +1,59 @@
+import config from "../../config.js";
+import { assertOkResponse, maybeCompressBase64 } from "../../lib/utils.js";
+import { SessionType } from "../../lib/constants.js";
+//Extracts screenshot URLs from BrowserStack session logs
+async function extractScreenshotUrls(sessionId, sessionType) {
+    const credentials = `${config.browserstackUsername}:${config.browserstackAccessKey}`;
+    const auth = Buffer.from(credentials).toString("base64");
+    const baseUrl = `https://api.browserstack.com/${sessionType === SessionType.Automate ? "automate" : "app-automate"}`;
+    const url = `${baseUrl}/sessions/${sessionId}/logs`;
+    const response = await fetch(url, {
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Basic ${auth}`,
+        },
+    });
+    await assertOkResponse(response, "Session");
+    const text = await response.text();
+    const urls = [];
+    const SCREENSHOT_PATTERN = /REQUEST.*GET.*\/screenshot/;
+    const RESPONSE_VALUE_PATTERN = /"value"\s*:\s*"([^"]+)"/;
+    // Split logs into lines and process them
+    const lines = text.split("\n");
+    for (let i = 0; i < lines.length - 1; i++) {
+        const currentLine = lines[i];
+        const nextLine = lines[i + 1];
+        if (SCREENSHOT_PATTERN.test(currentLine)) {
+            const match = nextLine.match(RESPONSE_VALUE_PATTERN);
+            if (match && match[1]) {
+                urls.push(match[1]);
+            }
+        }
+    }
+    return urls;
+}
+//Converts screenshot URLs to base64 encoded images
+async function convertUrlsToBase64(urls) {
+    const screenshots = await Promise.all(urls.map(async (url) => {
+        const response = await fetch(url);
+        const arrayBuffer = await response.arrayBuffer();
+        const base64 = Buffer.from(arrayBuffer).toString("base64");
+        // Compress the base64 image if needed
+        const compressedBase64 = await maybeCompressBase64(base64);
+        return {
+            url,
+            base64: compressedBase64,
+        };
+    }));
+    return screenshots;
+}
+//Fetches and converts screenshot URLs to base64 encoded images
+export async function fetchAutomationScreenshots(sessionId, sessionType = SessionType.Automate) {
+    const urls = await extractScreenshotUrls(sessionId, sessionType);
+    if (urls.length === 0) {
+        return [];
+    }
+    // Take only the last 5 URLs
+    const lastFiveUrls = urls.slice(-5);
+    return await convertUrlsToBase64(lastFiveUrls);
+}

package/dist/tools/automate.js

@@ -1,62 +1,69 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getNetworkFailures = getNetworkFailures;
-exports.default = addAutomateTools;
-const zod_1 = require("zod");
-const logger_1 = __importDefault(require("../logger"));
-const api_1 = require("../lib/api");
-const instrumentation_1 = require("../lib/instrumentation");
-/**
- * Fetches failed network requests from a BrowserStack Automate session.
- * Returns network requests that resulted in errors or failed to complete.
- */
-async function getNetworkFailures(args) {
+import { z } from "zod";
+import { fetchAutomationScreenshots } from "./automate-utils/fetch-screenshots.js";
+import { SessionType } from "../lib/constants.js";
+import { trackMCP } from "../lib/instrumentation.js";
+import logger from "../logger.js";
+// Tool function that fetches and processes screenshots from BrowserStack Automate session
+export async function fetchAutomationScreenshotsTool(args) {
     try {
-        const failureLogs = await (0, api_1.retrieveNetworkFailures)(args.sessionId);
-        logger_1.default.info("Successfully fetched failure network logs for session: %s", args.sessionId);
-        // Check if there are any failures
-        const hasFailures = failureLogs.totalFailures > 0;
-        const text = hasFailures
-            ? `${failureLogs.totalFailures} network failure(s) found for session :\n\n${JSON.stringify(failureLogs.failures, null, 2)}`
-            : `No network failures found for session`;
+        const screenshots = await fetchAutomationScreenshots(args.sessionId, args.sessionType);
+        if (screenshots.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "No screenshots found in the session or some unexpected error occurred",
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const results = screenshots.map((screenshot, index) => ({
+            type: "image",
+            text: `Screenshot ${index + 1}`,
+            data: screenshot.base64,
+            mimeType: "image/png",
+            metadata: { url: screenshot.url },
+        }));
         return {
             content: [
                 {
                     type: "text",
-                    text,
+                    text: `Retrieved ${screenshots.length} screenshot(s) from the end of the session.`,
                 },
+                ...results,
             ],
         };
     }
     catch (error) {
-        logger_1.default.error("Failed to fetch network logs: %s", error);
-        throw new Error(error instanceof Error ? error.message : String(error));
+        logger.error("Error during fetching screenshots", error);
+        throw error;
     }
 }
-function addAutomateTools(server) {
-    server.tool("getNetworkFailures", "Use this tool to fetch failed network requests from a BrowserStack Automate session.", {
-        sessionId: zod_1.z.string().describe("The Automate session ID."),
+//Registers the fetchAutomationScreenshots tool with the MCP server
+export default function addAutomationTools(server) {
+    server.tool("fetchAutomationScreenshots", "Fetch and process screenshots from a BrowserStack Automate session", {
+        sessionId: z
+            .string()
+            .describe("The BrowserStack session ID to fetch screenshots from"),
+        sessionType: z
+            .enum([SessionType.Automate, SessionType.AppAutomate])
+            .describe("Type of BrowserStack session"),
     }, async (args) => {
         try {
-            (0, instrumentation_1.trackMCP)("getNetworkFailures", server.server.getClientVersion());
-            return await getNetworkFailures(args);
+            trackMCP("fetchAutomationScreenshots", server.server.getClientVersion());
+            return await fetchAutomationScreenshotsTool(args);
         }
         catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            logger_1.default.error("Failed to fetch network logs: %s", errorMessage);
-            (0, instrumentation_1.trackMCP)("getNetworkFailures", server.server.getClientVersion(), error);
+            trackMCP("fetchAutomationScreenshots", server.server.getClientVersion(), error);
+            const errorMessage = error instanceof Error ? error.message : "Unknown error";
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Failed to fetch network logs: ${errorMessage}`,
-                        isError: true,
+                        text: `Error during fetching automate screenshots: ${errorMessage}`,
                     },
                 ],
-                isError: true,
             };
         }
     });

package/dist/tools/bstack-sdk.js

@@ -1,17 +1,13 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.bootstrapProjectWithSDK = bootstrapProjectWithSDK;
-exports.default = addSDKTools;
-const zod_1 = require("zod");
-const instructions_1 = require("./sdk-utils/instructions");
-const instrumentation_1 = require("../lib/instrumentation");
+import { z } from "zod";
+import { generateBrowserStackYMLInstructions, getInstructionsForProjectConfiguration, } from "./sdk-utils/instructions.js";
+import { trackMCP } from "../lib/instrumentation.js";
 /**
  * BrowserStack SDK hooks into your test framework to seamlessly run tests on BrowserStack.
  * This tool gives instructions to setup a browserstack.yml file in the project root and installs the necessary dependencies.
  */
-async function bootstrapProjectWithSDK({ detectedBrowserAutomationFramework, detectedTestingFramework, detectedLanguage, desiredPlatforms, }) {
-    const instructions = (0, instructions_1.generateBrowserStackYMLInstructions)(desiredPlatforms);
-    const instructionsForProjectConfiguration = (0, instructions_1.getInstructionsForProjectConfiguration)(detectedBrowserAutomationFramework, detectedTestingFramework, detectedLanguage);
+export async function bootstrapProjectWithSDK({ detectedBrowserAutomationFramework, detectedTestingFramework, detectedLanguage, desiredPlatforms, }) {
+    const instructions = generateBrowserStackYMLInstructions(desiredPlatforms);
+    const instructionsForProjectConfiguration = getInstructionsForProjectConfiguration(detectedBrowserAutomationFramework, detectedTestingFramework, detectedLanguage);
     return {
         content: [
             {
@@ -22,23 +18,23 @@ async function bootstrapProjectWithSDK({ detectedBrowserAutomationFramework, det
         ],
     };
 }
-function addSDKTools(server) {
+export default function addSDKTools(server) {
     server.tool("runTestsOnBrowserStack", "Use this tool to get instructions for running tests on BrowserStack.", {
-        detectedBrowserAutomationFramework: zod_1.z
+        detectedBrowserAutomationFramework: z
             .string()
             .describe("The automation framework configured in the project. Example: 'playwright', 'selenium'"),
-        detectedTestingFramework: zod_1.z
+        detectedTestingFramework: z
             .string()
             .describe("The testing framework used in the project. Example: 'jest', 'pytest'"),
-        detectedLanguage: zod_1.z
+        detectedLanguage: z
             .string()
             .describe("The programming language used in the project. Example: 'nodejs', 'python'"),
-        desiredPlatforms: zod_1.z
-            .array(zod_1.z.enum(["windows", "macos", "android", "ios"]))
+        desiredPlatforms: z
+            .array(z.enum(["windows", "macos", "android", "ios"]))
             .describe("The platforms the user wants to test on. Always ask this to the user, do not try to infer this."),
     }, async (args) => {
         try {
-            (0, instrumentation_1.trackMCP)("runTestsOnBrowserStack", server.server.getClientVersion());
+            trackMCP("runTestsOnBrowserStack", server.server.getClientVersion());
             return await bootstrapProjectWithSDK({
                 detectedBrowserAutomationFramework: args.detectedBrowserAutomationFramework,
                 detectedTestingFramework: args.detectedTestingFramework,
@@ -47,7 +43,7 @@ function addSDKTools(server) {
             });
         }
         catch (error) {
-            (0, instrumentation_1.trackMCP)("runTestsOnBrowserStack", server.server.getClientVersion(), error);
+            trackMCP("runTestsOnBrowserStack", server.server.getClientVersion(), error);
             return {
                 content: [
                     {

package/dist/tools/failurelogs-utils/app-automate.js

@@ -0,0 +1,88 @@
+import config from "../../config.js";
+import { assertOkResponse, filterLinesByKeywords } from "../../lib/utils.js";
+const auth = Buffer.from(`${config.browserstackUsername}:${config.browserstackAccessKey}`).toString("base64");
+// DEVICE LOGS
+export async function retrieveDeviceLogs(sessionId, buildId) {
+    const url = `https://api.browserstack.com/app-automate/builds/${buildId}/sessions/${sessionId}/deviceLogs`;
+    const response = await fetch(url, {
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Basic ${auth}`,
+        },
+    });
+    await assertOkResponse(response, "device logs");
+    const logText = await response.text();
+    return filterDeviceFailures(logText);
+}
+// APPIUM LOGS
+export async function retrieveAppiumLogs(sessionId, buildId) {
+    const url = `https://api.browserstack.com/app-automate/builds/${buildId}/sessions/${sessionId}/appiumlogs`;
+    const response = await fetch(url, {
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Basic ${auth}`,
+        },
+    });
+    await assertOkResponse(response, "Appium logs");
+    const logText = await response.text();
+    return filterAppiumFailures(logText);
+}
+// CRASH LOGS
+export async function retrieveCrashLogs(sessionId, buildId) {
+    const url = `https://api.browserstack.com/app-automate/builds/${buildId}/sessions/${sessionId}/crashlogs`;
+    const response = await fetch(url, {
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Basic ${auth}`,
+        },
+    });
+    await assertOkResponse(response, "crash logs");
+    const logText = await response.text();
+    return filterCrashFailures(logText);
+}
+// FILTER HELPERS
+export function filterDeviceFailures(logText) {
+    const keywords = [
+        "error",
+        "exception",
+        "fatal",
+        "anr",
+        "not responding",
+        "process crashed",
+        "crash",
+        "force close",
+        "signal",
+        "java.lang.",
+        "unable to",
+    ];
+    return filterLinesByKeywords(logText, keywords);
+}
+export function filterAppiumFailures(logText) {
+    const keywords = [
+        "error",
+        "fail",
+        "exception",
+        "not found",
+        "no such element",
+        "unable to",
+        "stacktrace",
+        "appium exited",
+        "command failed",
+        "invalid selector",
+    ];
+    return filterLinesByKeywords(logText, keywords);
+}
+export function filterCrashFailures(logText) {
+    const keywords = [
+        "fatal exception",
+        "crash",
+        "signal",
+        "java.lang.",
+        "caused by:",
+        "native crash",
+        "anr",
+        "abort message",
+        "application has stopped unexpectedly",
+    ];
+    return filterLinesByKeywords(logText, keywords);
+}

package/dist/tools/failurelogs-utils/automate.js

@@ -0,0 +1,97 @@
+import config from "../../config.js";
+import { assertOkResponse, filterLinesByKeywords } from "../../lib/utils.js";
+const auth = Buffer.from(`${config.browserstackUsername}:${config.browserstackAccessKey}`).toString("base64");
+// NETWORK LOGS
+export async function retrieveNetworkFailures(sessionId) {
+    const url = `https://api.browserstack.com/automate/sessions/${sessionId}/networklogs`;
+    const response = await fetch(url, {
+        method: "GET",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Basic ${auth}`,
+        },
+    });
+    await assertOkResponse(response, "network logs");
+    const networklogs = await response.json();
+    // Filter for failure logs
+    const failureEntries = networklogs.log.entries.filter((entry) => {
+        return (entry.response.status === 0 ||
+            entry.response.status >= 400 ||
+            entry.response._error !== undefined);
+    });
+    // Return only the failure entries with some context
+    return failureEntries.map((entry) => ({
+        startedDateTime: entry.startedDateTime,
+        request: {
+            method: entry.request?.method,
+            url: entry.request?.url,
+            queryString: entry.request?.queryString,
+        },
+        response: {
+            status: entry.response?.status,
+            statusText: entry.response?.statusText,
+            _error: entry.response?._error,
+        },
+        serverIPAddress: entry.serverIPAddress,
+        time: entry.time,
+    }));
+}
+// SESSION LOGS
+export async function retrieveSessionFailures(sessionId) {
+    const url = `https://api.browserstack.com/automate/sessions/${sessionId}/logs`;
+    const response = await fetch(url, {
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Basic ${auth}`,
+        },
+    });
+    await assertOkResponse(response, "session logs");
+    const logText = await response.text();
+    return filterSessionFailures(logText);
+}
+// CONSOLE LOGS
+export async function retrieveConsoleFailures(sessionId) {
+    const url = `https://api.browserstack.com/automate/sessions/${sessionId}/consolelogs`;
+    const response = await fetch(url, {
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Basic ${auth}`,
+        },
+    });
+    await assertOkResponse(response, "console logs");
+    const logText = await response.text();
+    return filterConsoleFailures(logText);
+}
+// FILTER: session logs
+export function filterSessionFailures(logText) {
+    const keywords = [
+        "error",
+        "fail",
+        "exception",
+        "fatal",
+        "unable to",
+        "not found",
+        '"success":false',
+        '"success": false',
+        '"msg":',
+        "console.error",
+        "stderr",
+    ];
+    return filterLinesByKeywords(logText, keywords);
+}
+// FILTER: console logs
+export function filterConsoleFailures(logText) {
+    const keywords = [
+        "failed to load resource",
+        "uncaught",
+        "typeerror",
+        "referenceerror",
+        "scanner is not ready",
+        "status of 4",
+        "status of 5",
+        "not found",
+        "undefined",
+        "error:",
+    ];
+    return filterLinesByKeywords(logText, keywords);
+}