Webby MCP Server

Instructions

Implementation Reference

• src/performance/webpagetest.ts:216-260 (handler)

  Primary handler function that executes the WebPageTest tool logic: submits test via Playwright automation, optionally waits and extracts performance metrics and grades.

  export async function analyzeWebPageTest(
    url: string,
    options: WebPageTestOptions = {}
  ): Promise<WebPageTestResult> {
    try {
      // Submit test
      const { testId, resultsUrl } = await submitWebPageTest(url, options);
  
      // If not waiting for results, return immediately with test ID
      if (!options.waitForResults) {
        return {
          tool: 'webpagetest',
          success: true,
          url,
          test_id: testId,
          results_url: resultsUrl,
          status: 'pending',
        };
      }
  
      // Wait for results
      const metrics = await waitForWebPageTestResults(testId, options.timeout);
      const grades = await getWebPageTestGrades(testId);
  
      return {
        tool: 'webpagetest',
        success: true,
        url,
        test_id: testId,
        results_url: resultsUrl,
        summary: metrics,
        performance_grade: grades.performance,
        security_grade: grades.security,
        status: 'complete',
      };
    } catch (error) {
      return {
        tool: 'webpagetest',
        success: false,
        url,
        status: 'error',
        error: error instanceof Error ? error.message : String(error),
      };
    }
  }

• index.ts:47-53 (schema)

  Zod input validation schema for the validate_performance_webpagetest tool arguments.

  const WebPageTestArgsSchema = z.object({
    url: z.string().url(),
    location: z.string().optional(),
    runs: z.number().optional(),
    waitForResults: z.boolean().optional(),
    timeout: z.number().optional(),
  });

• index.ts:158-172 (registration)

  MCP tool registration including name, description, and JSON schema for inputs.

  {
    name: 'validate_performance_webpagetest',
    description: 'Analyze website performance using WebPageTest via browser automation. Free 300 tests/month. Returns test ID immediately or waits for full results.',
    inputSchema: {
      type: 'object',
      properties: {
        url: { type: 'string', description: 'The URL to analyze' },
        location: { type: 'string', description: 'Test location (e.g., Dulles:Chrome)' },
        runs: { type: 'number', description: 'Number of test runs (default: 1)' },
        waitForResults: { type: 'boolean', description: 'Wait for test to complete (default: false, returns test ID immediately)' },
        timeout: { type: 'number', description: 'Timeout in milliseconds (default: 300000 = 5 minutes)' },
      },
      required: ['url'],
    },
  },

• index.ts:341-350 (handler)

  Server-side tool dispatcher case that validates arguments and calls the analyzeWebPageTest implementation.

  case 'validate_performance_webpagetest': {
    const validatedArgs = WebPageTestArgsSchema.parse(args);
    const result = await analyzeWebPageTest(validatedArgs.url, {
      location: validatedArgs.location,
      runs: validatedArgs.runs,
      waitForResults: validatedArgs.waitForResults,
      timeout: validatedArgs.timeout,
    });
    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
  }

• src/performance/webpagetest.ts:51-99 (helper)

  Helper function that uses Playwright to submit a performance test to the WebPageTest.org website and extracts the test ID.

  async function submitWebPageTest(
    url: string,
    options: WebPageTestOptions = {}
  ): Promise<{ testId: string; resultsUrl: string }> {
    const browserManager = await getBrowserManager();
    const page = await browserManager.newPage();
  
    try {
      const timeout = options.timeout || 300000; // 5 minutes default
  
      // Navigate to WebPageTest
      await page.goto('https://www.webpagetest.org/', { timeout });
  
      // Enter URL in the test input
      await page.fill('input[name="url"]', url);
  
      // Select location if provided (default is usually Dulles:Chrome)
      if (options.location) {
        await page.selectOption('select[name="location"]', options.location);
      }
  
      // Set number of runs if provided
      if (options.runs) {
        await page.fill('input[name="runs"]', options.runs.toString());
      }
  
      // Submit the test
      await Promise.all([
        page.waitForNavigation({ timeout }),
        page.click('input[type="submit"], button[type="submit"]'),
      ]);
  
      // Wait for redirect to results page
      await page.waitForURL(/.*\/result\/.*/, { timeout });
  
      const resultsUrl = page.url();
      const testIdMatch = resultsUrl.match(/\/result\/([^\/]+)/);
  
      if (!testIdMatch) {
        throw new Error('Could not extract test ID from results URL');
      }
  
      const testId = testIdMatch[1];
  
      return { testId, resultsUrl };
    } finally {
      await page.close();
    }
  }