Skip to main content
Glama
cwv-speed-engine
by 1nc0gn30

CWV Speed Engine

CWV Speed Engine

Zero-dependency Core Web Vitals (LCP, INP, CLS, FCP, TTFB) diagnostic analyzer, HTML asset transformer, W3C Speculation Rules compiler, Long Animation Frames (LoAF) profiler, immutable cache header generator, performance budget simulator, and Model Context Protocol (MCP) server.

Overview

CWV Speed Engine runs purely on the Python 3.8+ standard library (html.parser, urllib, json, http.server) and native browser DOM APIs with zero runtime dependencies. It statically and dynamically evaluates HTML documents and live URLs against Google Core Web Vitals thresholds (LCP <= 2.5s, INP <= 200ms, CLS <= 0.1), rewrites render-blocking markup, and generates edge caching and instant-navigation configurations.

Core capabilities:

  • Core Web Vitals Heuristic & Live Audit: Detects render-blocking scripts and stylesheets, unoptimized hero images missing fetchpriority="high", offscreen media missing loading="lazy", layout-shift sources missing intrinsic width/height, and main-thread Long Animation Frames (LoAF) bottlenecks.

  • Deterministic HTML Speed Transformer: Rewrites raw HTML to defer non-critical scripts, preload LCP candidates, add decoding="async" and loading="lazy" to below-the-fold media, and inline critical CSS.

  • W3C Speculation Rules & 103 Early Hints: Generates <script type="speculationrules"> JSON policies (conservative, balanced, aggressive) and HTTP 103 Early Hints Link headers for zero-latency navigation prerendering.

  • Performance Budget & Throttling Simulator: Audits script (170 KB default), stylesheet (50 KB default), and total payload budgets across simulated mobile/broadband RTT profiles and exports Lighthouse budget.json files.

  • Edge Cache, PWA & OpenGraph Compilers: Synthesizes immutable Cache-Control rules for Netlify, Vercel, Nginx, Next.js, Cloudflare, and Apache alongside W3C manifest.webmanifest, sw.js, and OpenGraph/Twitter Card tags.

Related MCP server: SiteAudit MCP

Architecture

cwv-speed-engine/
├── server.py                             # Standalone loopback workstation entrypoint (127.0.0.1:8128)
├── bin/
│   ├── cwv-speed.js                      # Unified CLI, Web UI, and Electron desktop launcher
│   └── cwv-speed-engine-tui              # Terminal dashboard launcher
├── public/                               # Zero-egress browser Speed Studio workstation
├── src/cwv_speed_engine/
│   ├── analyzer.py                       # LCP, INP, CLS, FCP, TTFB & DOM bottleneck analyzer
│   ├── loaf_analyzer.py                  # Long Animation Frames (LoAF) & INP script attribution
│   ├── transformer.py                    # AST/HTML loading-strategy optimizer
│   ├── speculation_engine.py             # W3C Speculation Rules & 103 Early Hints generator
│   ├── budget_simulator.py               # Payload budget & network latency simulator
│   ├── cache_rules.py                    # Netlify, Vercel, Nginx, Next.js, Cloudflare, Apache rules
│   ├── pwa_builder.py & og_builder.py    # Web manifest, ServiceWorker, and OpenGraph generators
│   ├── diff_engine.py & ci_gate.py       # Before/after score delta and CI/CD exit-code gate
│   ├── mcp_server.py                     # JSON-RPC 2.0 stdio MCP server (8 tools)
│   ├── ui_server.py                      # Threading HTTP REST API & Speed Studio server (:8128)
│   └── cli.py                            # cwv-engine / speed-engine CLI router
└── tests/                                # 175-test pytest verification suite

Quickstart

git clone https://github.com/1nc0gn30/cwv-speed-engine.git
cd cwv-speed-engine
pip install -e .

# Launch the local Speed Studio UI and REST API on 127.0.0.1:8128
python3 server.py --port 8128

Open http://127.0.0.1:8128 in any browser, or serve the client-side bundle directly:

python3 -m http.server 8128 --directory public

CLI & MCP Usage

Installing via pip install -e . registers cwv-engine, speed-engine, and cwv-mcp (and ZothOS v3.4.0 exposes cwv / cwv-speed on $PATH).

# Check status and JSON telemetry
cwv-engine --help
cwv-engine --status
cwv-engine --json

# Audit a live URL or local HTML file and run the CI quality gate
cwv-engine audit https://example.com --device mobile --json
cwv-engine check ./public/index.html --min-score 85 --json

# Transform HTML loading attributes and defer blocking assets
cwv-engine optimize ./public/index.html --inline --json

# Generate W3C Speculation Rules and audit performance budgets
cwv-engine speculation ./public/index.html --aggressiveness balanced --format json
cwv-engine budget ./public/index.html --script-budget 170 --css-budget 50 --json

# Export immutable edge cache configs, PWA bundles, OpenGraph tags, and audit diffs
cwv-engine cache --framework netlify --days 365 --json
cwv-engine pwa --name "NullAI App" --theme-color "#0f172a" --json
cwv-engine og --title "NullAI App" --desc "Core Web Vitals workstation" --json
cwv-engine diff baseline.html optimized.html --json

# Launch the HTTP server on 127.0.0.1:8128
cwv-engine serve --host 127.0.0.1 --port 8128

MCP Server Integration

Start the JSON-RPC 2.0 stdio MCP server or export client configurations for Claude Desktop, Cursor, Cline, or Zed:

cwv-engine mcp
cwv-engine mcp --tools
cwv-engine mcp --config claude

