lighthouse-mcp 0.1.1

package/README.md

@@ -0,0 +1,145 @@
+# Lighthouse MCP Server
+
+An MCP server that wraps around Google's Lighthouse tool to help measure various performance metrics for web pages.
+
+## Features
+
+- Run comprehensive Lighthouse audits on any URL
+- Get performance scores and metrics
+- Configure device emulation (mobile/desktop)
+- Control network throttling
+- Select specific audit categories
+
+## Installation
+
+### Option 1: Using npx (Recommended)
+
+You can run the tool directly using npx without installation:
+
+```bash
+npx lighthouse-mcp
+```
+
+### Option 2: Global Installation
+
+Install the package globally:
+
+```bash
+npm install -g lighthouse-mcp
+```
+
+Then run it:
+
+```bash
+lighthouse-mcp
+```
+
+### Option 3: Local Development
+
+1. Clone this repository
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+3. Build the project:
+   ```bash
+   npm run build
+   ```
+4. Run the server:
+   ```bash
+   npm start
+   ```
+
+## MCP Configuration
+
+### When installed via npm (global or npx)
+
+Add the following to your MCP settings configuration file:
+
+```json
+{
+  "mcpServers": {
+    "lighthouse": {
+      "command": "npx",
+      "args": ["lighthouse-mcp"],
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}
+```
+
+### When using local development version
+
+Add the following to your MCP settings configuration file:
+
+```json
+{
+  "mcpServers": {
+    "lighthouse": {
+      "command": "node",
+      "args": ["/absolute/path/to/lighthouse-mcp/build/index.js"],
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}
+```
+
+Replace `/absolute/path/to/lighthouse-mcp` with the actual path to this project.
+
+## Available Tools
+
+### run_audit
+
+Run a comprehensive Lighthouse audit on a URL.
+
+**Parameters:**
+- `url` (required): The URL to audit
+- `categories` (optional): Array of categories to audit (defaults to all)
+  - Options: "performance", "accessibility", "best-practices", "seo", "pwa"
+- `device` (optional): Device to emulate (defaults to "mobile")
+  - Options: "mobile", "desktop"
+- `throttling` (optional): Whether to apply network throttling (defaults to true)
+
+**Example:**
+```json
+{
+  "url": "https://example.com",
+  "categories": ["performance", "accessibility"],
+  "device": "desktop",
+  "throttling": false
+}
+```
+
+### get_performance_score
+
+Get just the performance score for a URL.
+
+**Parameters:**
+- `url` (required): The URL to audit
+- `device` (optional): Device to emulate (defaults to "mobile")
+  - Options: "mobile", "desktop"
+
+**Example:**
+```json
+{
+  "url": "https://example.com",
+  "device": "mobile"
+}
+```
+
+## Example Usage
+
+Once the MCP server is configured, you can use it with Claude:
+
+```
+What's the performance score for example.com?
+```
+
+Claude will use the `get_performance_score` tool to analyze the website and return the results.
+
+## Requirements
+
+- Node.js 16+
+- Chrome/Chromium browser (for Lighthouse)

