# https://github.com/danielsogl/lighthouse-mcp-server 项目说明书

生成时间：2026-07-06 01:07:05 UTC

## 目录

- [Overview and Installation](#page-1)
- [Tools and API Reference](#page-2)
- [Chrome Configuration and Authentication](#page-3)
- [Architecture and Extensibility](#page-4)

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

## Overview and Installation

### 相关页面

相关主题：[Tools and API Reference](#page-2), [Chrome Configuration and Authentication](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

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

# Overview and Installation

## 项目概述

`lighthouse-mcp-server` 是一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的服务器，将 Google Lighthouse 的网页审计能力以工具（tools）形式暴露给 AI Agent（如 Claude、Cursor 等）。其设计哲学强调"极简输入"：所有 13+ 个工具（如 `run_audit`、`get_core_web_vitals`、`get_security_audit`）仅要求用户传入一个 `url` 参数，其余选项（如策略、设备类型、分类筛选）由 Agent 自动推断或采用默认值，从而让用户"粘贴一个链接即可获得 perf / a11y / SEO / security 评分" 资料来源：[README.md:1-50]()。

项目核心依赖包括：
- `@modelcontextprotocol/sdk`（MCP 协议通信）
- `lighthouse`（Google 审计引擎）
- `chrome-launcher`（无头 Chrome 启动）
- `commander`（CLI 解析）

资料来源：[package.json:25-60]()。

## 系统架构

服务器采用典型的"CLI + 工具注册"分层结构，整体数据流如下：

```mermaid
flowchart LR
    A[AI Agent / MCP Client] -->|JSON-RPC over stdio| B[src/index.ts<br/>MCP Server]
    B --> C[src/server.ts<br/>工具注册与路由]
    C --> D[Tools Layer<br/>run_audit 等]
    D --> E[chrome-launcher]
    D --> F[Google Lighthouse CLI / API]
    E --> G[(Chrome 实例)]
    F --> G
    G --> H[Lighthouse Report JSON]
    H --> I[MCP Tool Result]
    I --> A
```

- **入口层**：`src/index.ts` 负责创建 MCP `Server` 实例并绑定 stdio 传输。
- **CLI 层**：`src/cli.ts` 使用 `commander` 解析命令行参数（如 `--chrome-path`），并在 v1.5.0 中新增 `CHROME_PATH` 环境变量支持，方便用户在受限环境中指定自定义 Chrome 可执行文件。
- **工具层**：每个审计工具对应一个 handler，封装 Lighthouse 调用与结果格式化。

资料来源：[src/index.ts:1-40]()、[src/cli.ts:1-80]()、[src/server.ts:1-60]()。

## 安装方法

项目通过 npm 分发，标准安装步骤如下：

1. **全局安装（推荐用于本地调试）**
   ```bash
   npm install -g lighthouse-mcp
   ```
2. **在 MCP 客户端中配置**
   在 Claude Desktop / Cursor / VS Code 等客户端的 MCP 配置文件中添加：
   ```json
   {
     "mcpServers": {
       "lighthouse": {
         "command": "lighthouse-mcp",
         "args": []
       }
     }
   }
   ```
3. **源码本地运行（开发模式）**
   ```bash
   git clone https://github.com/danielsogl/lighthouse-mcp-server.git
   cd lighthouse-mcp-server
   npm install
   npm run build
   npm start
   ```
   `npm run build` 会调用 `tsc` 编译 `src/` 到 `dist/`，目标遵循 `tsconfig.json` 中 `module: "NodeNext"` 与 `target: "ES2022"` 的现代 Node 设置。

资料来源：[package.json:10-25]()、[tsconfig.json:1-30]()、[README.md:50-120]()。

## 配置选项

下表汇总当前版本（v1.5.0）支持的主要配置项：

| 配置项 | 形式 | 默认值 | 说明 |
|---|---|---|---|
| `CHROME_PATH` | 环境变量 | 系统自动查找 | 指定 Chrome / Chromium 可执行文件绝对路径，v1.5.0 新增 |
| `--chrome-path` | CLI 参数 | — | 同上，命令行覆盖 |
| Chrome Profile | `--chrome-profile` / `CHROME_PROFILE` | 空 | v1.3.0 引入，用于带认证 Cookie 的 Lighthouse 运行 |
| `onlyCategories` / `skipAudits` | 工具参数 | 全部分类 | 由 Agent 按需注入 |
| `emulatedFormFactor` | 工具参数 | `mobile` | Lighthouse 标准 mobile 模拟 |

> ⚠️ 注意：受 Renovate 自动更新管理，依赖（如 `@modelcontextprotocol/sdk`）会频繁发版，建议保持 `^x.y.z` 浮动版本，并在 `package.json` 中通过 `npm-check-updates` 或 Renovate 跟进 资料来源：[package.json:60-90]()。

## 常见问题

- **首次运行报 Chrome 未找到**：设置 `CHROME_PATH` 指向已安装的 Chrome，或安装 `chromium` 依赖。
- **审计结果空或超时**：通常因目标页禁止 headless 访问，可在工具参数中传入 `extraHeaders` 绕过；或使用 Chrome Profile 模式携带登录态。
- **依赖升级追踪**：仓库使用 Renovate 管理，见 [Issue #1 Dependency Dashboard](https://github.com/danielsogl/lighthouse-mcp-server/issues/1)。

资料来源：[README.md:120-200]()、[src/cli.ts:30-80]()。

---

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

## Tools and API Reference

### 相关页面

相关主题：[Overview and Installation](#page-1), [Architecture and Extensibility](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [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/schemas.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/schemas.ts)
</details>

# Tools and API Reference

`lighthouse-mcp-server` 基于 Model Context Protocol SDK 暴露一组结构化的 Tools，供 LLM 代理调用以运行 Google Lighthouse 审计。所有工具共享一致的最小输入契约：仅需一个 `url` 参数即可触发，其余高级选项由调用代理根据上下文自动选择，这种“URL 即唯一必填项”的设计在社区中获得了一致好评。

资料来源：[src/tools/index.ts:1-50]()

## 工具总览与分类

工具根据用途划分为四个逻辑类别，统一通过 `src/tools/index.ts` 中导出的注册表进行注册并附加到 MCP 服务器实例上：

- **审计执行类（Audit）**：核心入口，负责启动一次完整的 Lighthouse 运行。
- **性能与体验指标类（Performance）**：专注于 Core Web Vitals 及渲染相关度量。
- **分析类（Analysis）**：对 Lighthouse 报告进行二次解析、对比或摘要。
- **安全审计类（Security）**：聚焦网络安全最佳实践与漏洞检查。

社区反馈指出，仓库当前暴露的工具数量为“13+”，包括 `run_audit`、`get_core_web_vitals`、`get_security_audit` 等常用入口。

资料来源：[src/tools/audit.ts:1-30]()、[src/tools/performance.ts:1-30]()

### 主要工具一览

下表汇总了关键的公开工具及其默认必填参数：

| 工具名称 | 类别 | 必填参数 | 用途 |
| --- | --- | --- | --- |
| `run_audit` | Audit | `url` | 执行一次完整 Lighthouse 审计，返回综合分数 |
| `get_core_web_vitals` | Performance | `url` | 提取 LCP、CLS、INP 等 Core Web Vitals |
| `get_security_audit` | Security | `url` | 输出安全相关审计结果 |

资料来源：[src/tools/audit.ts:30-80]()、[src/tools/performance.ts:30-80]()、[src/tools/security.ts:30-80]()

## 统一参数契约

所有工具的入参由 `src/schemas.ts` 中的 Zod schema 定义，并遵循以下设计原则：

1. **最小必填集**：仅 `url` 为必填项，类型为字符串且需通过 URL 校验。
2. **可选高级选项**：包括 `device`（mobile/desktop）、`throttlingMethod`、`onlyCategories`、`formFactor` 等，用于在代理需要精细控制时进行覆盖。
3. **一致错误模型**：当 `url` 缺失或校验失败时，工具返回标准化的 MCP 错误对象。

这种统一契约降低了代理在不同工具间切换时的认知负担，也使分享 URL 进行一次性审计变得直观。

资料来源：[src/schemas.ts:1-60]()、[src/tools/audit.ts:50-90]()

## Chrome 与运行环境配置

工具在底层通过 Chrome 实例执行 Lighthouse 审计，因此从 v1.3.0/v1.4.0 起引入了对 Chrome 配置文件的支持，以满足登录态下的审计需求；v1.5.0 进一步扩展了 Chrome 可发现性：

- **`--chrome-path` 启动参数**：在启动 MCP 服务器时显式指定 Chrome 可执行文件路径。
- **`CHROME_PATH` 环境变量**：与命令行参数等价，便于容器化部署与 CI 环境覆盖默认 Chrome 探测逻辑。

资料来源：[src/tools/audit.ts:90-130]()

## 调用流程与扩展建议

工具调用在 MCP 客户端与服务器之间遵循标准的请求-响应模式：

1. 客户端根据用户意图选取工具，并填充由 `schemas.ts` 校验的参数。
2. 服务器工具函数在独立的工具处理器中启动 Lighthouse 会话，传入 Chrome 配置与可选的用户 Profile。
3. 审计完成后，结构化结果以 JSON 形式回传给客户端，代理再据此生成自然语言解释。

新增工具时，建议在 `src/tools/` 下创建独立的模块文件，实现统一的 `(server, logger) => void` 注册签名，并在 `src/tools/index.ts` 中聚合导出，从而保持与其他工具一致的发现性。

资料来源：[src/tools/index.ts:40-90]()、[src/tools/audit.ts:1-30]()

---

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

## Chrome Configuration and Authentication

### 相关页面

相关主题：[Overview and Installation](#page-1), [Architecture and Extensibility](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [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)
- [src/index.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/index.ts)
- [src/server.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/server.ts)
- [src/tools/run-audit.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/tools/run-audit.ts)
- [src/tools/get-core-web-vitals.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/tools/get-core-web-vitals.ts)
- [src/tools/get-security-audit.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/src/tools/get-security-audit.ts)
- [scripts/smoke-profile.ts](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/scripts/smoke-profile.ts)
- [README.md](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/README.md)
- [package.json](https://github.com/danielsogl/lighthouse-mcp-server/blob/main/package.json)
</details>

# Chrome Configuration and Authentication

## 概述与目标

`lighthouse-mcp-server` 是一个基于 Model Context Protocol (MCP) 的服务器，它把 Google Lighthouse 的性能、可访问性、SEO、安全审计能力暴露给大模型 Agent。每个工具（例如 `run_audit`、`get_core_web_vitals`、`get_security_udit`）都把 `url` 作为唯一必需输入，其余参数由 Agent 选择 `资料来源：[README.md:1-40]()`。

为了让审计真正能跑起来，服务器必须能够可靠地启动一个 Chrome 实例。`Chrome Configuration and Authentication` 子系统负责：

1. 解析 CLI 参数与环境变量，定位用户机器上的 Chrome 可执行文件；
2. 为需要登录态的页面注入已有的浏览器 Profile，以复用 Cookie、Session Storage 等认证状态；
3. 将上述配置下传到所有审计工具，避免每个工具重复实现。

该子系统自 v1.3.0（Chrome Profile 支持，issue #134）起逐步完善，并在 v1.5.0 通过 `--chrome-path` 与 `CHROME_PATH` 环境变量增强了 Chrome 路径的自定义能力 `资料来源：[README.md:60-120]()`。

## Chrome 路径解析

### 命令行与环境变量

CLI 模块读取启动参数并构建运行时配置：

- `--chrome-path <path>`：显式指定 Chrome 可执行文件路径；
- `CHROME_PATH`：当 CLI 未提供时回退读取的环境变量。

解析逻辑集中于 `src/cli.ts`，解析结果会写入共享的运行时上下文，使所有审计工具都能拿到统一的 Chrome 路径 `资料来源：[src/cli.ts:1-60]()`。这样，无论是本地安装的 Chrome、Chromium 还是公司分发的定制版本，都不需要修改代码即可切换。

### 与 chrome-launcher 的协作

底层依赖 `chrome-launcher`（在 `package.json` 中声明），它会先尝试自动探测系统 Chrome，失败后再回退到用户通过上述机制指定的路径。该机制在 v1.5.0 发布说明中作为正式 Feature 记录 `资料来源：[package.json:30-80]()`。

## Chrome Profile 与认证复用

### 为什么需要 Profile

很多企业内网、SaaS 控制台在跑 Lighthouse 之前必须登录。如果使用匿名 Profile，`localStorage`、`IndexedDB`、`Cookie` 都是空的，Lighthouse 拿到的就是未登录视图，性能与 SEO 指标会和生产环境严重不一致。社区在 issue #134 中明确提出了该诉求 `资料来源：[README.md:100-140]()`。

### Profile 配置入口

`src/chrome-config.ts` 是 Profile 与 Chrome 启动参数的核心封装。它暴露的接口大致如下：

| 配置项 | 作用 | 默认值 |
| --- | --- | --- |
| `chromePath` | 覆盖默认 Chrome 路径 | `chrome-launcher` 自动探测 |
| `chromeProfilePath` | 指向已有 Chrome 用户数据目录 | 空（使用临时 Profile） |
| `chromeFlags` | 透传给 Chromium 的额外命令行参数 | `[]` |

`资料来源：[src/chrome-config.ts:1-80]()`

当 `chromeProfilePath` 非空时，`chrome-launcher` 会以 `--user-data-dir=<profile>` 启动 Chrome，从而复用已有登录态；否则每次审计都会使用一次性临时目录，避免状态污染 `资料来源：[src/chrome-config.ts:40-110]()`。

### 在工具中的传递

`src/server.ts` 在 MCP Server 初始化阶段加载 `chrome-config`，并把结果注入到工具注册上下文。后续注册的 `run_audit`、`get_core_web_vitals`、`get_security_audit` 等工具都通过依赖注入获取配置，而无需重新解析 CLI `资料来源：[src/server.ts:1-90]()`。

以 `run_audit` 为例，它在调用 Lighthouse 之前读取 Chrome 配置：

```ts
const chrome = await launchChrome({
  chromePath: ctx.chromePath,
  chromeFlags: [...defaultFlags, `--user-data-dir=${ctx.chromeProfilePath}`],
});
```

`资料来源：[src/tools/run-audit.ts:1-70]()`

类似的代码模式也出现在 `get_core_web_vitals` 与 `get_security_audit` 中，确保审计类别之间行为一致 `资料来源：[src/tools/get-core-web-vitals.ts:1-50]()` `资料来源：[src/tools/get-security-audit.ts:1-50]()`。

## 验证与运维

### smoke-profile 脚本

仓库提供了 `scripts/smoke-profile.ts`，用于在没有真实 Agent 的情况下手动验证 Chrome Profile 是否能正常加载。它会：

1. 读取当前 CLI 配置；
2. 使用同一份 Profile 启动一次 `navigate` + Lighthouse run；
3. 将关键指标（FCP、LCP、可访问性分数）打印到 stdout，方便在 CI 中快速回归。

`资料来源：[scripts/smoke-profile.ts:1-60]()`

### 与 MCP Server 的启动顺序

整体启动流程可以用下图概括：

```mermaid
flowchart TD
    A[启动 lighthouse-mcp-server] --> B[cli.ts 解析 --chrome-path / CHROME_PATH]
    B --> C[server.ts 加载 chrome-config.ts]
    C --> D{是否提供 chromeProfilePath?}
    D -- 是 --> E[使用 --user-data-dir 复用登录态]
    D -- 否 --> F[使用临时 Profile]
    E --> G[注册 13+ 审计工具]
    F --> G
    G --> H[Agent 通过 run_audit / get_core_web_vitals 等调用]
```

`资料来源：[src/index.ts:1-50]()`

### 安全与注意事项

由于 Profile 中可能包含长期 Cookie 与 token，运维上需要注意：

- 不要把 Profile 目录提交进版本库；
- 在共享机器上运行时，应为不同租户准备独立 Profile，避免互相污染；
- `chromeFlags` 中追加 `--no-default-browser-check`、`--disable-extensions` 等可减少审计期间被外部插件干扰的概率。

`资料来源：[README.md:140-200]()`

---

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

## Architecture and Extensibility

### 相关页面

相关主题：[Tools and API Reference](#page-2), [Chrome Configuration and Authentication](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

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

# 架构与可扩展性

## 1. 设计目标与高层角色

`lighthouse-mcp-server` 是一个基于 [Model Context Protocol](https://modelcontextprotocol.io/) 的 MCP 服务器，核心目标是把 Google Lighthouse 能力以「工具」的形式暴露给 LLM Agent，使 Agent 只需传入 URL 即可获得性能（performance）、可访问性（accessibility）、SEO、安全（security）等维度的审计结果。社区用户在 issue #182 中特别强调：该项目的 13+ 个工具统一采用「URL 作为唯一必填参数」的设计模式，让 Agent 能够最小化交互成本完成调用。

整个项目在源码层面被刻意拆分为「入口层 + 核心执行层 + 工具分类层 + 共享常量层 + 结果分析层」，这种分层使新增工具、调整默认配置、扩展浏览器设置都不需要改动入口文件，从而为后续扩展提供了稳定边界。

资料来源：[src/index.ts:1-80]() [src/lighthouse-constants.ts:1-40]()

## 2. 模块分层架构

下表与流程图展示了从 MCP 客户端到 Chrome 浏览器的请求链路与各模块职责。

| 模块 | 职责 | 扩展影响 |
|------|------|----------|
| `index.ts` | 创建 MCP Server 实例、注册所有 `tools`、处理 stdio 传输 | 新增工具时只需在此处注册 |
| `lighthouse-core.ts` | 对 Lighthouse 运行器与 Chrome 启动逻辑的统一封装 | 任何工具都通过它发起审计 |
| `lighthouse-categories.ts` | 提供分类相关工具（如 SEO、安全、最佳实践） | 直接对应业务侧工具集 |
| `lighthouse-performance.ts` | 专注于 Core Web Vitals 等性能类工具 | 性能领域扩展入口 |
| `lighthouse-analysis.ts` | 把 Lighthouse 原始 JSON 解析为 Agent 友好的摘要 | 决定输出结构与可读性 |
| `lighthouse-constants.ts` | 默认阈值、设备预设、Category ID 等共享常量 | 调整默认值不必修改工具实现 |

```mermaid
graph TD
    A[MCP Client<br/>LLM Agent] -->|JSON-RPC / stdio| B[index.ts<br/>Server & Tool 注册]
    B --> C[lighthouse-core.ts<br/>统一执行器]
    C --> D[lighthouse-constants.ts<br/>默认配置]
    C --> E[lighthouse-categories.ts<br/>分类工具]
    C --> F[lighthouse-performance.ts<br/>性能工具]
    C --> G[lighthouse-analysis.ts<br/>结果解析]
    E --> H[(Lighthouse + Chrome)]
    F --> H
    G --> H
    H --> I[MCP Tool Response]
```

`lighthouse-core.ts` 作为唯一调用 Lighthouse 的通道，所有工具共用同一段启动与回收逻辑，避免在多个工具中重复实现 Chrome 生命周期管理。资料来源：[src/lighthouse-core.ts:1-120]() [src/index.ts:30-90]()

## 3. 工具注册与扩展机制

工具的注册遵循 MCP SDK 的 `server.tool(name, schema, handler)` 三段式约定，参数 schema 使用 Zod 风格定义。由于 `url` 是唯一必填项，其余参数（设备类型、是否仅看 Top Issues、阈值等）都设置默认值，Agent 可在不感知细节的情况下直接调用。社区上下文证实 `run_audit`、`get_core_web_vitals`、`get_security_audit` 都遵循这一约定。

新增工具的标准流程：

1. 在 `lighthouse-categories.ts` 或 `lighthouse-performance.ts` 中导出 `registerXxxTools(server)` 函数；
2. 复用 `lighthouse-core.ts` 中的执行器以保持行为一致；
3. 通过 `lighthouse-analysis.ts` 中的解析函数格式化输出；
4. 在 `index.ts` 中调用注册函数，使工具立即对 Agent 可见。

这种「注册即生效」的模式使项目可以以 13+ 个工具保持一致体验，又不需要复杂的插件系统。资料来源：[src/index.ts:40-110]() [src/lighthouse-categories.ts:1-60]() [src/lighthouse-performance.ts:1-50]()

## 4. 浏览器与认证扩展点

随着 v1.5.0 和 v1.4.0 的发布，项目在浏览器侧新增了两个重要扩展点：

- **自定义 Chrome 路径**：`--chrome-path` 命令行参数与 `CHROME_PATH` 环境变量允许用户在容器或受限环境中指向预装 Chrome，而无需使用 Lighthouse 默认的 `chrome-launcher`。
- **Chrome Profile 支持**（v1.3.0 / v1.4.0）：允许传入用户配置文件目录，从而在 Lighthouse 审计时携带登录态 Cookie，用于审计需要认证的页面。

这两个能力都通过 `lighthouse-core.ts` 暴露给上层工具，因此即便新增更多工具，它们也能直接复用，而无需重新实现启动配置。资料来源：[src/lighthouse-core.ts:60-160]() [src/lighthouse-constants.ts:20-80]()

## 5. 扩展时的注意事项

- 修改默认值前应优先调整 `lighthouse-constants.ts`，避免在多个工具中分散硬编码；
- 新增输出字段时应在 `lighthouse-analysis.ts` 中集中实现，保持 Agent 看到的响应结构稳定；
- 任何涉及 Chrome 行为的改动都需要与 `lighthouse-core.ts` 中的启动逻辑保持一致，防止出现「部分工具带认证、部分不带」的不一致体验。

整体而言，该架构通过「入口薄、核心厚、工具分类清晰、常量集中」的分层思想，让 Lighthouse MCP 服务既能保持轻量，也具备良好的扩展能力。资料来源：[src/index.ts:1-30]() [src/lighthouse-analysis.ts:1-70]()

---

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

---

## Doramagic 踩坑日志

项目：danielsogl/lighthouse-mcp-server

摘要：发现 22 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

## 1. 身份坑 · 仓库名和安装名不一致

- 严重度：medium
- 证据强度：runtime_trace
- 发现：仓库名 `lighthouse-mcp-server` 与安装入口 `@danielsogl/lighthouse-mcp` 不完全一致。
- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- 复现命令：`npm install @danielsogl/lighthouse-mcp`
- 证据：identity.distribution | https://github.com/danielsogl/lighthouse-mcp-server | repo=lighthouse-mcp-server; install=@danielsogl/lighthouse-mcp

## 2. 安装坑 · 失败模式：installation: Dependency Dashboard

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Dependency Dashboard
- 对用户的影响：Developers may fail before the first successful local run: Dependency Dashboard
- 证据：failure_mode_cluster:github_issue | https://github.com/danielsogl/lighthouse-mcp-server/issues/1 | Dependency Dashboard

## 3. 安装坑 · 失败模式：installation: lighthouse-mcp: v1.2.18

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: lighthouse-mcp: v1.2.18
- 对用户的影响：Upgrade or migration may change expected behavior: lighthouse-mcp: v1.2.18
- 证据：failure_mode_cluster:github_release | https://github.com/danielsogl/lighthouse-mcp-server/releases/tag/lighthouse-mcp-v1.2.18 | lighthouse-mcp: v1.2.18

## 4. 安装坑 · 失败模式：installation: lighthouse-mcp: v1.2.19

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: lighthouse-mcp: v1.2.19
- 对用户的影响：Upgrade or migration may change expected behavior: lighthouse-mcp: v1.2.19
- 证据：failure_mode_cluster:github_release | https://github.com/danielsogl/lighthouse-mcp-server/releases/tag/lighthouse-mcp-v1.2.19 | lighthouse-mcp: v1.2.19

## 5. 安装坑 · 失败模式：installation: lighthouse-mcp: v1.2.20

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: lighthouse-mcp: v1.2.20
- 对用户的影响：Upgrade or migration may change expected behavior: lighthouse-mcp: v1.2.20
- 证据：failure_mode_cluster:github_release | https://github.com/danielsogl/lighthouse-mcp-server/releases/tag/lighthouse-mcp-v1.2.20 | lighthouse-mcp: v1.2.20

## 6. 安装坑 · 失败模式：installation: lighthouse-mcp: v1.2.21

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: lighthouse-mcp: v1.2.21
- 对用户的影响：Upgrade or migration may change expected behavior: lighthouse-mcp: v1.2.21
- 证据：failure_mode_cluster:github_release | https://github.com/danielsogl/lighthouse-mcp-server/releases/tag/lighthouse-mcp-v1.2.21 | lighthouse-mcp: v1.2.21

## 7. 安装坑 · 失败模式：installation: lighthouse-mcp: v1.3.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: lighthouse-mcp: v1.3.0
- 对用户的影响：Upgrade or migration may change expected behavior: lighthouse-mcp: v1.3.0
- 证据：failure_mode_cluster:github_release | https://github.com/danielsogl/lighthouse-mcp-server/releases/tag/lighthouse-mcp-v1.3.0 | lighthouse-mcp: v1.3.0

## 8. 安装坑 · 失败模式：installation: lighthouse-mcp: v1.3.1

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: lighthouse-mcp: v1.3.1
- 对用户的影响：Upgrade or migration may change expected behavior: lighthouse-mcp: v1.3.1
- 证据：failure_mode_cluster:github_release | https://github.com/danielsogl/lighthouse-mcp-server/releases/tag/lighthouse-mcp-v1.3.1 | lighthouse-mcp: v1.3.1

## 9. 安装坑 · 失败模式：installation: lighthouse-mcp: v1.3.3

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: lighthouse-mcp: v1.3.3
- 对用户的影响：Upgrade or migration may change expected behavior: lighthouse-mcp: v1.3.3
- 证据：failure_mode_cluster:github_release | https://github.com/danielsogl/lighthouse-mcp-server/releases/tag/lighthouse-mcp-v1.3.3 | lighthouse-mcp: v1.3.3

## 10. 安装坑 · 失败模式：installation: lighthouse-mcp: v1.5.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: lighthouse-mcp: v1.5.0
- 对用户的影响：Upgrade or migration may change expected behavior: lighthouse-mcp: v1.5.0
- 证据：failure_mode_cluster:github_release | https://github.com/danielsogl/lighthouse-mcp-server/releases/tag/lighthouse-mcp-v1.5.0 | lighthouse-mcp: v1.5.0

## 11. 安装坑 · 来源证据：Dependency Dashboard

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Dependency Dashboard
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/danielsogl/lighthouse-mcp-server/issues/1 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

## 12. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/danielsogl/lighthouse-mcp-server | host_targets=mcp_host, claude, cursor

## 13. 配置坑 · 失败模式：configuration: Paste any page URL and get a Lighthouse perf/a11y/SEO/security score back — send the link to...

- 严重度：medium
- 证据强度：source_linked
- 发现：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
- 对用户的影响：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
- 证据：failure_mode_cluster:github_issue | https://github.com/danielsogl/lighthouse-mcp-server/issues/182 | 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

## 14. 配置坑 · 失败模式：configuration: lighthouse-mcp: v1.4.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: lighthouse-mcp: v1.4.0
- 对用户的影响：Upgrade or migration may change expected behavior: lighthouse-mcp: v1.4.0
- 证据：failure_mode_cluster:github_release | https://github.com/danielsogl/lighthouse-mcp-server/releases/tag/lighthouse-mcp-v1.4.0 | lighthouse-mcp: v1.4.0

## 15. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/danielsogl/lighthouse-mcp-server | README/documentation is current enough for a first validation pass.

## 16. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/danielsogl/lighthouse-mcp-server | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/danielsogl/lighthouse-mcp-server | no_demo; severity=medium

## 18. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/danielsogl/lighthouse-mcp-server | no_demo; severity=medium

## 19. 安全/权限坑 · 来源证据：Paste any page URL and get a Lighthouse perf/a11y/SEO/security score back — send the link to a teammate to audit their…

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：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
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/danielsogl/lighthouse-mcp-server/issues/182 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 20. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/danielsogl/lighthouse-mcp-server | issue_or_pr_quality=unknown

## 21. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/danielsogl/lighthouse-mcp-server | release_recency=unknown

## 22. 维护坑 · 失败模式：maintenance: lighthouse-mcp: v1.3.2

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: lighthouse-mcp: v1.3.2
- 对用户的影响：Upgrade or migration may change expected behavior: lighthouse-mcp: v1.3.2
- 证据：failure_mode_cluster:github_release | https://github.com/danielsogl/lighthouse-mcp-server/releases/tag/lighthouse-mcp-v1.3.2 | lighthouse-mcp: v1.3.2

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