ruslanlap · engmsaleh · Oct 18, 2025 · Oct 18, 2025 · Oct 18, 2025
diff --git a/README.md b/README.md
@@ -8,6 +8,7 @@ MCP server for Google PageSpeed Insights API that enables web page performance a
 
 ## ✨ Features
 
+### Core Features
 - 🚀 **Performance Analysis** of web pages using Google PageSpeed Insights
 - 📱 **Multi-platform Support**: mobile and desktop devices
 - 🔍 **Detailed Lighthouse Reports** with comprehensive metrics
@@ -18,6 +19,16 @@ MCP server for Google PageSpeed Insights API that enables web page performance a
 - ⚡ **Quick Installation** - one command setup
 - 🐳 **Docker Support** for containerized deployment
 
+### Advanced Analysis Tools (New!)
+- 📸 **Visual Analysis** - Screenshots, filmstrip, and full-page captures
+- 🎯 **Element-Level Debugging** - Find specific DOM elements causing issues
+- 🌐 **Network Waterfall** - Detailed request timing and resource loading
+- ⚡ **JavaScript Profiling** - Execution breakdown and unused code detection
+- 🖼️ **Image Optimization** - Specific image issues with exact savings
+- 🚫 **Render-Blocking Analysis** - Critical request chains and dependencies
+- 🔌 **Third-Party Impact** - Script impact grouped by provider
+- 📊 **Full Audits** - Complete Lighthouse audits for all categories
+
 ## 🚀 Quick Installation
 
 ### Option 1: Automatic Installation (Recommended)
