BrowserStack

Implements the Model Context Protocol (MCP) standard using @modelcontextprotocol/sdk to expose BrowserStack testing capabilities as callable tools to AI clients. The server uses stdin/stdout transport to communicate with AI IDEs (VSCode, Cursor, Claude Desktop), automatically registering 20+ tools across 7 functional categories with Zod-based schema validation for parameter types. Each tool follows a consistent pattern: input validation → authentication via environment variables → Axios-based HTTP API calls to BrowserStack services → structured response formatting with error handling.

Enables AI agents and developers to launch interactive testing sessions on real BrowserStack devices through tools like runBrowserLiveSession and runAppLiveSession. The implementation manages device allocation, session lifecycle, and real-time interaction by calling BrowserStack's Live Testing API, returning session URLs and device metadata that allow users to control browsers/apps in real-time. Sessions are authenticated via BrowserStack credentials and support both web browsers and native mobile applications across iOS and Android platforms.

Implements credential management using environment variables (BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY) for secure storage of BrowserStack API credentials. The system validates credentials at server startup and injects them into all API requests via Basic Auth headers. Credentials are never logged or exposed in error messages, and the system fails fast if credentials are missing or invalid.

Implements input validation using Zod schemas for all tool parameters, ensuring type safety and catching invalid inputs before API calls. Each tool defines a Zod schema that validates parameter types, required fields, string formats (URLs, email addresses), enum values, and numeric ranges. Validation errors are caught and returned to the client with detailed error messages indicating which fields are invalid and why.

Supports deployment across multiple AI clients (VSCode with Copilot, Cursor IDE, Claude Desktop) through client-specific configuration files (.vscode/mcp.json, .cursor/mcp.json, ~/claude_desktop_config.json). The MCP server is distributed as an npm package and can be installed via npx with environment variables, with each client reading its configuration file to discover and connect to the server via stdin/stdout transport. Configuration includes server command, environment variables, and tool availability settings.

Organizes 20+ tools into 7 functional categories (SDK Integration, Live Testing, Test Management, Automation, Accessibility, Observability, AI Agent Tools) with each category following a consistent implementation pattern: input validation via Zod schemas, authentication via environment variables, API calls via shared Axios client, response formatting, and error handling. This modular architecture enables easy tool addition and maintenance while ensuring consistent behavior across all tools.

Handles asynchronous test execution patterns where test runs are queued and executed in the background, with results retrieved via polling or webhook callbacks. The implementation supports both synchronous tool calls (which return immediately with a test run ID) and asynchronous result retrieval (which polls BrowserStack's API or waits for webhook notifications). This enables long-running tests to execute without blocking the AI client.

Provides tools (createTestCase, createTestRun, listTestRuns) that allow AI agents to programmatically create test cases with structured metadata, execute test runs, and retrieve test execution history. The implementation uses Axios HTTP clients to call BrowserStack's Test Management API, accepting test case definitions (name, description, steps, expected results) and test run parameters (device configurations, build identifiers), then returning test IDs and run status. Test cases are stored in BrowserStack's backend and can be reused across multiple test runs.

Exposes tools (takeAppScreenshot, fetchAutomationScreenshots) that capture screenshots from automated test runs or live sessions across multiple devices and browsers. The implementation calls BrowserStack's App Automate and Automation APIs to retrieve screenshot artifacts, supporting both native mobile apps and web browsers. Screenshots are returned as image data or URLs and can be used for visual regression testing, documentation, or failure analysis without requiring manual screenshot collection.

Implements the startAccessibilityScan tool that triggers automated accessibility audits on web applications using BrowserStack's Accessibility Testing service. The tool calls the Accessibility API with target URLs and optional scan parameters, returning a list of detected accessibility violations (WCAG 2.1 Level A/AA/AAA, ADA compliance issues) with severity levels and remediation suggestions. Scans run asynchronously and results are retrieved via polling or webhook integration.

Provides tools (getFailuresInLastRun, fetchSelfHealedSelectors) that analyze test failures and detect automatically-healed selectors in failed test runs. The implementation queries BrowserStack's Observability API to retrieve failure details (assertion errors, timeout errors, element not found), and identifies selectors that were automatically corrected by BrowserStack's self-healing engine. This enables developers to understand why tests failed and which selectors need manual updates.

Implements device cache and version management infrastructure that maintains an up-to-date inventory of available devices, browsers, and OS versions supported by BrowserStack. The system periodically queries BrowserStack's Device API and caches results locally to reduce API calls, exposing device capabilities (screen resolution, RAM, CPU, supported features) through tool parameters. The cache is invalidated on a configurable schedule and supports filtering by device type, OS, browser, and custom capabilities.

Manages BrowserStack Local Tunnel connections that enable testing of private, internal, or localhost applications without exposing them to the internet. The implementation handles tunnel lifecycle (creation, authentication, health checks, teardown) using BrowserStack's Local API, supporting both direct tunnel connections and proxy-based routing. Tunnels are authenticated via BrowserStack credentials and can be shared across multiple test runs within a session.

Implements comprehensive error handling and observability infrastructure using Pino logger for structured logging of all tool executions, API calls, and failures. The system captures error context (request parameters, API responses, stack traces), categorizes errors by type (validation, authentication, rate limiting, API errors), and provides detailed error messages to clients. Logs are structured as JSON for easy parsing and integration with observability platforms (ELK, Datadog, etc.).

Provides a centralized HTTP client layer using Axios that handles all communication with BrowserStack's REST APIs (Test Management, Live Testing, Accessibility, App Automate, Automation, etc.). The client abstracts authentication (Basic Auth with API credentials), request/response formatting, timeout handling, and retry logic. All tool implementations use this shared client, ensuring consistent error handling and request formatting across the entire MCP server.