Registered MCP tools (8):

  • cwv_audit_site — Audit a URL or HTML string for LCP, INP, CLS, FCP, and TTFB bottlenecks.

  • cwv_optimize_html — Rewrite HTML with lazy-loading, hero prioritization, and deferred scripts.

  • cwv_generate_cache_config — Generate immutable caching configs for Netlify, Vercel, Nginx, Next.js, Cloudflare, or Apache.

  • cwv_generate_pwa — Compile W3C manifest.webmanifest and offline sw.js.

  • cwv_generate_og_card — Generate OpenGraph and Twitter Card <meta> snippets.

  • cwv_diff_performance — Compare baseline vs. candidate HTML/URL performance scores.

  • cwv_generate_speculation_rules — Generate W3C Speculation Rules and 103 Early Hints headers.

  • cwv_audit_performance_budget — Evaluate asset payload budgets and export Lighthouse budget.json.

REST API Endpoints

Bound by default to http://127.0.0.1:8128:

Method

Endpoint

Description

GET

/health, /api/health, /api/platform

Service health and runtime diagnostics

POST

/api/audit

Run Core Web Vitals diagnostic audit on URL or HTML

POST

/api/optimize, /api/transform

Transform and optimize HTML asset loading strategies

POST

/api/speculation

Generate W3C Speculation Rules and 103 Early Hints

POST

/api/budget

Run performance budget and network throttling simulation

POST

/api/cache, /api/cache/export

Generate edge server Cache-Control configurations

POST

/api/pwa, /api/pwa/generate

Generate web manifest and ServiceWorker assets

POST

/api/og, /api/og/generate

Generate OpenGraph and Twitter Card meta tags

POST

/api/diff, /api/compare

Compare two targets and compute score delta

GET

/api/tools, /api/mcp/config

List MCP tools and export client config JSON

POST

/api/export-zip

Download complete optimization bundle as a ZIP archive

Testing & Verification

# Run the 175-test pytest suite
PYTHONPATH=src python3 -m pytest -q

# Run built-in CLI verification suite
PYTHONPATH=src python3 -m cwv_speed_engine.cli --test

# Secret hygiene verification
gitleaks detect --source . --no-banner --redact

Support

CWV Speed Engine is 100% free and open-access software with zero paywalls or feature gates. Optional community support: Buy Us a Coffee (Stripe) or Solana Tip (GG2eQbVh8ut1BK6j1A2tz7pSySdLpD38BgyEhGcxdXoK).

License

MIT License — Engineered by Neal Frazier Tech (@1nc0gn30) & NullAI Platform.

Available Tools

8 tools
cwv_audit_performance_budgetB

Audit web page assets against Core Web Vitals performance budgets (Scripts, Styles, Fonts, Images), simulate multi-network latency (3G/4G/5G), and generate standard Lighthouse budget.json.

Inputs: html_or_path (required), target_name, custom_budgets.

cwv_audit_siteA

Run a comprehensive Core Web Vitals audit on a live URL or local HTML file, returning 0-100 score, LCP/CLS/INP metrics, and diagnostic findings.

Inputs: target (required), device, min_score.

cwv_diff_performanceA

Compare two performance audits (URLs, files, or audit results) with score deltas and diagnostic comparison.

Inputs: target_a (required), target_b (required).

cwv_generate_cache_configA

Generate immutable caching headers and security configuration files for Netlify, Vercel, Nginx, Next.js, Cloudflare, or Apache.

Inputs: framework (required), html_ttl_seconds, static_asset_ttl_days.

cwv_generate_og_cardA

Generate complete OpenGraph, Twitter Card meta tags, Schema.org JSON-LD, and SVG preview banner.

Inputs: title (required), description (required), url, image, +2 more.

cwv_generate_pwaB

Generate W3C webmanifest, Service Worker (sw.js) caching bundle, and HTML header snippet for Progressive Web App compliance.

Inputs: name (required), start_url, short_name, theme_color, +1 more.

cwv_generate_speculation_rulesC

Generate W3C Speculation Rules () for instant zero-latency prerendering and 103 Early Hints.

Inputs: html_or_urls (required), base_url, aggressiveness.

cwv_optimize_htmlB

Transform and optimize HTML code with automated image dimensions, font preconnects, script deferral, and lazy loading to boost CWV scores.

Inputs: html, file_path, defer_scripts, lazy_load_images, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 8 tools

    Disambiguation4/5

    Each tool targets a distinct action (audit, generate, optimize, diff), but the two audit tools (cwv_audit_site and cwv_audit_performance_budget) share the 'audit' verb and could cause slight confusion, though descriptions clarify their different scopes.

    Naming Consistency5/5

    All tools use a consistent cwv_ prefix and follow a clear verb_noun pattern (e.g., cwv_generate_speculation_rules, cwv_audit_site, cwv_diff_performance). No deviations in style.

    Tool Count5/5

    Eight tools is an ideal count for a focused Core Web Vitals engine, covering auditing, generation, optimization, and comparison without bloat.

    Completeness4/5

    The surface covers key CWV workflows: site/budget audits, generation of caching, PWA, OG, and speculation rules, HTML optimization, and performance diffing. Minor gaps include explicit generation of resource hints like preload/prefetch or critical CSS, but core lifecycle is well-covered.

    Maintenance

    ActivityActive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI models to perform Google Lighthouse website performance analysis, including Core Web Vitals, accessibility, SEO audits, and actionable optimization recommendations. Provides comprehensive web performance insights through natural language interactions.
      4
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to perform instant SEO, performance, and security audits of any website through the Model Context Protocol. It provides comprehensive analysis without requiring API keys or configuration.
      11
      5
      MIT