@browserstack/mcp-server 1.0.4 → 1.0.6

package/README.md

@@ -4,6 +4,7 @@
 <img src="assets/browserstack-logo.png" alt="BrowserStack Logo" height="100"> <img src="assets/mcp-logo.png" alt="MCP Server Logo" width="100">
 </div>
 
+
 <div align="center">
 <a href="https://www.npmjs.com/package/@browserstack/mcp-server">
 <img alt="NPM Version" src="https://img.shields.io/npm/v/%40browserstack%2Fmcp-server">
@@ -11,10 +12,20 @@
 
 </div>
 
+<p align="center">One Platform For All Your Testing Needs</p>
 
-<h3 align="center">One Platform For All Your Testing Needs</h4>
+<div align="center">
+<a href="https://glama.ai/mcp/servers/@browserstack/mcp-server">
+  <img width="380" height="200" src="https://glama.ai/mcp/servers/@browserstack/mcp-server/badge" alt="BrowserStack server MCP server" />
+</a>
+</div>
 
-## 📖 Overview
+<div>
+    <a href="https://www.youtube.com/watch?v=sLA7K9v7qZc">
+      <img src="assets/thumbnail.webp">
+    </a>
+  </div>
+  
 Enable every developer and tester in your team, whether they are testing manually, starting their automation journey, or scaling test automation.
 BrowserStack MCP Server allows you to use our cutting-edge [Test Platform](https://www.browserstack.com/test-platform) directly from your favourite AI tools.
 
@@ -38,20 +49,17 @@ Use the following prompts to use your **mobile apps** on BrowserStack's extensiv
 "My app crashed on Android 14 device, can you help me debug?"
 ```
 
-Video Walkthrough:
-
-[![Watch the video](https://img.youtube.com/vi/vy1sx0J7sTk/0.jpg)](https://www.youtube.com/watch?v=vy1sx0J7sTk)
 
 - Unlike emulators, test your app's real-world performance on actual devices. With advanced [App-Profiling features](https://www.browserstack.com/docs/app-live/app-performance-testing), you can debug crashes and performance issues in real-time.
 - Access all major devices and OS versions from our [device grid](https://www.browserstack.com/list-of-browsers-and-platforms/app_live), We have strict SLAs to provision our global datacenters with newly released devices on [launch day](https://www.browserstack.com/blog/browserstack-launches-iphone-15-on-day-0-behind-the-scenes/).
 
 ### 🌐 Manual Web Testing
 
-Similar to the app testing, you can use the following prompts to test your **websites** on BrowserStack's extensive cloud of real browsers and devices. Don't have a Windows machine to test on Internet Explorer? We've got you covered!
+Similar to the app testing, you can use the following prompts to test your **websites** on BrowserStack's extensive cloud of real browsers and devices. Don't have Edge browser installed on your machine ? We've got you covered!
 
 ```bash
 # Test your local websites
-"open my website hosted on localhost:3001 on Internet Explorer"
+"open my website hosted on localhost:3001 on Edge"
 ```
 
 - Test websites across different browsers and devices. We support [every major browser](https://www.browserstack.com/list-of-browsers-and-platforms/live) across every major OS.
@@ -81,10 +89,19 @@ Use the following prompts to run/debug/fix your **automated tests** on BrowserSt
 1. **Create a BrowserStack Account**
 
    - Sign up for [BrowserStack](https://www.browserstack.com/signup) if you don't have an account already.
-   - Note down your `username` and `access_key` from [Account Settings](https://www.browserstack.com/accounts/profile/details)
 
-2. **Install the MCP Server**
+   - ℹ️ If you have an open-source project, we'll be able to provide you with a [free plan](https://www.browserstack.com/open-source).
+   <div align="center">
+   <img src="assets/open-source-plan.png" alt="Open Source Plan">
+   </div>
+
+   - 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`:
+
    ```json
    {
      "servers": {
@@ -99,10 +116,12 @@ Use the following prompts to run/debug/fix your **automated tests** on BrowserSt
      }
    }
    ```
-   * In VSCode, make sure to click on `Start` button in the MCP Server to start the server.
-   ![Start MCP Server](assets/vscode_install.png)
 
-   - For Cursor: `.cursor/mcp.json`:
+   - In VSCode, make sure to click on `Start` button in the MCP Server to start the server.
+     ![Start MCP Server](assets/vscode_install.png)
+
+   * For Cursor: `.cursor/mcp.json`:
+
    ```json
    {
      "mcpServers": {
@@ -117,7 +136,9 @@ Use the following prompts to run/debug/fix your **automated tests** on BrowserSt
      }
    }
    ```
+
    - Claude Desktop: `~/claude_desktop_config.json`:
+
    ```json
    {
      "mcpServers": {
@@ -133,7 +154,6 @@ Use the following prompts to run/debug/fix your **automated tests** on BrowserSt
    }
    ```
 
-
 ## 🤝 Recommended MCP Clients
 
 - We recommend using **Github Copilot or Cursor** for automated testing + debugging use cases.
@@ -147,6 +167,7 @@ Use the following prompts to run/debug/fix your **automated tests** on BrowserSt
 ## 📝 Contributing
 
 We welcome contributions! Please open an issue to discuss any changes you'd like to make.
+👉 [**Click here to view our Contributing Guidelines**](https://github.com/browserstack/mcp-server/blob/main/CONTRIBUTING.md)
 
 ## 📞 Support
 
@@ -160,7 +181,6 @@ For support, please:
 
 Stay tuned for exciting updates! Have any suggestions? Please open an issue to discuss.
 
-
 ## 🔗 Resources
 
 - [BrowserStack Test Platform](https://www.browserstack.com/test-platform)

package/dist/index.js

@@ -14,12 +14,16 @@ const applive_1 = __importDefault(require("./tools/applive"));
 const observability_1 = __importDefault(require("./tools/observability"));
 const live_1 = __importDefault(require("./tools/live"));
 const accessibility_1 = __importDefault(require("./tools/accessibility"));
+const automate_1 = __importDefault(require("./tools/automate"));
+const testmanagement_1 = __importDefault(require("./tools/testmanagement"));
 function registerTools(server) {
     (0, bstack_sdk_1.default)(server);
     (0, applive_1.default)(server);
     (0, live_1.default)(server);
     (0, observability_1.default)(server);
     (0, accessibility_1.default)(server);
+    (0, automate_1.default)(server);
+    (0, testmanagement_1.default)(server);
 }
 // Create an MCP server
 const server = new mcp_js_1.McpServer({

package/dist/lib/api.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getLatestO11YBuildInfo = getLatestO11YBuildInfo;
+exports.retrieveNetworkFailures = retrieveNetworkFailures;
 const config_1 = __importDefault(require("../config"));
 async function getLatestO11YBuildInfo(buildName, projectName) {
     const buildsUrl = `https://api-observability.browserstack.com/ext/v1/builds/latest?build_name=${encodeURIComponent(buildName)}&project_name=${encodeURIComponent(projectName)}`;
@@ -20,3 +21,50 @@ async function getLatestO11YBuildInfo(buildName, projectName) {
     }
     return buildsResponse.json();
 }
+// Fetches network logs for a given session ID and returns only failure logs
+async function retrieveNetworkFailures(sessionId) {
+    if (!sessionId) {
+        throw new Error("Session ID is required");
+    }
+    const url = `https://api.browserstack.com/automate/sessions/${sessionId}/networklogs`;
+    const auth = Buffer.from(`${config_1.default.browserstackUsername}:${config_1.default.browserstackAccessKey}`).toString("base64");
+    const response = await fetch(url, {
+        method: "GET",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Basic ${auth}`,
+        },
+    });
+    if (!response.ok) {
+        if (response.status === 404) {
+            throw new Error("Invalid session ID");
+        }
+        throw new Error(`Failed to fetch network logs: ${response.statusText}`);
+    }
+    const networklogs = await response.json();
+    // Filter for failure logs
+    const failureEntries = networklogs.log.entries.filter((entry) => {
+        return (entry.response.status === 0 ||
+            entry.response.status >= 400 ||
+            entry.response._error !== undefined);
+    });
+    // Return only the failure entries with some context
+    return {
+        failures: failureEntries.map((entry) => ({
+            startedDateTime: entry.startedDateTime,
+            request: {
+                method: entry.request?.method,
+                url: entry.request?.url,
+                queryString: entry.request?.queryString,
+            },
+            response: {
+                status: entry.response?.status,
+                statusText: entry.response?.statusText,
+                _error: entry.response?._error,
+            },
+            serverIPAddress: entry.serverIPAddress,
+            time: entry.time,
+        })),
+        totalFailures: failureEntries.length,
+    };
+}

package/dist/lib/error.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatAxiosError = formatAxiosError;
+const axios_1 = require("axios");
+/**
+ * Formats an AxiosError into a CallToolResult with an appropriate message.
+ * @param err - The error object to format
+ * @param defaultText - The fallback error message
+ */
+function formatAxiosError(err, defaultText) {
+    let text = defaultText;
+    if (err instanceof axios_1.AxiosError && err.response?.data) {
+        const message = err.response.data.message ||
+            err.response.data.error ||
+            err.message ||
+            defaultText;
+        text = message;
+    }
+    else if (err instanceof Error) {
+        text = err.message;
+    }
+    return {
+        content: [{ type: "text", text }],
+        isError: true,
+    };
+}

package/dist/tools/automate.js

@@ -0,0 +1,52 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNetworkFailures = getNetworkFailures;
+exports.default = addAutomateTools;
+const zod_1 = require("zod");
+const logger_1 = __importDefault(require("../logger"));
+const api_1 = require("../lib/api");
+/**
+ * Fetches failed network requests from a BrowserStack Automate session.
+ * Returns network requests that resulted in errors or failed to complete.
+ */
+async function getNetworkFailures(args) {
+    try {
+        const failureLogs = await (0, api_1.retrieveNetworkFailures)(args.sessionId);
+        logger_1.default.info("Successfully fetched failure network logs for session: %s", args.sessionId);
+        // Check if there are any failures
+        const hasFailures = failureLogs.totalFailures > 0;
+        const text = hasFailures
+            ? `${failureLogs.totalFailures} network failure(s) found for session :\n\n${JSON.stringify(failureLogs.failures, null, 2)}`
+            : `No network failures found for session`;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : "An unknown error occurred";
+        logger_1.default.error("Failed to fetch network logs: %s", errorMessage);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to fetch network logs: ${errorMessage}`,
+                    isError: true,
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+function addAutomateTools(server) {
+    server.tool("getNetworkFailures", "Use this tool to fetch failed network requests from a BrowserStack Automate session.", {
+        sessionId: zod_1.z.string().describe("The Automate session ID."),
+    }, getNetworkFailures);
+}

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

@@ -17,6 +17,7 @@ const nodejsInstructions = `
   \`\`\`json
   "browserstack-node-sdk": "latest"
   \`\`\`
+- Inform user to export BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY as environment variables.
 `;
 const pythonInstructions = `
 Run the following command to install the browserstack-sdk:

package/dist/tools/testmanagement-utils/create-project-folder.js

@@ -0,0 +1,107 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CreateProjFoldSchema = void 0;
+exports.createProjectOrFolder = createProjectOrFolder;
+const axios_1 = __importDefault(require("axios"));
+const config_1 = __importDefault(require("../../config"));
+const zod_1 = require("zod");
+const error_1 = require("../../lib/error"); // or correct path
+// Schema for combined project/folder creation
+exports.CreateProjFoldSchema = zod_1.z.object({
+    project_name: zod_1.z
+        .string()
+        .optional()
+        .describe("Name of the project to create."),
+    project_description: zod_1.z
+        .string()
+        .optional()
+        .describe("Description for the new project."),
+    project_identifier: zod_1.z
+        .string()
+        .optional()
+        .describe("Existing project identifier to use for folder creation."),
+    folder_name: zod_1.z.string().optional().describe("Name of the folder to create."),
+    folder_description: zod_1.z
+        .string()
+        .optional()
+        .describe("Description for the new folder."),
+    parent_id: zod_1.z
+        .number()
+        .optional()
+        .describe("Parent folder ID; if omitted, folder is created at root."),
+});
+/**
+ * Creates a project and/or folder in BrowserStack Test Management.
+ */
+async function createProjectOrFolder(args) {
+    const { project_name, project_description, project_identifier, folder_name, folder_description, parent_id, } = exports.CreateProjFoldSchema.parse(args);
+    if (!project_name && !project_identifier && !folder_name) {
+        throw new Error("Provide project_name (to create project), or project_identifier and folder_name (to create folder).");
+    }
+    let projId = project_identifier;
+    // Step 1: Create project if project_name provided
+    if (project_name) {
+        try {
+            const res = await axios_1.default.post("https://test-management.browserstack.com/api/v2/projects", { project: { name: project_name, description: project_description } }, {
+                auth: {
+                    username: config_1.default.browserstackUsername,
+                    password: config_1.default.browserstackAccessKey,
+                },
+                headers: { "Content-Type": "application/json" },
+            });
+            if (!res.data.success) {
+                throw new Error(`Failed to create project: ${JSON.stringify(res.data)}`);
+            }
+            // Project created successfully
+            projId = res.data.project.identifier;
+        }
+        catch (err) {
+            return (0, error_1.formatAxiosError)(err, "Failed to create project..");
+        }
+    }
+    // Step 2: Create folder if folder_name provided
+    if (folder_name) {
+        if (!projId)
+            throw new Error("Cannot create folder without project_identifier.");
+        try {
+            const res = await axios_1.default.post(`https://test-management.browserstack.com/api/v2/projects/${encodeURIComponent(projId)}/folders`, {
+                folder: {
+                    name: folder_name,
+                    description: folder_description,
+                    parent_id,
+                },
+            }, {
+                auth: {
+                    username: config_1.default.browserstackUsername,
+                    password: config_1.default.browserstackAccessKey,
+                },
+                headers: { "Content-Type": "application/json" },
+            });
+            if (!res.data.success) {
+                throw new Error(`Failed to create folder: ${JSON.stringify(res.data)}`);
+            }
+            // Folder created successfully
+            const folder = res.data.folder;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Folder created: ID=${folder.id}, name=${folder.name} in project with identifier ${projId}`,
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return (0, error_1.formatAxiosError)(err, "Failed to create folder.");
+        }
+    }
+    // Only project was created
+    return {
+        content: [
+            { type: "text", text: `Project created with identifier=${projId}` },
+        ],
+    };
+}

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

@@ -0,0 +1,115 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CreateTestCaseSchema = void 0;
+exports.sanitizeArgs = sanitizeArgs;
+exports.createTestCase = createTestCase;
+const axios_1 = __importDefault(require("axios"));
+const config_1 = __importDefault(require("../../config"));
+const zod_1 = require("zod");
+const error_1 = require("../../lib/error"); // or correct
+exports.CreateTestCaseSchema = zod_1.z.object({
+    project_identifier: zod_1.z
+        .string()
+        .describe("The ID of the BrowserStack project where the test case should be created. If no project identifier is provided, ask the user if they would like to create a new project using the createProjectOrFolder tool."),
+    folder_id: zod_1.z
+        .string()
+        .describe("The ID of the folder within the project where the test case should be created. If not provided, ask the user if they would like to create a new folder using the createProjectOrFolder tool."),
+    name: zod_1.z.string().describe("Name of the test case."),
+    description: zod_1.z
+        .string()
+        .optional()
+        .describe("Brief description of the test case."),
+    owner: zod_1.z
+        .string()
+        .email()
+        .describe("Email of the test case owner.")
+        .optional(),
+    preconditions: zod_1.z
+        .string()
+        .optional()
+        .describe("Any preconditions (HTML allowed)."),
+    test_case_steps: zod_1.z
+        .array(zod_1.z.object({
+        step: zod_1.z.string().describe("Action to perform in this step."),
+        result: zod_1.z.string().describe("Expected result of this step."),
+    }))
+        .describe("List of steps and expected results."),
+    issues: zod_1.z
+        .array(zod_1.z.string())
+        .optional()
+        .describe("List of the linked Jira, Asana or Azure issues ID's. This should be strictly in array format not the string of json."),
+    issue_tracker: zod_1.z
+        .object({
+        name: zod_1.z
+            .string()
+            .describe("Issue tracker name,  For example, use jira for Jira, azure for Azure DevOps, or asana for Asana."),
+        host: zod_1.z.string().url().describe("Base URL of the issue tracker."),
+    })
+        .optional(),
+    tags: zod_1.z
+        .array(zod_1.z.string())
+        .optional()
+        .describe("Tags to attach to the test case. This should be strictly in array format not the string of json"),
+    custom_fields: zod_1.z
+        .record(zod_1.z.string(), zod_1.z.string())
+        .optional()
+        .describe("Map of custom field names to values."),
+});
+function sanitizeArgs(args) {
+    const cleaned = { ...args };
+    if (cleaned.description === null)
+        delete cleaned.description;
+    if (cleaned.owner === null)
+        delete cleaned.owner;
+    if (cleaned.preconditions === null)
+        delete cleaned.preconditions;
+    if (cleaned.issue_tracker) {
+        if (cleaned.issue_tracker.name === undefined ||
+            cleaned.issue_tracker.host === undefined) {
+            delete cleaned.issue_tracker;
+        }
+    }
+    return cleaned;
+}
+async function createTestCase(params) {
+    const body = { test_case: params };
+    try {
+        const response = await axios_1.default.post(`https://test-management.browserstack.com/api/v2/projects/${encodeURIComponent(params.project_identifier)}/folders/${encodeURIComponent(params.folder_id)}/test-cases`, body, {
+            auth: {
+                username: config_1.default.browserstackUsername,
+                password: config_1.default.browserstackAccessKey,
+            },
+            headers: { "Content-Type": "application/json" },
+        });
+        const { data } = response.data;
+        if (!data.success) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to create test case: ${JSON.stringify(response.data)}`,
+                        isError: true,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const tc = data.test_case;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Successfully created test case ${tc.identifier}: ${tc.title}`,
+                },
+                { type: "text", text: JSON.stringify(tc, null, 2) },
+            ],
+        };
+    }
+    catch (err) {
+        // Delegate to our centralized Axios error formatter
+        return (0, error_1.formatAxiosError)(err, "Failed to create test case");
+    }
+}

