使用说明

Webtools MCP服务器

⚠️ 重要免责声明：该软件是在人工智能技术的帮助下开发的。它按原样提供，未经彻底测试和验证，不得在生产环境中使用。代码可能包含错误、安全漏洞或意外行为。仅用于研究、学习或开发目的，风险自负。

一个模型上下文协议服务器，提供全面的web分析工具，包括HTML提取、markdown转换、屏幕截图功能、调试控制台、高级性能分析以及Lighthouse支持的web审计，用于性能、可访问性、SEO等。

先决条件

Node.js：版本14或更高版本
铬/铬：由Puppeteer自动提供
- 服务器将使用Puppeteer的捆绑Chrome
- 无需单独安装Chrome

特性

核心工具

webtool_gethtml：原始HTML内容提取
- JavaScript渲染支持
- 代理支持
- 自动重试
webtool_readpage：Markdown转换
- 清洁内容物提取
- 链接保存
- 图像处理
- 自定义选择器支持
webtool_screenshot：屏幕截图
- 全页截图
- 特定元素捕获
- 设备仿真
- 自定义视口设置
webtool_debug：调试控制台
- 控制台输出捕获
- 网络请求监控
- 误差跟踪
- 性能指标
- 布局抖动检测
webtool_lighthouse：全面的网络审计
- 性能分析
- 可访问性测试
- SEO评估
- 最佳做法审查
- 渐进式Web应用程序评估
- 设备仿真支持

性能分析工具

webtool_performance_trace：高级性能分析
- 布局抖动检测
- CSS变量影响分析
- 带有布局相关性的JavaScript执行时间线
- 长期任务分解和归因
- 内存和DOM大小分析
- 资源加载优化
webtool_network_monitor：网络活动分析
- 详细的请求和响应分析
- 资源定时信息
- 瀑布可视化数据
- 优化建议
- 第三方请求分析
- 缓存分析
webtool_coverage_analysis：代码覆盖率分析
- JavaScript和CSS覆盖率分析
- 未使用的代码标识
- 代码拆分建议
- 第三方代码分析
webtool_web_vitals：核心网络生命分析
- LCP（最大含量涂料）分析
- CLS（累积布局偏移）分析
- FID/INP（第一次输入延迟/与下一次涂漆的交互）分析
- TTFB（首字节时间）分析
- 元素特定分析
webtool_performance_test：跨设备和网络测试
- 多设备测试
- 网络状态模拟
- 比较分析
- 基线比较
- 设备特定建议

MCP提示

analyze-website：综合网站分析
- 性能、可访问性、SEO和UX分析
- 设备类型选择（移动/桌面）
- 针对设备类型量身定制的详细建议
- 完整的分析报告，包含可操作的见解
get-website-content：内容提取
- 从任何网页提取主要内容
- 清洁降价转换
- 删除导航、广告和非必要元素
- 重要格式和结构的保存
screenshot-website：屏幕截图
- 网页的视觉呈现
- 完整页面捕获
- 基于URL的简单界面
technical-performance-analysis：技术性能分析
- 性能瓶颈的详细技术分析
- 代码示例和优化建议
- 焦点区域选择（JavaScript、渲染、资源、网络）
- 带有严重性评估的性能指标
- 可操作的代码级建议

安装

您可以全局安装该软件包：

npm install -g @bschauer/webtools-mcp-server

或者直接与npx一起使用：

npx @bschauer/webtools-mcp-server

快速开始

适用于Claude桌面用户

{
  "mcpServers": {
    "webtools": {
      "command": "npx",
      "args": ["-y", "@bschauer/webtools-mcp-server@latest"],
      "env": {
        "ENABLED_TOOLS": "BASIC"
      }
    }
  }
}

此配置仅使用基本工具，并将令牌使用率降低了89%。

适用于Claude Code用户

# Install with token optimization
claude mcp add webtools-basic --env ENABLED_TOOLS=BASIC -- npx -y @bschauer/webtools-mcp-server@latest

测试您的安装

配置后，您可以询问Claude：

“请从中提取主要内容https://example.com"
“截图https://google.com"
“分析性能https://news.ycombinator.com"

令牌使用优化

默认情况下，加载所有工具（~10.3k令牌）。您可以通过仅启用所需的工具来减少令牌的使用：

配置选项

环境变量: ENABLED_TOOLS=<preset|tools>
CLI参数: --tools=<preset|tools>

预置模式

预设	包含的工具	令牌使用	减少	用例
`ALL`	全部10个工具	~10.3k令牌	0%	完整功能（默认）
`BASIC`	`gethtml`, `readpage`	约1k代币	89%	仅内容提取
`WEB`	`gethtml`, `readpage`, `screenshot`	约1.5万个代币	85%	网络内容+视觉效果
`DEBUG`	`gethtml`, `readpage`, `screenshot`, `debug`	约2.5k个令牌	76%	内容+调试
`PERFORMANCE`	所有性能分析工具	~6k个令牌	42%	仅用于性能测试
`FULL_ANALYSIS`	除性能测试框架外的所有工具	~9k个令牌	13%	完整的分析套件

