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