README.md•11.7 kB
# Lighthouse MCP (Model Context Protocol)
[](https://github.com/mizchi/lighthouse-mcp/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
A comprehensive web application performance analysis toolset integrating Google Lighthouse with Model Context Protocol (MCP), providing structured analysis capabilities accessible to AI assistants and automation tools.
## 📋 Overview
This project provides Google Lighthouse's powerful analysis capabilities through MCP (Model Context Protocol), enabling AI assistants to automatically detect, diagnose, and suggest improvements for website performance issues.
### Key Features
- **🏗️ Three-Layer Architecture**: Clear separation of concerns with Collection (L1) → Analysis (L2) → Intelligence (L3)
- **📊 Comprehensive Performance Analysis**: Detailed analysis of all metrics including Core Web Vitals
- **🎯 Advanced Problem Detection**: Automatic identification and prioritization of performance issues
- **💰 Performance Budget Management**: Target tracking and violation detection
- **🔍 Pattern Recognition**: Identification of common issues across multiple sites
- **🤖 MCP Integration**: Standardized interface for AI assistants and automation tools
- **✅ Complete Test Coverage**: Quality assurance through unit, integration, and E2E tests
## 🚀 Quick Start
### Installation
```bash
# Global installation
npm install -g lighthouse-mcp
# Project installation
npm install lighthouse-mcp
# Development setup (pnpm recommended)
git clone https://github.com/mizchi/lighthouse-mcp.git
cd lighthouse-mcp
pnpm install
```
### Basic Usage
```bash
# Analyze a website
lhmcp https://example.com
# Start as MCP server
lhmcp --mcp
# Detailed analysis (critical chains + unused code)
lhmcp https://example.com --chains --unused --device desktop
```
## 🏗️ Architecture
### Three-Layer Design
```
┌─────────────────────────────────────────┐
│ L3 - Intelligence Layer │
│ (AI insights, strategy, recommendations)│
└─────────────────────────────────────────┘
↑
┌─────────────────────────────────────────┐
│ L2 - Analysis Layer │
│ (Quantitative analysis, pattern detection)│
└─────────────────────────────────────────┘
↑
┌─────────────────────────────────────────┐
│ L1 - Collection Layer │
│ (Lighthouse execution, data collection) │
└─────────────────────────────────────────┘
```
#### L1 - Collection Layer
Foundation layer that directly executes Lighthouse and collects raw data:
- **`l1_collect_single`**: Execute Lighthouse analysis on a single URL
- **`l1_collect_multi`**: Parallel analysis of multiple URLs
- **`l1_collect_comparative`**: Collect data for comparative analysis
- **`l1_get_report`**: Retrieve saved reports
- **`l1_list_reports`**: List available reports
#### L2 - Analysis Layer
Analyzes collected data and provides structured insights:
- **`l2_deep_analysis`**: Comprehensive performance problem detection
- **`l2_critical_chain`**: Critical request chain analysis
- **`l2_critical_chain_report`**: Detailed critical chain report generation
- **`l2_unused_code`**: Detect and quantify unused JavaScript/CSS
- **`l2_third_party_impact`**: Measure third-party script impact
- **`l2_progressive_third_party`**: Progressive third-party blocking analysis
- **`l2_lcp_chain_analysis`**: LCP element critical path analysis
- **`l2_score_analysis`**: Systematic score and improvement analysis
- **`l2_weighted_issues`**: Priority ranking through weighted analysis
- **`l2_patterns`**: Performance pattern detection
#### L3 - Intelligence Layer
Provides advanced interpretation and strategic recommendations:
- **`l3_action_plan_generator`**: Generate actionable improvement plans
- **`l3_performance_budget`**: Performance budget management and violation detection
- **`l3_pattern_insights`**: Pattern insights from multiple analysis results
## 🔧 Available Tools
### Primary Analysis Tools
| Tool Name | Detectable Issues | Primary Use Case |
|-----------|------------------|------------------|
| `l2_deep_analysis` | LCP delays, CLS issues, TBT increase, unused resources | Comprehensive problem diagnosis |
| `l2_critical_chain` | Render-blocking resources, request chains | Load order optimization |
| `l2_unused_code` | Unused CSS/JS, dead code | Bundle size reduction |
| `l2_third_party_impact` | Third-party impact, ad/analytics load | External dependency optimization |
| `l2_lcp_chain_analysis` | LCP bottlenecks, image optimization opportunities | LCP improvement strategy |
| `l3_action_plan_generator` | Prioritized actions, implementation guide | Improvement planning |
### Problem Detection Capabilities
This toolset can automatically detect:
- **Core Web Vitals**
- LCP > 4s delay detection and root cause analysis
- CLS > 0.25 visual instability
- FID/INP > 300ms responsiveness issues
- **Resource Optimization**
- Unused CSS/JavaScript (up to 90% reduction possible)
- Render-blocking resources
- Inefficient caching strategies
- **Third-Party Impact**
- Google Analytics, Facebook SDK impact measurement
- Ad network load analysis
- Progressive blocking impact assessment
## 💻 Programmatic Usage
### TypeScript/JavaScript
```typescript
import {
executeL1Collect,
executeL2DeepAnalysis,
executeL3ActionPlanGenerator
} from 'lighthouse-mcp';
// 1. Data collection
const collectResult = await executeL1Collect({
url: 'https://example.com',
device: 'mobile',
categories: ['performance']
});
// 2. Deep analysis
const analysis = await executeL2DeepAnalysis({
reportId: collectResult.reportId,
includeChains: true,
includeUnusedCode: true
});
// 3. Generate action plan
const actionPlan = await executeL3ActionPlanGenerator({
reportId: collectResult.reportId,
includeTools: ['deep', 'unused', 'weighted']
});
console.log('Detected issues:', analysis.analysis.problems);
console.log('Recommended actions:', actionPlan.actionPlan);
```
### MCP Usage
```javascript
// Call tools from MCP client
const result = await client.callTool('l2_deep_analysis', {
url: 'https://example.com',
includeChains: true
});
```
## 🧪 Testing
The project includes a comprehensive test suite:
```bash
# Run all tests
pnpm test
# Unit tests only
pnpm test:unit
# Integration tests only
pnpm test:integration
# E2E tests (actual Lighthouse execution)
pnpm test:e2e
# With coverage report
pnpm test:coverage
```
### Test Fixtures
HTML files in `test/fixtures/problem-cases/` reproduce actual problems:
- `slow-lcp.html` - LCP delay detection test
- `high-cls.html` - CLS problem detection test
- `third-party-heavy.html` - Third-party impact test
- `unused-code-heavy.html` - Unused code detection test
- `cpu-intensive-dom-css.html` - High CPU load DOM/CSS test
## 🔄 CI/CD
Automated CI/CD pipeline with GitHub Actions:
```yaml
# .github/workflows/ci.yml
- Lint: Code quality checks
- TypeCheck: Type safety verification
- Test: Compatibility testing on Node.js 18/20/22
- Build: Production build
- Integration: Integration tests
- Lighthouse Test: Actual Lighthouse execution tests
```
## 📁 Project Structure
```
lighthouse-mcp/
├── src/
│ ├── analyzers/ # Analysis modules
│ │ ├── criticalChain.ts # Critical chain analysis
│ │ ├── unusedCode.ts # Unused code detection
│ │ ├── thirdParty.ts # Third-party impact analysis
│ │ ├── deepAnalysis.ts # Comprehensive analysis
│ │ └── ...
│ ├── core/ # Core functionality
│ │ ├── lighthouse.ts # Lighthouse execution
│ │ ├── browserPool.ts # Browser management
│ │ ├── database.ts # SQLite storage
│ │ └── metrics.ts # Metrics extraction
│ ├── tools/ # MCP tool implementations
│ │ ├── l1-*.ts # L1: Collection layer
│ │ ├── l2-*.ts # L2: Analysis layer
│ │ ├── l3-*.ts # L3: Intelligence layer
│ │ └── utils/ # Utilities
│ ├── types/ # TypeScript type definitions
│ └── cli.ts # CLI entry point
├── test/ # Test files
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests
│ ├── e2e/ # E2E tests
│ └── fixtures/ # Test data
├── docs/ # Documentation
├── .github/workflows/ # CI/CD configuration
└── CLAUDE.md # Architecture guide
```
## 📚 Documentation
- [Analysis Capabilities](./docs/analysis-capabilities.md) - Detailed analysis capabilities of each tool
- [Problem-Tool Matrix](./docs/problem-tool-matrix.md) - Guide for selecting appropriate tools by problem
- [Tool Layers](./docs/tool-layers.md) - Detailed L1/L2/L3 architecture
- [MCP Tools Catalog](./docs/MCP-TOOLS-CATALOG.md) - Complete tool catalog
- [CLAUDE.md](./CLAUDE.md) - Developer architecture guide
## 🛠️ Development
### Setup
```bash
# Clone repository
git clone https://github.com/mizchi/lighthouse-mcp.git
cd lighthouse-mcp
# Install dependencies (pnpm recommended)
pnpm install
# Build
pnpm build
# Start development server
pnpm dev
```
### Development Commands
```bash
# TypeScript compilation
pnpm typecheck
# Run linter
pnpm lint
# Watch mode for tests
pnpm test:watch
# CLI development execution
pnpm cli -- https://example.com
```
## 🔑 Environment Variables
```bash
# Optional: Custom user data directory
LIGHTHOUSE_USER_DATA_DIR=.lhdata/custom
# Optional: Debug mode
DEBUG=lighthouse:*
# CI environment flag
CI=true
```
## 📈 Performance Improvement Results
Typical improvements achieved using this toolset:
- **LCP Improvement**: 8.5s → 2.1s (75% reduction)
- **Unused Code Reduction**: 840KB → 120KB (85% reduction)
- **Third-Party Impact**: TBT 1200ms → 300ms (75% reduction)
- **Performance Score**: 35 → 92 points
## 🤝 Contributing
Pull requests are welcome! Please follow these guidelines:
1. Create an issue to propose features or fixes
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Add tests (maintain 90%+ coverage)
4. Pass type checking and linting (`pnpm typecheck && pnpm lint`)
5. Create a pull request
## 📄 License
MIT License - See [LICENSE](LICENSE) file for details
## 👥 Author
- mizchi ([@mizchi](https://github.com/mizchi))
## 🙏 Acknowledgments
- Google Lighthouse Team
- Puppeteer Developers
- MCP (Model Context Protocol) Specification Contributors
- All Contributors
---
**Note**: This project is actively under development. Features and APIs may change.