@browserstack/mcp-server 1.2.1 → 1.2.2-beta.1

package/README.md

@@ -35,6 +35,10 @@ 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.
 
+## ⚡️ One Click MCP Setup
+
+[![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)
+
 ## 💡 Usage Examples
 
 ### 📱 Manual App Testing
@@ -138,6 +142,13 @@ Generate test cases from PRDs, convert manual tests to low-code automation, and
 
 ## 🛠️ Installation
 
+### **One Click MCP Setup**
+
+[![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)
+
+
+### **Alternate ways to Setup MCP server**
+
 1. **Create a BrowserStack Account**
 
    - Sign up for [BrowserStack](https://www.browserstack.com/users/sign_up) if you don't have an account already.
@@ -148,9 +159,21 @@ Generate test cases from PRDs, convert manual tests to low-code automation, and
    - Once you have an account (and purchased appropriate plan), note down your `username` and `access_key` from [Account Settings](https://www.browserstack.com/accounts/profile/details).
 
 2. Ensure you are using Node version >= `18.0`. Check your node version using `node --version`. Recommended version: `v22.15.0` (LTS)
+
 3. **Install the MCP Server**
 
    - VSCode (Copilot - Agent Mode): `.vscode/mcp.json`:
+    
+      - Locate or Create the Configuration File: 
+        In the root directory of your project, look for a folder named .vscode. This folder is usually hidden so you will need to find it as mentioned in the expand.
+    
+      - If this folder doesn't exist, create it.
+    
+      - Inside the .vscode folder, create a new file named mcp.json
+      
+      - Add the Configuration: Open the mcp.json file and then add the  following JSON content. 
+      
+      - Replace the username and <access_key> with your BrowserStack   credentials.
 
    ```json
    {
@@ -170,6 +193,30 @@ Generate test cases from PRDs, convert manual tests to low-code automation, and
    - In VSCode, make sure to click on `Start` button in the MCP Server to start the server.
      ![Start MCP Server](assets/vscode_install.png)
 
+   
+   #### ** Alternate way to setup MCP on VSCode Copilot
+
+   1.Click on the gear icon to Select Tools
+    <div align="center">
+      <img src="assets/select_tools.png" alt="Select Tools" height="100"> 
+    </div>
+   2. A tool menu would appear at the top-centre, scroll down on the     menu at the top and then Click on Add MCP Server
+    <div align="center">
+      <img src="assets/add_mcp_server.png" alt="Add MCP Server" height="100"> 
+    </div>
+   3. Select NPM package option (Install fron an NPM package) - 3rd in the list
+    <div align="center">
+      <img src="assets/select_npm_package.png" alt="Select NPM Package" height="100"> 
+    </div>
+   4. Enter NPM Package Name (@browserstack/mcp-server)
+    <div align="center">
+      <img src="assets/enter_npm_package.png" alt="Enter NPM Package" height="100"> 
+    </div>
+   5. Enter browserstack user name and access key
+   
+   
+   
+   
    * For Cursor: `.cursor/mcp.json`:
 
    ```json
@@ -231,6 +278,186 @@ To install BrowserStack Test Platform Server for Claude Desktop automatically vi
 npx -y @smithery/cli install @browserstack/mcp-server --client claude
 ```
 
+
+### 💡 List of BrowserStack MCP Tools
+
+As of now we support 20 tools.
+
+
+---
+
+## 🧾 Test Management
+
+ 1. `createProjectOrFolder` — Create a Test Management project and/or folders to organize test cases. Returns with Folder ID, Project ID and Test Management Link to access the TM Project Dashboard.
+  **Prompt example**
+
+  ```text
+  Create a new Test Management project named 'Shopping App' with two folders - Login and Checkout
+  ```
+
+
+ 2. `createTestCase` — Add a manual test case under a specific project/folder (uses project identifier like PR-xxxxx and a folder ID).
+  **Prompt example**
+
+  ```text
+  Add a test case named 'Invalid Login Scenario' to the Login folder in the 'Shopping App' project with PR-53617, Folder ID: 117869
+  ```
+
+ 3. `listTestCases` — List test cases for a project (supports filters like priority, status, tags).
+  **Prompt example**
+
+  ```text
+  List all high-priority test cases in the 'Shopping App' project with project_identifier: PR-59457
+  ```
+
+ 4. `createTestRun` — Create a test run (suite) for selected test cases in a project.
+  **Prompt example**
+
+  ```text
+  Create a test run for the Login folder in the 'Shopping App' project and name it 'Release v1.0 Login Flow'
+  ```
+
+ 5. `listTestRuns` — List test runs for a project (filter by dates, assignee, state).
+  **Prompt example**
+
+  ```text
+  List all test runs from the 'Shopping App' project that were executed last week and are currently marked in-progress
+  ```
+
+ 6. `updateTestRun` — Partially update a test run (status, tags, notes, associated test cases).
+  **Prompt example**
+
+  ```text
+  Update test run ID 1043 in the 'Shopping App' project and mark it as complete with the note 'Regression cycle done'
+  ```
+
+ 7. `addTestResult` — Add a manual execution result (passed/failed/blocked/skipped) for a test case within a run.
+  **Prompt example**
+
+  ```text
+  Mark the test case 'Invalid Login Scenario' as passed in test run ID 1043 of the 'Shopping App' project
+  ```
+
+ 8. `createTestCasesFromFile` — Bulk-create test cases from an uploaded file (e.g., PDF).
+  **Prompt example**
+
+  ```text
+  Upload test cases from '/Users/xyz/testcases.pdf' to the 'Shopping App' project in Test Management
+  ```
+
+---
+
+## ⚙️ BrowserStack SDK Setup / Automate Test
+
+ 9. `setupBrowserStackAutomateTests` — Integrate BrowserStack SDK and run web tests on BrowserStack (optionally enable Percy).
+  **Prompt example**
+
+  ```text
+  Run my Selenium-JUnit5 tests written in Java on Chrome and Firefox. Enable Percy for visual testing.
+  ```
+
+ 10. `fetchAutomationScreenshots` — Fetch screenshots captured during a given Automate/App Automate session.
+  **Prompt example**
+
+  ```text
+  Get screenshots from Automate session ID abc123xyz for my desktop test run
+  ```
+
+---
+
+## 🔍 Observability
+
+ 11. `getFailureLogs` — Retrieve error logs for Automate/App Automate sessions (optionally by Build ID for App Automate).
+  **Prompt example**
+
+  ```text
+  Get the error logs from the session ID: 21a864032a7459f1e7634222249b316759d6827f, Build ID: dt7ung4wmjittzff8kksrjadjax9gzvbscoyf9qn of App Automate test session
+  ```
+
+---
+
+## 📱 App Live
+
+ 12. `runAppLiveSession` — Start a manual app testing session on a real device in the cloud.
+  **Prompt example**
+
+  ```text
+  Open my app on iPhone 15 Pro Max with iOS 17. App path is /Users/xyz/app.ipa
+  ```
+
+---
+
+## 💻 Live
+
+ 13. `runBrowserLiveSession` — Start a Live session for website testing on desktop or mobile browsers.
+  **Prompt example**
+
+  ```text
+  Open www.google.com on the latest version of Microsoft Edge on Windows 11
+  ```
+
+---
+
+## 📲 App Automate
+
+ 14. `takeAppScreenshot` — Launch the app on a specified device and captures a quick verification screenshot. This tool is just to verify whether your app has been launched.
+  **Prompt example**
+
+  ```text
+  Take a screenshot of my app on Google Pixel 6 with Android 14 while testing on App Automate. App file path: /Users/xyz/app-debug.apk
+  ```
+
+ 15. `runAppTestsOnBrowserStack` — Run automated mobile tests (Espresso/XCUITest, etc.) on real devices.
+  **Prompt example**
+
+  ```text
+  Run Espresso tests from /tests/checkout.zip on Galaxy S21 and Pixel 6 with Android 14. App path is /apps/beta-release.apk under project 'Checkout Flow'
+  ```
+
+---
+
+## ♿ Accessibility
+
+ 16. `accessibilityExpert` — Ask A11y Expert (WCAG 2.0/2.1/2.2, mobile/web usability, best practices).
+  **Prompt example**
+
+  ```text
+  What WCAG guidelines apply to form field error messages on mobile web?
+  ```
+
+ 17. `startAccessibilityScan` — Start a web accessibility scan and return the result link.
+  **Prompt example**
+
+  ```text
+  Run accessibility scan for "www.example.com"
+  ```
+
+---
+
+## 🤖 BrowserStack AI Agents
+
+ 18. `fetchSelfHealedSelectors` — Retrieve AI self-healed selectors to fix flaky tests due to DOM changes.
+  **Prompt example**
+
+  ```text
+  Fetch and fix flaky test selectors in Automate session ID session_9482 using MCP
+  ```
+
+ 19. `createLCASteps` — Generate Low Code Automation steps from a manual test case in Test Management.
+  **Prompt example**
+
+  ```text
+  Convert the manual test case 'Add to Cart' in the 'Shopping App' project into LCA steps
+  ```
+
+ 20. `uploadProductRequirementFile` — Upload a PRD/screenshot/PDF and get a file mapping ID (used with `createTestCasesFromFile`).
+  **Prompt example**
+
+  ```text
+  Upload PRD from /Users/xyz/Desktop/login-flow.pdf and use BrowserStack AI to generate test cases
+  ```
+
+
 ## 🤝 Recommended MCP Clients
 
 - We recommend using **Github Copilot or Cursor** for automated testing + debugging use cases.

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/lib/inmemory-store.d.ts

@@ -1 +1,2 @@
 export declare const signedUrlMap: Map<string, object>;
+export declare const testFilePathsMap: Map<string, string[]>;

package/dist/lib/inmemory-store.js

@@ -1 +1,2 @@
 export const signedUrlMap = new Map();
+export const testFilePathsMap = new Map();

package/dist/lib/instrumentation.js

@@ -4,6 +4,7 @@ import { createRequire } from "module";
 const require = createRequire(import.meta.url);
 const packageJson = require("../../package.json");
 import axios from "axios";
+import globalConfig from "../config.js";
 export function trackMCP(toolName, clientInfo, error, config) {
     const instrumentationEndpoint = "https://api.browserstack.com/sdk/v1/event";
     const isSuccess = !error;
@@ -22,6 +23,7 @@ export function trackMCP(toolName, clientInfo, error, config) {
             tool_name: toolName,
             mcp_client: mcpClient,
             success: isSuccess,
+            is_remote: globalConfig.REMOTE_MCP,
         },
     };
     // Add error details if applicable

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.js

@@ -4,11 +4,12 @@ const require = createRequire(import.meta.url);
 const packageJson = require("../package.json");
 import logger from "./logger.js";
 import addSDKTools from "./tools/bstack-sdk.js";
+import addPercyTools from "./tools/percy-sdk.js";
 import addBrowserLiveTools from "./tools/live.js";
 import addAccessibilityTools from "./tools/accessibility.js";
 import addTestManagementTools from "./tools/testmanagement.js";
 import addAppAutomationTools from "./tools/appautomate.js";
-import addFailureLogsTools from "./tools/getFailureLogs.js";
+import addFailureLogsTools from "./tools/get-failure-logs.js";
 import addAutomateTools from "./tools/automate.js";
 import addSelfHealTools from "./tools/selfheal.js";
 import addAppLiveTools from "./tools/applive.js";
@@ -38,6 +39,7 @@ export class BrowserStackMcpServer {
         const toolAdders = [
             addAccessibilityTools,
             addSDKTools,
+            addPercyTools,
             addAppLiveTools,
             addBrowserLiveTools,
             addTestManagementTools,