runPerformanceAudit

Analyze webpage performance metrics to identify optimization opportunities and improve loading speed.

Instructions

Run a performance audit on the current page

Input Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Implementation Reference

browser-tools-server/lighthouse/performance.ts:89-102 (handler)

Core handler function that executes the performance audit using Lighthouse and processes the results into an AI-optimized report format.

export async function runPerformanceAudit(
  url: string
): Promise<AIOptimizedPerformanceReport> {
  try {
    const lhr = await runLighthouseAudit(url, [AuditCategory.PERFORMANCE]);
    return extractAIOptimizedData(lhr, url);
  } catch (error) {
    throw new Error(
      `Performance audit failed: ${
        error instanceof Error ? error.message : String(error)
      }`
    );
  }
}

browser-tools-mcp/mcp-server.ts:435-515 (registration)

MCP server tool registration for 'runPerformanceAudit', which proxies requests to the browser-tools-server's /performance-audit endpoint.

server.tool(
  "runPerformanceAudit",
  "Run a performance audit on the current page",
  {},
  async () => {
    return await withServerConnection(async () => {
      try {
        // Simplified approach - let the browser connector handle the current tab and URL
        console.log(
          `Sending POST request to http://${discoveredHost}:${discoveredPort}/performance-audit`
        );
        const response = await fetch(
          `http://${discoveredHost}:${discoveredPort}/performance-audit`,
          {
            method: "POST",
            headers: {
              "Content-Type": "application/json",
              Accept: "application/json",
            },
            body: JSON.stringify({
              category: AuditCategory.PERFORMANCE,
              source: "mcp_tool",
              timestamp: Date.now(),
            }),
          }
        );

        // Log the response status
        console.log(`Performance audit response status: ${response.status}`);

        if (!response.ok) {
          const errorText = await response.text();
          console.error(`Performance audit error: ${errorText}`);
          throw new Error(`Server returned ${response.status}: ${errorText}`);
        }

        const json = await response.json();

        // flatten it by merging metadata with the report contents
        if (json.report) {
          const { metadata, report } = json;
          const flattened = {
            ...metadata,
            ...report,
          };

          return {
            content: [
              {
                type: "text",
                text: JSON.stringify(flattened, null, 2),
              },
            ],
          };
        } else {
          // Return as-is if it's not in the new format
          return {
            content: [
              {
                type: "text",
                text: JSON.stringify(json, null, 2),
              },
            ],
          };
        }
      } catch (error) {
        const errorMessage =
          error instanceof Error ? error.message : String(error);
        console.error("Error in performance audit:", errorMessage);
        return {
          content: [
            {
              type: "text",
              text: `Failed to run performance audit: ${errorMessage}`,
            },
          ],
        };
      }
    });
  }
);

browser-tools-server/browser-connector.ts:1335-1403 (handler)

HTTP endpoint handler setup for /performance-audit (invoked via setupPerformanceAudit()), which calls the runPerformanceAudit lighthouse function.

private setupAuditEndpoint(
  auditType: string,
  endpoint: string,
  auditFunction: (url: string) => Promise<LighthouseReport>
) {
  // Add server identity validation endpoint
  this.app.get("/.identity", (req, res) => {
    res.json({
      signature: "mcp-browser-connector-24x7",
      version: "1.2.0",
    });
  });

  this.app.post(endpoint, async (req: any, res: any) => {
    try {
      console.log(`${auditType} audit request received`);

      // Get URL using our helper method
      const url = await this.getUrlForAudit();

      if (!url) {
        console.log(`No URL available for ${auditType} audit`);
        return res.status(400).json({
          error: `URL is required for ${auditType} audit. Make sure you navigate to a page in the browser first, and the browser-tool extension tab is open.`,
        });
      }

      // If we're using the stored URL (not from request body), log it now
      if (!req.body?.url && url === currentUrl) {
        console.log(`Using stored URL for ${auditType} audit:`, url);
      }

      // Check if we're using the default URL
      if (url === "about:blank") {
        console.log(`Cannot run ${auditType} audit on about:blank`);
        return res.status(400).json({
          error: `Cannot run ${auditType} audit on about:blank`,
        });
      }

      console.log(`Preparing to run ${auditType} audit for: ${url}`);

      // Run the audit using the provided function
      try {
        const result = await auditFunction(url);

        console.log(`${auditType} audit completed successfully`);
        // Return the results
        res.json(result);
      } catch (auditError) {
        console.error(`${auditType} audit failed:`, auditError);
        const errorMessage =
          auditError instanceof Error
            ? auditError.message
            : String(auditError);
        res.status(500).json({
          error: `Failed to run ${auditType} audit: ${errorMessage}`,
        });
      }
    } catch (error) {
      console.error(`Error in ${auditType} audit endpoint:`, error);
      const errorMessage =
        error instanceof Error ? error.message : String(error);
      res.status(500).json({
        error: `Error in ${auditType} audit endpoint: ${errorMessage}`,
      });
    }
  });
}