package/build/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/index.js

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
+import lighthouse from 'lighthouse';
+import * as chromeLauncher from 'chrome-launcher';
+const isValidAuditArgs = (args) => {
+    return (typeof args === 'object' &&
+        args !== null &&
+        typeof args.url === 'string' &&
+        (args.categories === undefined ||
+            (Array.isArray(args.categories) &&
+                args.categories.every((cat) => typeof cat === 'string'))) &&
+        (args.device === undefined ||
+            args.device === 'mobile' ||
+            args.device === 'desktop') &&
+        (args.throttling === undefined || typeof args.throttling === 'boolean'));
+};
+class LighthouseServer {
+    constructor() {
+        this.server = new Server({
+            name: 'lighthouse-mcp',
+            version: '0.1.0',
+        }, {
+            capabilities: {
+                tools: {},
+            },
+        });
+        this.setupToolHandlers();
+        // Error handling
+        this.server.onerror = (error) => console.error('[MCP Error]', error);
+        process.on('SIGINT', async () => {
+            await this.server.close();
+            process.exit(0);
+        });
+    }
+    setupToolHandlers() {
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+            tools: [
+                {
+                    name: 'run_audit',
+                    description: 'Run a Lighthouse audit on a URL',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            url: {
+                                type: 'string',
+                                description: 'URL to audit',
+                            },
+                            categories: {
+                                type: 'array',
+                                items: {
+                                    type: 'string',
+                                    enum: [
+                                        'performance',
+                                        'accessibility',
+                                        'best-practices',
+                                        'seo',
+                                        'pwa',
+                                    ],
+                                },
+                                description: 'Categories to audit (defaults to all)',
+                            },
+                            device: {
+                                type: 'string',
+                                enum: ['mobile', 'desktop'],
+                                description: 'Device to emulate (defaults to mobile)',
+                            },
+                            throttling: {
+                                type: 'boolean',
+                                description: 'Whether to apply network throttling (defaults to true)',
+                            },
+                        },
+                        required: ['url'],
+                    },
+                },
+                {
+                    name: 'get_performance_score',
+                    description: 'Get just the performance score for a URL',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            url: {
+                                type: 'string',
+                                description: 'URL to audit',
+                            },
+                            device: {
+                                type: 'string',
+                                enum: ['mobile', 'desktop'],
+                                description: 'Device to emulate (defaults to mobile)',
+                            },
+                        },
+                        required: ['url'],
+                    },
+                },
+            ],
+        }));
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            switch (request.params.name) {
+                case 'run_audit':
+                    return this.handleRunAudit(request.params.arguments);
+                case 'get_performance_score':
+                    return this.handleGetPerformanceScore(request.params.arguments);
+                default:
+                    throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
+            }
+        });
+    }
+    async handleRunAudit(args) {
+        if (!isValidAuditArgs(args)) {
+            throw new McpError(ErrorCode.InvalidParams, 'Invalid audit arguments');
+        }
+        try {
+            const chrome = await chromeLauncher.launch({ chromeFlags: ['--headless'] });
+            const options = {
+                logLevel: 'info',
+                output: 'json',
+                onlyCategories: args.categories,
+                port: chrome.port,
+                formFactor: args.device || 'mobile',
+                screenEmulation: {
+                    mobile: args.device !== 'desktop',
+                    width: args.device === 'desktop' ? 1350 : 360,
+                    height: args.device === 'desktop' ? 940 : 640,
+                    deviceScaleFactor: 1,
+                    disabled: false,
+                },
+                throttling: args.throttling !== false ? {
+                    rttMs: 150,
+                    throughputKbps: 1638.4,
+                    cpuSlowdownMultiplier: 4,
+                } : {
+                    rttMs: 0,
+                    throughputKbps: 10 * 1024,
+                    cpuSlowdownMultiplier: 1,
+                },
+            };
+            const runnerResult = await lighthouse(args.url, options);
+            await chrome.kill();
+            if (!runnerResult) {
+                throw new McpError(ErrorCode.InternalError, 'Failed to run Lighthouse audit');
+            }
+            const { lhr } = runnerResult;
+            // Format the results
+            const formattedResults = {
+                url: lhr.finalDisplayedUrl,
+                fetchTime: lhr.fetchTime,
+                version: lhr.lighthouseVersion,
+                userAgent: lhr.userAgent,
+                scores: {},
+                metrics: {},
+            };
+            // Add category scores
+            const scores = {};
+            for (const [key, category] of Object.entries(lhr.categories)) {
+                scores[key] = {
+                    title: category.title,
+                    score: category.score,
+                    description: category.description,
+                };
+            }
+            formattedResults.scores = scores;
+            // Add key metrics
+            const metrics = {};
+            if (lhr.audits) {
+                const keyMetrics = [
+                    'first-contentful-paint',
+                    'largest-contentful-paint',
+                    'total-blocking-time',
+                    'cumulative-layout-shift',
+                    'speed-index',
+                    'interactive',
+                ];
+                for (const metric of keyMetrics) {
+                    const audit = lhr.audits[metric];
+                    if (audit) {
+                        metrics[metric] = {
+                            title: audit.title,
+                            value: audit.numericValue,
+                            displayValue: audit.displayValue,
+                            score: audit.score,
+                        };
+                    }
+                }
+            }
+            formattedResults.metrics = metrics;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(formattedResults, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            console.error('Lighthouse error:', error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error running Lighthouse audit: ${error.message || error}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+    async handleGetPerformanceScore(args) {
+        if (!isValidAuditArgs(args)) {
+            throw new McpError(ErrorCode.InvalidParams, 'Invalid performance score arguments');
+        }
+        try {
+            // Run a focused performance audit
+            const auditArgs = {
+                url: args.url,
+                categories: ['performance'],
+                device: args.device || 'mobile',
+                throttling: true,
+            };
+            const result = await this.handleRunAudit(auditArgs);
+            // Extract just the performance data
+            const resultData = JSON.parse(result.content[0].text);
+            const performanceData = {
+                url: resultData.url,
+                performanceScore: resultData.scores.performance.score,
+                metrics: resultData.metrics,
+            };
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(performanceData, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            console.error('Performance score error:', error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error getting performance score: ${error.message || error}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+    async run() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        console.error('Lighthouse MCP server running on stdio');
+    }
+}
+const server = new LighthouseServer();
+server.run().catch(console.error);

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "lighthouse-mcp",
+  "version": "0.1.1",
+  "description": "MCP server for Google Lighthouse performance metrics",
+  "type": "module",
+  "main": "build/index.js",
+  "bin": {
+    "lighthouse-mcp": "./build/index.js"
+  },
+  "files": [
+    "build",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x build/index.js",
+    "start": "node build/index.js",
+    "dev": "tsc -w",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "lighthouse",
+    "performance",
+    "mcp",
+    "audit",
+    "web",
+    "metrics",
+    "claude"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "latest",
+    "lighthouse": "^11.0.0",
+    "chrome-launcher": "^0.15.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.4.5",
+    "typescript": "^5.1.6"
+  }
+}