runBrowserLiveSession
Manually test and debug websites on specific browser and OS combinations using BrowserStack's cloud infrastructure. Identify layout or compatibility issues in real-time by specifying the browser, OS version, and URL to analyze.
Instructions
Use this tool when user wants to manually check their website on a particular browser and OS combination using BrowserStack's cloud infrastructure. Can be used to debug layout issues, compatibility problems, etc.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| desiredBrowser | Yes | The browser to run the test on. Example: 'Chrome', 'IE', 'Safari', 'Edge'. Always ask the user for the browser they want to use, do not assume it. | |
| desiredBrowserVersion | Yes | The version of the browser to use. Example: 133.0, 134.0, 87.0 | |
| desiredOS | Yes | The operating system to run the browser on. Example: 'Windows', 'OS X' | |
| desiredOSVersion | Yes | The OS version to run the browser on. Example: '10' for Windows, '12' for macOS, '14' for iOS | |
| desiredURL | Yes | The URL of the website to test. This can be a local URL (e.g., http://localhost:3000) or a public URL. Always ask the user for the URL, do not assume it. |
Implementation Reference
- src/tools/live.ts:127-160 (registration)Registers the 'runBrowserLiveSession' tool on the McpServer, specifying name, description, input schema (LiveArgsShape), and the handler function that calls runBrowserSession with error handling and tracking.tools.runBrowserLiveSession = server.tool( "runBrowserLiveSession", "Launch a BrowserStack Live session (desktop or mobile).", LiveArgsShape, async (args) => { try { trackMCP( "runBrowserLiveSession", server.server.getClientVersion()!, undefined, config, ); return await runBrowserSession(args, config); } catch (error) { logger.error("Live session failed: %s", error); trackMCP( "runBrowserLiveSession", server.server.getClientVersion()!, error, config, ); return { content: [ { type: "text" as const, text: `Failed to start a browser live session. Error: ${error}`, isError: true, }, ], isError: true, }; } }, );
- src/tools/live.ts:11-38 (schema)Defines the Zod input schema (LiveArgsShape and LiveArgsSchema) used for validating tool arguments including platformType, desiredURL, OS, browser, etc.const LiveArgsShape = { platformType: z .nativeEnum(PlatformType) .describe("Must be 'desktop' or 'mobile'"), desiredURL: z.string().url().describe("The URL to test"), desiredOS: z .enum(["Windows", "OS X", "android", "ios", "winphone"]) .describe( "Desktop OS ('Windows' or 'OS X') or mobile OS ('android','ios','winphone')", ), desiredOSVersion: z .string() .describe( "The OS version must be specified as a version number (e.g., '10', '14.0') or as a keyword such as 'latest' or 'oldest'. Normalize variations like 'newest' or 'most recent' to 'latest', and terms like 'earliest' or 'first' to 'oldest'. For macOS, version names (e.g., 'Sequoia') must be used instead of numeric versions.", ), desiredBrowser: z .enum(["chrome", "firefox", "safari", "edge", "ie"]) .describe("Browser for desktop (Chrome, IE, Firefox, Safari, Edge)"), desiredBrowserVersion: z .string() .optional() .describe( "Browser version for desktop (e.g. '133.2', 'latest'). If the user says 'latest', 'newest', or similar, normalize it to 'latest'. Likewise, convert terms like 'earliest' or 'oldest' to 'oldest'.", ), desiredDevice: z.string().optional().describe("Device name for mobile"), }; const LiveArgsSchema = z.object(LiveArgsShape);
- src/tools/live.ts:90-119 (handler)Core handler function invoked by the registered tool handler. Validates input args, determines desktop/mobile, launches the session via launchDesktopSession or launchMobileSession, and returns the launch URL in a response object.async function runBrowserSession(rawArgs: any, config: BrowserStackConfig) { // Validate and narrow const args = LiveArgsSchema.parse(rawArgs); // Branch desktop vs mobile and delegate const launchUrl = args.platformType === PlatformType.DESKTOP ? await launchDesktopSession(args, config) : await launchMobileSession(args, config); let response = [ { type: "text" as const, text: `✅ Session started. If it didn't open automatically, visit:\n${launchUrl}`, }, ]; if (globalConfig.REMOTE_MCP) { response = [ { type: "text" as const, text: `✅ To start the session. Click on ${launchUrl}`, }, ]; } return { content: response, }; }
- Key helper function that starts the browser session: filters device/browser capabilities, sets up local tunnel if needed, builds the BrowserStack dashboard URL with parameters, opens browser if local, returns the URL.export async function startBrowserSession( args: DesktopSearchArgs | MobileSearchArgs, config: BrowserStackConfig, ): Promise<string> { const entry = args.platformType === PlatformType.DESKTOP ? await filterDesktop(args as DesktopSearchArgs) : await filterMobile(args as MobileSearchArgs); // Get credentials from config const authString = getBrowserStackAuth(config); const [username, password] = authString.split(":"); if (!username || !password) { throw new Error( "BrowserStack credentials are not set. Please configure them in the server settings.", ); } const isLocal = await prepareLocalTunnel(args.url, username, password); const url = args.platformType === PlatformType.DESKTOP ? buildDesktopUrl( args as DesktopSearchArgs, entry as DesktopEntry, isLocal, ) : buildMobileUrl(args as MobileSearchArgs, entry as MobileEntry, isLocal); if (!envConfig.REMOTE_MCP) { openBrowser(url); } return entry.notes ? `${url}, ${entry.notes}` : url; }