Webby MCP Server

Instructions

Implementation Reference

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

  The main handler function `analyzePageSpeed` that performs the Google PageSpeed Insights API call, processes the response, extracts performance metrics and scores, 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:34-38 (schema)

  Zod schema for validating input arguments to the validate_performance_pagespeed tool.

  const PageSpeedArgsSchema = z.object({
    url: z.string().url(),
    strategy: z.enum(['mobile', 'desktop']).optional(),
    apiKey: z.string().optional(),
  });

• index.ts:131-143 (registration)

  Tool registration in the tools array, defining name, description, and input schema for MCP server.

  {
    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:322-329 (registration)

  Dispatch handler in the switch statement that validates arguments and calls the analyzePageSpeed implementation.

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