@browserstack/mcp-server 1.2.3 → 1.2.5

package/README.md

@@ -35,10 +35,21 @@ 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
+## ⚡️ 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)
+Click on the buttons below to install MCP in your respective IDE:
 
+<a href="http://mcp.browserstack.com/one-click-setup?client=vscode"><img src="assets/one-click-vs-code.png" alt="Install in VS Code" width="160" height="80"></a>&nbsp;&nbsp;&nbsp;<a href="http://mcp.browserstack.com/one-click-setup?client=cursor"><img src="assets/one-click-cursor.png" alt="Install in Cursor" width="150" height="70"></a>
+
+#### Note : Ensure you are using Node version >= `18.0` 
+- Check your node version using `node --version`. Recommended version: `v22.15.0` (LTS)
+- To Upgrade Node :
+- 1. On macOS `(Homebrew) - brew update && brew upgrade node  or if using (nvm) - nvm install 22.15.0 && nvm use 22.15.0 && nvm alias default 22.15.0`
+- 2. On Windows `(nvm-windows) : nvm install 22.15.0 && nvm use 22.15.0`
+- 👉 <a href="https://nodejs.org/en/download" target="_blank">Or directly download the Node.js LTS Installer</a>
+
+.
+        
 ## 💡 Usage Examples
 
 ### 📱 Manual App Testing
@@ -142,10 +153,15 @@ Generate test cases from PRDs, convert manual tests to low-code automation, and
 
 ## 🛠️ Installation
 
+### 📋 Prerequisites for MCP Setup
+#### Note : Ensure you are using Node version >= `18.0` 
+- Check your node version using `node --version`. Recommended version: `v22.15.0` (LTS)
+   
 ### **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) &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)
+Click on the buttons below to install MCP in your respective IDE:
 
+<a href="http://mcp.browserstack.com/one-click-setup?client=vscode"><img src="assets/one-click-vs-code.png" alt="Install in VS Code" width="160" height="80"></a>&nbsp;&nbsp;&nbsp;<a href="http://mcp.browserstack.com/one-click-setup?client=cursor"><img src="assets/one-click-cursor.png" alt="Install in Cursor" width="150" height="70"></a>
 
 ### **Alternate ways to Setup MCP server**
 
@@ -158,7 +174,9 @@ 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)
+2. #### Note : 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**
 
@@ -404,14 +422,14 @@ As of now we support 20 tools.
   **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
