runBestPracticesAudit

Audit web pages to identify and report best practice violations for improved performance, accessibility, and security compliance.

Instructions

Run a best practices audit on the current page

Input Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Implementation Reference

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

Core handler function that executes the Lighthouse best practices audit on the given URL and processes results into AI-optimized format using the helper 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)
      }`
    );
  }
}

/**
 * Extract AI-optimized Best Practices data from Lighthouse results
 */
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-mcp/mcp-server.ts:1350-1425 (registration)

MCP server tool registration for runBestPracticesAudit, which proxies requests to the browser 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/browser-connector.ts:1335-1403 (helper)

Generic helper that sets up audit endpoints like /best-practices-audit, which calls the specific audit function (runBestPracticesAudit). Called specifically at line 1325 for best-practices.

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/best-practices.ts:10-51 (schema)

Type definitions for input/output schema: report content structure, AI-optimized issue format, etc.

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>;

/**
 * AI-optimized Best Practices issue
 */
interface AIBestPracticesIssue {
  id: string; // e.g., "js-libraries"
  title: string; // e.g., "Detected JavaScript libraries"
  impact: "critical" | "serious" | "moderate" | "minor";
  category: string; // e.g., "security", "trust", "user-experience", "browser-compat"
  details?: {
    name?: string; // Name of the item (e.g., library name, vulnerability)
    version?: string; // Version information if applicable
    value?: string; // Current value or status
    issue?: string; // Description of the issue
  }[];
  score: number | null; // 0-1 or null
}

browser-tools-server/browser-connector.ts:1321-1327 (registration)
Server-side registration of the /best-practices-audit endpoint that invokes runBestPracticesAudit.
```
private setupBestPracticesAudit() {
  this.setupAuditEndpoint(
    AuditCategory.BEST_PRACTICES,
    "/best-practices-audit",
    runBestPracticesAudit
  );
}
```

BrowserTools MCP