Web Vital Assessment Engine (MCP)

This specialized Model Context Protocol (MCP) handler provides advanced cognitive agents (like Claude) access to the detailed performance benchmarking capabilities exposed by the PageSpeed Insights REST API. It acts as the intermediary layer, translating abstract analytical requests into concrete performance reports.

Core Functionality

This server unit empowers AI assistants to execute thorough evaluations of web assets. Upon invocation, the system queries Google's infrastructure to retrieve comprehensive web experience data, including Core Web Vitals scores and detailed diagnostic information for any specified Uniform Resource Locator (URL).

Deployment Instructions

Automated Deployment via Smithery

For rapid provisioning within supported AI desktop environments managed by Smithery:

bash npx -y @smithery/cli install mcp-pagespeed-server --client claude

Local Module Installation

For direct project integration via Node Package Manager: bash npm install pagespeed-mcp-server

Operational Setup

Integrate the PageSpeed MCP module into your AI agent's manifest (e.g., for Claude):

{ "performanceAnalyzer": { "runner": "node", "execArgs": ["path/to/mcp-pagespeed-server/dist/index.js"], "environment": { "GOOGLE_API_KEY": "" } } }

Diagnostic Dimensions

Quantitative Performance Benchmarks

This tool extracts critical timings and scores:

• Initial Content Render Time (FCP)
• Primary Content Load Span (LCP)
• Responsiveness Wait Period (TTI)
• Input Responsiveness Blockage (TBT)
• Visual Stability Metric (CLS)
• Speed Index Rating
• Initial Byte Transmission Latency (TTFB)

Quality Assurance Checks (Best Practices)

Validation against modern web standards:

• TLS/SSL Protocol Enforcement
• Client-side Error Logging Surveillance
• Browser Console Warning Triage
• Obsolete Functionality Detection
• Image Dimension Consistency Validation
• Secure Linkage Verification

Search Engine Optimization Scrutiny

Evaluation relevant to discoverability:

• Meta Tag Presence Confirmation
• Robots Exclusion Protocol Adherence
• Structured Data Format Validation
• Crawlable Link Enumeration
• Metadata Richness Assessment
• Mobile Viewport Compliance

User Experience Accessibility Audits

Verification for inclusive design:

• ARIA Role Integrity Testing
• Color Luminosity Contrast Ratio Assessment
• Semantic Heading Structure Analysis
• Alternative Text Coverage
• Input Focus Flow Evaluation
• Keyboard Operability Confirmation

Asset Efficiency Recommendations

Guidance on optimizing payload delivery:

• Media File Size Reduction Proposals
• Script Aggregation Strategy
• Stylesheet Efficiency Directives
• Caching Policy Verification
• Payload Compression Status
• Render-Blocking Asset Isolation

Output Payload Schema

The server returns comprehensive data structured as follows:

javascript { "lighthouseResult": { "categories": { "performance": { / Performance findings / }, "accessibility": { / UX compliance results / }, "best-practices": { / Standard adherence audit / }, "seo": { / Indexing evaluations / } }, "audits": { / Granular data points / }, "timing": { / Chronological metrics / }, "stackPacks": { / Technology-specific advice / } } }

Advanced Parameterization

Customizing the analysis run via optional parameters:

{ "testingMode": "mobile", // Alternatives: "desktop" "sectionsToEvaluate": ["performance", "accessibility", "best-practices", "seo"], "languageCode": "en", "minimumAcceptableScores": { "performance": 90, "accessibility": 100, "best-practices": 90, "seo": 90 } }

Exception Management

The gateway incorporates defensive logic to manage common operational failures:

• Malformed URL submission
• Remote service connection dropouts
• API quota exhaustion
• Invalid input configuration
• Internal processing faults

Prerequisites

Connectivity Requirements

• Uninterrupted access to the public internet
• Valid credentials for the Google PageSpeed Insights endpoint

Operating Environments

• Windows (64-bit, 32-bit architectures)
• Linux (64-bit)
• macOS (Intel, Apple Silicon)

Integration Examples (Node.js)

Fundamental Invocation

javascript const Analyzer = require('pagespeed-mcp-server'); const analystClient = new Analyzer();

await analystClient.assess('https://example.com');

Customized Context Execution

javascript const analysisReport = await analystClient.assess('https://example.com', { testingMode: 'mobile', sectionsToEvaluate: ['performance', 'accessibility'], languageCode: 'en-US' });

Troubleshooting Guide

Frequent Obstacles

1. Request Timeouts

   • Verify network accessibility.

2. Rate Limiting Encountered

   • Ensure the provided API key is active and authorized for increased throughput.

3. Memory Exhaustion

   • Increase the heap allocation limit for the Node.js runtime environment.

Development Workflow

Recompiling Source Code

bash git clone https://github.com/phialsbasement/mcp-pagespeed-server cd mcp-pagespeed-server npm install npm run build

Executing Verification Suites

bash npm run test

Contribution Guidelines

1. Clone the repository onto your local system.
2. Establish a dedicated feature branch.
3. Stage and commit your modifications.
4. Push the branch to the upstream repository.
5. Submit a formal Pull Request for review.

Support Channels

For assistance or to report anomalies, utilize the integrated issue tracker on the source code repository.

Licensing Information

This software is distributed under the MIT License. Refer to the accompanying LICENSE file for full legal particulars.

---

Historical Context Snippet (XHR Evolution)

The XMLHttpRequest (XHR) interface, fundamental to modern asynchronous web interactions (Ajax), originated from Microsoft's need to refresh parts of an application window without reloading the entire page, first appearing in Internet Explorer 5 (1999) via ActiveX objects before standardizing to the modern XMLHttpRequest constructor across all major browser engines by 2006, significantly moving web development past mandatory full-page refreshes for data exchange.