+  Take a screenshot of my app on Google Pixel 6 with Android 12 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'
+  Run Espresso tests from /tests/checkout.zip on Galaxy S21 and Pixel 6 with Android 12. App path is /apps/beta-release.apk under project 'Checkout Flow'
   ```
 
 ---
@@ -456,7 +474,79 @@ As of now we support 20 tools.
   ```text
   Upload PRD from /Users/xyz/Desktop/login-flow.pdf and use BrowserStack AI to generate test cases
   ```
+##  🚀 Remote MCP Server
+
+Remote MCP comes with all the functionalities of an MCP server without the hassles of complex setup or local installation.
+
+### Key benefits:
+
+- ✅ Works seamlessly in enterprise networks without worrying about firewalls or binaries or where local installation is not allowed.
+
+- ✅ Secure OAuth integration – no password sharing or manual credential handling.
+
+### Limitations:
+
+- ❌ No Local Testing support (cannot test apps behind VPNs, firewalls, or localhost). If you have to do Local Testing, you would have to use a BrowserStack Local MCP server.
+- ❌ Latency can be slightly higher, but nothing considerable — you generally won’t notice it in normal use.
 
+### Installation Steps: 
+
+   - On 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
+      - To setup Remote BrowserStack MCP instead of local BrowserStack MCP you can add the following JSON content :
+         <div align="center">
+         <img src="assets/remotemcp_json_file.png" alt="Remote MCP JSON file" height="300" width="300">
+         </div>
+        
+        ### Alternative way to Setup Remote MCP
+
+      -  Step 1.Click on the gear icon to Select Tools
+      
+          <div align="center">
+          <img src="assets/select_tools.png" alt="Select Tools" height="300" width="300"> 
+          </div>
+          
+      -  Step 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="300" width="300"> 
+        </div>
+
+      - Step 3. Click on HTTP option
+         <div align="center">
+         <img src="assets/http_option.png" alt="HTTP Option" height="300" width="300">
+         </div>
+         
+      - Step 4. Paste Remote MCP Server URL : https://mcp.browserstack.com/mcp
+         <div align="center">
+         <img src="assets/server_url.png" alt="Remote MCP Server URL" height="300" width="300">
+         </div>
+         
+      - Step 5. Give server id as : browserstack
+      
+          <div align="center">
+          <img src="assets/server_id.png" alt="Remote MCP Server ID" height="300" width="300">
+          </div>
+          
+      - Step 6. In VSCode Click on start MCP Server and then click on "Allow"
+      
+          <div align="center">
+          <img src="assets/authentication1.png" alt="authentication1" height="300" width="300">
+          </div>
+          
+          <div align="center">
+          <img src="assets/authentication2.png" alt="authentication2" height="300" width="300">
+          </div>
+          
+          <div align="center">
+          <img src="assets/signin_success.png" alt="Sign_in_success" height="300" width="300">
+          </div>
+
+     
 
 ## 🤝 Recommended MCP Clients
 

package/dist/lib/apiClient.d.ts

@@ -4,6 +4,7 @@ type RequestOptions = {
     headers?: Record<string, string>;
     params?: Record<string, string | number>;
     body?: any;
+    timeout?: number;
     raise_error?: boolean;
 };
 declare class ApiResponse<T = any> {
@@ -20,12 +21,13 @@ declare class ApiResponse<T = any> {
 declare class ApiClient {
     private instance;
     private get axiosAgent();
+    private validateUrl;
     private requestWrapper;
-    get<T = any>({ url, headers, params, raise_error, }: RequestOptions): Promise<ApiResponse<T>>;
-    post<T = any>({ url, headers, body, raise_error, }: RequestOptions): Promise<ApiResponse<T>>;
-    put<T = any>({ url, headers, body, raise_error, }: RequestOptions): Promise<ApiResponse<T>>;
-    patch<T = any>({ url, headers, body, raise_error, }: RequestOptions): Promise<ApiResponse<T>>;
-    delete<T = any>({ url, headers, params, raise_error, }: RequestOptions): Promise<ApiResponse<T>>;
+    get<T = any>({ url, headers, params, timeout, raise_error, }: RequestOptions): Promise<ApiResponse<T>>;
+    post<T = any>({ url, headers, body, timeout, raise_error, }: RequestOptions): Promise<ApiResponse<T>>;
+    put<T = any>({ url, headers, body, timeout, raise_error, }: RequestOptions): Promise<ApiResponse<T>>;
+    patch<T = any>({ url, headers, body, timeout, raise_error, }: RequestOptions): Promise<ApiResponse<T>>;
+    delete<T = any>({ url, headers, params, timeout, raise_error, }: RequestOptions): Promise<ApiResponse<T>>;
 }
 export declare const apiClient: ApiClient;
 export type { ApiResponse, RequestOptions };

package/dist/lib/apiClient.js

@@ -4,6 +4,7 @@ const { HttpsProxyAgent } = httpsProxyAgentPkg;
 import * as https from "https";
 import * as fs from "fs";
 import config from "../config.js";
+import { isDataUrlPayloadTooLarge } from "../lib/utils.js";
 class ApiResponse {
     _response;
     constructor(response) {
@@ -77,8 +78,38 @@ class ApiClient {
     get axiosAgent() {
         return getAxiosAgent();
     }
-    async requestWrapper(fn, raise_error = true) {
+    validateUrl(url, options) {
         try {
+            const parsedUrl = new URL(url);
+            // Default safe limits
+            const maxContentLength = options?.maxContentLength ?? 20 * 1024 * 1024; // 20MB
+            const maxBodyLength = options?.maxBodyLength ?? 20 * 1024 * 1024; // 20MB
+            const maxUrlLength = 8000; // cutoff for URLs
+            // Check overall URL length
+            if (url.length > maxUrlLength) {
+                throw new Error(`URL length exceeds maxUrlLength (${maxUrlLength} chars)`);
+            }
+            if (parsedUrl.protocol === "data:") {
+                // Either reject completely OR check payload size
+                if (isDataUrlPayloadTooLarge(url, maxContentLength)) {
+                    throw new Error("data: URI payload too large or invalid");
+                }
+            }
+            else if (!["http:", "https:"].includes(parsedUrl.protocol)) {
+                throw new Error(`Unsupported URL scheme: ${parsedUrl.protocol}`);
+            }
+            if (options?.data &&
+                Buffer.byteLength(JSON.stringify(options.data), "utf8") > maxBodyLength) {
+                throw new Error(`Request body exceeds maxBodyLength (${maxBodyLength} bytes)`);
+            }
+        }
+        catch (error) {
+            throw new Error(`Invalid URL: ${error.message}`);
+        }
+    }
+    async requestWrapper(fn, url, config, raise_error = true) {
+        try {
+            this.validateUrl(url, config);
             const res = await fn(this.axiosAgent);
             return new ApiResponse(res);
         }
@@ -89,20 +120,50 @@ class ApiClient {
             throw error;
         }
     }
-    async get({ url, headers, params, raise_error = true, }) {
-        return this.requestWrapper((agent) => this.instance.get(url, { headers, params, httpsAgent: agent }), raise_error);
-    }
-    async post({ url, headers, body, raise_error = true, }) {
-        return this.requestWrapper((agent) => this.instance.post(url, body, { headers, httpsAgent: agent }), raise_error);
-    }
-    async put({ url, headers, body, raise_error = true, }) {
-        return this.requestWrapper((agent) => this.instance.put(url, body, { headers, httpsAgent: agent }), raise_error);
-    }
-    async patch({ url, headers, body, raise_error = true, }) {
-        return this.requestWrapper((agent) => this.instance.patch(url, body, { headers, httpsAgent: agent }), raise_error);
-    }
-    async delete({ url, headers, params, raise_error = true, }) {
-        return this.requestWrapper((agent) => this.instance.delete(url, { headers, params, httpsAgent: agent }), raise_error);
+    async get({ url, headers, params, timeout, raise_error = true, }) {
+        const config = {
+            headers,
+            params,
+            timeout,
+            httpsAgent: this.axiosAgent,
+        };
+        return this.requestWrapper(() => this.instance.get(url, config), url, config, raise_error);
+    }
+    async post({ url, headers, body, timeout, raise_error = true, }) {
+        const config = {
+            headers,
+            timeout,
+            httpsAgent: this.axiosAgent,
+            data: body,
+        };
+        return this.requestWrapper(() => this.instance.post(url, config.data, config), url, config, raise_error);
+    }
+    async put({ url, headers, body, timeout, raise_error = true, }) {
+        const config = {
+            headers,
+            timeout,
+            httpsAgent: this.axiosAgent,
+            data: body,
+        };
+        return this.requestWrapper(() => this.instance.put(url, config.data, config), url, config, raise_error);
+    }
+    async patch({ url, headers, body, timeout, raise_error = true, }) {
+        const config = {
+            headers,
+            timeout,
+            httpsAgent: this.axiosAgent,
+            data: body,
+        };
+        return this.requestWrapper(() => this.instance.patch(url, config.data, config), url, config, raise_error);
+    }
+    async delete({ url, headers, params, timeout, raise_error = true, }) {
+        const config = {
+            headers,
+            params,
+            timeout,
+            httpsAgent: this.axiosAgent,
+        };
+        return this.requestWrapper(() => this.instance.delete(url, config), url, config, raise_error);
     }
 }
 export const apiClient = new ApiClient();

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

@@ -1,7 +1,9 @@
 export declare enum BrowserStackProducts {
     LIVE = "live",
     APP_LIVE = "app_live",
-    APP_AUTOMATE = "app_automate"
+    APP_AUTOMATE = "app_automate",
+    SELENIUM_AUTOMATE = "selenium_automate",
+    PLAYWRIGHT_AUTOMATE = "playwright_automate"
 }
 /**
  * Fetches and caches BrowserStack datasets (live + app_live + app_automate) with a shared TTL.

package/dist/lib/device-cache.js

@@ -12,11 +12,15 @@ export var BrowserStackProducts;
     BrowserStackProducts["LIVE"] = "live";
     BrowserStackProducts["APP_LIVE"] = "app_live";
     BrowserStackProducts["APP_AUTOMATE"] = "app_automate";
+    BrowserStackProducts["SELENIUM_AUTOMATE"] = "selenium_automate";
+    BrowserStackProducts["PLAYWRIGHT_AUTOMATE"] = "playwright_automate";
 })(BrowserStackProducts || (BrowserStackProducts = {}));
 const URLS = {
     [BrowserStackProducts.LIVE]: "https://www.browserstack.com/list-of-browsers-and-platforms/live.json",
     [BrowserStackProducts.APP_LIVE]: "https://www.browserstack.com/list-of-browsers-and-platforms/app_live.json",
     [BrowserStackProducts.APP_AUTOMATE]: "https://www.browserstack.com/list-of-browsers-and-platforms/app_automate.json",
+    [BrowserStackProducts.SELENIUM_AUTOMATE]: "https://www.browserstack.com/list-of-browsers-and-platforms/automate.json",
+    [BrowserStackProducts.PLAYWRIGHT_AUTOMATE]: "https://www.browserstack.com/list-of-browsers-and-platforms/playwright.json",
 };
 /**
  * Fetches and caches BrowserStack datasets (live + app_live + app_automate) with a shared TTL.
@@ -26,30 +30,33 @@ export async function getDevicesAndBrowsers(type) {
         fs.mkdirSync(CACHE_DIR, { recursive: true });
     }
     let cache = {};
+    // Load existing cache
     if (fs.existsSync(CACHE_FILE)) {
-        const stats = fs.statSync(CACHE_FILE);
-        if (Date.now() - stats.mtimeMs < TTL_MS) {
-            try {
-                cache = JSON.parse(fs.readFileSync(CACHE_FILE, "utf8"));
-                if (cache[type]) {
-                    return cache[type];
-                }
-            }
-            catch (error) {
-                console.error("Error parsing cache file:", error);
-                // Continue with fetching fresh data
-            }
+        try {
+            cache = JSON.parse(fs.readFileSync(CACHE_FILE, "utf8"));
+        }
+        catch (err) {
+            console.error("Error parsing cache file:", err);
+            cache = {};
+        }
+        // Check per-product TTL
+        const cachedEntry = cache[type];
+        if (cachedEntry?.timestamp && Date.now() - cachedEntry.timestamp < TTL_MS) {
+            return cachedEntry.data;
         }
     }
+    // Fetch fresh data from BrowserStack
     const liveRes = await apiClient.get({ url: URLS[type], raise_error: false });
     if (!liveRes.ok) {
-        throw new Error(`Failed to fetch configuration from BrowserStack : ${type}=${liveRes.statusText}`);
+        throw new Error(`Failed to fetch configuration from BrowserStack: ${type} = ${liveRes.statusText}`);
     }
-    cache = {
-        [type]: liveRes.data,
+    // Save to cache with timestamp and data directly under product key
+    cache[type] = {
+        timestamp: Date.now(),
+        data: liveRes.data,
     };
-    fs.writeFileSync(CACHE_FILE, JSON.stringify(cache), "utf8");
-    return cache[type];
+    fs.writeFileSync(CACHE_FILE, JSON.stringify(cache, null, 2), "utf8");
+    return liveRes.data;
 }
 // Rate limiter for started event (3H)
 export function shouldSendStartedEvent() {

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

@@ -3,7 +3,7 @@ import { getBrowserStackAuth } from "./get-auth.js";
 import { createRequire } from "module";
 const require = createRequire(import.meta.url);
 const packageJson = require("../../package.json");
-import axios from "axios";
+import { apiClient } from "./apiClient.js";
 import globalConfig from "../config.js";
 export function trackMCP(toolName, clientInfo, error, config) {
     const instrumentationEndpoint = "https://api.browserstack.com/sdk/v1/event";
@@ -38,13 +38,16 @@ export function trackMCP(toolName, clientInfo, error, config) {
         const authString = getBrowserStackAuth(config);
         authHeader = `Basic ${Buffer.from(authString).toString("base64")}`;
     }
-    axios
-        .post(instrumentationEndpoint, event, {
+    apiClient
+        .post({
+        url: instrumentationEndpoint,
+        body: event,
         headers: {
             "Content-Type": "application/json",
             ...(authHeader ? { Authorization: authHeader } : {}),
         },
         timeout: 2000,
+        raise_error: false,
     })
         .catch(() => { });
 }

package/dist/lib/utils.d.ts

@@ -1,4 +1,82 @@
 import type { ApiResponse } from "./apiClient.js";
+import { BrowserStackConfig } from "./types.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 export declare function sanitizeUrlParam(param: string): string;
 export declare function maybeCompressBase64(base64: string): Promise<string>;
 export declare function assertOkResponse(response: Response | ApiResponse, action: string): Promise<void>;
+export declare function fetchFromBrowserStackAPI(url: string, config: BrowserStackConfig): Promise<any>;
+export declare function handleMCPError(toolName: string, server: McpServer, config: BrowserStackConfig, error: unknown): {
+    [x: string]: unknown;
+    content: ({
+        [x: string]: unknown;
+        type: "text";
+        text: string;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    } | {
+        [x: string]: unknown;
+        type: "image";
+        data: string;
+        mimeType: string;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    } | {
+        [x: string]: unknown;
+        type: "audio";
+        data: string;
+        mimeType: string;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    } | {
+        [x: string]: unknown;
+        type: "resource_link";
+        name: string;
+        uri: string;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+        mimeType?: string | undefined;
+        title?: string | undefined;
+        description?: string | undefined;
+        icons?: {
+            [x: string]: unknown;
+            src: string;
+            mimeType?: string | undefined;
+            sizes?: string | undefined;
+        }[] | undefined;
+    } | {
+        [x: string]: unknown;
+        type: "resource";
+        resource: {
+            [x: string]: unknown;
+            text: string;
+            uri: string;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            mimeType?: string | undefined;
+        } | {
+            [x: string]: unknown;
+            uri: string;
+            blob: string;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            mimeType?: string | undefined;
+        };
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    })[];
+    _meta?: {
+        [x: string]: unknown;
+    } | undefined;
+    structuredContent?: {
+        [x: string]: unknown;
+    } | undefined;
+    isError?: boolean | undefined;
+};
+export declare function isDataUrlPayloadTooLarge(dataUrl: string, maxBytes: number): boolean;

package/dist/lib/utils.js

@@ -1,4 +1,6 @@
 import sharp from "sharp";
+import { getBrowserStackAuth } from "./get-auth.js";
+import { trackMCP } from "../index.js";
 export function sanitizeUrlParam(param) {
     // Remove any characters that could be used for command injection
     return param.replace(/[;&|`$(){}[\]<>]/g, "");
