Webby MCP Server

# Webby - Comprehensive Website Validator MCP Server A Model Context Protocol (MCP) server that provides comprehensive website testing across performance, accessibility, SEO, and security dimensions. ## Features ### 🚀 Performance Testing - **WebPageTest** ✅ - Real browser testing via Playwright automation (300 tests/month free, no API key) - **Google PageSpeed Insights** ✅ - Core Web Vitals and Google ranking signals (25K API calls/day free) - **GTmetrix** ✅ - Lighthouse + custom metrics with historical tracking (requires API key) ### ♿ Accessibility Testing - **Axe DevTools** ✅ - Fast WCAG scans via Playwright + axe-core (free, open-source) - **WAVE** ✅ - WCAG compliance and contrast analysis (requires API key) ### 🔍 SEO Testing - **PageSpeed Insights SEO** ✅ - Uses Lighthouse SEO (free, comprehensive) ### 🔒 Security Testing - **Mozilla Observatory** ✅ - HTTP security headers analysis (CSP, HSTS) - Free API, 1 scan/min - **SSL Labs** ✅ - Comprehensive SSL/TLS certificate testing - Free API (requires email) ## Installation ```bash cd ~/mcp-servers/servers/src/webby npm install npm run build ``` ## MCP Tools (11 Total) ### Performance Tools (3) **`validate_performance_pagespeed`** ```typescript { url: string, strategy?: 'mobile' | 'desktop', // default: mobile apiKey?: string // optional, for higher quota } // Returns: Performance score, Core Web Vitals, metrics ``` **`validate_performance_webpagetest`** ✨ NEW ```typescript { url: string, location?: string, // e.g., 'Dulles:Chrome' runs?: number, // default: 1 waitForResults?: boolean, // default: false (returns test ID immediately) timeout?: number // default: 300000 (5 min) } // Returns: Test ID + results URL immediately OR full results if waitForResults=true // Metrics: Load Time, FCP, LCP, Speed Index, TTI, TBT, CLS, Performance Grade ``` **`validate_performance_gtmetrix`** ```typescript { url: string, apiKey: string, // required location?: string, // e.g., 'vancouver-canada' browser?: string // e.g., 'chrome' } // Returns: Lighthouse score, PageSpeed score, load time, page size ``` ### Accessibility Tools (2) **`validate_accessibility_axe`** ```typescript { url: string, wcagLevel?: string // wcag2a, wcag2aa, wcag2aaa, wcag21aa, wcag22aa } // Returns: Violations by severity (critical, serious, moderate, minor), passes, incomplete ``` **`validate_accessibility_wave`** ```typescript { url: string, apiKey: string, // required reporttype?: 1 | 2 | 3 | 4 // detail level (default: 2) } // Returns: Errors, contrast errors, alerts, WAVE report URL, credits remaining ``` ### Security Tools (2) **`validate_security_mozilla_observatory`** ```typescript { url: string, forceRescan?: boolean // default: false } // Returns: Grade (A+ to F), score, tests passed/failed, details URL ``` **`validate_security_ssl_labs`** ```typescript { url: string, email: string, // required by API maxAge?: number, // cached report age in hours startNew?: boolean, // force new assessment waitForComplete?: boolean, // wait for completion (can take 2-5 min) maxWaitMinutes?: number // default: 5 } // Returns: Grade (A+ to F), endpoint details, protocol info, status ``` ### Category Runners (4) **`validate_all_performance`** ```typescript { url: string, pagespeedApiKey?: string, gtmetrixApiKey?: string, webpagetestEnabled?: boolean, // enable browser automation webpagetestWaitForResults?: boolean // wait for WPT completion } // Returns: Results from PageSpeed + optionally WebPageTest + optionally GTmetrix ``` **`validate_all_accessibility`** ```typescript { url: string, waveApiKey?: string, // optional wcagLevel?: string // for Axe } // Returns: Results from Axe + optionally WAVE ``` **`validate_all_seo`** ```typescript { url: string } // Returns: SEO analysis from PageSpeed Insights (Lighthouse SEO) ``` **`validate_all_security`** ```typescript { url: string, email: string, // for SSL Labs waitForSSL?: boolean // wait for SSL Labs completion } // Returns: Results from Mozilla Observatory + SSL Labs ``` ### Master Runner (1) **`validate_comprehensive`** ```typescript { url: string, email: string, // required for SSL Labs categories?: string[], // ['performance', 'accessibility', 'seo', 'security'] pagespeedApiKey?: string, gtmetrixApiKey?: string, waveApiKey?: string, wcagLevel?: string, waitForSSL?: boolean } // Returns: Complete analysis across all selected categories with overall health score ``` ## Response Format ```json { "tool": "webpagetest", "success": true, "url": "https://example.com", "test_id": "250107_AiDcA4_ABC", "results_url": "https://www.webpagetest.org/result/250107_AiDcA4_ABC/", "status": "complete", "summary": { "loadTime": 2500, "firstContentfulPaint": 1200, "speedIndex": 2300, "largestContentfulPaint": 2100, "timeToInteractive": 3500, "totalBlockingTime": 250, "cumulativeLayoutShift": 0.05 }, "performance_grade": "A", "security_grade": "A+" } ``` ## Implementation Status ### ✅ Fully Implemented (9 tools) - `validate_performance_pagespeed` - Google PageSpeed Insights API - `validate_performance_webpagetest` - Playwright browser automation ✨ - `validate_performance_gtmetrix` - GTmetrix API - `validate_accessibility_axe` - Playwright + axe-core - `validate_accessibility_wave` - WAVE API - `validate_security_mozilla_observatory` - Mozilla Observatory API - `validate_security_ssl_labs` - SSL Labs API with polling - `validate_all_*` - All 4 category orchestrators - `validate_comprehensive` - Master orchestrator ### ✅ All Tools Functional No placeholders - all 11 tools are fully implemented and working! ## API Quotas & Limits | Tool | Free Limit | API Key Required | Implementation | |------|------------|------------------|----------------| | Mozilla Observatory | 1 scan/min per domain | No | ✅ Direct API | | SSL Labs | Unlimited (rate limited) | Email only | ✅ Direct API | | PageSpeed Insights | 25,000/day | Optional (free) | ✅ Direct API | | WebPageTest | 300/month | No | ✅ **Browser automation** | | GTmetrix | Limited credits | Yes (free tier) | ✅ Direct API | | Axe | Unlimited | No | ✅ **Browser automation** | | WAVE | Varies by plan | Yes (paid) | ✅ Direct API | ## Browser Automation WebPageTest and Axe use **Playwright** for headless browser automation: - **Singleton browser instance** - Reused across tests for efficiency - **Configurable timeouts** - Default 5 minutes for WebPageTest, 1 minute for Axe - **Graceful cleanup** - Browser closed on MCP server shutdown - **No API keys needed** - Free access via web UI automation ## Project Structure ``` webby/ ├── src/ │ ├── performance/ │ │ ├── pagespeed.ts ✅ Google API │ │ ├── webpagetest.ts ✅ Playwright automation │ │ └── gtmetrix.ts ✅ GTmetrix API │ ├── accessibility/ │ │ ├── axe.ts ✅ Playwright + axe-core │ │ └── wave.ts ✅ WAVE API │ ├── security/ │ │ ├── mozilla-observatory.ts ✅ Mozilla API │ │ └── ssl-labs.ts ✅ SSL Labs API + polling │ ├── shared/ │ │ └── browser-utils.ts ✅ Playwright utilities │ └── orchestrator/ │ └── run-all.ts ✅ All orchestrators ├── dist/ # Compiled JavaScript ├── index.ts # Main MCP server entry ├── package.json └── README.md ``` ## Usage Examples ### Quick WebPageTest (instant response) ```typescript validate_performance_webpagetest("https://example.com") // Returns test ID immediately, check results later at provided URL ``` ### Complete WebPageTest (wait for results) ```typescript validate_performance_webpagetest("https://example.com", { waitForResults: true, timeout: 300000 // 5 minutes }) // Waits for test completion, returns full metrics ``` ### Run all performance tests ```typescript validate_all_performance("https://example.com", { webpagetestEnabled: true, // Enable browser automation webpagetestWaitForResults: false // Get test ID instantly }) // Returns: PageSpeed + WebPageTest results ``` ### Comprehensive validation ```typescript validate_comprehensive("https://example.com", { email: "your@email.com", // For SSL Labs categories: ["performance", "security"], webpagetestEnabled: true }) // Returns: Full analysis with overall health score ``` ## License MIT