Lighthouse MCP

Instructions

Implementation Reference

• src/lighthouse-performance.ts:84-136 (handler)

  The core handler function that executes the performance budget check by running a Lighthouse performance audit and comparing metrics against the provided budget thresholds.

  export async function checkPerformanceBudget(
    url: string,
    device: "desktop" | "mobile" = "desktop",
    budget: {
      performanceScore?: number;
      firstContentfulPaint?: number;
      largestContentfulPaint?: number;
      totalBlockingTime?: number;
      cumulativeLayoutShift?: number;
      speedIndex?: number;
    },
  ) {
    const result = await runLighthouseAudit(url, ["performance"], device);
  
    const budgetResults = {
      url: result.url,
      device: result.device,
      fetchTime: result.fetchTime,
      results: {} as Record<string, { actual: number; budget: number; passed: boolean; unit: string }>,
      overallPassed: true,
    };
  
    // Check performance score
    if (budget.performanceScore !== undefined) {
      const actual = result.categories.performance?.score || 0;
      const passed = actual >= budget.performanceScore;
      budgetResults.results.performanceScore = {
        actual,
        budget: budget.performanceScore,
        passed,
        unit: "score",
      };
      if (!passed) budgetResults.overallPassed = false;
    }
  
    // Check metrics using constants
    for (const { key, metric, unit } of BUDGET_METRIC_MAPPINGS) {
      const budgetValue = budget[key as keyof typeof budget];
      if (budgetValue !== undefined) {
        const actual = result.metrics[metric]?.value || 0;
        const passed = actual <= budgetValue;
        budgetResults.results[key] = {
          actual,
          budget: budgetValue,
          passed,
          unit,
        };
        if (!passed) budgetResults.overallPassed = false;
      }
    }
  
    return budgetResults;
  }

• src/schemas.ts:67-78 (schema)

  Zod schema defining the input parameters for the check_performance_budget tool: URL, device, and optional budget thresholds for various performance metrics.

  export const performanceBudgetSchema = {
    url: baseSchemas.url,
    device: baseSchemas.device,
    budget: z.object({
      performanceScore: baseSchemas.threshold,
      firstContentfulPaint: z.number().min(0).optional().describe("FCP budget in milliseconds"),
      largestContentfulPaint: z.number().min(0).optional().describe("LCP budget in milliseconds"),
      totalBlockingTime: z.number().min(0).optional().describe("TBT budget in milliseconds"),
      cumulativeLayoutShift: z.number().min(0).optional().describe("CLS budget"),
      speedIndex: z.number().min(0).optional().describe("Speed Index budget in milliseconds"),
    }),
  };

• src/tools/performance.ts:233-303 (registration)

  Registers the check_performance_budget tool with the MCP server, providing the schema, description, and a wrapper async handler that calls the core checkPerformanceBudget function and formats the response.

  server.tool(
    "check_performance_budget",
    "Check if website performance meets specified budget thresholds",
    performanceBudgetSchema,
    async ({ url, device, budget }) => {
      try {
        const result = await checkPerformanceBudget(url, device, budget);
  
        const structuredResult = createStructuredPerformance(
          "Performance Budget Check",
          result.url,
          result.device,
          {
            overallPassed: result.overallPassed,
            results: Object.fromEntries(
              Object.entries(result.results).map(([metric, data]) => [
                metric,
                {
                  actual: data.actual,
                  budget: data.budget,
                  unit: data.unit,
                  passed: data.passed,
                  difference:
                    typeof data.actual === "number" && typeof data.budget === "number"
                      ? data.actual - data.budget
                      : null,
                },
              ]),
            ),
            fetchTime: result.fetchTime,
          },
          result.overallPassed
            ? ["Performance budget requirements met"]
            : [
                "Review failing metrics and optimize accordingly",
                "Consider adjusting budget thresholds if realistic",
                "Focus on the metrics with largest budget overruns",
              ],
        );
  
        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify(structuredResult, null, 2),
            },
          ],
        };
      } catch (error: unknown) {
        const errorMessage = error instanceof Error ? error.message : String(error);
        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify(
                {
                  error: "Performance budget check failed",
                  url,
                  device: device || "desktop",
                  message: errorMessage,
                },
                null,
                2,
              ),
            },
          ],
          isError: true,
        };
      }
    },
  );

• src/tools/performance.ts:23-35 (helper)

  Helper function used across performance tools to create a standardized structured response format with summary, data, and recommendations.

  function createStructuredPerformance(
    type: string,
    url: string,
    device: string,
    data: Record<string, unknown>,
    recommendations?: string[],
  ): StructuredResponse {
    return {
      summary: `${type} analysis for ${url} on ${device}`,
      data,
      ...(recommendations && { recommendations }),
    };
  }