@@ -24,3 +26,48 @@ export async function assertOkResponse(response, action) {
         throw new Error(`Failed to fetch logs for ${action}: ${response.statusText}`);
     }
 }
+export async function fetchFromBrowserStackAPI(url, config) {
+    const authString = getBrowserStackAuth(config);
+    const auth = Buffer.from(authString).toString("base64");
+    const res = await fetch(url, {
+        headers: {
+            Authorization: `Basic ${auth}`,
+        },
+    });
+    if (!res.ok) {
+        throw new Error(`Failed to fetch from ${url}: ${res.status} ${res.statusText}`);
+    }
+    return res.json();
+}
+function errorContent(message) {
+    return {
+        content: [{ type: "text", text: message }],
+        isError: true,
+    };
+}
+export function handleMCPError(toolName, server, config, error) {
+    trackMCP(toolName, server.server.getClientVersion(), error, config);
+    const errorMessage = error instanceof Error ? error.message : "Unknown error";
+    const readableToolName = toolName.replace(/([A-Z])/g, " $1").toLowerCase();
+    return errorContent(`Failed to ${readableToolName}: ${errorMessage}. Please open an issue on GitHub if the problem persists`);
+}
+export function isDataUrlPayloadTooLarge(dataUrl, maxBytes) {
+    const commaIndex = dataUrl.indexOf(",");
+    if (commaIndex === -1)
+        return true; // malformed
+    const meta = dataUrl.slice(0, commaIndex);
+    const payload = dataUrl.slice(commaIndex + 1);
+    const isBase64 = /;base64$/i.test(meta);
+    if (!isBase64) {
+        try {
+            const decoded = decodeURIComponent(payload);
+            return Buffer.byteLength(decoded, "utf8") > maxBytes;
+        }
+        catch {
+            return true;
+        }
+    }
+    const padding = payload.endsWith("==") ? 2 : payload.endsWith("=") ? 1 : 0;
+    const decodedBytes = Math.floor((payload.length * 3) / 4) - padding;
+    return decodedBytes > maxBytes;
+}