@@ -212,6 +223,46 @@ Get smart recommendations for improving https://example.com performance
 Clear the cache to get fresh data for all subsequent requests
 ```
 
+### 📸 Visual analysis
+```
+Get visual analysis for https://example.com showing screenshots and loading timeline
+```
+
+### 🎯 Element-level debugging
+```
+Show me which specific elements are causing performance issues on https://example.com
+```
+
+### 🌐 Network waterfall analysis
+```
+Analyze the network requests and resource loading for https://example.com
+```
+
+### ⚡ JavaScript performance
+```
+Get JavaScript execution breakdown for https://example.com
+```
+
+### 🖼️ Image optimization opportunities
+```
+Show me which images need optimization on https://example.com
+```
+
+### 🚫 Render-blocking resources
+```
+Find render-blocking resources on https://example.com
+```
+
+### 🔌 Third-party script impact
+```
+Analyze third-party script impact on https://example.com performance
+```
+
+### 📊 Full Lighthouse audit
+```
+Run a full audit including accessibility, SEO, and best practices for https://example.com
+```
+
 ## Available Tools
 
 ### `analyze_page_speed`
@@ -242,6 +293,115 @@ Generate smart performance recommendations with priority scoring and actionable
 
 Clear the internal cache to force fresh API requests for all subsequent analyses.
 
+### `get_visual_analysis`
+
+Get screenshots and visual timeline showing how the page loads.
+
+**Parameters:**
+- `url` (required): URL of the page to analyze
+- `strategy`: "mobile" or "desktop" (default: "mobile")
+
+**Returns:**
+- Final screenshot of the loaded page
+- Filmstrip showing page load progression
+- Full-page screenshot with DOM node mapping
+
+### `get_element_analysis`
+
+Get specific DOM elements causing performance issues.
+
+**Parameters:**
+- `url` (required): URL of the page to analyze
+- `strategy`: "mobile" or "desktop" (default: "mobile")
+
+**Returns:**
+- LCP (Largest Contentful Paint) element details
+- CLS (Cumulative Layout Shift) causing elements
+- Lazy-loaded LCP warnings
+
+### `get_network_analysis`
+
+Get detailed network waterfall showing all requests with timing and size.
+
+**Parameters:**
+- `url` (required): URL of the page to analyze
+- `strategy`: "mobile" or "desktop" (default: "mobile")
+
+**Returns:**
+- All network requests with timing data
+- Resource breakdown by type
+- Total transfer size and request count
+- Network RTT and server latency
+
+### `get_javascript_analysis`
+
+Get JavaScript execution breakdown showing performance impact.
+
+**Parameters:**
+- `url` (required): URL of the page to analyze
+- `strategy`: "mobile" or "desktop" (default: "mobile")
+
+**Returns:**
+- JavaScript bootup time by script
+- Main thread work breakdown
+- Unused JavaScript analysis
+- Duplicated JavaScript modules
+
+### `get_image_optimization_details`
+
+Get specific images needing optimization with exact savings potential.
+
+**Parameters:**
+- `url` (required): URL of the page to analyze
+- `strategy`: "mobile" or "desktop" (default: "mobile")
+
+**Returns:**
+- Improperly sized images
+- Offscreen images (lazy-loading candidates)
+- Unoptimized images
+- Modern format recommendations (WebP/AVIF)
+
+### `get_render_blocking_details`
+
+Get render-blocking resources and critical request chains.
+
+**Parameters:**
+- `url` (required): URL of the page to analyze
+- `strategy`: "mobile" or "desktop" (default: "mobile")
+
+**Returns:**
+- Render-blocking CSS and JavaScript files
+- Critical request chains showing dependencies
+- Total blocking time
+
+### `get_third_party_impact`
+
+Get third-party script impact analysis grouped by entity.
+
+**Parameters:**
+- `url` (required): URL of the page to analyze
+- `strategy`: "mobile" or "desktop" (default: "mobile")
+
+**Returns:**
+- Impact by provider (Google, Facebook, etc.)
+- Transfer size and blocking time per provider
+- Recommended facade replacements
+
+### `get_full_audit`
+
+Get comprehensive audit results for all Lighthouse categories.
+
+**Parameters:**
+- `url` (required): URL of the page to analyze
+- `strategy`: "mobile" or "desktop" (default: "mobile")
+- `categories`: array of categories to audit (default: ["performance", "accessibility", "best-practices", "seo"])
+
+**Returns:**
+- Scores for all categories
+- Detailed Core Web Vitals and metrics
+- Key failing audits for each category
+- Framework-specific advice (if applicable)
+
 
 ### Example
 answer example from Claude Desktop with pagespeed-insights-mcp 🔥🔥🔥

diff --git a/TESTING.md b/TESTING.md
@@ -0,0 +1,180 @@
+# Testing Guide for PageSpeed Insights MCP
+
+This guide explains how to test all the features of the PageSpeed Insights MCP server.
+
+## Prerequisites
+
+1. Build the project first:
+   ```bash
+   npm run build
+   ```
+
+2. Get a Google API Key:
+   - Go to [Google Cloud Console](https://console.cloud.google.com/)
+   - Enable PageSpeed Insights API
+   - Create an API key
+
+## Testing Methods
+
+### Method 1: Automated Test Script (Recommended)
+
+Run the automated test script that tests all tools:
+
+```bash
+# Pass API key as argument
+node test-tools.js YOUR_GOOGLE_API_KEY
+
+# Or use environment variable
+export GOOGLE_API_KEY=your-api-key
+node test-tools.js
+```
+
+This script will:
+- Start the MCP server
+- Test all 12 tools sequentially
+- Show success/failure for each tool
+- Display a summary at the end
+
+Expected output:
+```
+🧪 Testing PageSpeed Insights MCP Tools
+=====================================
+API Key: AIzaSyD7mU...
+✅ Server started successfully
+
+Testing analyze_page_speed - Complete PageSpeed analysis...
+✅ analyze_page_speed: SUCCESS
+   - Text content: ✓
+   - JSON resource: ✓
+
+... (tests for all tools) ...
+
+📊 Test Summary
+===============
+✅ Passed: 12/12
+❌ Failed: 0/12
+```
+
+### Method 2: Manual Testing with Claude Desktop
+
+1. Update your Claude Desktop config (`claude_desktop_config.json`):
+   ```json
+   {
+     "mcpServers": {
+       "pagespeed-insights": {
+         "command": "node",
+         "args": ["/path/to/pagespeed-insights-mcp/dist/index.js"],
+         "env": {
+           "GOOGLE_API_KEY": "your-google-api-key"
+         }
+       }
+     }
+   }
+   ```
+
+2. Restart Claude Desktop
+
+3. Test each tool by typing these commands:
+
+#### Original Tools
+- `Analyze the performance of https://www.google.com`
+- `Get a quick performance report for https://www.google.com`
+- `Get smart recommendations for improving https://www.google.com performance`
+- `Clear the cache`
+
+#### New Tools (v1.1.0)
+- `Get visual analysis for https://www.google.com`
+- `Show me which elements are causing performance issues on https://www.google.com`
+- `Analyze the network waterfall for https://www.google.com`
+- `Get JavaScript execution breakdown for https://www.google.com`
+- `Show me which images need optimization on https://www.google.com`
+- `Find render-blocking resources on https://www.google.com`
+- `Analyze third-party script impact on https://www.google.com`
+- `Run a full audit including accessibility and SEO for https://www.google.com`
+
+### Method 3: Direct MCP Testing
+
+Run the manual test helper:
+
+```bash
+./manual-test.sh
+```
+
+This will:
+- Show you a checklist of commands to test
+- Create a test results template
+- Provide guidance on expected results
+
+## What to Look For
+
+### ✅ Success Indicators
+- Tool returns formatted text output
+- JSON resource is attached with detailed data
+- No error messages
+- Response time is reasonable (5-15 seconds)
+
+### ❌ Failure Indicators
+- Error messages in response
+- Timeout (>30 seconds)
+- Missing data in response
+- Server crashes
+
+## Common Issues
+
+1. **API Key Issues**
+   - Error: "The provided API key is invalid"
+   - Solution: Check your API key is correct and has PageSpeed Insights API enabled
+
+2. **Rate Limiting**
+   - Error: "Quota exceeded"
+   - Solution: Wait a few minutes or use a different API key
+
+3. **Network Issues**
+   - Error: "Failed to fetch"
+   - Solution: Check internet connection and firewall settings
+
+## Testing Different URLs
+
+Try testing with various types of websites:
+- Simple: `https://www.example.com`
+- Complex: `https://www.youtube.com`
+- News site: `https://www.cnn.com`
+- E-commerce: `https://www.amazon.com`
+- Your own site
+
+## Debugging
+
+If a test fails, check:
+
+1. Server logs:
+   ```bash
+   npm run dev  # Run in development mode for more logs
+   ```
+
+2. Check the raw API response:
+   - The JSON resource attachment contains the raw data
+   - Look for missing fields or unexpected structure
+
+3. Verify the API is working:
+   ```bash
+   curl "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=https://www.google.com&key=YOUR_API_KEY"
+   ```
+
+## Performance Testing
+
+For performance testing:
+1. Note response times for each tool
+2. Check memory usage during execution
+3. Test with multiple concurrent requests
+
+## Reporting Issues
+
+If you find issues:
+1. Note which tool failed
+2. Copy the error message
+3. Include the test URL used
+4. Check if it's reproducible
+
+---
+
+Happy testing! 🚀