可用的单个工具：

webtool_gethtml -原始HTML提取
webtool_readpage -Markdown转换
webtool_screenshot -屏幕截图
webtool_debug -调试控制台+网络监控
webtool_lighthouse -灯塔审计
webtool_performance_trace -性能跟踪
webtool_coverage_analysis -代码覆盖率分析
webtool_web_vitals -核心网络重要指标
webtool_network_monitor -网络活动分析
webtool_performance_test -跨设备性能测试

例子

# Use only basic tools (90% token reduction)
ENABLED_TOOLS=BASIC npx @bschauer/webtools-mcp-server

# Use performance tools only
npx @bschauer/webtools-mcp-server --tools=PERFORMANCE

# Use web + debugging tools
ENABLED_TOOLS=DEBUG npx @bschauer/webtools-mcp-server

# Use specific individual tools
npx @bschauer/webtools-mcp-server --tools=webtool_gethtml,webtool_readpage,webtool_screenshot

# Show all available options
npx @bschauer/webtools-mcp-server --help

# Use environment variable with any command
export ENABLED_TOOLS=WEB
npx @bschauer/webtools-mcp-server

Claude桌面集成

基本配置（所有工具）

{
  "mcpServers": {
    "webtools": {
      "command": "npx",
      "args": ["-y", "@bschauer/webtools-mcp-server@latest"]
    }
  }
}

令牌优化配置

仅限基本工具（代币减少89%）

{
  "mcpServers": {
    "webtools-basic": {
      "command": "npx",
      "args": ["-y", "@bschauer/webtools-mcp-server@latest"],
      "env": {
        "ENABLED_TOOLS": "BASIC"
      }
    }
  }
}

网页内容+截图

{
  "mcpServers": {
    "webtools-web": {
      "command": "npx",
      "args": ["-y", "@bschauer/webtools-mcp-server@latest"],
      "env": {
        "ENABLED_TOOLS": "WEB"
      }
    }
  }
}

仅性能分析

{
  "mcpServers": {
    "webtools-perf": {
      "command": "npx",
      "args": ["-y", "@bschauer/webtools-mcp-server@latest"],
      "env": {
        "ENABLED_TOOLS": "PERFORMANCE"
      }
    }
  }
}

自定义工具选择

{
  "mcpServers": {
    "webtools-custom": {
      "command": "npx",
      "args": ["-y", "@bschauer/webtools-mcp-server@latest"],
      "env": {
        "ENABLED_TOOLS": "webtool_gethtml,webtool_readpage,webtool_screenshot,webtool_debug"
      }
    }
  }
}

使用CLI参数（替代）

{
  "mcpServers": {
    "webtools": {
      "command": "npx",
      "args": ["-y", "@bschauer/webtools-mcp-server@latest", "--tools=BASIC"]
    }
  }
}

Claude代码集成

Claude Code为添加MCP服务器提供了一个简化的命令行界面：

基本安装（所有工具）

# Install with all tools (default)
claude mcp add webtools -- npx -y @bschauer/webtools-mcp-server@latest

令牌优化安装

# Basic tools only (89% token reduction)
claude mcp add webtools-basic --env ENABLED_TOOLS=BASIC -- npx -y @bschauer/webtools-mcp-server@latest

# Web content + screenshots
claude mcp add webtools-web --env ENABLED_TOOLS=WEB -- npx -y @bschauer/webtools-mcp-server@latest

# Performance analysis only
claude mcp add webtools-perf --env ENABLED_TOOLS=PERFORMANCE -- npx -y @bschauer/webtools-mcp-server@latest

# Debug tools
claude mcp add webtools-debug --env ENABLED_TOOLS=DEBUG -- npx -y @bschauer/webtools-mcp-server@latest

# Custom tool selection
claude mcp add webtools-custom --env ENABLED_TOOLS=webtool_gethtml,webtool_readpage,webtool_screenshot -- npx -y @bschauer/webtools-mcp-server@latest

使用CLI参数（替代方法）

# Using --tools parameter instead of environment variable
claude mcp add webtools-basic -- npx -y @bschauer/webtools-mcp-server@latest --tools=BASIC
claude mcp add webtools-perf -- npx -y @bschauer/webtools-mcp-server@latest --tools=PERFORMANCE

管理您的安装

# List all MCP servers
claude mcp list

# Get details about the webtools server
claude mcp get webtools-basic

# Remove a server
claude mcp remove webtools-basic

# Check server status in Claude Code
/mcp

项目范围内的安装（团队共享）

