BrowserStack MCP server

Instructions

Implementation Reference

• src/tools/accessibility.ts:198-221 (handler)

  Handler wrapper for startAccessibilityScan tool: handles tracking, executes the core scan logic, and error handling.

  async function executeAccessibilityScan(
    args: { name: string; pageURL: string; authConfigId?: number },
    context: ScanProgressContext,
    server: McpServer,
    config: BrowserStackConfig,
  ): Promise<CallToolResult> {
    try {
      trackMCP(
        "startAccessibilityScan",
        server.server.getClientVersion()!,
        undefined,
        config,
      );
      return await runAccessibilityScan(
        args.name,
        args.pageURL,
        context,
        config,
        args.authConfigId,
      );
    } catch (error) {
      return handleMCPError("startAccessibilityScan", server, config, error);
    }
  }

• src/tools/accessibility.ts:366-402 (handler)

  Core handler function that performs the accessibility scan: starts scan on BrowserStack, waits for completion, fetches and parses the report.

  async function runAccessibilityScan(
    name: string,
    pageURL: string,
    context: ScanProgressContext,
    config: BrowserStackConfig,
    authConfigId?: number,
  ): Promise<CallToolResult> {
    const scanner = await initializeScanner(config);
  
    const startResp = await scanner.startScan(name, [pageURL], authConfigId);
    const scanId = startResp.data!.id;
    const scanRunId = startResp.data!.scanRunId;
  
    await notifyScanProgress(context, `Accessibility scan "${name}" started`, 0);
  
    const status = await scanner.waitUntilComplete(scanId, scanRunId, context);
    if (status !== "completed") {
      return createScanFailureResponse(name, status);
    }
  
    const reportFetcher = await initializeReportFetcher(config);
    const reportLink = await reportFetcher.getReportLink(scanId, scanRunId);
  
    const { records, page_length, total_issues, next_page } =
      await parseAccessibilityReportFromCSV(reportLink);
  
    return createScanSuccessResponse(
      name,
      total_issues,
      page_length,
      records,
      scanId,
      scanRunId,
      reportLink,
      next_page,
    );
  }

• src/tools/accessibility.ts:425-439 (registration)

  Registers the startAccessibilityScan tool on the MCP server with schema and handler.

  tools.startAccessibilityScan = server.tool(
    "startAccessibilityScan",
    "Start an accessibility scan via BrowserStack and retrieve a local CSV report path.",
    {
      name: z.string().describe("Name of the accessibility scan"),
      pageURL: z.string().describe("The URL to scan for accessibility issues"),
      authConfigId: z
        .number()
        .optional()
        .describe("Optional auth config ID for authenticated scans"),
    },
    async (args, context) => {
      return await executeAccessibilityScan(args, context, server, config);
    },
  );

• src/tools/accessibility.ts:429-435 (schema)

  Input schema for startAccessibilityScan tool using Zod validation.

    name: z.string().describe("Name of the accessibility scan"),
    pageURL: z.string().describe("The URL to scan for accessibility issues"),
    authConfigId: z
      .number()
      .optional()
      .describe("Optional auth config ID for authenticated scans"),
  },

• src/tools/accessibility.ts:76-86 (helper)

  Helper function for standardized error handling in MCP tools, used by startAccessibilityScan.

    toolName: string,
    server: McpServer,
    config: BrowserStackConfig,
    error: unknown,
  ): CallToolResult {
    trackMCP(toolName, server.server.getClientVersion()!, error, config);
    const errorMessage = error instanceof Error ? error.message : "Unknown error";
    return createErrorResponse(
      `Failed to ${toolName.replace(/([A-Z])/g, " $1").toLowerCase()}: ${errorMessage}. Please open an issue on GitHub if the problem persists`,
    );
  }