check_performance_budget
Audit website performance against predefined thresholds for metrics like FCP, LCP, TBT, CLS, and Speed Index to ensure compliance with performance budgets.
Instructions
Check if website performance meets specified budget thresholds
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| budget | Yes | ||
| device | No | Device to emulate (default: desktop) | desktop |
| url | Yes | URL to audit |
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 }), }; }