# https://github.com/danielsogl/lighthouse-mcp-server Project Manual

Generated at: 2026-07-06 01:10:07 UTC

## Table of Contents

- [Project Overview & System Architecture](#page-1)
- [Tool Reference: Audit, Performance, Analysis & Security](#page-2)
- [Chrome & Browser Configuration](#page-3)
- [Schemas, Prompts & Reference Resources](#page-4)

<a id='page-1'></a>

## Project Overview & System Architecture

### Related Pages

Related topics: [Tool Reference: Audit, Performance, Analysis & Security](#page-2), [Chrome & Browser Configuration](#page-3), [Schemas, Prompts & Reference Resources](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/index.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/index.ts)
- [src/cli.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/cli.ts)
- [src/types.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/types.ts)
- [src/lighthouse-core.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/lighthouse-core.ts)
- [package.json](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/package.json)
- [README.md](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/README.md)
</details>

# Project Overview & System Architecture

## Purpose and Scope

`lighthouse-mcp-server` is a Model Context Protocol (MCP) server that exposes Google Lighthouse as a set of MCP tools consumable by LLM agents. The server allows an agent to submit a URL and receive structured performance, accessibility, SEO, best-practices, and security audit results. The design philosophy, confirmed by community feedback in [issue #182](https://github.com/danielsogl/lighthouse-mcp-server/issues/182), is that `url` is the only required input across every audit tool; the agent discovers and chooses the remaining parameters (`categories`, `device`, `throttling`, etc.) on its own. Source: [README.md](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/README.md)

The project is distributed as a single npm package (`lighthouse-mcp`) and relies on the official `@modelcontextprotocol/sdk` to register tools and transport JSON-RPC messages to MCP clients (such as Claude Desktop or Cursor). Source: [package.json](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/package.json)

## High-Level Architecture

The runtime is composed of three cooperating layers:

1. **Entry layer** — `src/cli.ts` parses `process.argv`, resolves CLI flags (`--chrome-path`, `--port`, etc.), falls back to environment variables (`CHROME_PATH`), and decides whether to start an `stdio` MCP server or an `http` (SSE) one. The `CHROME_PATH` discovery was added in `lighthouse-mcp v1.5.0`. Source: [src/cli.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/cli.ts)
2. **Protocol layer** — `src/index.ts` boots an `McpServer` instance from `@modelcontextprotocol/sdk`, registers every tool handler, and wires stdio/HTTP transports. Source: [src/index.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/index.ts)
3. **Domain layer** — `src/lighthouse-core.ts` is the only module that talks to `chrome-launcher` and the `lighthouse` programmatic API. It hides browser launching, page loading, audit execution, and result normalization from the rest of the codebase. Source: [src/lighthouse-core.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/lighthouse-core.ts)

```mermaid
flowchart LR
    Agent[LLM Agent / MCP Client] -- JSON-RPC --> Server[src/index.ts<br/>McpServer]
    Server -- registerTool --> Handlers[Tool Handlers]
    Handlers -- url + options --> Core[src/lighthouse-core.ts]
    Core -- launch --> Chrome[chrome-launcher<br/>CHROME_PATH / --chrome-path]
    Core -- audit --> LH[Lighthouse programmatic API]
    LH --> Core
    Core -- normalized result --> Handlers
    Handlers --> Agent
    CLI[src/cli.ts<br/>stdin/argv] --> Server
```

The shared shape of every tool's input/output is declared in `src/types.ts` so that the JSON Schema exposed to the agent stays consistent regardless of which tool is invoked. Source: [src/types.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/types.ts)

## Tool Surface and Request Flow

`src/index.ts` registers 13+ tools, each following the URL-first convention. The most commonly used are:

- `run_audit` — generic Lighthouse run with category selection.
- `get_core_web_vitals` — LCP/CLS/INP focused report.
- `get_security_audit` — CSP, mixed-content, HTTPS checks.

Every handler validates its `inputSchema` (declared in `src/types.ts`), delegates the heavy lifting to `src/lighthouse-core.ts`, and returns a normalized object containing the score, top failing audits, and raw LHR (Lighthouse Result) JSON. Source: [src/index.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/index.ts)

The core wrapper accepts a `LaunchOptions` object (device emulation, throttling, Chrome flags, optional profile directory) added in `lighthouse-mcp v1.3.0` / `v1.4.0` to support authenticated Lighthouse runs. The resolved Chrome executable comes from one of, in priority order: `--chrome-path` CLI flag → `CHROME_PATH` env var → `chrome-launcher`'s default discovery. Source: [src/lighthouse-core.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/lighthouse-core.ts)

## Process, Distribution, and Release Cadence

`package.json` declares the package as `lighthouse-mcp` with a `bin` entry that points at the compiled `cli.js`, so installation via `npm i -g lighthouse-mcp` puts an executable on `PATH`. The server is launched by an MCP client (e.g. Claude Desktop) typically via `npx lighthouse-mcp`. Source: [package.json](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/package.json)

Releases are semver-tagged (`lighthouse-mcp-v1.x.y`) and published to npm with provenance; release tooling is managed in GitHub Actions. Recent history shows a stable cadence centered on SDK upgrades and Chrome handling:

| Version | Date | Notable change |
|---|---|---|
| v1.5.0 | 2026-04-05 | `--chrome-path` flag + `CHROME_PATH` env var |
| v1.4.0 / v1.3.0 | 2025-12-28 | Chrome profile support for authenticated runs |
| v1.2.x | 2025-09 → 2025-12 | Incremental `@modelcontextprotocol/sdk` bumps |

Source: [package.json](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/package.json), [README.md](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/README.md)

## Boundaries and Design Trade-offs

- **Single-process, ephemeral Chrome** — Each tool call spawns a Chrome instance via `chrome-launcher`, tears it down on completion, and returns JSON. There is no persistent browser pool, which keeps the server stateless at the cost of per-call startup latency. Source: [src/lighthouse-core.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/lighthouse-core.ts)
- **URL as the only required input** — Tool schemas in `src/types.ts` mark `url` required and every other parameter optional with sensible defaults, which simplifies agent prompting and reduces invalid call rates reported in [issue #182](https://github.com/danielsogl/lighthouse-mcp-server/issues/182). Source: [src/types.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/types.ts)
- **MCP SDK isolation** — The Lighthouse API never leaks past `src/lighthouse-core.ts`; handlers in `src/index.ts` only consume the normalized result, which makes upgrading either `@modelcontextprotocol/sdk` or `lighthouse` itself a localized change (as evidenced by the frequent SDK bumps in `v1.2.x`). Source: [src/index.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/index.ts)

---

<a id='page-2'></a>

## Tool Reference: Audit, Performance, Analysis & Security

### Related Pages

Related topics: [Project Overview & System Architecture](#page-1), [Schemas, Prompts & Reference Resources](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/tools/index.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/tools/index.ts)
- [src/tools/audit.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/tools/audit.ts)
- [src/tools/performance.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/tools/performance.ts)
- [src/tools/analysis.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/tools/analysis.ts)
- [src/tools/security.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/tools/security.ts)
- [src/lighthouse-analysis.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/lighthouse-analysis.ts)
</details>

# Tool Reference: Audit, Performance, Analysis & Security

## Overview

The lighthouse-mcp-server exposes 13+ Model Context Protocol (MCP) tools that wrap Google Lighthouse and Chrome DevTools into agent-callable primitives. The audit, performance, analysis, and security families share a consistent ergonomic design: a single `url` parameter is the only required input, and all other options (throttling, form factor, categories, Chrome flags) are optional and agent-selectable. Tool registration is centralized in `src/tools/index.ts`, where each family module exports its tool definitions and they are merged into the MCP server's tool list. Source: [src/tools/index.ts:1-120]()

The four families covered on this page map onto Lighthouse's category model:

- **Audit** — general-purpose run of the full Lighthouse suite.
- **Performance** — focused runs that surface Core Web Vitals, resource timing, and runtime metrics.
- **Analysis** — post-processing helpers that interpret a finished Lighthouse result and produce narratives, prioritized recommendations, or comparison deltas.
- **Security** — runs that emphasize the `best-practices` and security-relevant `csp-xss`/`csp` audits, including header and mixed-content checks.

Shared helpers (Chrome launcher, flag assembly, result normalization, category scoring) live in `src/lighthouse-analysis.ts` and are reused across all four families to keep behavior consistent. Source: [src/lighthouse-analysis.ts:1-200]()

## Audit Family (`run_audit` and related)

The audit family is implemented in `src/tools/audit.ts` and is the canonical entry point. `run_audit` launches Chrome, runs a full Lighthouse audit against the supplied URL, and returns the raw LHR (Lighthouse Result) along with a normalized score summary.

Key parameters (all optional except `url`):

| Parameter | Type | Purpose |
|---|---|---|
| `url` | string | The page to audit (required). |
| `categories` | string[] | Subset of Lighthouse categories to evaluate. |
| `formFactor` | `"mobile" \| "desktop"` | Default `mobile`. |
| `throttlingMethod` | string | `"simulate"`, `"devtools"`, or `"provided"`. |
| `chromePath` | string | Added in v1.5.0 via the `--chrome-path` flag and `CHROME_PATH` env variable. Source: [src/tools/audit.ts:40-95]() |

The tool returns scores for `performance`, `accessibility`, `best-practices`, `seo`, and `pwa` (where applicable), plus the full audits object. A community user noted that "the URL is the only required input across all 13+ tools" and that `run_audit` is the canonical "audit a teammate's page in one click" tool. Source: GitHub issue #182.

## Performance Family

`src/tools/performance.ts` exposes focused performance tools, including `get_core_web_vitals`. These tools accept the same single-URL signature and return metric-by-metric output rather than the full LHR.

Typical tools in this family:

- `get_core_web_vitals` — returns LCP, INP/CLS, TTFB, FCP, and Speed Index with pass/fail thresholds.
- `get_performance_metrics` — detailed runtime metrics (main-thread blocking time, bootup time, JS execution).
- `get_resource_summary` — aggregates network requests by type and cache state.

Because all performance tools reuse the Chrome launcher defined in `src/lighthouse-analysis.ts`, they automatically pick up the Chrome profile support introduced in v1.3.0/v1.4.0 for authenticated runs against pages behind login. Source: [src/lighthouse-analysis.ts:80-140]() Source: release notes for lighthouse-mcp v1.4.0.

## Analysis Family

The analysis family in `src/tools/analysis.ts` operates on a previously captured LHR rather than re-running Lighthouse. This makes it cheap to call repeatedly in an agent loop without re-launching Chrome.

Common patterns:

- `analyze_results(lhr)` — produces a prioritized fix list keyed by estimated impact.
- `compare_runs(baseline, current)` — diffs two LHRs and reports regressions/improvements.
- `extract_opportunities(lhr)` — returns only failing audits with high potential savings.

These tools rely on the scoring and normalization utilities in `src/lighthouse-analysis.ts`, which translate raw numeric metrics into the "0–1" Lighthouse score space and attach opportunity cost estimates. Source: [src/tools/analysis.ts:30-110]() Source: [src/lighthouse-analysis.ts:200-280]()

## Security Family

`src/tools/security.ts` exposes `get_security_audit` and related helpers. They restrict the Lighthouse run to security-relevant categories (`best-practices`, parts of `seo` for HTTPS, and dedicated security audits) and additionally post-process the result to highlight:

- Missing or misconfigured security headers (`Content-Security-Policy`, `Strict-Transport-Security`, `X-Frame-Options`, `Referrer-Policy`).
- Mixed-content and insecure form submissions.
- Known-vulnerable libraries flagged by Lighthouse's `no-vulnerable-libraries` audit.

Like all other tools, `get_security_audit` takes only `url` as required input and inherits Chrome flags (`--chrome-path`, `CHROME_PATH`) from the shared launcher. Source: [src/tools/security.ts:25-90]() Source: [src/lighthouse-analysis.ts:140-200]()

## Common Configuration Surface

All four tool families share the following runtime controls, surfaced through both flags and environment variables:

- `CHROME_PATH` / `--chrome-path` — explicit Chrome executable (v1.5.0+).
- Chrome profile directory — enables authenticated Lighthouse runs (v1.3.0/v1.4.0+).
- `--preset` — convenience presets (e.g., `mobile`, `desktop`, `seo-only`) that pre-fill `categories` and `formFactor`.

Tool registration order and category defaults are defined in `src/tools/index.ts`; new tools added to any family module are picked up automatically by the central registry. Source: [src/tools/index.ts:60-120]()

---

<a id='page-3'></a>

## Chrome & Browser Configuration

### Related Pages

Related topics: [Project Overview & System Architecture](#page-1), [Tool Reference: Audit, Performance, Analysis & Security](#page-2)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/chrome-config.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/chrome-config.ts)
- [src/cli.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/cli.ts)
- [scripts/smoke-profile.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/scripts/smoke-profile.ts)
- [src/lighthouse-core.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/lighthouse-core.ts)
- [src/index.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/index.ts)
</details>

# Chrome & Browser Configuration

The Chrome & Browser Configuration subsystem controls how the Lighthouse MCP server locates, launches, and prepares the headless Chrome instance used to run audits. Because Lighthouse is fundamentally a browser-driven tool, every one of the 13+ MCP tools (`run_audit`, `get_core_web_vitals`, `get_security_audit`, etc.) ultimately depends on this layer to produce a valid browsing context. The configuration has grown across releases — Chrome profile support shipped in `v1.3.0`/`v1.4.0` (issue [#134](https://github.com/danielsogl/lighthouse-mcp-server/issues/134)), and explicit Chrome path overrides landed in `v1.5.0` — and is now a first-class concern of the server.

## Configuration Sources and Precedence

Chrome settings can be supplied through three independent channels that are merged in a defined order:

1. **CLI flags** parsed in the server bootstrap.
2. **Environment variables** consumed at startup.
3. **Defaults** resolved by the chrome-config module when no override is given.

The CLI layer in `src/cli.ts` parses process arguments and exposes user-facing flags. Source: [src/cli.ts:1-40](). The most relevant flag for browser control is `--chrome-path`, introduced in `v1.5.0`, which accepts an absolute filesystem path to a Chrome or Chromium executable. Source: [src/cli.ts:42-58](). This flag maps directly to the `CHROME_PATH` environment variable, allowing operators to inject the same value through deployment configuration without changing the command line. Source: [src/cli.ts:60-72]().

## Chrome Path Resolution

`src/chrome-config.ts` is the single source of truth for resolving which Chrome binary Lighthouse will spawn. It exposes a `getChromePath()`-style accessor that:

- Returns the explicit path passed via `--chrome-path` or `CHROME_PATH` when present.
- Falls back to the platform-default Chrome discovery used by the underlying `chrome-launcher` dependency.
- Validates that the resolved path exists and is executable, surfacing a clear error otherwise.

Source: [src/chrome-config.ts:1-60](). This indirection is important because audits run in environments where Chrome is not on `PATH` — container images, CI runners, and developer laptops with custom Chromium builds. Without this layer, the MCP server would inherit whatever the host provides, leading to non-reproducible audits.

## Chrome Profile Support for Authenticated Runs

Many real-world performance and accessibility audits require an authenticated session (e.g. auditing a logged-in dashboard). The Chrome profile feature, delivered in `v1.3.0` / `v1.4.0` (issue [#134](https://github.com/danielsogl/lighthouse-mcp-server/issues/134)), allows the server to launch Chrome with a persistent user-data directory.

The flow is:

1. The server reads a profile directory path from configuration.
2. `src/chrome-config.ts` builds the `chrome-launcher` launch options, including `userDataDir` and any related flags (e.g. `--profile-directory` for multi-profile setups). Source: [src/chrome-config.ts:62-110]().
3. `src/lighthouse-core.ts` passes those options through to the `lighthouse()` core call, ensuring cookies and local storage survive across runs. Source: [src/lighthouse-core.ts:1-80]().
4. A smoke harness at `scripts/smoke-profile.ts` verifies the launch options are wired correctly before any release. Source: [scripts/smoke-profile.ts:1-45]().

This design keeps the auth state separate from the server process itself, which means users can re-run audits against the same profile without re-authenticating each time.

## Integration With the MCP Server

`src/index.ts` wires the chrome configuration into the MCP server lifecycle. When the server starts, it eagerly resolves Chrome configuration so that misconfigurations are reported immediately rather than at the first tool invocation. Source: [src/index.ts:1-70](). The resolved configuration is then injected into the audit factory defined in `src/lighthouse-core.ts`, which exposes a single `runLighthouse(url, options)` entry point consumed by every tool. Source: [src/lighthouse-core.ts:80-140]().

The following table summarizes the main knobs and where they are read:

| Knob | CLI flag | Env var | Read in |
|------|----------|---------|---------|
| Chrome executable | `--chrome-path` | `CHROME_PATH` | `src/chrome-config.ts` |
| Chrome profile dir | `--chrome-profile-path` | `CHROME_PROFILE_PATH` | `src/chrome-config.ts` |
| Headless mode | `--headless` / `--no-headless` | `LIGHTHOUSE_HEADLESS` | `src/chrome-config.ts` |
| Additional Chrome flags | `--chrome-flags` | `CHROME_FLAGS` | `src/cli.ts`, `src/chrome-config.ts` |

Because all tool implementations ultimately funnel through `runLighthouse()`, any improvement to the chrome-config layer benefits every audit endpoint at once — which is why community issue [#182](https://github.com/danielsogl/lighthouse-mcp-server/issues/182) highlights that a single `url` is enough to drive all 13+ tools: the rest of the variability lives behind this configuration surface.

## Operational Notes

- When running inside Docker or other minimal images, set `CHROME_PATH` explicitly; auto-discovery frequently fails in these environments.
- For authenticated audits, prefer a dedicated Chrome profile directory per environment to avoid cookie collisions between local development and CI.
- The `--chrome-flags` escape hatch is the recommended way to pass experimental Chromium switches (e.g. `--enable-features=...`) without waiting for first-class support in the server.

Together, `chrome-config.ts`, `cli.ts`, `lighthouse-core.ts`, `index.ts`, and `scripts/smoke-profile.ts` form a small but coherent configuration pipeline that turns deployment-time decisions into deterministic browser launches for every Lighthouse audit the MCP server performs.

---

<a id='page-4'></a>

## Schemas, Prompts & Reference Resources

### Related Pages

Related topics: [Project Overview & System Architecture](#page-1), [Tool Reference: Audit, Performance, Analysis & Security](#page-2)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/schemas.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/schemas.ts)
- [src/prompts.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/prompts.ts)
- [src/resources.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/resources.ts)
- [src/types.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/types.ts)
</details>

# Schemas, Prompts & Reference Resources

The `schemas.ts`, `prompts.ts`, `resources.ts`, and `types.ts` modules form the contract layer between the Lighthouse MCP server and any Model Context Protocol (MCP) client. Together they define *what can be invoked*, *how it must be described to the model*, and *what reference data the model can read*. They are intentionally separated from the execution logic in `src/tools.ts` so that the public surface of the server can evolve without touching the underlying Lighthouse runner. `Source: [src/schemas.ts:1-40]()`

## Schemas — Tool Input Validation

`src/schemas.ts` exports Zod schemas that describe every tool parameter accepted by the server. These schemas are consumed by `src/tools.ts` to register MCP tools with `server.tool(name, description, schema, handler)` and to validate arguments before they reach Lighthouse. `Source: [src/schemas.ts:1-60]()`

The design follows a "URL-first" philosophy discussed in the community: `url` is the only mandatory field across the 13+ audit tools (`run_audit`, `get_core_web_vitals`, `get_security_audit`, etc.), and every other parameter is optional with sensible defaults so the agent can choose the rest. `Source: [src/schemas.ts:42-180]()`

| Group | Example fields | Purpose |
|-------|----------------|---------|
| Target | `url` (required, URL) | Page under audit |
| Form factor | `formFactor`, `screenEmulation`, `throttlingMethod` | Mobile vs desktop emulation |
| Categories | `categories` (array of `performance`, `accessibility`, `best-practices`, `seo`, `pwa`) | Which Lighthouse categories to score |
| Auth | `chromePath`, `chromeProfile`, `extraHeaders` | Authenticated runs (added in v1.3.0 / v1.4.0) |
| Output | `outputFormat`, `saveArtifacts` | Response shape and artifact persistence |

Common shared building blocks live at the top of the file — for example a `urlSchema` (z.string().url()), an `emulatedFormFactorSchema` enum, and a `categoriesSchema` accepting any subset of Lighthouse categories — and are composed into per-tool schemas such as `runAuditSchema`, `getCoreWebVitalsSchema`, and `getSecurityAuditSchema`. `Source: [src/schemas.ts:20-95]()`

A representative pattern looks like:

```ts
export const runAuditSchema = z.object({
  url: urlSchema,
  categories: categoriesSchema.optional(),
  formFactor: emulatedFormFactorSchema.optional(),
  chromePath: z.string().optional(),
});
```

Because Zod schemas double as JSON Schema for the MCP client, model-facing tool descriptions are generated from the same source, eliminating drift between validation and documentation. `Source: [src/schemas.ts:1-20]()`

## Prompts — Guided Workflows for the Model

`src/prompts.ts` registers MCP **prompts**, which are reusable, parameterised message templates the host can expose to the user. Unlike tools (model-called) and resources (model-read), prompts are user-initiated and steer the model toward a well-defined Lighthouse workflow. `Source: [src/prompts.ts:1-50]()`

Each prompt is registered via `server.prompt(name, description, args, template)` and typically accepts a `url` plus optional arguments such as `focus`, `audience`, or `depth`. The body of the template then instructs the model to:

1. Call the appropriate tool from `src/tools.ts` (e.g. `run_audit` for a full report, `get_core_web_vitals` for field metrics).
2. Summarise the scores and the top three opportunities in the user's tone.
3. Offer concrete fixes grounded in the failing audits. `Source: [src/prompts.ts:30-120]()`

Common prompt names in the file include `audit-summary`, `seo-check`, `accessibility-review`, and `performance-deep-dive`. Each is a thin wrapper that converts a natural-language request into a deterministic tool-call sequence, which is the pattern celebrated in issue #182 ("paste a URL and get scores back"). `Source: [src/prompts.ts:55-140]()`

## Resources — Reference Data Exposed to the Model

`src/resources.ts` registers MCP **resources**, which are read-only, URI-addressable blobs of reference material that the model can fetch on demand. They do not perform audits; they provide context that improves the model's interpretation of audit results. `Source: [src/resources.ts:1-40]()`

Resources are registered with `server.resource(name, uri, metadata, reader)` and addressable via custom URI schemes such as `lighthouse://categories`, `lighthouse://audits/{id}`, and `lighthouse://best-practices`. The reader returns either a static JSON document baked into the repository or a small computed view over the local Lighthouse installation. `Source: [src/resources.ts:25-90]()`

Typical resources shipped in this file:

- `lighthouse://categories` — definitions, scoring weights, and what each Lighthouse category measures.
- `lighthouse://audits/{id}` — human-readable description, fix guidance, and weight for any audit id (e.g. `largest-contentful-paint`).
- `lighthouse://chrome-flags` — reference for the Chrome flags accepted via `chromePath` and `CHROME_PATH` (added in v1.5.0).
- `lighthouse://scoring` — current Lighthouse v10/v11 scoring curves used by the server.

These resources let a host UI render rich "what does this audit mean?" panels and let the model reason about scores without re-implementing Lighthouse's reference data. `Source: [src/resources.ts:60-160]()`

## Shared Types — The Glue

`src/types.ts` holds the TypeScript types that the three above modules share with `src/tools.ts` and `src/index.ts`. It typically re-exports Zod-inferred types (`z.infer<typeof runAuditSchema>`) under names such as `RunAuditInput`, declares result envelopes (`LighthouseResult`, `CategoryScore`, `AuditDetails`), and defines the discriminated union returned by every tool handler. `Source: [src/types.ts:1-80]()`

This file is the single source of truth referenced by the release workflow — when a new flag like `chromePath` is added (v1.5.0), the type, the Zod schema, the prompt template, and any resource documentation are updated together so the public surface stays consistent. `Source: [src/types.ts:40-130]()`

## Interaction Summary

```
   user ──prompt──> Prompts (prompts.ts)
                       │
                       ▼
   model ──tool call──> Schemas (schemas.ts) ──validated──> tools.ts ──> Lighthouse
                       │
                       ▼
                  Types (types.ts)

   model ──read──> Resources (resources.ts)  (reference docs, scoring, audits)
```

In short, `schemas.ts` defines the *shape of requests*, `prompts.ts` defines the *recipes the model can follow*, `resources.ts` defines the *reference material the model can read*, and `types.ts` keeps them all in lock-step — the four files together constitute the public, model-facing API of the Lighthouse MCP server. `Source: [src/schemas.ts:1-180]() Source: [src/prompts.ts:1-160]() Source: [src/resources.ts:1-180]() Source: [src/types.ts:1-160]()`

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: danielsogl/lighthouse-mcp-server

Summary: Found 22 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Identity risk - Identity risk requires verification.

## 1. Identity risk - Identity risk requires verification

- Severity: medium
- Evidence strength: runtime_trace
- Finding: Project evidence flags a identity risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Repro command: `npm install @danielsogl/lighthouse-mcp`
- Evidence: identity.distribution | https://github.com/danielsogl/lighthouse-mcp-server

## 2. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Dependency Dashboard
- User impact: Developers may fail before the first successful local run: Dependency Dashboard
- Evidence: failure_mode_cluster:github_issue | https://github.com/danielsogl/lighthouse-mcp-server/issues/1

## 3. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: lighthouse-mcp: v1.2.18
- User impact: Upgrade or migration may change expected behavior: lighthouse-mcp: v1.2.18
- Evidence: failure_mode_cluster:github_release | https://github.com/danielsogl/lighthouse-mcp-server/releases/tag/lighthouse-mcp-v1.2.18

## 4. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: lighthouse-mcp: v1.2.19
- User impact: Upgrade or migration may change expected behavior: lighthouse-mcp: v1.2.19
- Evidence: failure_mode_cluster:github_release | https://github.com/danielsogl/lighthouse-mcp-server/releases/tag/lighthouse-mcp-v1.2.19

## 5. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: lighthouse-mcp: v1.2.20
- User impact: Upgrade or migration may change expected behavior: lighthouse-mcp: v1.2.20
- Evidence: failure_mode_cluster:github_release | https://github.com/danielsogl/lighthouse-mcp-server/releases/tag/lighthouse-mcp-v1.2.20

## 6. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: lighthouse-mcp: v1.2.21
- User impact: Upgrade or migration may change expected behavior: lighthouse-mcp: v1.2.21
- Evidence: failure_mode_cluster:github_release | https://github.com/danielsogl/lighthouse-mcp-server/releases/tag/lighthouse-mcp-v1.2.21

## 7. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: lighthouse-mcp: v1.3.0
- User impact: Upgrade or migration may change expected behavior: lighthouse-mcp: v1.3.0
- Evidence: failure_mode_cluster:github_release | https://github.com/danielsogl/lighthouse-mcp-server/releases/tag/lighthouse-mcp-v1.3.0

## 8. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: lighthouse-mcp: v1.3.1
- User impact: Upgrade or migration may change expected behavior: lighthouse-mcp: v1.3.1
- Evidence: failure_mode_cluster:github_release | https://github.com/danielsogl/lighthouse-mcp-server/releases/tag/lighthouse-mcp-v1.3.1

## 9. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: lighthouse-mcp: v1.3.3
- User impact: Upgrade or migration may change expected behavior: lighthouse-mcp: v1.3.3
- Evidence: failure_mode_cluster:github_release | https://github.com/danielsogl/lighthouse-mcp-server/releases/tag/lighthouse-mcp-v1.3.3

## 10. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: lighthouse-mcp: v1.5.0
- User impact: Upgrade or migration may change expected behavior: lighthouse-mcp: v1.5.0
- Evidence: failure_mode_cluster:github_release | https://github.com/danielsogl/lighthouse-mcp-server/releases/tag/lighthouse-mcp-v1.5.0

## 11. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/danielsogl/lighthouse-mcp-server/issues/1

## 12. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/danielsogl/lighthouse-mcp-server

## 13. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Paste any page URL and get a Lighthouse perf/a11y/SEO/security score back — send the link to a teammate to audit their page in one click
- User impact: Developers may misconfigure credentials, environment, or host setup: Paste any page URL and get a Lighthouse perf/a11y/SEO/security score back — send the link to a teammate to audit their page in one click
- Evidence: failure_mode_cluster:github_issue | https://github.com/danielsogl/lighthouse-mcp-server/issues/182

## 14. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: lighthouse-mcp: v1.4.0
- User impact: Upgrade or migration may change expected behavior: lighthouse-mcp: v1.4.0
- Evidence: failure_mode_cluster:github_release | https://github.com/danielsogl/lighthouse-mcp-server/releases/tag/lighthouse-mcp-v1.4.0

## 15. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/danielsogl/lighthouse-mcp-server

## 16. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/danielsogl/lighthouse-mcp-server

## 17. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/danielsogl/lighthouse-mcp-server

## 18. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/danielsogl/lighthouse-mcp-server

## 19. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/danielsogl/lighthouse-mcp-server/issues/182

## 20. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/danielsogl/lighthouse-mcp-server

## 21. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/danielsogl/lighthouse-mcp-server

## 22. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: lighthouse-mcp: v1.3.2
- User impact: Upgrade or migration may change expected behavior: lighthouse-mcp: v1.3.2
- Evidence: failure_mode_cluster:github_release | https://github.com/danielsogl/lighthouse-mcp-server/releases/tag/lighthouse-mcp-v1.3.2

<!-- canonical_name: danielsogl/lighthouse-mcp-server; human_manual_source: deepwiki_human_wiki -->