Webby MCP Server

Instructions

Implementation Reference

• src/performance/pagespeed.ts:58-130 (handler)

  Main handler function that calls Google PageSpeed Insights API, processes Lighthouse results, extracts performance scores, Core Web Vitals metrics, and returns structured results.
  export async function analyzePageSpeed( url: string, options: PageSpeedOptions = {} ): Promise<PageSpeedResult> { try { const strategy = options.strategy || 'mobile'; const categories = options.categories || ['performance', 'accessibility', 'best-practices', 'seo']; // Build API URL const params = new URLSearchParams({ url, strategy, }); // Add categories categories.forEach(cat => params.append('category', cat)); // Add API key if provided if (options.apiKey) { params.set('key', options.apiKey); } const apiUrl = `https://pagespeedonline.googleapis.com/pagespeedonline/v5/runPagespeed?${params.toString()}`; const response = await fetch(apiUrl); if (!response.ok) { throw new Error(`PageSpeed API error: ${response.status} ${response.statusText}`); } const data: PageSpeedResponse = await response.json(); // Extract scores (0-1 range, convert to 0-100) const scores = data.lighthouseResult.categories; const performance_score = scores.performance ? Math.round(scores.performance.score * 100) : undefined; const accessibility_score = scores.accessibility ? Math.round(scores.accessibility.score * 100) : undefined; const best_practices_score = scores['best-practices'] ? Math.round(scores['best-practices'].score * 100) : undefined; const seo_score = scores.seo ? Math.round(scores.seo.score * 100) : undefined; // Extract key metrics (convert to milliseconds) const audits = data.lighthouseResult.audits; const metrics: PageSpeedMetrics = { firstContentfulPaint: audits['first-contentful-paint']?.numericValue, largestContentfulPaint: audits['largest-contentful-paint']?.numericValue, totalBlockingTime: audits['total-blocking-time']?.numericValue, cumulativeLayoutShift: audits['cumulative-layout-shift']?.numericValue, speedIndex: audits['speed-index']?.numericValue, timeToInteractive: audits['interactive']?.numericValue, }; return { tool: 'pagespeed', success: true, url, strategy, performance_score, accessibility_score, best_practices_score, seo_score, metrics, crux_data: !!data.loadingExperience, raw: data, }; } catch (error) { return { tool: 'pagespeed', success: false, url, strategy: options.strategy || 'mobile', error: error instanceof Error ? error.message : String(error), }; } }
• index.ts:131-143 (registration)

  Tool registration in the MCP server, defining name, description, and input schema.
  { name: 'validate_performance_pagespeed', description: 'Analyze website performance using Google PageSpeed Insights. Returns Core Web Vitals and performance scores. Free API with 25K requests/day.', inputSchema: { type: 'object', properties: { url: { type: 'string', description: 'The URL to analyze' }, strategy: { type: 'string', enum: ['mobile', 'desktop'], description: 'Device type (default: mobile)' }, apiKey: { type: 'string', description: 'Optional API key for higher quota' }, }, required: ['url'], }, },
• index.ts:34-38 (schema)

  Zod schema for validating input arguments to the PageSpeed tool.
  const PageSpeedArgsSchema = z.object({ url: z.string().url(), strategy: z.enum(['mobile', 'desktop']).optional(), apiKey: z.string().optional(), });
• index.ts:322-329 (handler)

  MCP server handler case that validates arguments using Zod and delegates to analyzePageSpeed function.
  case 'validate_performance_pagespeed': { const validatedArgs = PageSpeedArgsSchema.parse(args); const result = await analyzePageSpeed(validatedArgs.url, { strategy: validatedArgs.strategy, apiKey: validatedArgs.apiKey, }); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }; }