浏览器调试 MCP Server

一个基于 Puppeteer 和 Chrome DevTools Protocol (CDP) 的 MCP Server 插件，支持通过持久化浏览器连接进行网页调试、性能分析和内存检测。

功能特性

• Console 异常检查：监听和收集 Console 错误、警告和日志
• 元素状态检查：检查 DOM 元素的属性、样式、可见性和交互性
• 缓存状态检查：获取 LocalStorage、SessionStorage、Cookies 和 IndexedDB 状态
• 性能数据获取：收集 Performance Timeline 和页面加载指标
• 内存堆栈分析：获取堆快照、分析内存使用、跟踪对象分配、检测内存泄漏
• 持久化连接：浏览器实例在 Server 启动时创建，保持运行直到 Server 关闭，提高性能

系统要求

• Node.js 20 或更高版本
• Chrome 或 Chromium 浏览器

安装与配置

在 MCP 客户端（如 Cursor、Claude Desktop 等）的配置文件中添加以下配置：

{
  "mcpServers": {
    "puppeteer-debugger-mcp": {
      "command": "npx",
      "args": ["-y", "@aliex7664/puppeteer-debugger-mcp@latest"]
    }
  }
}

配置完成后，重启 MCP 客户端即可使用。npx 会自动下载并运行最新版本的包，无需手动安装。

可用工具

1. navigate

导航到指定 URL。

参数：

• url (string, 必需): 要导航到的 URL

示例：

{
  "name": "navigate",
  "arguments": {
    "url": "https://example.com"
  }
}

2. get_console_errors

获取 Console 异常和日志。

参数：

• url (string, 可选): 页面 URL，如果未提供则使用当前页面
• level (string, 可选): 日志级别过滤 (error | warning | all)，默认为 all

示例：

{
  "name": "get_console_errors",
  "arguments": {
    "url": "https://example.com",
    "level": "error"
  }
}

3. check_element

检查元素状态（属性、样式、可见性等）。

参数：

• selector (string, 必需): CSS 选择器
• url (string, 可选): 页面 URL

示例：

{
  "name": "check_element",
  "arguments": {
    "selector": "#my-button",
    "url": "https://example.com"
  }
}

4. get_cache_status

获取缓存状态（LocalStorage、SessionStorage、Cookies、IndexedDB）。

参数：

• url (string, 可选): 页面 URL

示例：

{
  "name": "get_cache_status",
  "arguments": {
    "url": "https://example.com"
  }
}

5. get_performance

获取性能数据（Performance Timeline、页面加载指标）。

参数：

• url (string, 可选): 页面 URL

示例：

{
  "name": "get_performance",
  "arguments": {
    "url": "https://example.com"
  }
}

6. get_heap_snapshot

获取堆快照。

参数：

• url (string, 可选): 页面 URL
• topN (number, 可选): Top N（构造函数/节点）数量，默认 20
• collectGarbage (boolean, 可选): 采集前是否触发 GC，默认 false
• maxSnapshotBytes (number, 可选): raw snapshot 采集最大字节数，默认 200MB（超出将截断并跳过解析）
• maxParseBytes (number, 可选): JSON.parse 解析最大字节数，默认 50MB（超出将跳过解析）
• export (object, 可选): raw snapshot 导出选项
  • mode ('none' | 'file' | 'inline' | 'both', 可选): 导出方式，默认 none
  • filePath (string, 可选): file/both 模式输出路径；不填则默认写入当前目录下的 ./.heapsnapshot/（服务端会自动创建目录）
  • maxInlineBytes (number, 可选): inline/both 模式 inline 输出最大字节数（超出截断）

示例：

{
  "name": "get_heap_snapshot",
  "arguments": {
    "url": "https://example.com",
    "topN": 20,
    "export": {
      "mode": "both",
      "maxInlineBytes": 65536
    }
  }
}

返回（new shape）：

• timestamp: 采集时间戳
• summary: 解析摘要（parsed 为 true 时包含 totalNodes/totalSizeBytes/topConstructors/topNodes）
• export: raw snapshot 导出结果（file/inline/both）
• limitations（可选）: 截断/跳过解析等限制说明