# Install for the entire project team
claude mcp add webtools-basic --scope project --env ENABLED_TOOLS=BASIC -- npx -y @bschauer/webtools-mcp-server@latest

# This creates a .mcp.json file in your project root that can be committed to version control

配置

在以下位置创建配置文件 ~/.mcp/webtools-mcp-server.config.json:

{
  "proxy": {
    "enabled": false,
    "url": "http://your-proxy-server:port",
    "timeout": 10000
  },
  "browser": {
    "ignoreSSLErrors": false,
    "defaultViewport": {
      "width": 1920,
      "height": 1080
    }
  },
  "devices": {
    "mobile": {
      "width": 375,
      "height": 812,
      "deviceScaleFactor": 3,
      "isMobile": true,
      "hasTouch": true,
      "isLandscape": false,
      "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.0 Mobile/15E148 Safari/604.1"
    },
    "tablet": {
      "width": 768,
      "height": 1024,
      "deviceScaleFactor": 2,
      "isMobile": true,
      "hasTouch": true,
      "isLandscape": false,
      "userAgent": "Mozilla/5.0 (iPad; CPU OS 15_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.0 Mobile/15E148 Safari/604.1"
    },
    "desktop": {
      "width": 1920,
      "height": 1080,
      "deviceScaleFactor": 1,
      "isMobile": false,
      "hasTouch": false,
      "isLandscape": true,
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36"
    }
  },
  "networkConditions": {
    "Slow 3G": {
      "downloadThroughput": 500000,
      "uploadThroughput": 300000,
      "latency": 400
    },
    "Fast 3G": {
      "downloadThroughput": 1500000,
      "uploadThroughput": 750000,
      "latency": 300
    },
    "4G": {
      "downloadThroughput": 4000000,
      "uploadThroughput": 2000000,
      "latency": 100
    },
    "WiFi": {
      "downloadThroughput": 10000000,
      "uploadThroughput": 5000000,
      "latency": 20
    },
    "Fiber": {
      "downloadThroughput": 100000000,
      "uploadThroughput": 50000000,
      "latency": 5
    }
  }
}

环境变量

您还可以使用环境变量配置服务器：

USE_PROXY：启用代理支持（true/false）
PROXY_URL：代理服务器URL
PROXY_TIMEOUT：代理超时（毫秒）
IGNORE_SSL_ERRORS：默认情况下，忽略所有工具的SSL证书错误（true/false）-适用于DDEV等开发环境

工具使用示例

HTML内容提取

webtool_gethtml({
  url: "https://example.com",
  useJavaScript: true,
  useProxy: false,
  ignoreSSLErrors: false,
});

页面阅读（Markdown转换）

webtool_readpage({
  url: "https://example.com",
  useJavaScript: true,
  useProxy: false,
  selector: "main",
  ignoreSSLErrors: false,
});

电脑屏幕截图工具

webtool_screenshot({
  url: "https://example.com",
  selector: ".content",
  useProxy: false,
  deviceConfig: {
    width: 1920,
    height: 1080,
    deviceScaleFactor: 1,
    isMobile: false,
  },
});

调试控制台

webtool_debug({
  url: "https://example.com",
  captureConsole: true,
  captureNetwork: true,
  captureErrors: true,
  captureLayoutThrashing: true, // Enable layout thrashing detection
  timeoutMs: 15000,
});

//专注于布局抖动检测

webtool_debug({
  url: "https://example.com",
  captureConsole: false,
  captureNetwork: false,
  captureErrors: true,
  captureLayoutThrashing: true,
  timeoutMs: 15000,
});

Lighthouse网络审计

webtool_lighthouse({
  url: "https://example.com",
  categories: ["performance", "accessibility", "best-practices", "seo", "pwa"],
  device: "mobile", // or "desktop"
  ignoreSSLErrors: false,
});

//仅运行特定类别审核

webtool_lighthouse({
  url: "https://example.com",
  categories: ["performance", "seo"], // Only performance and SEO
  device: "desktop",
});

高级性能分析

webtool_performance_trace({
  url: "https://example.com",
  timeoutMs: 15000,
  captureCPUProfile: true,
  captureNetworkActivity: true,
  captureJSProfile: true,
  captureRenderingPerformance: true,
  captureMemoryProfile: true,
  deviceConfig: {
    width: 1920,
    height: 1080,
    deviceScaleFactor: 1,
    isMobile: false,
  },
});

//专注于特定的性能方面

webtool_performance_trace({
  url: "https://example.com",
  captureRenderingPerformance: true, // Focus on layout and rendering
  captureMemoryProfile: true, // Include memory analysis
  deviceConfig: {
    width: 375,
    height: 812,
    deviceScaleFactor: 3,
    isMobile: true,
  },
});

网络活动分析

