@browserstack/mcp-server 1.4.0 → 1.4.1

package/README.md

@@ -292,6 +292,8 @@ Select the “Installed” tab. Click the “Configure MCP Servers” button at
    }
    ```
 
+> **File & app uploads:** tools that upload a local file/app (`uploadProductRequirementFile`, `takeAppScreenshot`, `runAppTestsOnBrowserStack`, `runAppLiveSession`) require the `MCP_UPLOAD_BASE_DIR` env var set to a directory containing those files; uploads are restricted to it.
+
 ### 💡 List of BrowserStack MCP Tools
 
 As of now we support 46 tools.

package/dist/lib/upload-validator.d.ts

@@ -1,7 +1,7 @@
 export interface UploadValidationOptions {
     allowedExtensions: readonly string[];
     maxSizeBytes: number;
-    allowedBaseDir?: string;
+    allowedBaseDir: string | undefined;
 }
 /**
  * Canonicalizes and validates a user-supplied upload path. Returns the resolved
@@ -13,7 +13,8 @@ export interface UploadValidationOptions {
  *  - File extension is in `allowedExtensions` (case-insensitive)
  *  - No path segment is a hidden dir/file (starts with `.`); blocks ~/.ssh,
  *    ~/.aws, .env, etc. even after symlink resolution
- *  - If `allowedBaseDir` is set, the canonical path must live inside it
+ *  - `allowedBaseDir` is mandatory: uploads are refused unless it is configured
+ *    (via MCP_UPLOAD_BASE_DIR), and the canonical path must live inside it
  */
 export declare function validateUploadPath(filePath: string, options: UploadValidationOptions): string;
 export declare const APP_BINARY_EXTENSIONS: readonly [".apk", ".aab", ".ipa", ".app", ".zip"];

package/dist/lib/upload-validator.js

@@ -10,7 +10,8 @@ import path from "path";
  *  - File extension is in `allowedExtensions` (case-insensitive)
  *  - No path segment is a hidden dir/file (starts with `.`); blocks ~/.ssh,
  *    ~/.aws, .env, etc. even after symlink resolution
- *  - If `allowedBaseDir` is set, the canonical path must live inside it
+ *  - `allowedBaseDir` is mandatory: uploads are refused unless it is configured
+ *    (via MCP_UPLOAD_BASE_DIR), and the canonical path must live inside it
  */
 export function validateUploadPath(filePath, options) {
     if (typeof filePath !== "string" || filePath.trim().length === 0) {
@@ -48,20 +49,22 @@ export function validateUploadPath(filePath, options) {
     if (!allowed.includes(ext)) {
         throw new Error(`Upload rejected: file extension "${ext || "(none)"}" is not in the allowed list (${allowed.join(", ")}).`);
     }
-    if (options.allowedBaseDir) {
-        let baseCanonical;
-        try {
-            baseCanonical = fs.realpathSync(path.resolve(options.allowedBaseDir));
-        }
-        catch {
-            throw new Error(`Upload rejected: configured MCP_UPLOAD_BASE_DIR does not exist (${options.allowedBaseDir}).`);
-        }
-        const baseWithSep = baseCanonical.endsWith(path.sep)
-            ? baseCanonical
-            : baseCanonical + path.sep;
-        if (canonical !== baseCanonical && !canonical.startsWith(baseWithSep)) {
-            throw new Error(`Upload rejected: file must be located inside ${baseCanonical}.`);
-        }
+    if (!options.allowedBaseDir) {
+        throw new Error("Upload rejected: MCP_UPLOAD_BASE_DIR is not set. Set it to the directory " +
+            "containing the files to upload, then restart the MCP server.");
+    }
+    let baseCanonical;
+    try {
+        baseCanonical = fs.realpathSync(path.resolve(options.allowedBaseDir));
+    }
+    catch {
+        throw new Error(`Upload rejected: configured MCP_UPLOAD_BASE_DIR does not exist (${options.allowedBaseDir}).`);
+    }
+    const baseWithSep = baseCanonical.endsWith(path.sep)
+        ? baseCanonical
+        : baseCanonical + path.sep;
+    if (canonical !== baseCanonical && !canonical.startsWith(baseWithSep)) {
+        throw new Error(`Upload rejected: file must be located inside ${baseCanonical}.`);
     }
     return canonical;
 }

package/dist/tools/appautomate-utils/native-execution/constants.js

@@ -20,7 +20,8 @@ export const RUN_APP_AUTOMATE_SCHEMA = {
         "  xcodebuild clean -scheme YOUR_SCHEME && \\\n" +
         "  xcodebuild archive -scheme YOUR_SCHEME -configuration Release -archivePath build/app.xcarchive && \\\n" +
         "  xcodebuild -exportArchive -archivePath build/app.xcarchive -exportPath build/ipa -exportOptionsPlist exportOptions.plist\n\n" +
-        "If in other directory, provide existing app path"),
+        "If in other directory, provide existing app path.\n" +
+        "The resolved file must be located inside the directory set in MCP_UPLOAD_BASE_DIR."),
     testSuitePath: z
         .string()
         .describe("Path to your test suite file:\n" +
@@ -30,7 +31,8 @@ export const RUN_APP_AUTOMATE_SCHEMA = {
         "  xcodebuild test-without-building -scheme YOUR_SCHEME -destination 'generic/platform=iOS' && \\\n" +
         "  cd ~/Library/Developer/Xcode/DerivedData/*/Build/Products/Debug-iphonesimulator/ && \\\n" +
         "  zip -r Tests.zip *.xctestrun *-Runner.app\n\n" +
-        "If in other directory, provide existing test file path"),
+        "If in other directory, provide existing test file path.\n" +
+        "The resolved file must be located inside the directory set in MCP_UPLOAD_BASE_DIR."),
     devices: z
         .array(MobileDeviceSchema)
         .max(3)

package/dist/tools/appautomate.js

@@ -206,7 +206,7 @@ export default function addAppAutomationTools(server, config) {
             .describe("Platform to run the app on. Either 'android' or 'ios'."),
         appPath: z
             .string()
-            .describe("The path to the .apk or .ipa file. Required for app installation."),
+            .describe("The path to the .apk or .ipa file. Required for app installation. Must be located inside the directory set in MCP_UPLOAD_BASE_DIR."),
     }, {
         title: "Take App Screenshot",
         readOnlyHint: false,
@@ -266,9 +266,11 @@ export default function addAppAutomationTools(server, config) {
         idempotentHint: true,
     }, async (args) => {
         try {
+            trackMCP("setupBrowserStackAppAutomateTests", server.server.getClientVersion(), undefined, config);
             return await setupAppAutomateHandler(args, config);
         }
         catch (error) {
+            trackMCP("setupBrowserStackAppAutomateTests", server.server.getClientVersion(), error, config);
             const error_message = error instanceof Error ? error.message : "Unknown error";
             return {
                 content: [

package/dist/tools/applive.js

@@ -66,7 +66,7 @@ export default function addAppLiveTools(server, config) {
             .describe("Which platform to run on, examples: 'android', 'ios'. Set this based on the app path provided."),
         appPath: z
             .string()
-            .describe("The path to the .ipa or .apk file to install on the device. Always ask the user for the app path, do not assume it."),
+            .describe("The path to the .ipa or .apk file to install on the device. Always ask the user for the app path, do not assume it. Must be located inside the directory set in MCP_UPLOAD_BASE_DIR."),
     }, {
         title: "Run App Live Session",
         readOnlyHint: false,

package/dist/tools/bstack-sdk.js

@@ -13,11 +13,11 @@ export function registerRunBrowserStackTestsTool(server, config) {
         idempotentHint: true,
     }, async (args) => {
         try {
-            trackMCP("runTestsOnBrowserStack", server.server.getClientVersion(), config);
+            trackMCP("setupBrowserStackAutomateTests", server.server.getClientVersion(), undefined, config);
             return await runTestsOnBrowserStackHandler(args, config);
         }
         catch (error) {
-            return handleMCPError("runTestsOnBrowserStack", server, config, error);
+            return handleMCPError("setupBrowserStackAutomateTests", server, config, error);
         }
     });
     return tools;

package/dist/tools/build-insights.js

@@ -108,7 +108,7 @@ export default function addBuildInsightsTools(server, config) {
         idempotentHint: true,
     }, async (args) => {
         try {
-            trackMCP("fetchBuildInsights", server.server.getClientVersion(), config);
+            trackMCP("fetchBuildInsights", server.server.getClientVersion(), undefined, config);
             return await fetchBuildInsightsTool(args, config);
         }
         catch (error) {

package/dist/tools/percy-sdk.js

@@ -38,11 +38,11 @@ export function registerPercyTools(server, config) {
         idempotentHint: true,
     }, async (args) => {
         try {
-            trackMCP("VisualTestIntegrationAgent", server.server.getClientVersion(), config);
+            trackMCP("percyVisualTestIntegrationAgent", server.server.getClientVersion(), undefined, config);
             return simulatePercyChangeHandler(args, config);
         }
         catch (error) {
-            return handleMCPError("VisualTestIntegrationAgent", server, config, error);
+            return handleMCPError("percyVisualTestIntegrationAgent", server, config, error);
         }
     });
     tools.setupPercyVisualTesting = server.tool("expandPercyVisualTesting", SETUP_PERCY_DESCRIPTION, SetUpPercyParamsShape, {
@@ -53,11 +53,11 @@ export function registerPercyTools(server, config) {
         idempotentHint: true,
     }, async (args) => {
         try {
-            trackMCP("setupPercyVisualTesting", server.server.getClientVersion(), config);
+            trackMCP("expandPercyVisualTesting", server.server.getClientVersion(), undefined, config);
             return setUpPercyHandler(args, config);
         }
         catch (error) {
-            return handleMCPError("setupPercyVisualTesting", server, config, error);
+            return handleMCPError("expandPercyVisualTesting", server, config, error);
         }
     });
     tools.addPercySnapshotCommands = server.tool("addPercySnapshotCommands", PERCY_SNAPSHOT_COMMANDS_DESCRIPTION, UpdateTestFileWithInstructionsParams, {
@@ -68,7 +68,7 @@ export function registerPercyTools(server, config) {
         idempotentHint: true,
     }, async (args) => {
         try {
-            trackMCP("addPercySnapshotCommands", server.server.getClientVersion(), config);
+            trackMCP("addPercySnapshotCommands", server.server.getClientVersion(), undefined, config);
             return await updateTestsWithPercyCommands(args);
         }
         catch (error) {
@@ -83,7 +83,7 @@ export function registerPercyTools(server, config) {
         idempotentHint: true,
     }, async () => {
         try {
-            trackMCP("listTestFiles", server.server.getClientVersion(), config);
+            trackMCP("listTestFiles", server.server.getClientVersion(), undefined, config);
             return addListTestFiles();
         }
         catch (error) {
@@ -98,7 +98,7 @@ export function registerPercyTools(server, config) {
         idempotentHint: true,
     }, async (args) => {
         try {
-            trackMCP("runPercyScan", server.server.getClientVersion(), config);
+            trackMCP("runPercyScan", server.server.getClientVersion(), undefined, config);
             return runPercyScan(args);
         }
         catch (error) {
@@ -113,7 +113,7 @@ export function registerPercyTools(server, config) {
         idempotentHint: true,
     }, async (args) => {
         try {
-            trackMCP("fetchPercyChanges", server.server.getClientVersion(), config);
+            trackMCP("fetchPercyChanges", server.server.getClientVersion(), undefined, config);
             return await fetchPercyChanges(args, config);
         }
         catch (error) {
@@ -128,7 +128,7 @@ export function registerPercyTools(server, config) {
         idempotentHint: true,
     }, async (args) => {
         try {
-            trackMCP("managePercyBuildApproval", server.server.getClientVersion(), config);
+            trackMCP("managePercyBuildApproval", server.server.getClientVersion(), undefined, config);
             return await approveOrDeclinePercyBuild(args, config);
         }
         catch (error) {

package/dist/tools/testmanagement-utils/TCG-utils/api.js

@@ -1,5 +1,5 @@
 import { apiClient } from "../../../lib/apiClient.js";
-import { TCG_TRIGGER_URL, TCG_POLL_URL, FETCH_DETAILS_URL, FORM_FIELDS_URL, BULK_CREATE_URL, TC_DETAILS_MAX_BATCH, } from "./config.js";
+import { TCG_TRIGGER_URL, TCG_POLL_URL, FETCH_DETAILS_URL, FORM_FIELDS_URL, BULK_CREATE_URL, TC_DETAILS_MAX_BATCH, TCG_POLL_INTERVAL_MS, TCG_POLL_MAX_WAIT_MS, } from "./config.js";
 import { createTestCasePayload } from "./helpers.js";
 import { getBrowserStackAuth } from "../../../lib/get-auth.js";
 import { getTMBaseURL } from "../../../lib/tm-base-url.js";
@@ -118,9 +118,15 @@ export async function pollTestCaseDetails(traceRequestId, config) {
     let done = false;
     const tmBaseUrl = await getTMBaseURL(config);
     const TCG_POLL_URL_VALUE = TCG_POLL_URL(tmBaseUrl);
+    const deadline = Date.now() + TCG_POLL_MAX_WAIT_MS;
     while (!done) {
+        // Bail out if the backend never sends a "termination" message, so a stuck
+        // job cannot keep this loop (and its callers) alive forever.
+        if (Date.now() > deadline) {
+            throw new Error(`TCG test-case detail polling timed out after ${TCG_POLL_MAX_WAIT_MS}ms (trace ${traceRequestId})`);
+        }
         // add a bit of jitter to avoid synchronized polling storms
-        await new Promise((r) => setTimeout(r, 10000 + Math.random() * 5000));
+        await new Promise((r) => setTimeout(r, TCG_POLL_INTERVAL_MS + Math.random() * 5000));
         const poll = await apiClient.post({
             url: `${TCG_POLL_URL_VALUE}?x-bstack-traceRequestId=${encodeURIComponent(traceRequestId)}`,
             headers: {
@@ -159,7 +165,20 @@ export async function pollScenariosTestDetails(args, traceId, context, documentI
     const TCG_POLL_URL_VALUE = TCG_POLL_URL(tmBaseUrl);
     // Promisify interval-style polling using a wrapper
     await new Promise((resolve, reject) => {
-        const intervalId = setInterval(async () => {
+        const timers = {};
+        const stop = () => {
+            if (timers.interval)
+                clearInterval(timers.interval);
+            if (timers.timeout)
+                clearTimeout(timers.timeout);
+        };
+        // Hard wall-clock deadline: if the backend never sends a "termination"
+        // message, reject instead of letting the interval fire forever.
+        timers.timeout = setTimeout(() => {
+            stop();
+            reject(new Error(`TCG scenario polling timed out after ${TCG_POLL_MAX_WAIT_MS}ms (trace ${traceId})`));
+        }, TCG_POLL_MAX_WAIT_MS);
+        timers.interval = setInterval(async () => {
             try {
                 const poll = await apiClient.post({
                     url: `${TCG_POLL_URL_VALUE}?x-bstack-traceRequestId=${encodeURIComponent(traceId)}`,
@@ -169,7 +188,7 @@ export async function pollScenariosTestDetails(args, traceId, context, documentI
                     body: {},
                 });
                 if (poll.status !== 200) {
-                    clearInterval(intervalId);
+                    stop();
                     reject(new Error(`Polling error: ${poll.statusText || poll.status}`));
                     return;
                 }
@@ -221,16 +240,16 @@ export async function pollScenariosTestDetails(args, traceId, context, documentI
                         }
                     }
                     if (msg.type === "termination") {
-                        clearInterval(intervalId);
+                        stop();
                         resolve();
                     }
                 }
             }
             catch (err) {
-                clearInterval(intervalId);
+                stop();
                 reject(err);
             }
-        }, 10000); // 10 second interval
+        }, TCG_POLL_INTERVAL_MS);
     });
     // once all detail fetches are triggered, wait for them to complete
     const detailsList = await Promise.all(detailPromises);

package/dist/tools/testmanagement-utils/TCG-utils/config.d.ts

@@ -1,4 +1,6 @@
 export declare const TC_DETAILS_MAX_BATCH = 10;
+export declare const TCG_POLL_INTERVAL_MS = 10000;
+export declare const TCG_POLL_MAX_WAIT_MS: number;
 export declare const TCG_TRIGGER_URL: (baseUrl: string) => string;
 export declare const TCG_POLL_URL: (baseUrl: string) => string;
 export declare const FETCH_DETAILS_URL: (baseUrl: string) => string;

package/dist/tools/testmanagement-utils/TCG-utils/config.js

@@ -1,4 +1,9 @@
 export const TC_DETAILS_MAX_BATCH = 10;
+// Wall-clock bounds for the TCG generation polling loops. Without a hard
+// deadline, a job that never emits a "termination" message keeps the loop
+// (and every caller awaiting it) alive forever.
+export const TCG_POLL_INTERVAL_MS = 10_000;
+export const TCG_POLL_MAX_WAIT_MS = 10 * 60 * 1000; // 10 minutes
 export const TCG_TRIGGER_URL = (baseUrl) => `${baseUrl}/api/v1/integration/tcg/test-generation/suggest-test-cases`;
 export const TCG_POLL_URL = (baseUrl) => `${baseUrl}/api/v1/integration/tcg/test-generation/test-cases-polling`;
 export const FETCH_DETAILS_URL = (baseUrl) => `${baseUrl}/api/v1/integration/tcg/test-generation/fetch-test-case-details`;

package/dist/tools/testmanagement.js

@@ -264,11 +264,11 @@ export async function uploadProductRequirementFileTool(args, config, server) {
  */
 export async function createTestCasesFromFileTool(args, context, config, server) {
     try {
-        trackMCP("createTestCasesFromFile", server.server.getClientVersion(), undefined);
+        trackMCP("createTestCasesFromFile", server.server.getClientVersion(), undefined, config);
         return await createTestCasesFromFile(args, context, config);
     }
     catch (err) {
-        trackMCP("createTestCasesFromFile", server.server.getClientVersion(), err);
+        trackMCP("createTestCasesFromFile", server.server.getClientVersion(), err, config);
         return {
             content: [
                 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserstack/mcp-server",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "BrowserStack's Official MCP Server",
   "mcpName": "io.github.browserstack/mcp-server",
   "main": "dist/index.js",