兼容字段（deprecated，计划下个 major 移除）：

• totalSize：请迁移到 summary.totalSizeBytes
• totalNodes：请迁移到 summary.totalNodes
• nodes：为避免响应过大，可能仅返回 TopN 节点（截断）；请迁移到 summary.topNodes（或使用 export.filePath 导出原始快照后再做离线分析）

7. analyze_memory

分析内存使用情况。

参数：

• url (string, 可选): 页面 URL

示例：

{
  "name": "analyze_memory",
  "arguments": {
    "url": "https://example.com"
  }
}

8. track_allocations

跟踪对象分配。

参数：

• url (string, 可选): 页面 URL
• duration (number, 可选): 跟踪时长（毫秒），默认 5000
• topN (number, 可选): Top N（调用栈）数量，默认 20
• collectGarbage (boolean, 可选): 采集前是否触发 GC，默认 false
• maxSnapshotBytes (number, 可选): raw profile（带 trace 的 heap snapshot）采集最大字节数，默认 200MB
• maxParseBytes (number, 可选): JSON.parse 解析最大字节数，默认 50MB
• export (object, 可选): raw profile 导出选项（推荐 file，避免响应过大）
  • mode (string, 可选): none | file | inline | both
  • filePath (string, 可选): file/both 模式输出路径（推荐相对路径，如 ./.heapsnapshot/alloc.heapsnapshot）
  • maxInlineBytes (number, 可选): inline/both 模式 inline 最大字节数（超出截断）

示例：

{
  "name": "track_allocations",
  "arguments": {
    "url": "https://example.com",
    "duration": 10000,
    "topN": 20,
    "export": {
      "mode": "file",
      "filePath": "./.heapsnapshot/alloc-example.heapsnapshot"
    }
  }
}

9. take_screenshot

截图（辅助调试）。支持智能输出模式，自动根据图片大小选择返回 base64 或保存为文件，改进的全页截图功能可正确处理懒加载内容。

参数：

• url (string, 可选): 页面 URL（可选）
• fullPage (boolean, 可选): 是否截取整页，默认 false
• outputMode (string, 可选): 输出模式，默认 auto
  • auto：根据图片大小自动选择（小图片返回 base64，大图片保存为文件）
  • file：始终保存为文件，返回路径
  • inline：始终返回 base64（仅用于小图片）
• filePath (string, 可选): 文件保存路径（file/auto 模式使用，默认：./screenshots/screenshot-{timestamp}-{random}.png）
• maxBase64SizeKB (number, 可选): auto 模式阈值（KB，base64 大小，默认 100KB base64 ≈ 75KB 原图）
• scrollDelay (number, 可选): 滚动后等待时间（毫秒，用于触发懒加载，默认 1000）
• waitForSelector (string, 可选): 等待特定选择器加载（可选）

示例：

基本截图（视口）：

{
  "name": "take_screenshot",
  "arguments": {
    "url": "https://example.com"
  }
}

全页截图（自动输出模式）：

{
  "name": "take_screenshot",
  "arguments": {
    "url": "https://example.com",
    "fullPage": true,
    "outputMode": "auto"
  }
}

保存为文件：

{
  "name": "take_screenshot",
  "arguments": {
    "url": "https://example.com",
    "fullPage": true,
    "outputMode": "file",
    "filePath": "./screenshots/example.png"
  }
}

返回 base64（小图片）：

{
  "name": "take_screenshot",
  "arguments": {
    "url": "https://example.com",
    "outputMode": "inline"
  }
}

等待特定元素加载后截图：

{
  "name": "take_screenshot",
  "arguments": {
    "url": "https://example.com",
    "fullPage": true,
    "waitForSelector": ".main-content",
    "scrollDelay": 2000
  }
}

10. get_lighthouse

获取 Lighthouse 性能报告（包括性能、可访问性、最佳实践、SEO 等指标）。

参数：

• url (string, 可选): 页面 URL（可选）
• onlyCategories (string[], 可选): 只分析的类别（可选，如：performance, accessibility, best-practices, seo）
• skipAudits (string[], 可选): 跳过的审计项 ID（可选，如：uses-optimized-images, render-blocking-resources）