browser-tools-server/lighthouse/index.ts:49-128 (helper)

Core helper that launches a headless browser instance and runs the Lighthouse audit engine.

export async function runLighthouseAudit(
  url: string,
  categories: string[]
): Promise<LighthouseResult> {
  console.log(`Starting Lighthouse ${categories.join(", ")} audit for: ${url}`);

  if (!url || url === "about:blank") {
    console.error("Invalid URL for Lighthouse audit");
    throw new Error(
      "Cannot run audit on an empty page or about:blank. Please navigate to a valid URL first."
    );
  }

  try {
    // Always use a dedicated headless browser for audits
    console.log("Using dedicated headless browser for audit");

    // Determine if this is a performance audit - we need to load all resources for performance audits
    const isPerformanceAudit = categories.includes(AuditCategory.PERFORMANCE);

    // For performance audits, we want to load all resources
    // For accessibility or other audits, we can block non-essential resources
    try {
      const { port } = await connectToHeadlessBrowser(url, {
        blockResources: !isPerformanceAudit,
      });

      console.log(`Connected to browser on port: ${port}`);

      // Create Lighthouse config
      const { flags, config } = createLighthouseConfig(categories);
      flags.port = port;

      console.log(
        `Running Lighthouse with categories: ${categories.join(", ")}`
      );
      const runnerResult = await lighthouse(url, flags as Flags, config);
      console.log("Lighthouse scan completed");

      if (!runnerResult?.lhr) {
        console.error("Lighthouse audit failed to produce results");
        throw new Error("Lighthouse audit failed to produce results");
      }

      // Schedule browser cleanup after a delay to allow for subsequent audits
      scheduleBrowserCleanup();

      // Return the result
      const result = runnerResult.lhr;

      return result;
    } catch (browserError) {
      // Check if the error is related to Chrome/Edge not being available
      const errorMessage =
        browserError instanceof Error
          ? browserError.message
          : String(browserError);
      if (
        errorMessage.includes("Chrome could not be found") ||
        errorMessage.includes("Failed to launch browser") ||
        errorMessage.includes("spawn ENOENT")
      ) {
        throw new Error(
          "Chrome or Edge browser could not be found. Please ensure that Chrome or Edge is installed on your system to run audits."
        );
      }
      // Re-throw other errors
      throw browserError;
    }
  } catch (error) {
    console.error("Lighthouse audit failed:", error);
    // Schedule browser cleanup even if the audit fails
    scheduleBrowserCleanup();
    throw new Error(
      `Lighthouse audit failed: ${
        error instanceof Error ? error.message : String(error)
      }`
    );
  }
}

browser-tools-server/lighthouse/performance.ts:10-30 (schema)

Type definitions for the AI-optimized performance report structure returned by the tool.

export interface PerformanceReportContent {
  score: number; // Overall score (0-100)
  audit_counts: {
    // Counts of different audit types
    failed: number;
    passed: number;
    manual: number;
    informative: number;
    not_applicable: number;
  };
  metrics: AIOptimizedMetric[];
  opportunities: AIOptimizedOpportunity[];
  page_stats?: AIPageStats; // Optional page statistics
  prioritized_recommendations?: string[]; // Ordered list of recommendations
}

/**
 * Full performance report implementing the base LighthouseReport interface
 */
export type AIOptimizedPerformanceReport =
  LighthouseReport<PerformanceReportContent>;

BrowserTools MCP