# 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