示例：

{
  "name": "get_lighthouse",
  "arguments": {
    "url": "https://example.com",
    "onlyCategories": ["performance", "accessibility"],
    "skipAudits": ["uses-optimized-images"]
  }
}

返回结构：

返回的报告中包含以下字段：

• url: 页面 URL
• fetchTime: 报告生成时间
• userAgent: 用户代理字符串
• categories: 类别评分（根据 onlyCategories 参数过滤）
  • performance: 性能评分
  • accessibility: 可访问性评分
  • best-practices: 最佳实践评分
  • seo: SEO 评分
• metrics: 性能指标
  • firstContentfulPaint: 首次内容绘制时间
  • largestContentfulPaint: 最大内容绘制时间
  • totalBlockingTime: 总阻塞时间
  • cumulativeLayoutShift: 累积布局偏移
  • speedIndex: 速度指数
  • timeToInteractive: 可交互时间
  • firstInputDelay: 首次输入延迟
  • timeToFirstByte: 首字节时间
• opportunities: 优化建议（根据 skipAudits 参数过滤）
• diagnostics: 诊断信息（根据 skipAudits 参数过滤）
• implementation: 固定为 "approximation"，表示这是基于 Web Vitals 和 CDP 的近似实现
• limitations: 限制说明数组，包含以下内容：
  • "accessibility/best-practices/seo 评分为近似值，非完整审计"
  • "指标采集基于 Web Vitals 和 CDP，可能与真实 Lighthouse 结果有差异"
  • "部分审计项可能缺失或不完整"

注意事项：

• onlyCategories 参数用于过滤返回的类别，如果未指定则返回所有类别
• skipAudits 参数用于跳过特定的审计项，这些审计项不会出现在 opportunities 和 diagnostics 中
• 返回的评分和指标是基于 Web Vitals 和 CDP 的近似值，可能与真实 Lighthouse 结果有差异
• accessibility、best-practices 和 seo 的评分为占位值，仅供参考

使用示例

检查页面错误

// 1. 导航到页面
{
  "name": "navigate",
  "arguments": {
    "url": "https://example.com"
  }
}

// 2. 获取 Console 错误
{
  "name": "get_console_errors",
  "arguments": {
    "level": "error"
  }
}

分析页面性能

{
  "name": "get_performance",
  "arguments": {
    "url": "https://example.com"
  }
}

检查元素状态

{
  "name": "check_element",
  "arguments": {
    "selector": "button.submit",
    "url": "https://example.com"
  }
}

内存泄漏检测

// 获取初始堆快照
{
  "name": "get_heap_snapshot",
  "arguments": {
    "url": "https://example.com"
  }
}

// 分析内存使用情况
{
  "name": "analyze_memory",
  "arguments": {
    "url": "https://example.com"
  }
}

// 跟踪对象分配
{
  "name": "track_allocations",
  "arguments": {
    "url": "https://example.com",
    "duration": 10000
  }
}

Lighthouse 性能分析

// 获取完整的 Lighthouse 报告
{
  "name": "get_lighthouse",
  "arguments": {
    "url": "https://example.com"
  }
}

// 只分析性能类别
{
  "name": "get_lighthouse",
  "arguments": {
    "url": "https://example.com",
    "onlyCategories": ["performance"]
  }
}

// 跳过特定审计项
{
  "name": "get_lighthouse",
  "arguments": {
    "url": "https://example.com",
    "skipAudits": ["uses-optimized-images", "render-blocking-resources"]
  }
}

注意事项

• 持久化连接：浏览器实例在 Server 启动时创建，保持运行直到 Server 关闭。
• 动态 URL：所有工具都支持通过参数传入 URL。如果页面不存在，系统会自动创建新页面并导航到指定 URL。
• Chrome 路径：如果系统未安装 Chrome 或 Chromium，或安装路径不在默认位置，可以通过 PUPPETEER_EXECUTABLE_PATH 环境变量指定浏览器路径：
  • Windows: C:\Program Files\Google\Chrome\Application\chrome.exe
  • macOS: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
  • Linux: /usr/bin/google-chrome 或 /usr/bin/chromium-browser

许可证

MIT