@browserstack/mcp-server 1.0.8 → 1.0.10

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

@@ -0,0 +1,64 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_CONFIGURATIONS = void 0;
+const config_1 = __importDefault(require("../../config"));
+const nodejsInstructions = `
+- Ensure that \`browserstack-node-sdk\` is present in package.json, use the latest version.
+- Add new scripts to package.json for running tests on BrowserStack (use \`npx\` to trigger the sdk):
+  \`\`\`json
+  "scripts": {
+    "test:browserstack": "npx browserstack-node-sdk <framework-specific-test-execution-command>"
+  }
+  \`\`\`
+- Add to dependencies:
+  \`\`\`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:
+\`\`\`bash
+python3 -m pip install browserstack-sdk
+\`\`\`
+
+Run the following command to setup the browserstack-sdk:
+\`\`\`bash
+browserstack-sdk setup --username "${config_1.default.browserstackUsername}" --key "${config_1.default.browserstackAccessKey}"
+\`\`\`
+
+In order to run tests on BrowserStack, run the following command:
+\`\`\`bash
+browserstack-sdk python <path-to-test-file>
+\`\`\`
+`;
+exports.SUPPORTED_CONFIGURATIONS = {
+    nodejs: {
+        playwright: {
+            jest: { instructions: nodejsInstructions },
+            codeceptjs: { instructions: nodejsInstructions },
+            playwright: { instructions: nodejsInstructions },
+        },
+        selenium: {
+            jest: { instructions: nodejsInstructions },
+            webdriverio: { instructions: nodejsInstructions },
+            mocha: { instructions: nodejsInstructions },
+            cucumber: { instructions: nodejsInstructions },
+            nightwatch: { instructions: nodejsInstructions },
+            codeceptjs: { instructions: nodejsInstructions },
+        },
+    },
+    python: {
+        playwright: {
+            pytest: { instructions: pythonInstructions },
+        },
+        selenium: {
+            pytest: { instructions: pythonInstructions },
+            robot: { instructions: pythonInstructions },
+            behave: { instructions: pythonInstructions },
+        },
+    },
+};

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

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getInstructionsForProjectConfiguration = void 0;
+exports.generateBrowserStackYMLInstructions = generateBrowserStackYMLInstructions;
+const constants_1 = require("./constants");
+const errorMessageSuffix = "Please open an issue at our Github repo: https://github.com/browserstack/browserstack-mcp-server/issues to request support for your project configuration";
+const getInstructionsForProjectConfiguration = (detectedBrowserAutomationFramework, detectedTestingFramework, detectedLanguage) => {
+    const configuration = constants_1.SUPPORTED_CONFIGURATIONS[detectedLanguage];
+    if (!configuration) {
+        throw new Error(`BrowserStack MCP Server currently does not support ${detectedLanguage}, ${errorMessageSuffix}`);
+    }
+    if (!configuration[detectedBrowserAutomationFramework]) {
+        throw new Error(`BrowserStack MCP Server currently does not support ${detectedBrowserAutomationFramework} for ${detectedLanguage}, ${errorMessageSuffix}`);
+    }
+    if (!configuration[detectedBrowserAutomationFramework][detectedTestingFramework]) {
+        throw new Error(`BrowserStack MCP Server currently does not support ${detectedTestingFramework} for ${detectedBrowserAutomationFramework} on ${detectedLanguage}, ${errorMessageSuffix}`);
+    }
+    return configuration[detectedBrowserAutomationFramework][detectedTestingFramework].instructions;
+};
+exports.getInstructionsForProjectConfiguration = getInstructionsForProjectConfiguration;
+function generateBrowserStackYMLInstructions(desiredPlatforms) {
+    return `
+      Create a browserstack.yml file in the project root. The file should be in the following format:
+
+      \`\`\`yaml
+# ======================
+# BrowserStack Reporting
+# ======================
+projectName: BrowserStack MCP Runs
+build: mcp-run
+
+# =======================================
+# Platforms (Browsers / Devices to test)
+# =======================================
+# Platforms object contains all the browser / device combinations you want to test on.
+# Generate this on the basis of the following platforms requested by the user:
+# Requested platforms: ${desiredPlatforms}
+platforms:
+  - os: Windows
+    osVersion: 11
+    browserName: chrome
+    browserVersion: latest
+  
+# =======================
+# Parallels per Platform
+# =======================
+# The number of parallel threads to be used for each platform set.
+# BrowserStack's SDK runner will select the best strategy based on the configured value
+#
+# Example 1 - If you have configured 3 platforms and set \`parallelsPerPlatform\` as 2, a total of 6 (2 * 3) parallel threads will be used on BrowserStack
+#
+# Example 2 - If you have configured 1 platform and set \`parallelsPerPlatform\` as 5, a total of 5 (1 * 5) parallel threads will be used on BrowserStack
+parallelsPerPlatform: 1
+
+browserstackLocal: true
+
+# ===================
+# Debugging features
+# ===================
+debug: true
+testObservability: true
+      \`\`\`
+      \n`;
+}

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

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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.8",
+  "version": "1.0.10",
   "description": "BrowserStack's Official MCP Server",
   "main": "dist/index.js",
   "repository": {