webtool_network_monitor({
  url: "https://example.com",
  timeoutMs: 15000,
  waitAfterLoadMs: 2000,
  includeThirdParty: true,
  disableCache: true,
  captureHeaders: true,
  captureTimings: true,
  deviceName: "mobile", // Use predefined device
  networkConditionName: "4G", // Use predefined network condition
});

代码覆盖率分析

webtool_coverage_analysis({
  url: "https://example.com",
  timeoutMs: 15000,
  waitAfterLoadMs: 2000,
  includeThirdParty: true,
  disableCache: true,
  deviceName: "desktop",
});

核心网络生命分析

webtool_web_vitals({
  url: "https://example.com",
  timeoutMs: 15000,
  waitAfterLoadMs: 3000,
  interactWithPage: true,
  deviceName: "mobile",
  networkConditionName: "4G",
});

跨设备和网络测试

webtool_performance_test({
  url: "https://example.com",
  timeoutMs: 30000,
  devices: ["desktop", "mobile", "tablet"],
  networkConditions: ["WiFi", "4G", "3G"],
  tests: ["web_vitals", "network", "coverage"],
  compareResults: true,
  baselineDevice: "desktop",
  baselineNetwork: "WiFi",
  includeScreenshots: true,
});

响应格式

所有工具都以以下格式返回响应：

{
  "content": [
    {
      "type": "text",
      "text": "..." // Markdown formatted report
    }
  ]
}

截图：

{
  "content": [
    {
      "type": "image",
      "data": "...", // Base64 encoded PNG
      "mimeType": "image/png"
    }
  ]
}

对于Lighthouse审计：

{
  "content": [
    {
      "type": "text",
      "text": "..." // Markdown formatted report with audit results
    }
  ]
}

最佳实践

在使用高级分析之前，先从基本的HTML检索开始
仅在必要时使用JavaScript渲染（速度较慢但更完整）
为复杂页面设置适当的超时
尽可能使用选择器来定位特定的页面部分
仅在需要地理限制内容时启用代理支持
对于Lighthouse审核，只指定需要提高性能的类别
仔细检查错误-它们通常包含有用的故障排除提示
使用设备仿真时，请匹配真实的设备规格以获得准确的结果
对于大型网站，关注特定页面而不是整个网站
在应用修复程序之前，使用调试工具了解JavaScript错误
对于性能测试，从基线设备和网络条件开始
比较不同设备和网络条件下的结果，以确定设备特定的问题
使用性能测试框架确定特定场景的优化机会
专注于核心网络关键指标，以改善最佳用户体验
使用代码覆盖率分析来识别未使用的代码并优化包大小

故障排除

常见问题和解决方案：

Chrome安装

备注：Chrome现在通过Puppeteer自动安装-无需额外步骤
如果您遇到任何与Chrome相关的问题，请尝试使用重新安装该软件包 npm install -g @bschauer/webtools-mcp-server

连接问题

问题：无法连接到网站
解决方案：检查URL格式、网站可用性，或尝试启用代理

SSL证书问题

问题：DDEV或本地开发站点的SSL证书错误
解决方案：设置 IGNORE_SSL_ERRORS=true 环境变量或用途 ignoreSSLErrors=true 单个工具的参数
备注：对于生产站点，确保正确的SSL证书配置，而不是绕过SSL检查

JavaScript渲染问题

问题：使用JavaScript渲染时缺少页面内容
解决方案：增加超时时间，检查调试输出中的导航错误

屏幕截图问题

问题：空白或不完整的屏幕截图
解决方案：确保选择器正确，增加视口大小，检查调试控制台

Lighthouse审计超时

问题：灯塔审计超时
解决方案：增加超时设置，减少类别，尝试更快的连接

代理连接失败

问题：无法通过代理连接
解决方案：验证代理URL，检查代理连接超时，确保代理正常运行

布局色觉检测问题

问题：未检测到布局抖动事件
解决方案：确保captureLayoutThrashing设置为true，增加timeoutMs，尝试使用不同的页面

性能测试框架问题

问题：性能测试框架超时
解决方案：减少设备数量和网络状况，增加超时时间，单独运行测试

网络监视器问题

问题：网络监视器显示不完整的数据
解决方案：增加waitAfterLoadMs，确保captureTimings设置为true，检查CORS问题

代码覆盖率分析问题

问题：代码覆盖率分析显示没有结果
解决方案：确保页面加载JavaScript，增加waitAfterLoadMs，检查脚本加载错误

安全考虑

此工具可以访问任意网站-负责任地使用
应谨慎使用代理功能，并遵守适用法律
除非绝对必要，否则SSL证书检查应保持启用状态
网站所有者可能会检测并阻止自动访问
一些网站在其服务条款中禁止抓取

贡献

欢迎投稿！请随时提交拉取请求。

许可证

麻省理工学院

作者

bschauer