@browserstack/mcp-server 1.2.1 → 1.2.2

package/README.md

@@ -138,6 +138,8 @@ Generate test cases from PRDs, convert manual tests to low-code automation, and
 
 ## 🛠️ Installation
 
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](http://mcp.browserstack.com/one-click-setup?client=vscode)   [![Install in Cursor](https://img.shields.io/badge/Cursor-Install_Server-24bfa5?style=flat-square&color=000000&logo=visualstudiocode&logoColor=white)](http://mcp.browserstack.com/one-click-setup?client=cursor)
+
 1. **Create a BrowserStack Account**
 
    - Sign up for [BrowserStack](https://www.browserstack.com/users/sign_up) if you don't have an account already.

package/dist/index.d.ts

@@ -2,3 +2,4 @@
 import "dotenv/config";
 export { setLogger } from "./logger.js";
 export { BrowserStackMcpServer } from "./server-factory.js";
+export { trackMCP } from "./lib/instrumentation.js";

package/dist/index.js

@@ -35,3 +35,4 @@ process.on("exit", () => {
 });
 export { setLogger } from "./logger.js";
 export { BrowserStackMcpServer } from "./server-factory.js";
+export { trackMCP } from "./lib/instrumentation.js";

package/dist/lib/device-cache.d.ts

@@ -7,3 +7,4 @@ export declare enum BrowserStackProducts {
  * Fetches and caches BrowserStack datasets (live + app_live + app_automate) with a shared TTL.
  */
 export declare function getDevicesAndBrowsers(type: BrowserStackProducts): Promise<any>;
+export declare function shouldSendStartedEvent(): boolean;

package/dist/lib/device-cache.js

@@ -2,9 +2,11 @@ import fs from "fs";
 import os from "os";
 import path from "path";
 import { apiClient } from "./apiClient.js";
+import config from "../config.js";
 const CACHE_DIR = path.join(os.homedir(), ".browserstack", "combined_cache");
 const CACHE_FILE = path.join(CACHE_DIR, "data.json");
 const TTL_MS = 24 * 60 * 60 * 1000; // 1 day
+const TTL_STARTED_MS = 3 * 60 * 60 * 1000; // 3 Hours
 export var BrowserStackProducts;
 (function (BrowserStackProducts) {
     BrowserStackProducts["LIVE"] = "live";
@@ -49,3 +51,29 @@ export async function getDevicesAndBrowsers(type) {
     fs.writeFileSync(CACHE_FILE, JSON.stringify(cache), "utf8");
     return cache[type];
 }
+// Rate limiter for started event (3H)
+export function shouldSendStartedEvent() {
+    try {
+        if (config && config.REMOTE_MCP) {
+            return false;
+        }
+        if (!fs.existsSync(CACHE_DIR)) {
+            fs.mkdirSync(CACHE_DIR, { recursive: true });
+        }
+        let cache = {};
+        if (fs.existsSync(CACHE_FILE)) {
+            const raw = fs.readFileSync(CACHE_FILE, "utf8");
+            cache = JSON.parse(raw || "{}");
+            const last = parseInt(cache.lastStartedEvent, 10);
+            if (!isNaN(last) && Date.now() - last < TTL_STARTED_MS) {
+                return false;
+            }
+        }
+        cache.lastStartedEvent = Date.now();
+        fs.writeFileSync(CACHE_FILE, JSON.stringify(cache, null, 2), "utf8");
+        return true;
+    }
+    catch {
+        return true;
+    }
+}

package/dist/oninitialized.js

@@ -1,4 +1,5 @@
 import { trackMCP } from "./lib/instrumentation.js";
+import { shouldSendStartedEvent } from "./lib/device-cache.js";
 export function setupOnInitialized(server, config) {
     const nodeVersion = process.versions.node;
     // Check for Node.js version
@@ -6,6 +7,8 @@ export function setupOnInitialized(server, config) {
         throw new Error("Node version is not supported. Please upgrade to 18.0.0 or later.");
     }
     server.server.oninitialized = () => {
-        trackMCP("started", server.server.getClientVersion(), undefined, config);
+        if (shouldSendStartedEvent()) {
+            trackMCP("started", server.server.getClientVersion(), undefined, config);
+        }
     };
 }

package/dist/tools/appautomate-utils/appautomate.d.ts

@@ -26,8 +26,9 @@ export declare function resolveVersion(versions: string[], requestedVersion: str
 export declare function validateArgs(args: {
     desiredPlatform: string;
     desiredPlatformVersion: string;
-    appPath: string;
+    appPath?: string;
     desiredPhone: string;
+    browserstackAppUrl?: string;
 }): void;
 /**
  * Uploads an application file to AppAutomate and returns the app URL

package/dist/tools/appautomate-utils/appautomate.js

@@ -49,21 +49,24 @@ export function resolveVersion(versions, requestedVersion) {
  * Checks for presence and correctness of platform, device, and file types.
  */
 export function validateArgs(args) {
-    const { desiredPlatform, desiredPlatformVersion, appPath, desiredPhone } = args;
+    const { desiredPlatform, desiredPlatformVersion, appPath, desiredPhone, browserstackAppUrl, } = args;
     if (!desiredPlatform || !desiredPhone) {
         throw new Error("Missing required arguments: desiredPlatform and desiredPhone are required");
     }
     if (!desiredPlatformVersion) {
         throw new Error("Missing required arguments: desiredPlatformVersion is required");
     }
-    if (!appPath) {
-        throw new Error("You must provide an appPath.");
-    }
-    if (desiredPlatform === "android" && !appPath.endsWith(".apk")) {
-        throw new Error("You must provide a valid Android app path (.apk).");
-    }
-    if (desiredPlatform === "ios" && !appPath.endsWith(".ipa")) {
-        throw new Error("You must provide a valid iOS app path (.ipa).");
+    if (!appPath && !browserstackAppUrl) {
+        throw new Error("Either appPath or browserstackAppUrl must be provided");
+    }
+    // Only validate app path format if appPath is provided
+    if (appPath) {
+        if (desiredPlatform === "android" && !appPath.endsWith(".apk")) {
+            throw new Error("You must provide a valid Android app path (.apk).");
+        }
+        if (desiredPlatform === "ios" && !appPath.endsWith(".ipa")) {
+            throw new Error("You must provide a valid iOS app path (.ipa).");
+        }
     }
 }
 /**

package/dist/tools/appautomate.js

@@ -19,7 +19,7 @@ async function takeAppScreenshot(args) {
     let driver;
     try {
         validateArgs(args);
-        const { desiredPlatform, desiredPhone, appPath, config } = args;
+        const { desiredPlatform, desiredPhone, appPath, browserstackAppUrl, config, } = args;
         let { desiredPlatformVersion } = args;
         const platforms = (await getDevicesAndBrowsers(BrowserStackProducts.APP_AUTOMATE)).mobile;
         const platformData = platforms.find((p) => p.os === desiredPlatform.toLowerCase());
@@ -35,8 +35,18 @@ async function takeAppScreenshot(args) {
         }
         const authString = getBrowserStackAuth(config);
         const [username, password] = authString.split(":");
-        const app_url = await uploadApp(appPath, username, password);
-        logger.info(`App uploaded. URL: ${app_url}`);
+        let app_url;
+        if (browserstackAppUrl) {
+            app_url = browserstackAppUrl;
+            logger.info(`Using provided BrowserStack app URL: ${app_url}`);
+        }
+        else {
+            if (!appPath) {
+                throw new Error("appPath is required when browserstackAppUrl is not provided");
+            }
+            app_url = await uploadApp(appPath, username, password);
+            logger.info(`App uploaded. URL: ${app_url}`);
+        }
         const capabilities = {
             platformName: desiredPlatform,
             "appium:platformVersion": selectedDevice.os_version,
@@ -89,11 +99,34 @@ async function takeAppScreenshot(args) {
 }
 //Runs AppAutomate tests on BrowserStack by uploading app and test suite, then triggering a test run.
 async function runAppTestsOnBrowserStack(args, config) {
+    // Validate that either paths or URLs are provided for both app and test suite
+    if (!args.browserstackAppUrl && !args.appPath) {
+        throw new Error("appPath is required when browserstackAppUrl is not provided");
+    }
+    if (!args.browserstackTestSuiteUrl && !args.testSuitePath) {
+        throw new Error("testSuitePath is required when browserstackTestSuiteUrl is not provided");
+    }
     switch (args.detectedAutomationFramework) {
         case AppTestPlatform.ESPRESSO: {
             try {
-                const app_url = await uploadEspressoApp(args.appPath, config);
-                const test_suite_url = await uploadEspressoTestSuite(args.testSuitePath, config);
+                let app_url;
+                if (args.browserstackAppUrl) {
+                    app_url = args.browserstackAppUrl;
+                    logger.info(`Using provided BrowserStack app URL: ${app_url}`);
+                }
+                else {
+                    app_url = await uploadEspressoApp(args.appPath, config);
+                    logger.info(`App uploaded. URL: ${app_url}`);
+                }
+                let test_suite_url;
+                if (args.browserstackTestSuiteUrl) {
+                    test_suite_url = args.browserstackTestSuiteUrl;
+                    logger.info(`Using provided BrowserStack test suite URL: ${test_suite_url}`);
+                }
+                else {
+                    test_suite_url = await uploadEspressoTestSuite(args.testSuitePath, config);
+                    logger.info(`Test suite uploaded. URL: ${test_suite_url}`);
+                }
                 const build_id = await triggerEspressoBuild(app_url, test_suite_url, args.devices, args.project);
                 return {
                     content: [
@@ -111,8 +144,24 @@ async function runAppTestsOnBrowserStack(args, config) {
         }
         case AppTestPlatform.XCUITEST: {
             try {
-                const app_url = await uploadXcuiApp(args.appPath, config);
-                const test_suite_url = await uploadXcuiTestSuite(args.testSuitePath, config);
+                let app_url;
+                if (args.browserstackAppUrl) {
+                    app_url = args.browserstackAppUrl;
+                    logger.info(`Using provided BrowserStack app URL: ${app_url}`);
+                }
+                else {
+                    app_url = await uploadXcuiApp(args.appPath, config);
+                    logger.info(`App uploaded. URL: ${app_url}`);
+                }
+                let test_suite_url;
+                if (args.browserstackTestSuiteUrl) {
+                    test_suite_url = args.browserstackTestSuiteUrl;
+                    logger.info(`Using provided BrowserStack test suite URL: ${test_suite_url}`);
+                }
+                else {
+                    test_suite_url = await uploadXcuiTestSuite(args.testSuitePath, config);
+                    logger.info(`Test suite uploaded. URL: ${test_suite_url}`);
+                }
                 const build_id = await triggerXcuiBuild(app_url, test_suite_url, args.devices, args.project, config);
                 return {
                     content: [

package/dist/tools/applive-utils/start-session.d.ts

@@ -1,9 +1,10 @@
 import { BrowserStackConfig } from "../../lib/types.js";
 interface StartSessionArgs {
-    appPath: string;
+    appPath?: string;
     desiredPlatform: "android" | "ios";
     desiredPhone: string;
     desiredPlatformVersion: string;
+    browserstackAppUrl?: string;
 }
 interface StartSessionOptions {
     config: BrowserStackConfig;

package/dist/tools/applive-utils/start-session.js

@@ -11,7 +11,7 @@ import envConfig from "../../config.js";
  * Start an App Live session: filter, select, upload, and open.
  */
 export async function startSession(args, options) {
-    const { appPath, desiredPlatform, desiredPhone, desiredPlatformVersion } = args;
+    const { appPath, desiredPlatform, desiredPhone, desiredPlatformVersion, browserstackAppUrl, } = args;
     const { config } = options;
     // 1) Fetch devices for APP_LIVE
     const data = await getDevicesAndBrowsers(BrowserStackProducts.APP_LIVE);
@@ -38,11 +38,22 @@ export async function startSession(args, options) {
         desiredPlatformVersion !== "oldest") {
         note = `\n Note: The requested version "${desiredPlatformVersion}" is not available. Using "${version}" instead.`;
     }
-    // 6) Upload app
-    const authString = getBrowserStackAuth(config);
-    const [username, password] = authString.split(":");
-    const { app_url } = await uploadApp(appPath, username, password);
-    logger.info(`App uploaded: ${app_url}`);
+    // 6) Upload app or use provided URL
+    let app_url;
+    if (browserstackAppUrl) {
+        app_url = browserstackAppUrl;
+        logger.info(`Using provided BrowserStack app URL: ${app_url}`);
+    }
+    else {
+        if (!appPath) {
+            throw new Error("appPath is required when browserstackAppUrl is not provided");
+        }
+        const authString = getBrowserStackAuth(config);
+        const [username, password] = authString.split(":");
+        const result = await uploadApp(appPath, username, password);
+        app_url = result.app_url;
+        logger.info(`App uploaded: ${app_url}`);
+    }
     if (!app_url) {
         throw new Error("Failed to upload app. Please try again.");
     }

package/dist/tools/applive.d.ts

@@ -7,7 +7,8 @@ import { BrowserStackConfig } from "../lib/types.js";
 export declare function startAppLiveSession(args: {
     desiredPlatform: string;
     desiredPlatformVersion: string;
-    appPath: string;
+    appPath?: string;
     desiredPhone: string;
+    browserstackAppUrl?: string;
 }, config: BrowserStackConfig): Promise<CallToolResult>;
 export default function addAppLiveTools(server: McpServer, config: BrowserStackConfig): Record<string, any>;

package/dist/tools/applive.js

@@ -10,34 +10,38 @@ export async function startAppLiveSession(args, config) {
     if (!args.desiredPlatform) {
         throw new Error("You must provide a desiredPlatform.");
     }
-    if (!args.appPath) {
-        throw new Error("You must provide a appPath.");
+    if (!args.appPath && !args.browserstackAppUrl) {
+        throw new Error("You must provide either appPath or browserstackAppUrl.");
     }
     if (!args.desiredPhone) {
         throw new Error("You must provide a desiredPhone.");
     }
-    if (args.desiredPlatform === "android" && !args.appPath.endsWith(".apk")) {
-        throw new Error("You must provide a valid Android app path.");
-    }
-    if (args.desiredPlatform === "ios" && !args.appPath.endsWith(".ipa")) {
-        throw new Error("You must provide a valid iOS app path.");
-    }
-    // check if the app path exists && is readable
-    try {
-        if (!fs.existsSync(args.appPath)) {
-            throw new Error("The app path does not exist.");
+    // Only validate app path if it's provided (not using browserstackAppUrl)
+    if (args.appPath) {
+        if (args.desiredPlatform === "android" && !args.appPath.endsWith(".apk")) {
+            throw new Error("You must provide a valid Android app path.");
+        }
+        if (args.desiredPlatform === "ios" && !args.appPath.endsWith(".ipa")) {
+            throw new Error("You must provide a valid iOS app path.");
+        }
+        // check if the app path exists && is readable
+        try {
+            if (!fs.existsSync(args.appPath)) {
+                throw new Error("The app path does not exist.");
+            }
+            fs.accessSync(args.appPath, fs.constants.R_OK);
+        }
+        catch (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.");
         }
-        fs.accessSync(args.appPath, fs.constants.R_OK);
-    }
-    catch (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 startSession({
         appPath: args.appPath,
         desiredPlatform: args.desiredPlatform,
         desiredPhone: args.desiredPhone,
         desiredPlatformVersion: args.desiredPlatformVersion,
+        browserstackAppUrl: args.browserstackAppUrl,
     }, { config });
     return {
         content: [

package/dist/tools/sdk-utils/constants.js

@@ -426,7 +426,7 @@ exports.config.capabilities.forEach(function (caps) {
 ---STEP---
 
 Run your tests:
-You can now run your tests on BrowserStack using your standard WebdriverIO command.
+You can now run your tests on BrowserStack using your standard WebdriverIO command or Use the commands defined in your package.json file to run the tests.
 `;
 const cypressInstructions = (username, accessKey) => `
 ---STEP---
@@ -555,5 +555,8 @@ export const SUPPORTED_CONFIGURATIONS = {
         cypress: {
             cypress: { instructions: cypressInstructions },
         },
+        webdriverio: {
+            mocha: { instructions: webdriverioInstructions },
+        },
     },
 };

package/dist/tools/sdk-utils/types.d.ts

@@ -8,7 +8,8 @@ export type SDKSupportedLanguage = keyof typeof SDKSupportedLanguageEnum;
 export declare enum SDKSupportedBrowserAutomationFrameworkEnum {
     playwright = "playwright",
     selenium = "selenium",
-    cypress = "cypress"
+    cypress = "cypress",
+    webdriverio = "webdriverio"
 }
 export type SDKSupportedBrowserAutomationFramework = keyof typeof SDKSupportedBrowserAutomationFrameworkEnum;
 export declare enum SDKSupportedTestingFrameworkEnum {

package/dist/tools/sdk-utils/types.js

@@ -10,6 +10,7 @@ export var SDKSupportedBrowserAutomationFrameworkEnum;
     SDKSupportedBrowserAutomationFrameworkEnum["playwright"] = "playwright";
     SDKSupportedBrowserAutomationFrameworkEnum["selenium"] = "selenium";
     SDKSupportedBrowserAutomationFrameworkEnum["cypress"] = "cypress";
+    SDKSupportedBrowserAutomationFrameworkEnum["webdriverio"] = "webdriverio";
 })(SDKSupportedBrowserAutomationFrameworkEnum || (SDKSupportedBrowserAutomationFrameworkEnum = {}));
 export var SDKSupportedTestingFrameworkEnum;
 (function (SDKSupportedTestingFrameworkEnum) {

package/dist/tools/testmanagement-utils/create-testcase.d.ts

@@ -21,6 +21,7 @@ export interface TestCaseCreateRequest {
     issue_tracker?: IssueTracker;
     tags?: string[];
     custom_fields?: Record<string, string>;
+    automation_status?: string;
 }
 export interface TestCaseResponse {
     data: {
@@ -80,6 +81,7 @@ export declare const CreateTestCaseSchema: z.ZodObject<{
     }>>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     custom_fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    automation_status: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     name: string;
     test_case_steps: {
@@ -90,6 +92,7 @@ export declare const CreateTestCaseSchema: z.ZodObject<{
     folder_id: string;
     issues?: string[] | undefined;
     description?: string | undefined;
+    automation_status?: string | undefined;
     tags?: string[] | undefined;
     custom_fields?: Record<string, string> | undefined;
     preconditions?: string | undefined;
@@ -108,6 +111,7 @@ export declare const CreateTestCaseSchema: z.ZodObject<{
     folder_id: string;
     issues?: string[] | undefined;
     description?: string | undefined;
+    automation_status?: string | undefined;
     tags?: string[] | undefined;
     custom_fields?: Record<string, string> | undefined;
     preconditions?: string | undefined;

package/dist/tools/testmanagement-utils/create-testcase.js

@@ -49,6 +49,10 @@ export const CreateTestCaseSchema = z.object({
         .record(z.string(), z.string())
         .optional()
         .describe("Map of custom field names to values."),
+    automation_status: z
+        .string()
+        .optional()
+        .describe("Automation status of the test case. Common values include 'not_automated', 'automated', 'automation_not_required'."),
 });
 export function sanitizeArgs(args) {
     const cleaned = { ...args };
@@ -58,6 +62,8 @@ export function sanitizeArgs(args) {
         delete cleaned.owner;
     if (cleaned.preconditions === null)
         delete cleaned.preconditions;
+    if (cleaned.automation_status === null)
+        delete cleaned.automation_status;
     if (cleaned.issue_tracker) {
         if (cleaned.issue_tracker.name === undefined ||
             cleaned.issue_tracker.host === undefined) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserstack/mcp-server",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "BrowserStack's Official MCP Server",
   "main": "dist/index.js",
   "repository": {