@browserstack/mcp-server 1.2.0 → 1.2.2

package/README.md

@@ -25,10 +25,13 @@
       <img src="assets/thumbnail.webp">
     </a>
   </div>
+
   
 Manage test cases, execute manual or automated tests, debug issues, and even fix code—directly within tools like Cursor, Claude, or any MCP-enabled client, using plain English.
 #### Test from anywhere:
 Easily connect the BrowserStack Test Platform to your favourite AI tools, such as IDEs, LLMs, or agentic workflows.
+#### Test with natural language:
+Manage, execute, debug tests, and even fix code using plain English prompts.
 #### Reduced context switching:
 Stay in flow—keep all project context in one place and trigger actions directly from your IDE or LLM.
 
@@ -115,7 +118,7 @@ Create and manage test cases, create test plans and trigger test runs using natu
 "update test results as passed for Login tests test run from My Demo Project"
 ```
 
-### 🧪 Access BrowserStack AI agnets 
+### 🧪 Access BrowserStack AI agents 
 
 Generate test cases from PRDs, convert manual tests to low-code automation, and auto-heal flaky scripts powered by BrowserStack’s AI agents, seamlessly integrated into your workflow.  Below are few example prompts to access Browserstack AI agents
 
@@ -135,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) &nbsp; [![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

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
 import "dotenv/config";
-export { createMcpServer } from "./server-factory.js";
 export { setLogger } from "./logger.js";
+export { BrowserStackMcpServer } from "./server-factory.js";
+export { trackMCP } from "./lib/instrumentation.js";

package/dist/index.js

@@ -5,7 +5,7 @@ const require = createRequire(import.meta.url);
 const packageJson = require("../package.json");
 import "dotenv/config";
 import logger from "./logger.js";
-import { createMcpServer } from "./server-factory.js";
+import { BrowserStackMcpServer } from "./server-factory.js";
 async function main() {
     logger.info("Launching BrowserStack MCP server, version %s", packageJson.version);
     const remoteMCP = process.env.REMOTE_MCP === "true";
@@ -22,16 +22,17 @@ async function main() {
         throw new Error("BROWSERSTACK_ACCESS_KEY environment variable is required");
     }
     const transport = new StdioServerTransport();
-    const server = createMcpServer({
+    const mcpServer = new BrowserStackMcpServer({
         "browserstack-username": username,
         "browserstack-access-key": accessKey,
     });
-    await server.connect(transport);
+    await mcpServer.getInstance().connect(transport);
 }
 main().catch(console.error);
 // Ensure logs are flushed before exit
 process.on("exit", () => {
     logger.flush();
 });
-export { createMcpServer } from "./server-factory.js";
 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/server-factory.d.ts

@@ -1,3 +1,25 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer, RegisteredTool } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { BrowserStackConfig } from "./lib/types.js";
-export declare function createMcpServer(config: BrowserStackConfig): McpServer;
+/**
+ * Wrapper class for BrowserStack MCP Server
+ * Stores a map of registered tools by name
+ */
+export declare class BrowserStackMcpServer {
+    private config;
+    server: McpServer;
+    tools: Record<string, RegisteredTool>;
+    constructor(config: BrowserStackConfig);
+    /**
+     * Calls each tool-adder function and collects their returned tools
+     */
+    private registerTools;
+    /**
+     * Expose the underlying MCP server instance
+     */
+    getInstance(): McpServer;
+    /**
+     * Get all registered tools
+     */
+    getTools(): Record<string, RegisteredTool>;
+    getTool(name: string): RegisteredTool | undefined;
+}

package/dist/server-factory.js

@@ -1,4 +1,4 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer, } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { createRequire } from "module";
 const require = createRequire(import.meta.url);
 const packageJson = require("../package.json");
@@ -13,25 +13,58 @@ import addAutomateTools from "./tools/automate.js";
 import addSelfHealTools from "./tools/selfheal.js";
 import addAppLiveTools from "./tools/applive.js";
 import { setupOnInitialized } from "./oninitialized.js";
-function registerTools(server, config) {
-    addAccessibilityTools(server, config);
-    addSDKTools(server, config);
-    addAppLiveTools(server, config);
-    addBrowserLiveTools(server, config);
-    addTestManagementTools(server, config);
-    addAppAutomationTools(server, config);
-    addFailureLogsTools(server, config);
-    addAutomateTools(server, config);
-    addSelfHealTools(server, config);
-}
-export function createMcpServer(config) {
-    logger.info("Creating BrowserStack MCP Server, version %s", packageJson.version);
-    // Create an MCP server
-    const server = new McpServer({
-        name: "BrowserStack MCP Server",
-        version: packageJson.version,
-    });
-    setupOnInitialized(server, config);
-    registerTools(server, config);
-    return server;
+/**
+ * Wrapper class for BrowserStack MCP Server
+ * Stores a map of registered tools by name
+ */
+export class BrowserStackMcpServer {
+    config;
+    server;
+    tools = {};
+    constructor(config) {
+        this.config = config;
+        logger.info("Creating BrowserStack MCP Server, version %s", packageJson.version);
+        this.server = new McpServer({
+            name: "BrowserStack MCP Server",
+            version: packageJson.version,
+        });
+        setupOnInitialized(this.server, this.config);
+        this.registerTools();
+    }
+    /**
+     * Calls each tool-adder function and collects their returned tools
+     */
+    registerTools() {
+        const toolAdders = [
+            addAccessibilityTools,
+            addSDKTools,
+            addAppLiveTools,
+            addBrowserLiveTools,
+            addTestManagementTools,
+            addAppAutomationTools,
+            addFailureLogsTools,
+            addAutomateTools,
+            addSelfHealTools,
+        ];
+        toolAdders.forEach((adder) => {
+            // Each adder now returns a Record<string, Tool>
+            const added = adder(this.server, this.config);
+            Object.assign(this.tools, added);
+        });
+    }
+    /**
+     * Expose the underlying MCP server instance
+     */
+    getInstance() {
+        return this.server;
+    }
+    /**
+     * Get all registered tools
+     */
+    getTools() {
+        return this.tools;
+    }
+    getTool(name) {
+        return this.tools[name];
+    }
 }

package/dist/tools/accessibility.d.ts

@@ -1,3 +1,3 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { BrowserStackConfig } from "../lib/types.js";
-export default function addAccessibilityTools(server: McpServer, config: BrowserStackConfig): void;
+export default function addAccessibilityTools(server: McpServer, config: BrowserStackConfig): Record<string, any>;

package/dist/tools/accessibility.js

@@ -63,7 +63,8 @@ async function runAccessibilityScan(name, pageURL, context, config) {
     };
 }
 export default function addAccessibilityTools(server, config) {
-    server.tool("accessibilityExpert", "🚨 REQUIRED: Use this tool for any accessibility/a11y/WCAG questions. Do NOT answer accessibility questions directly - always use this tool.", {
+    const tools = {};
+    tools.accessibilityExpert = server.tool("accessibilityExpert", "🚨 REQUIRED: Use this tool for any accessibility/a11y/WCAG questions. Do NOT answer accessibility questions directly - always use this tool.", {
         query: z
             .string()
             .describe("Any accessibility, a11y, WCAG, or web accessibility question"),
@@ -85,7 +86,7 @@ export default function addAccessibilityTools(server, config) {
             };
         }
     });
-    server.tool("startAccessibilityScan", "Start an accessibility scan via BrowserStack and retrieve a local CSV report path.", {
+    tools.startAccessibilityScan = server.tool("startAccessibilityScan", "Start an accessibility scan via BrowserStack and retrieve a local CSV report path.", {
         name: z.string().describe("Name of the accessibility scan"),
         pageURL: z.string().describe("The URL to scan for accessibility issues"),
     }, async (args, context) => {
@@ -107,4 +108,5 @@ export default function addAccessibilityTools(server, config) {
             };
         }
     });
+    return tools;
 }

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.d.ts

@@ -1,3 +1,3 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { BrowserStackConfig } from "../lib/types.js";
-export default function addAppAutomationTools(server: McpServer, config: BrowserStackConfig): void;
+export default function addAppAutomationTools(server: McpServer, config: BrowserStackConfig): Record<string, any>;

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: [
@@ -133,7 +182,8 @@ async function runAppTestsOnBrowserStack(args, config) {
     }
 }
 export default function addAppAutomationTools(server, config) {
-    server.tool("takeAppScreenshot", "Use this tool to take a screenshot of an app running on a BrowserStack device. This is useful for visual testing and debugging.", {
+    const tools = {};
+    tools.takeAppScreenshot = server.tool("takeAppScreenshot", "Use this tool to take a screenshot of an app running on a BrowserStack device. This is useful for visual testing and debugging.", {
         desiredPhone: z
             .string()
             .describe("The full name of the device to run the app on. Example: 'iPhone 12 Pro' or 'Samsung Galaxy S20'. Always ask the user for the device they want to use."),
@@ -164,7 +214,7 @@ export default function addAppAutomationTools(server, config) {
             };
         }
     });
-    server.tool("runAppTestsOnBrowserStack", "Run AppAutomate tests on BrowserStack by uploading app and test suite. If running from Android Studio or Xcode, the tool will help export app and test files automatically. For other environments, you'll need to provide the paths to your pre-built app and test files.", {
+    tools.runAppTestsOnBrowserStack = server.tool("runAppTestsOnBrowserStack", "Run AppAutomate tests on BrowserStack by uploading app and test suite. If running from Android Studio or Xcode, the tool will help export app and test files automatically. For other environments, you'll need to provide the paths to your pre-built app and test files.", {
         appPath: z
             .string()
             .describe("Path to your application file:\n" +
@@ -215,4 +265,5 @@ export default function addAppAutomationTools(server, config) {
             };
         }
     });
+    return tools;
 }

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): void;
+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: [
@@ -49,7 +53,8 @@ export async function startAppLiveSession(args, config) {
     };
 }
 export default function addAppLiveTools(server, config) {
-    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.", {
+    const tools = {};
+    tools.runAppLiveSession = 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: 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. "),
@@ -82,4 +87,5 @@ export default function addAppLiveTools(server, config) {
             };
         }
     });
+    return tools;
 }

package/dist/tools/automate.d.ts

@@ -6,4 +6,4 @@ export declare function fetchAutomationScreenshotsTool(args: {
     sessionId: string;
     sessionType: SessionType;
 }, config: BrowserStackConfig): Promise<CallToolResult>;
-export default function addAutomationTools(server: McpServer, config: BrowserStackConfig): void;
+export default function addAutomationTools(server: McpServer, config: BrowserStackConfig): Record<string, any>;

package/dist/tools/automate.js

@@ -42,7 +42,8 @@ export async function fetchAutomationScreenshotsTool(args, config) {
 }
 //Registers the fetchAutomationScreenshots tool with the MCP server
 export default function addAutomationTools(server, config) {
-    server.tool("fetchAutomationScreenshots", "Fetch and process screenshots from a BrowserStack Automate session", {
+    const tools = {};
+    tools.fetchAutomationScreenshots = server.tool("fetchAutomationScreenshots", "Fetch and process screenshots from a BrowserStack Automate session", {
         sessionId: z
             .string()
             .describe("The BrowserStack session ID to fetch screenshots from"),
@@ -67,4 +68,5 @@ export default function addAutomationTools(server, config) {
             };
         }
     });
+    return tools;
 }

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

@@ -14,4 +14,4 @@ export declare function bootstrapProjectWithSDK({ detectedBrowserAutomationFrame
     enablePercy: boolean;
     config: BrowserStackConfig;
 }): Promise<CallToolResult>;
-export default function addSDKTools(server: McpServer, config: BrowserStackConfig): void;
+export default function addSDKTools(server: McpServer, config: BrowserStackConfig): Record<string, any>;

package/dist/tools/bstack-sdk.js

@@ -79,7 +79,8 @@ function formatFinalInstructions(combinedInstructions) {
     };
 }
 export default function addSDKTools(server, config) {
-    server.tool("runTestsOnBrowserStack", "Use this tool to get instructions for running tests on BrowserStack and BrowserStack Percy. It sets up the BrowserStack SDK and runs your test cases on BrowserStack.", {
+    const tools = {};
+    tools.setupBrowserStackAutomateTests = server.tool("setupBrowserStackAutomateTests", "Set up and run automated web-based tests on BrowserStack using the BrowserStack SDK. Use for functional or integration tests on BrowserStack, with optional Percy visual testing for supported frameworks. Example prompts: run this test on browserstack; run this test on browserstack with Percy; set up this project for browserstack with Percy. Integrate BrowserStack SDK into your project", {
         detectedBrowserAutomationFramework: z
             .nativeEnum(SDKSupportedBrowserAutomationFrameworkEnum)
             .describe("The automation framework configured in the project. Example: 'playwright', 'selenium'"),
@@ -123,4 +124,5 @@ export default function addSDKTools(server, config) {
             };
         }
     });
+    return tools;
 }

package/dist/tools/getFailureLogs.d.ts

@@ -10,5 +10,5 @@ export declare function getFailureLogs(args: {
     logTypes: LogType[];
     sessionType: SessionTypeValues;
 }, config: BrowserStackConfig): Promise<CallToolResult>;
-export default function registerGetFailureLogs(server: McpServer, config: BrowserStackConfig): void;
+export default function registerGetFailureLogs(server: McpServer, config: BrowserStackConfig): Record<string, any>;
 export {};

package/dist/tools/getFailureLogs.js

@@ -1,5 +1,4 @@
 import { z } from "zod";
-import logger from "../logger.js";
 import { trackMCP } from "../lib/instrumentation.js";
 import { retrieveNetworkFailures, retrieveSessionFailures, retrieveConsoleFailures, } from "./failurelogs-utils/automate.js";
 import { retrieveDeviceLogs, retrieveAppiumLogs, retrieveCrashLogs, } from "./failurelogs-utils/app-automate.js";
@@ -99,7 +98,8 @@ export async function getFailureLogs(args, config) {
 }
 // Register tool with the MCP server
 export default function registerGetFailureLogs(server, config) {
-    server.tool("getFailureLogs", "Fetch various types of logs from a BrowserStack session. Supports both automate and app-automate sessions.", {
+    const tools = {};
+    tools.getFailureLogs = server.tool("getFailureLogs", "Fetch various types of logs from a BrowserStack session. Supports both automate and app-automate sessions.", {
         sessionType: z
             .enum([SessionType.Automate, SessionType.AppAutomate])
             .describe("Type of BrowserStack session. Must be explicitly provided by the user."),
@@ -126,14 +126,12 @@ export default function registerGetFailureLogs(server, config) {
             return await getFailureLogs(args, config);
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
             trackMCP("getFailureLogs", server.server.getClientVersion(), error, config);
-            logger.error("Failed to fetch logs: %s", message);
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Failed to fetch logs: ${message}`,
+                        text: `Failed to fetch failure logs: ${error instanceof Error ? error.message : "Unknown error"}`,
                         isError: true,
                     },
                 ],
