lighthouse-mcp/README.md

MCP server for Google Lighthouse performance metrics

# Lighthouse MCP Server

An MCP server that wraps around Google's Lighthouse tool to help measure various performance metrics for web pages.

![Lighthouse MCP Server Screenshot](screenshot.png)

## 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: From MCP Registry (Recommended)

This server is available in the [Model Context Protocol Registry](https://registry.modelcontextprotocol.io/servers/io.github.priyankark/lighthouse-mcp). Install it using your MCP client or Claude Desktop.

### Option 2: Using npx

You can run the tool directly using npx without installation:

```bash
npx lighthouse-mcp
```

### Option 3: Global Installation

Install the package globally from npm:

```bash
npm install -g lighthouse-mcp
```

Then run it:

```bash
lighthouse-mcp
```

### Option 4: 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)

## Development & Release

### Prerequisites

Before releasing, ensure you're authenticated with both registries:

**NPM Authentication:**
```bash
npm login
```

**MCP Registry Authentication:**
```bash
mcp-publisher login github
```

If your authentication tokens expire, you'll need to re-login to the respective services.

### Making Releases

Use the interactive release script to publish to both NPM and the MCP Registry:

```bash
./release.sh
```

The script will:
1. Check NPM login status
2. Check for uncommitted changes
3. Run tests (if they exist)
4. Build the project
5. Prompt for version bump type (patch/minor/major/custom)
6. Update both package.json and server.json versions
7. Create a preview of the package contents
8. Publish to NPM
9. Publish to MCP Registry (if mcp-publisher is available)
10. Create git commit and tag
11. Optionally push to remote repository

This ensures consistent releases to both registries with proper version synchronization.