Webtools MCP Server

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令牌）。您可以通过仅启用所需的工具来减少令牌的使用：

配置选项

1. 环境变量: `ENABLED_TOOLS=

`

1. CLI参数: `--tools=

`

预置模式

可用的单个工具：

• 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
    }
  ]
}

最佳实践

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

故障排除

常见问题和解决方案：

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