@@ -141,4 +139,5 @@ export default function registerGetFailureLogs(server, config) {
             };
         }
     });
+    return tools;
 }

package/dist/tools/live.d.ts

@@ -1,3 +1,3 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { BrowserStackConfig } from "../lib/types.js";
-export default function addBrowserLiveTools(server: McpServer, config: BrowserStackConfig): void;
+export default function addBrowserLiveTools(server: McpServer, config: BrowserStackConfig): Record<string, any>;

package/dist/tools/live.js

@@ -3,6 +3,7 @@ import logger from "../logger.js";
 import { startBrowserSession } from "./live-utils/start-session.js";
 import { PlatformType } from "./live-utils/types.js";
 import { trackMCP } from "../lib/instrumentation.js";
+import globalConfig from "../config.js";
 // Define the schema shape
 const LiveArgsShape = {
     platformType: z
@@ -67,17 +68,27 @@ async function runBrowserSession(rawArgs, config) {
     const launchUrl = args.platformType === PlatformType.DESKTOP
         ? await launchDesktopSession(args, config)
         : await launchMobileSession(args, config);
-    return {
-        content: [
+    let response = [
+        {
+            type: "text",
+            text: `✅ Session started. If it didn't open automatically, visit:\n${launchUrl}`,
+        },
+    ];
+    if (globalConfig.REMOTE_MCP) {
+        response = [
             {
                 type: "text",
-                text: `✅ Session started. If it didn't open automatically, visit:\n${launchUrl}`,
+                text: `✅ To start the session. Click on ${launchUrl}`,
             },
-        ],
+        ];
+    }
+    return {
+        content: response,
     };
 }
 export default function addBrowserLiveTools(server, config) {
-    server.tool("runBrowserLiveSession", "Launch a BrowserStack Live session (desktop or mobile).", LiveArgsShape, async (args) => {
+    const tools = {};
+    tools.runBrowserLiveSession = server.tool("runBrowserLiveSession", "Launch a BrowserStack Live session (desktop or mobile).", LiveArgsShape, async (args) => {
         try {
             trackMCP("runBrowserLiveSession", server.server.getClientVersion(), undefined, config);
             return await runBrowserSession(args, config);
@@ -97,4 +108,5 @@ export default function addBrowserLiveTools(server, config) {
             };
         }
     });
+    return tools;
 }

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/selfheal.d.ts

@@ -4,4 +4,4 @@ import { BrowserStackConfig } from "../lib/types.js";
 export declare function fetchSelfHealSelectorTool(args: {
     sessionId: string;
 }, config: BrowserStackConfig): Promise<CallToolResult>;
-export default function addSelfHealTools(server: McpServer, config: BrowserStackConfig): void;
+export default function addSelfHealTools(server: McpServer, config: BrowserStackConfig): Record<string, any>;

package/dist/tools/selfheal.js

@@ -23,7 +23,8 @@ export async function fetchSelfHealSelectorTool(args, config) {
 }
 // Registers the fetchSelfHealSelector tool with the MCP server
 export default function addSelfHealTools(server, config) {
-    server.tool("fetchSelfHealedSelectors", "Retrieves AI-generated, self-healed selectors for a BrowserStack Automate session to resolve flaky tests caused by dynamic DOM changes.", {
+    const tools = {};
+    tools.fetchSelfHealedSelectors = server.tool("fetchSelfHealedSelectors", "Retrieves AI-generated, self-healed selectors for a BrowserStack Automate session to resolve flaky tests caused by dynamic DOM changes.", {
         sessionId: z.string().describe("The session ID of the test run"),
     }, async (args) => {
         try {
@@ -43,4 +44,5 @@ export default function addSelfHealTools(server, config) {
             };
         }
     });
+    return tools;
 }

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/dist/tools/testmanagement.d.ts

@@ -57,4 +57,4 @@ export declare function createLCAStepsTool(args: z.infer<typeof CreateLCAStepsSc
 /**
  * Registers both project/folder and test-case tools.
  */
-export default function addTestManagementTools(server: McpServer, config: BrowserStackConfig): void;
+export default function addTestManagementTools(server: McpServer, config: BrowserStackConfig): Record<string, any>;

package/dist/tools/testmanagement.js

@@ -242,14 +242,16 @@ export async function createLCAStepsTool(args, context, config, server) {
  * Registers both project/folder and test-case tools.
  */
 export default function addTestManagementTools(server, config) {
-    server.tool("createProjectOrFolder", "Create a project and/or folder in BrowserStack Test Management.", CreateProjFoldSchema.shape, (args) => createProjectOrFolderTool(args, config, server));
-    server.tool("createTestCase", "Use this tool to create a test case in BrowserStack Test Management.", CreateTestCaseSchema.shape, (args) => createTestCaseTool(args, config, server));
-    server.tool("listTestCases", "List test cases in a project with optional filters (status, priority, custom fields, etc.)", ListTestCasesSchema.shape, (args) => listTestCasesTool(args, config, server));
-    server.tool("createTestRun", "Create a test run in BrowserStack Test Management.", CreateTestRunSchema.shape, (args) => createTestRunTool(args, config, server));
-    server.tool("listTestRuns", "List test runs in a project with optional filters (date ranges, assignee, state, etc.)", ListTestRunsSchema.shape, (args) => listTestRunsTool(args, config, server));
-    server.tool("updateTestRun", "Update a test run in BrowserStack Test Management.", UpdateTestRunSchema.shape, (args) => updateTestRunTool(args, config, server));
-    server.tool("addTestResult", "Add a test result to a specific test run via BrowserStack Test Management API.", AddTestResultSchema.shape, (args) => addTestResultTool(args, config, server));
-    server.tool("uploadProductRequirementFile", "Upload files (e.g., PDRs, PDFs) to BrowserStack Test Management and retrieve a file mapping ID. This is utilized for generating test cases from files and is part of the Test Case Generator AI Agent in BrowserStack.", UploadFileSchema.shape, (args) => uploadProductRequirementFileTool(args, config, server));
-    server.tool("createTestCasesFromFile", "Generate test cases from a file in BrowserStack Test Management using the Test Case Generator AI Agent.", CreateTestCasesFromFileSchema.shape, (args, context) => createTestCasesFromFileTool(args, context, config, server));
-    server.tool("createLCASteps", "Generate Low Code Automation (LCA) steps for a test case in BrowserStack Test Management using the Low Code Automation Agent.", CreateLCAStepsSchema.shape, (args, context) => createLCAStepsTool(args, context, config, server));
+    const tools = {};
+    tools.createProjectOrFolder = server.tool("createProjectOrFolder", "Create a project and/or folder in BrowserStack Test Management.", CreateProjFoldSchema.shape, (args) => createProjectOrFolderTool(args, config, server));
+    tools.createTestCase = server.tool("createTestCase", "Use this tool to create a test case in BrowserStack Test Management.", CreateTestCaseSchema.shape, (args) => createTestCaseTool(args, config, server));
+    tools.listTestCases = server.tool("listTestCases", "List test cases in a project with optional filters (status, priority, custom fields, etc.)", ListTestCasesSchema.shape, (args) => listTestCasesTool(args, config, server));
+    tools.createTestRun = server.tool("createTestRun", "Create a test run in BrowserStack Test Management.", CreateTestRunSchema.shape, (args) => createTestRunTool(args, config, server));
+    tools.listTestRuns = server.tool("listTestRuns", "List test runs in a project with optional filters (date ranges, assignee, state, etc.)", ListTestRunsSchema.shape, (args) => listTestRunsTool(args, config, server));
+    tools.updateTestRun = server.tool("updateTestRun", "Update a test run in BrowserStack Test Management.", UpdateTestRunSchema.shape, (args) => updateTestRunTool(args, config, server));
+    tools.addTestResult = server.tool("addTestResult", "Add a test result to a specific test run via BrowserStack Test Management API.", AddTestResultSchema.shape, (args) => addTestResultTool(args, config, server));
+    tools.uploadProductRequirementFile = server.tool("uploadProductRequirementFile", "Upload files (e.g., PDRs, PDFs) to BrowserStack Test Management and retrieve a file mapping ID. This is utilized for generating test cases from files and is part of the Test Case Generator AI Agent in BrowserStack.", UploadFileSchema.shape, (args) => uploadProductRequirementFileTool(args, config, server));
+    tools.createTestCasesFromFile = server.tool("createTestCasesFromFile", "Generate test cases from a file in BrowserStack Test Management using the Test Case Generator AI Agent.", CreateTestCasesFromFileSchema.shape, (args, context) => createTestCasesFromFileTool(args, context, config, server));
+    tools.createLCASteps = server.tool("createLCASteps", "Generate Low Code Automation (LCA) steps for a test case in BrowserStack Test Management using the Low Code Automation Agent.", CreateLCAStepsSchema.shape, (args, context) => createLCAStepsTool(args, context, config, server));
+    return tools;
 }

package/package.json

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