package/dist/tools/testmanagement.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProjectOrFolderTool = createProjectOrFolderTool;
+exports.createTestCaseTool = createTestCaseTool;
+exports.default = addTestManagementTools;
+const create_project_folder_1 = require("./testmanagement-utils/create-project-folder");
+const create_testcase_1 = require("./testmanagement-utils/create-testcase");
+/**
+ * Wrapper to call createProjectOrFolder util.
+ */
+async function createProjectOrFolderTool(args) {
+    try {
+        return await (0, create_project_folder_1.createProjectOrFolder)(args);
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to create project/folder: ${err instanceof Error ? err.message : "Unknown error"}. Please open an issue on GitHub if the problem persists`,
+                    isError: true,
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+/**
+ * Creates a test case in BrowserStack Test Management.
+ */
+async function createTestCaseTool(args) {
+    // Sanitize input arguments
+    const cleanedArgs = (0, create_testcase_1.sanitizeArgs)(args);
+    try {
+        return await (0, create_testcase_1.createTestCase)(cleanedArgs);
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to create test case: ${err instanceof Error ? err.message : "Unknown error"}. Please open an issue on GitHub if the problem persists`,
+                    isError: true,
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+/**
+ * Registers both project/folder and test-case tools.
+ */
+function addTestManagementTools(server) {
+    server.tool("createProjectOrFolder", "Create a project and/or folder in BrowserStack Test Management.", create_project_folder_1.CreateProjFoldSchema.shape, createProjectOrFolderTool);
+    server.tool("createTestCase", "Use this tool to create a test case in BrowserStack Test Management.", create_testcase_1.CreateTestCaseSchema.shape, createTestCaseTool);
+}

package/package.json

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