BrowserTools MCP

Instructions

Implementation Reference

• browser-tools-server/lighthouse/best-practices.ts:81-94 (handler)

  The primary handler function that executes the Lighthouse best practices audit by calling runLighthouseAudit and processing results with extractAIOptimizedData.

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

• browser-tools-mcp/mcp-server.ts:1350-1425 (registration)

  MCP server registration of the 'runBestPracticesAudit' tool, which proxies requests to the browser-tools-server endpoint /best-practices-audit.

  server.tool(
    "runBestPracticesAudit",
    "Run a best practices audit on the current page",
    {},
    async () => {
      return await withServerConnection(async () => {
        try {
          console.log(
            `Sending POST request to http://${discoveredHost}:${discoveredPort}/best-practices-audit`
          );
          const response = await fetch(
            `http://${discoveredHost}:${discoveredPort}/best-practices-audit`,
            {
              method: "POST",
              headers: {
                "Content-Type": "application/json",
                Accept: "application/json",
              },
              body: JSON.stringify({
                source: "mcp_tool",
                timestamp: Date.now(),
              }),
            }
          );
  
          // Check for errors
          if (!response.ok) {
            const errorText = await response.text();
            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 Best Practices audit:", errorMessage);
          return {
            content: [
              {
                type: "text",
                text: `Failed to run Best Practices audit: ${errorMessage}`,
              },
            ],
          };
        }
      });
    }
  );

• browser-tools-server/lighthouse/best-practices.ts:10-34 (schema)

  Type definitions for the Best Practices report structure, including content schema and AI-optimized report type.

  export interface BestPracticesReportContent {
    score: number; // Overall score (0-100)
    audit_counts: {
      // Counts of different audit types
      failed: number;
      passed: number;
      manual: number;
      informative: number;
      not_applicable: number;
    };
    issues: AIBestPracticesIssue[];
    categories: {
      [category: string]: {
        score: number;
        issues_count: number;
      };
    };
    prioritized_recommendations?: string[]; // Ordered list of recommendations
  }
  
  /**
   * Full Best Practices report implementing the base LighthouseReport interface
   */
  export type AIOptimizedBestPracticesReport =
    LighthouseReport<BestPracticesReportContent>;

• browser-tools-server/lighthouse/best-practices.ts:99-336 (helper)

  Helper function that transforms raw Lighthouse results into the AI-optimized Best Practices report format, including issue categorization, scoring, and recommendations.

  const extractAIOptimizedData = (
    lhr: LighthouseResult,
    url: string
  ): AIOptimizedBestPracticesReport => {
    const categoryData = lhr.categories[AuditCategory.BEST_PRACTICES];
    const audits = lhr.audits || {};
  
    // Add metadata
    const metadata = {
      url,
      timestamp: lhr.fetchTime || new Date().toISOString(),
      device: lhr.configSettings?.formFactor || "desktop",
      lighthouseVersion: lhr.lighthouseVersion || "unknown",
    };
  
    // Process audit results
    const issues: AIBestPracticesIssue[] = [];
    const categories: { [key: string]: { score: number; issues_count: number } } =
      {
        security: { score: 0, issues_count: 0 },
        trust: { score: 0, issues_count: 0 },
        "user-experience": { score: 0, issues_count: 0 },
        "browser-compat": { score: 0, issues_count: 0 },
        other: { score: 0, issues_count: 0 },
      };
  
    // Counters for audit types
    let failedCount = 0;
    let passedCount = 0;
    let manualCount = 0;
    let informativeCount = 0;
    let notApplicableCount = 0;
  
    // Process failed audits (score < 1)
    const failedAudits = Object.entries(audits)
      .filter(([, audit]) => {
        const score = audit.score;
        return (
          score !== null &&
          score < 1 &&
          audit.scoreDisplayMode !== "manual" &&
          audit.scoreDisplayMode !== "notApplicable"
        );
      })
      .map(([auditId, audit]) => ({ auditId, ...audit }));
  
    // Update counters
    Object.values(audits).forEach((audit) => {
      const { score, scoreDisplayMode } = audit;
  
      if (scoreDisplayMode === "manual") {
        manualCount++;
      } else if (scoreDisplayMode === "informative") {
        informativeCount++;
      } else if (scoreDisplayMode === "notApplicable") {
        notApplicableCount++;
      } else if (score === 1) {
        passedCount++;
      } else if (score !== null && score < 1) {
        failedCount++;
      }
    });
  
    // Process failed audits into AI-friendly format
    failedAudits.forEach((ref: any) => {
      // Determine impact level based on audit score and weight
      let impact: "critical" | "serious" | "moderate" | "minor" = "moderate";
      const score = ref.score || 0;
  
      // Use a more reliable approach to determine impact
      if (score === 0) {
        impact = "critical";
      } else if (score < 0.5) {
        impact = "serious";
      } else if (score < 0.9) {
        impact = "moderate";
      } else {
        impact = "minor";
      }
  
      // Categorize the issue
      let category = "other";
  
      // Security-related issues
      if (
        ref.auditId.includes("csp") ||
        ref.auditId.includes("security") ||
        ref.auditId.includes("vulnerab") ||
        ref.auditId.includes("password") ||
        ref.auditId.includes("cert") ||
        ref.auditId.includes("deprecat")
      ) {
        category = "security";
      }
      // Trust and legitimacy issues
      else if (
        ref.auditId.includes("doctype") ||
        ref.auditId.includes("charset") ||
        ref.auditId.includes("legit") ||
        ref.auditId.includes("trust")
      ) {
        category = "trust";
      }
      // User experience issues
      else if (
        ref.auditId.includes("user") ||
        ref.auditId.includes("experience") ||
        ref.auditId.includes("console") ||
        ref.auditId.includes("errors") ||
        ref.auditId.includes("paste")
      ) {
        category = "user-experience";
      }
      // Browser compatibility issues
      else if (
        ref.auditId.includes("compat") ||
        ref.auditId.includes("browser") ||
        ref.auditId.includes("vendor") ||
        ref.auditId.includes("js-lib")
      ) {
        category = "browser-compat";
      }
  
      // Count issues by category
      categories[category].issues_count++;
  
      // Create issue object
      const issue: AIBestPracticesIssue = {
        id: ref.auditId,
        title: ref.title,
        impact,
        category,
        score: ref.score,
        details: [],
      };
  
      // Extract details if available
      const refDetails = ref.details as BestPracticesAuditDetails | undefined;
      if (refDetails?.items && Array.isArray(refDetails.items)) {
        const itemLimit = DETAIL_LIMITS[impact];
        const detailItems = refDetails.items.slice(0, itemLimit);
  
        detailItems.forEach((item: Record<string, unknown>) => {
          issue.details = issue.details || [];
  
          // Different audits have different detail structures
          const detail: Record<string, string> = {};
  
          if (typeof item.name === "string") detail.name = item.name;
          if (typeof item.version === "string") detail.version = item.version;
          if (typeof item.issue === "string") detail.issue = item.issue;
          if (item.value !== undefined) detail.value = String(item.value);
  
          // For JS libraries, extract name and version
          if (
            ref.auditId === "js-libraries" &&
            typeof item.name === "string" &&
            typeof item.version === "string"
          ) {
            detail.name = item.name;
            detail.version = item.version;
          }
  
          // Add other generic properties that might exist
          for (const [key, value] of Object.entries(item)) {
            if (!detail[key] && typeof value === "string") {
              detail[key] = value;
            }
          }
  
          issue.details.push(detail as any);
        });
      }
  
      issues.push(issue);
    });
  
    // Calculate category scores (0-100)
    Object.keys(categories).forEach((category) => {
      // Simplified scoring: if there are issues in this category, score is reduced proportionally
      const issueCount = categories[category].issues_count;
      if (issueCount > 0) {
        // More issues = lower score, max penalty of 25 points per issue
        const penalty = Math.min(100, issueCount * 25);
        categories[category].score = Math.max(0, 100 - penalty);
      } else {
        categories[category].score = 100;
      }
    });
  
    // Generate prioritized recommendations
    const prioritized_recommendations: string[] = [];
  
    // Prioritize recommendations by category with most issues
    Object.entries(categories)
      .filter(([_, data]) => data.issues_count > 0)
      .sort(([_, a], [__, b]) => b.issues_count - a.issues_count)
      .forEach(([category, data]) => {
        let recommendation = "";
  
        switch (category) {
          case "security":
            recommendation = `Address ${data.issues_count} security issues: vulnerabilities, CSP, deprecations`;
            break;
          case "trust":
            recommendation = `Fix ${data.issues_count} trust & legitimacy issues: doctype, charset`;
            break;
          case "user-experience":
            recommendation = `Improve ${data.issues_count} user experience issues: console errors, user interactions`;
            break;
          case "browser-compat":
            recommendation = `Resolve ${data.issues_count} browser compatibility issues: outdated libraries, vendor prefixes`;
            break;
          default:
            recommendation = `Fix ${data.issues_count} other best practice issues`;
        }
  
        prioritized_recommendations.push(recommendation);
      });
  
    // Return the optimized report
    return {
      metadata,
      report: {
        score: categoryData?.score ? Math.round(categoryData.score * 100) : 0,
        audit_counts: {
          failed: failedCount,
          passed: passedCount,
          manual: manualCount,
          informative: informativeCount,
          not_applicable: notApplicableCount,
        },
        issues,
        categories,
        prioritized_recommendations,
      },
    };
  };

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

  Core helper function that runs the actual Lighthouse audit using a dedicated headless browser instance.

  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)
        }`
      );
    }
  }