package/dist/lib/version-resolver.js

@@ -20,26 +20,38 @@ export function resolveVersion(requested, available) {
         const lex = uniq.slice().sort();
         return requested === "latest" ? lex[lex.length - 1] : lex[0];
     }
-    // exact?
+    // exact match?
     if (uniq.includes(requested)) {
         return requested;
     }
-    // try closest numeric
+    // Try major version matching (e.g., "14" matches "14.0", "14.1", etc.)
     const reqNum = parseFloat(requested);
-    const nums = uniq
-        .map((v) => ({ v, n: parseFloat(v) }))
-        .filter((x) => !isNaN(x.n));
-    if (!isNaN(reqNum) && nums.length) {
-        let best = nums[0], bestDiff = Math.abs(nums[0].n - reqNum);
-        for (const x of nums) {
-            const d = Math.abs(x.n - reqNum);
-            if (d < bestDiff) {
-                best = x;
-                bestDiff = d;
+    if (!isNaN(reqNum)) {
+        const majorVersionMatches = uniq.filter((v) => {
+            const vNum = parseFloat(v);
+            return !isNaN(vNum) && Math.floor(vNum) === Math.floor(reqNum);
+        });
+        if (majorVersionMatches.length > 0) {
+            // If multiple matches, prefer the most common format or latest
+            const exactMatch = majorVersionMatches.find((v) => v === `${Math.floor(reqNum)}.0`);
+            if (exactMatch) {
+                return exactMatch;
             }
+            // Return the first match (usually the most common format)
+            return majorVersionMatches[0];
         }
-        return best.v;
     }
-    // final fallback
+    // Fuzzy matching: find the closest version
+    const reqNumForFuzzy = parseFloat(requested);
+    if (!isNaN(reqNumForFuzzy)) {
+        const numericVersions = uniq
+            .map((v) => ({ v, n: parseFloat(v) }))
+            .filter((x) => !isNaN(x.n))
+            .sort((a, b) => Math.abs(a.n - reqNumForFuzzy) - Math.abs(b.n - reqNumForFuzzy));
+        if (numericVersions.length > 0) {
+            return numericVersions[0].v;
+        }
+    }
+    // Fallback: return the first available version
     return uniq[0];
 }

package/dist/server-factory.js

@@ -4,6 +4,7 @@ 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";
@@ -12,7 +13,9 @@ 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";
+import addBuildInsightsTools from "./tools/build-insights.js";
 import { setupOnInitialized } from "./oninitialized.js";
+import addRCATools from "./tools/rca-agent.js";
 /**
  * Wrapper class for BrowserStack MCP Server
  * Stores a map of registered tools by name
@@ -38,6 +41,7 @@ export class BrowserStackMcpServer {
         const toolAdders = [
             addAccessibilityTools,
             addSDKTools,
+            addPercyTools,
             addAppLiveTools,
             addBrowserLiveTools,
             addTestManagementTools,
@@ -45,6 +49,8 @@ export class BrowserStackMcpServer {
             addFailureLogsTools,
             addAutomateTools,
             addSelfHealTools,
+            addBuildInsightsTools,
+            addRCATools,
         ];
         toolAdders.forEach((adder) => {
             // Each adder now returns a Record<string, Tool>

package/dist/tools/add-percy-snapshots.d.ts

@@ -0,0 +1,5 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare function updateTestsWithPercyCommands(args: {
+    uuid: string;
+    index: number;
+}): Promise<CallToolResult>;

package/dist/tools/add-percy-snapshots.js

@@ -0,0 +1,17 @@
+import { testFilePathsMap } from "../lib/inmemory-store.js";
+import { updateFileAndStep } from "./percy-snapshot-utils/utils.js";
+import { percyWebSetupInstructions } from "../tools/sdk-utils/percy-web/handler.js";
+export async function updateTestsWithPercyCommands(args) {
+    const { uuid, index } = args;
+    const filePaths = testFilePathsMap.get(uuid);
+    if (!filePaths) {
+        throw new Error(`No test files found in memory for UUID: ${uuid}`);
+    }
+    if (index < 0 || index >= filePaths.length) {
+        throw new Error(`Invalid index: ${index}. There are ${filePaths.length} files for UUID: ${uuid}`);
+    }
+    const result = await updateFileAndStep(filePaths[index], index, filePaths.length, percyWebSetupInstructions);
+    return {
+        content: result,
+    };
+}