BrowserStack MCP server

Instructions

Implementation Reference

• src/tools/observability.ts:9-53 (handler)

  Core handler function that fetches the latest BrowserStack build info, extracts observability URL, overview insight, and top error details, then formats and returns them as tool result.

  export async function getFailuresInLastRun(
    buildName: string,
    projectName: string,
    config: BrowserStackConfig,
  ): Promise<CallToolResult> {
    const buildsData = await getLatestO11YBuildInfo(
      buildName,
      projectName,
      config,
    );
  
    if (!buildsData.data) {
      throw new Error(
        "No observability URL found in build data, this is likely because the build is not yet available on BrowserStack Observability.",
      );
    }
    const observabilityUrl = buildsData.data.observability_url;
    if (!observabilityUrl) {
      throw new Error(
        "No observability URL found in build data, this is likely because the build is not yet available on BrowserStack Observability.",
      );
    }
  
    let overview = "No overview available";
    if (buildsData.data.unique_errors?.overview?.insight) {
      overview = buildsData.data.unique_errors.overview.insight;
    }
  
    let details = "No error details available";
    if (buildsData.data.unique_errors?.top_unique_errors?.length > 0) {
      details = buildsData.data.unique_errors.top_unique_errors
        .map((error: any) => error.error)
        .filter(Boolean)
        .join("\n");
    }
  
    return {
      content: [
        {
          type: "text",
          text: `Observability URL: ${observabilityUrl}\nOverview: ${overview}\nError Details: ${details}`,
        },
      ],
    };
  }

• src/tools/observability.ts:62-73 (schema)

  Zod input schema defining parameters buildName and projectName for the tool.

  {
    buildName: z
      .string()
      .describe(
        "Name of the build to get failures for. This is the 'build' key in the browserstack.yml file. If not sure, ask the user for the build name.",
      ),
    projectName: z
      .string()
      .describe(
        "Name of the project to get failures for. This is the 'projectName' key in the browserstack.yml file. If not sure, ask the user for the project name.",
      ),
  },

• src/tools/observability.ts:59-107 (registration)

  Registers the getFailuresInLastRun tool with the MCP server, including description, input schema, and a wrapper handler that provides tracking and error handling around the core logic.

  server.tool(
    "getFailuresInLastRun",
    "Use this tool to debug failures in the last run of the test suite on BrowserStack. Use only when browserstack.yml file is present in the project root.",
    {
      buildName: z
        .string()
        .describe(
          "Name of the build to get failures for. This is the 'build' key in the browserstack.yml file. If not sure, ask the user for the build name.",
        ),
      projectName: z
        .string()
        .describe(
          "Name of the project to get failures for. This is the 'projectName' key in the browserstack.yml file. If not sure, ask the user for the project name.",
        ),
    },
    async (args) => {
      try {
        trackMCP(
          "getFailuresInLastRun",
          server.server.getClientVersion()!,
          undefined,
          config,
        );
        return await getFailuresInLastRun(
          args.buildName,
          args.projectName,
          config,
        );
      } catch (error) {
        logger.error("Failed to get failures in the last run: %s", error);
        trackMCP(
          "getFailuresInLastRun",
          server.server.getClientVersion()!,
          error,
          config,
        );
        return {
          content: [
            {
              type: "text",
              text: `Failed to get failures in the last run. Error: ${error}. Please open an issue on GitHub if this is an issue with BrowserStack`,
              isError: true,
            },
          ],
          isError: true,
        };
      }
    },
  );