当前位置： 首页 > news >正文

基于MCP协议构建可编程网页监控工具：从原理到实践

news 2026/5/13 7:13:19

1. 项目概述：一个面向开发者的网页检查与监控工具

最近在折腾一个自动化监控项目时，发现市面上很多现成的网页监控工具要么太重，要么太贵，要么就是API调用限制太多，不够灵活。作为一个习惯了自己动手的开发者，我决定基于一个开源项目来搭建一套轻量级、可编程的网页检查与监控系统。这就是今天要聊的yifanyifan897645/webcheck-mcp。

简单来说，webcheck-mcp是一个基于 Model Context Protocol (MCP) 的网页检查工具。它的核心价值在于，它不是一个独立的、封闭的SaaS服务，而是一个可以被集成到你的自动化工作流、CI/CD管道，甚至是AI助手（比如Claude Desktop）里的“组件”。你可以把它想象成一个专门用来“看”网页的机器人，它能告诉你一个网页是否可访问、加载速度如何、内容是否发生了关键变化，或者是否存在特定的错误信息。对于需要监控官网状态、追踪竞争对手产品更新、自动化测试网页功能，或者确保关键服务页面健康的开发者和运维人员来说，这是一个非常实用的工具。

2. 核心架构与设计思路拆解

2.1 为什么选择 MCP 协议？

MCP，即 Model Context Protocol，是Anthropic提出的一种协议，旨在为AI模型（如Claude）提供一种标准化的方式来连接和使用外部工具、数据源和服务。webcheck-mcp选择基于MCP构建，是一个非常聪明的设计，这直接决定了它的定位和优势。

核心优势在于“可集成性”和“标准化”。传统的监控脚本或工具，往往需要你写一大堆胶水代码来调用其API、解析返回结果，再整合到你的系统中。而MCP定义了一套标准的Server-Client模型。webcheck-mcp作为一个MCP Server，任何兼容MCP的Client（比如Claude Desktop，或者你自己写的客户端）都可以通过标准化的方式调用它的功能。这意味着：

  1. 开箱即用AI集成：你可以直接在Claude Desktop中安装这个Server，然后就能用自然语言让Claude帮你检查网页了。比如你说：“帮我检查一下https://example.com的状态，看看标题有没有变。” Claude就能调用webcheck-mcp去执行并返回结果。
  2. 易于嵌入自动化流程：你可以编写一个轻量的MCP客户端脚本，定期调用webcheck-mcp的检查功能，将结果发送到你的告警系统（如钉钉、Slack）或数据库。由于协议标准，这部分集成工作变得非常简单。
  3. 功能解耦：检查网页的逻辑被封装在独立的Server中。你的业务逻辑（何时检查、检查什么、结果如何处理）与具体的网页抓取、解析技术是分离的。这提高了代码的维护性和可测试性。

2.2 项目核心功能模块解析

拆解webcheck-mcp的源码或设计，我们可以推断它至少包含以下几个核心模块：

  1. 网页获取器：负责发起HTTP/HTTPS请求，获取目标网页的原始HTML内容。这里需要考虑超时设置、重试机制、User-Agent模拟、处理重定向、支持代理（用于访问特定网络环境下的网页）等。一个健壮的获取器是后续所有检查的基础。
  2. 内容解析与检查器：这是工具的核心。获取HTML后，需要根据用户定义的检查规则进行解析。规则可能包括：
    • 存在性检查：检查页面中是否包含（或不包含）某个特定的CSS选择器、HTML标签或文本片段。例如，检查“购买按钮”是否存在。
    • 内容匹配检查：使用正则表达式或字符串匹配，验证页面特定区域的内容是否符合预期。例如，检查版本号是否更新到了“v2.1.0”。
    • 状态码检查：验证HTTP响应状态码是否为200（成功）或其他预期值。
    • 性能指标检查：粗略计算页面大小，或记录响应时间（虽然精准性能监控通常需要浏览器环境，但简单的网络耗时仍有参考价值）。
  3. 规则定义与配置：如何让用户方便地定义“检查什么”。可能通过一个JSON或YAML配置文件，或者通过MCP工具调用的参数来动态指定。例如，一个检查规则可能定义为：{ “url”: “https://api.example.com/health”, “assertion”: “status_code equals 200”, “timeout”: 10 }。
  4. MCP服务器封装：将上述网页检查能力包装成符合MCP协议的“工具”。MCP Server会向Client声明自己提供了哪些“工具”（比如check_webpage），每个工具需要什么参数。当Client调用时，Server执行对应的检查逻辑，并将结果格式化成MCP规定的格式返回。
  5. 结果格式化与输出：将检查结果（成功、失败、以及详细的检查数据如状态码、匹配到的内容、耗时等）结构化成清晰的JSON或文本，通过MCP协议返回，也可以支持本地日志输出。

2.3 技术栈选型考量

虽然原项目可能使用了特定语言，但我们可以分析一个典型实现会考虑的技术栈：

  • 语言：Python是极佳的选择。因为它有极其强大的网络请求库（requests,httpx）、HTML解析库（BeautifulSoup,lxml）、以及丰富的生态系统。同时，已有成熟的MCP Server SDK（如mcp-sdk）可以简化开发。Node.js也是一个候选，其异步特性适合高并发检查。
  • 关键库：
    • httpx： 支持HTTP/2和异步请求，比传统的requests在某些场景下性能更好，尤其适合并发检查多个URL。
    • BeautifulSoup： 对开发者友好的HTML解析库，使用CSS选择器或查找方法定位元素非常方便。
    • pydantic： 用于定义和验证检查规则的配置模型，确保输入参数的合法性。
    • mcp： 官方的Python SDK，用于快速构建MCP Server。
  • 配置管理：使用pyyaml或直接使用JSON来定义监控任务列表，便于版本管理和批量修改。

3. 从零开始实现一个基础版 Webcheck MCP Server

理解了设计思路后，我们可以动手实现一个简化但功能完整的webcheck-mcpServer。这将帮助你彻底掌握其工作原理。

3.1 环境准备与依赖安装

首先，创建一个新的项目目录并初始化虚拟环境，这是保持环境清洁的好习惯。

mkdir my-webcheck-mcp && cd my-webcheck-mcp python -m venv venv # Windows: venv\Scripts\activate # macOS/Linux: source venv/bin/activate

安装核心依赖库：

pip install httpx beautifulsoup4 mcp pydantic
  • httpx： 用于进行HTTP请求。
  • beautifulsoup4： 用于解析HTML。
  • mcp： Anthropic官方SDK，用于构建MCP Server。
  • pydantic： 用于数据验证和设置管理。

3.2 定义检查规则与配置模型

我们使用Pydantic来定义清晰的配置结构。创建一个config.py文件：

from pydantic import BaseModel, HttpUrl, Field from typing import Optional, List, Union from enum import Enum class CheckType(str, Enum): STATUS_CODE = “status_code” CONTENT_CONTAINS = “content_contains” SELECTOR_EXISTS = “selector_exists” JSON_PATH = “json_path” # 扩展支持JSON API检查 class WebCheckConfig(BaseModel): “”“单个网页检查任务的配置”“” name: str = Field(…, description=“检查任务名称”) url: HttpUrl = Field(…, description=“要检查的网页URL”) check_type: CheckType = Field(…, description=“检查类型”) # 根据不同检查类型，expectation的含义不同 expectation: Union[str, int] = Field(…, description=“期望值。对于状态码是数字，对于内容检查是字符串”) selector: Optional[str] = Field(None, description=“CSS选择器，用于selector_exists或content_contains类型”) timeout: int = Field(10, description=“请求超时时间（秒）”) enabled: bool = Field(True, description=“是否启用此检查”)

这个模型定义了一个检查任务所需的所有信息：名称、URL、检查类型、期望值、可选的CSS选择器以及超时设置。

3.3 实现核心网页检查引擎

接下来，在engine.py中实现执行检查的逻辑。这是整个工具最核心的部分。

import httpx from bs4 import BeautifulSoup import json import time from typing import Dict, Any, Tuple from .config import WebCheckConfig, CheckType class WebCheckEngine: def __init__(self): self.client = httpx.AsyncClient(timeout=30, follow_redirects=True, http2=True) async def check(self, config: WebCheckConfig) -> Dict[str, Any]: “”“执行单次网页检查”“” result = { “name”: config.name, “url”: str(config.url), “check_type”: config.check_type, “expectation”: config.expectation, “success”: False, “message”: “”, “data”: {}, # 存放额外数据，如响应时间、实际内容等 “timestamp”: time.time() } try: start_time = time.time() # 发起网络请求 resp = await self.client.get(str(config.url), timeout=config.timeout) elapsed = time.time() - start_time result[“data”][“status_code”] = resp.status_code result[“data”][“response_time”] = round(elapsed, 3) result[“data”][“content_length”] = len(resp.content) # 根据检查类型进行验证 if config.check_type == CheckType.STATUS_CODE: result[“success”] = resp.status_code == config.expectation result[“message”] = f“Status code: {resp.status_code}” elif config.check_type == CheckType.CONTENT_CONTAINS: # 注意：这里简单解码，实际项目需考虑编码检测 text = resp.text result[“success”] = config.expectation in text result[“message”] = f“Content contains ‘{config.expectation}’: {result[‘success’]}” result[“data”][“snippet”] = text[:500] # 截取片段供调试 elif config.check_type == CheckType.SELECTOR_EXISTS: soup = BeautifulSoup(resp.content, ‘html.parser’) elements = soup.select(config.selector) if config.selector else [] result[“success”] = len(elements) > 0 result[“message”] = f“Selector ‘{config.selector}’ found {len(elements)} time(s)” result[“data”][“element_count”] = len(elements) # 可以在此扩展 JSON_PATH 等其他检查类型 else: result[“message”] = f“Unsupported check type: {config.check_type}” except httpx.TimeoutException: result[“message”] = f“Request timeout after {config.timeout}s” except httpx.RequestError as e: result[“message”] = f“Request failed: {str(e)}” except Exception as e: result[“message”] = f“Check error: {str(e)}” return result async def close(self): await self.client.aclose()

这个引擎类封装了HTTP请求、内容解析和规则验证。它使用异步客户端以提高并发效率，并妥善处理了超时和网络错误。

3.4 构建 MCP Server 主程序

现在，我们将引擎与MCP协议结合起来。创建server.py：

from mcp import Server, types import asyncio from engine import WebCheckEngine from config import WebCheckConfig, CheckType from pydantic import ValidationError import json app = Server(“webcheck-mcp”) # 初始化检查引擎（在实际应用中，可能需要考虑生命周期管理） engine = WebCheckEngine() @app.list_tools() async def handle_list_tools() -> list[types.Tool]: “”“向客户端声明本Server提供的工具”“” return [ types.Tool( name=“check_webpage”, description=“检查一个网页是否符合特定预期”, inputSchema={ “type”: “object”, “properties”: { “url”: {“type”: “string”, “description”: “要检查的网页URL”}, “check_type”: { “type”: “string”, “enum”: [ct.value for ct in CheckType], “description”: “检查类型” }, “expectation”: { “type”: “string”, “description”: “期望值。对于状态码，传入数字字符串如‘200’；对于内容检查，传入期望的文本。” }, “selector”: { “type”: “string”, “description”: “CSS选择器（仅当check_type为selector_exists或content_contains时需要）” }, “timeout”: {“type”: “number”, “description”: “超时时间（秒）”, “default”: 10} }, “required”: [“url”, “check_type”, “expectation”] } ), types.Tool( name=“batch_check”, description=“根据配置文件批量检查多个网页”, inputSchema={ “type”: “object”, “properties”: { “config_path”: {“type”: “string”, “description”: “检查任务配置文件的路径（JSON格式）”} }, “required”: [“config_path”] } ) ] @app.call_tool() async def handle_call_tool(name: str, arguments: dict) -> list[types.TextContent]: “”“处理客户端对工具的调用”“” if name == “check_webpage”: try: # 将传入参数转换为配置模型 config = WebCheckConfig( name=“single_check”, url=arguments[“url”], check_type=arguments[“check_type”], expectation=arguments[“expectation”], selector=arguments.get(“selector”), timeout=arguments.get(“timeout”, 10) ) result = await engine.check(config) return [types.TextContent( type=“text”, text=json.dumps(result, indent=2, ensure_ascii=False) )] except ValidationError as e: return [types.TextContent(type=“text”, text=f“配置错误: {e}”)] except KeyError as e: return [types.TextContent(type=“text”, text=f“缺少必要参数: {e}”)] elif name == “batch_check”: config_path = arguments[“config_path”] try: with open(config_path, ‘r’, encoding=‘utf-8’) as f: configs_data = json.load(f) results = [] for cfg_data in configs_data: if cfg_data.get(“enabled”, True): config = WebCheckConfig(**cfg_data) result = await engine.check(config) results.append(result) summary = {“total”: len(results), “success”: sum(1 for r in results if r[“success”]), “details”: results} return [types.TextContent( type=“text”, text=json.dumps(summary, indent=2, ensure_ascii=False) )] except FileNotFoundError: return [types.TextContent(type=“text”, text=f“配置文件未找到: {config_path}”)] except (json.JSONDecodeError, ValidationError) as e: return [types.TextContent(type=“text”, text=f“配置文件解析错误: {e}”)] else: return [types.TextContent(type=“text”, text=f“未知工具: {name}”)] async def main(): # 启动MCP Server（标准输入输出） async with app.run_stdio_server() as server: await server.wait_closed() await engine.close() # 优雅关闭引擎 if __name__ == “__main__”: asyncio.run(main())

这个Server提供了两个工具：check_webpage用于单次即时检查，batch_check用于读取配置文件进行批量检查。它通过标准输入输出与MCP客户端通信，这是MCP Server最常见的运行方式。

3.5 创建配置文件并运行测试

创建一个示例配置文件checks.json：

[ { “name”: “Homepage Availability”, “url”: “https://httpbin.org/status/200”, “check_type”: “status_code”, “expectation”: 200, “timeout”: 5 }, { “name”: “Check Blog Title”, “url”: “https://httpbin.org/html”, “check_type”: “content_contains”, “expectation”: “Herman Melville”, “timeout”: 5 }, { “name”: “Search Button Exists”, “url”: “https://httpbin.org/html”, “check_type”: “selector_exists”, “expectation”: true, “selector”: “h1”, “timeout”: 5 } ]

现在，你可以运行这个Server：python server.py。它将在后台等待MCP客户端的连接。

如何测试？最直接的方式是使用Claude Desktop。你需要将Server配置到Claude Desktop的MCP设置中（通常是一个配置文件，指定Server的命令和参数）。配置成功后，在Claude Desktop的对话中，你就可以直接说：“使用webcheck工具，检查一下https://example.com的状态码是不是200。” Claude会自动调用你的Server并返回结果。

4. 生产环境部署与高级功能扩展

一个基础的玩具项目已经完成，但要用于实际生产监控，还需要考虑更多。

4.1 部署与运行模式

  1. 作为系统服务运行：使用systemd(Linux) 或launchd(macOS) 将你的server.py注册为后台服务，确保其持续运行和开机自启。
  2. 容器化部署：编写Dockerfile，将应用打包成镜像。这简化了环境依赖管理和跨服务器部署。
    FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install –no-cache-dir -r requirements.txt COPY . . CMD [“python”, “server.py”]
  3. 与调度器集成：MCP Server本身是常驻服务，但定时触发检查需要外部调度器。你可以：
    • 编写一个独立的客户端脚本，使用cron或systemd timer定时运行，调用batch_check工具。
    • 使用更强大的工作流调度器，如Apache Airflow或Prefect，将webcheck-mcp作为一个任务节点集成到复杂的数据管道中。

4.2 增强检查能力

基础检查只是开始，可以扩展更多实用功能：

  • 性能监控：集成playwright或puppeteer的无头浏览器模式，获取真实的页面加载时间、LCP、FCP等Web Vitals指标。这比简单的HTTP请求耗时更有价值。
  • 视觉回归测试：使用pixelmatch或applitools等库，对页面截图并进行像素级对比，检测UI布局的非预期变化。
  • API健康检查：专门针对JSON API，支持JSONPath表达式来提取和验证响应体中的特定字段。
  • 证书检查：检查HTTPS网站的SSL证书过期时间。
  • 地理位置检查：通过配置不同区域的代理，检查网站在全球各地的可访问性和性能。

4.3 结果处理与告警

检查结果不能只停留在返回的JSON里，需要流动起来。

  1. 结果存储：将每次检查的结果写入时序数据库（如InfluxDB、TimescaleDB）或普通数据库（如PostgreSQL），便于历史查询和趋势分析。
  2. 告警触发：在客户端脚本或专门的告警引擎中，判断检查结果success字段。如果失败，根据严重程度触发告警：
    • 即时通讯通知：通过Webhook发送消息到钉钉、企业微信、Slack、飞书。
    • 短信/电话告警：集成像阿里云、腾讯云的短信/语音呼叫服务，用于最高优先级的告警。
    • 事件管理平台：将告警推送到PagerDuty、Opsgenie或开源的Prometheus Alertmanager，实现分派、升级和静默管理。
  3. 仪表盘可视化：使用Grafana连接你的结果数据库，创建监控仪表盘，直观展示所有被监控网页的可用性、响应时间趋势等。

4.4 安全性与稳定性考量

  • 认证与授权：如果你的MCP Server暴露在网络上，需要考虑添加认证。MCP协议本身支持传输层安全，确保使用TLS加密通信。对于敏感的内部URL检查，Server本身应运行在可信网络内。
  • 资源限制：防止恶意或错误的配置导致Server过载。需要实现：
    • 请求速率限制：对调用频率进行限制。
    • 超时控制：严格设置每个检查任务的超时时间，并确保异步任务能被正确取消。
    • 内存/CPU监控：避免解析过大的HTML页面导致内存溢出。
  • 错误恢复与重试：网络检查天生不稳定。引擎应实现智能重试机制（如指数退避），并对暂时性错误和永久性错误进行区分。
  • 日志与审计：记录详细的检查日志，包括请求时间、URL、配置、结果和错误信息，便于问题排查和审计。

5. 常见问题与排查技巧实录

在实际使用和开发这类工具时，我踩过不少坑，这里分享一些典型的排查思路。

5.1 检查结果不稳定，时而成功时而失败

这是网络监控中最常见的问题。

  • 可能原因1：网络抖动或目标服务器不稳定。
    • 排查：在服务器上直接使用curl或wget多次测试目标URL，观察延迟和成功率。使用ping和traceroute检查网络链路。
    • 解决：在检查逻辑中加入重试机制。不要一次失败就告警。可以设置重试3次，每次间隔2秒，只有全部失败才判定为不可用。在WebCheckEngine的check方法中包裹一个重试循环。
  • 可能原因2：请求被目标网站屏蔽。
    • 排查：检查返回的状态码是否是403、429，或者返回内容中包含“Access Denied”、“Bot detected”等字样。对比使用浏览器访问和工具访问的差异。
    • 解决：
      1. 优化请求头：模拟真实浏览器的User-Agent，添加Accept、Accept-Language等常见头。
      2. 使用代理：通过代理IP池轮询请求，分散请求来源。在httpx.AsyncClient中配置proxies参数。
      3. 降低频率：过于频繁的检查会被视为攻击，需要拉大检查间隔。
  • 可能原因3：DNS解析问题。
    • 排查：在工具中记录解析出的IP，看是否变化或不正确。
    • 解决：在客户端或服务器配置更稳定的DNS（如8.8.8.8），或者考虑使用HTTP客户端的本地hosts缓存。

5.2 CSS选择器匹配不到元素

页面结构变化是导致监控失效的主要原因。

  • 可能原因1：页面动态加载。
    • 现象：用工具获取的HTML是空的或缺少内容，但浏览器能看到。
    • 排查：检查工具获取的HTML源码，是否只是一段JavaScript加载器。
    • 解决：升级到无头浏览器方案。使用playwright或selenium等工具，等待页面完全加载（包括异步请求和JS执行完毕）后再进行元素查找。这虽然消耗更多资源，但对于现代Web应用是必须的。
  • 可能原因2：选择器写得太“脆”。
    • 现象：开发者微调了class名或DOM结构，选择器就失效了。
    • 解决：
      1. 使用更稳健的选择器：优先选择id、具有明确语义的>async def batch_check_concurrent(configs: List[WebCheckConfig]): tasks = [engine.check(cfg) for cfg in configs if cfg.enabled] results = await asyncio.gather(*tasks, return_exceptions=True) # 处理结果，注意区分异常和正常结果 return results
      2. 问题：解析大HTML页面内存消耗高。
        • 优化：
          1. 流式处理：如果只是检查状态码或特定标签，可以在收到响应头或部分内容后就做出判断，无需下载完整Body。
          2. 限制解析：对于BeautifulSoup，如果只需要检查特定选择器，可以使用SoupStrainer只解析文档的一部分。
          3. 设置超时和大小限制：在客户端强制限制最大响应体大小。
      3. 问题：数据库或通知接口成为瓶颈。
        • 优化：引入消息队列。检查Worker只负责执行检查并将结果投递到消息队列（如Redis Streams,RabbitMQ,Kafka）。由独立的消费者负责从队列中取出结果，进行写入数据库和发送告警等IO密集型操作。这样实现了生产与消费的解耦，提高了系统的吞吐量和抗压能力。

    最后，我想分享一个最深的体会：这类工具的价值不在于其技术有多复杂，而在于它如何无缝地融入并增强你现有的工作流。webcheck-mcp基于MCP的设计，正是这种“可嵌入性”的绝佳体现。你可以从最简单的状态码监控开始，逐步根据需要添加更复杂的检查规则、集成到你的运维平台、甚至为你的团队开发一个内部监控面板。关键在于开始动手，并在实际使用中不断迭代。当你发现一个凌晨三点的服务宕机告警，是由你亲手搭建的这个系统发出并帮你避免了重大损失时，那种成就感是无与伦比的。

http://www.jsqmd.com/news/807261/

相关文章：

  • DownKyi技术架构解析：构建高性能B站视频下载引擎的设计与实践
  • DownKyi终极指南：5步掌握B站8K视频下载的完整教程
  • 免费好用的去水印工具推荐：哪个效果最好？免费去水印工具对比 2026 实测
  • 如何快速掌握SPT-AKI存档编辑器：终极单机版游戏修改指南
  • Sora 2国内可用性深度测评（2024Q2最新版）：API调用失败率＜0.8%的私有化部署方案首次公开
  • 开源工具集qmd-openclaw-kit：开发者效率提升与自动化实践指南
  • 2026年5月商业医保公司推荐：五家产品专业评测夜班族防大病 - 品牌推荐
  • 纯前端PDF合并工具开发：基于Astro与PDF-lib的A6面单智能排版方案
  • 如何选北京二手房装修公司？2026年5月推荐五家品牌评测对比旧房改造避隐患 - 品牌推荐
  • “数字珍珠港”再现：西北能源基地DNS篡改事件深度复盘与防护升级
  • 紧急预警：Midjourney即将下线Pastel专属渲染节点（内部消息源证实），速存这8个离线替代工作流
  • go语言兼容win7的最后一个版本
  • 多模态生成新纪元已至，Sora 2+3D Gaussian协同架构全拆解，深度对比NeRF/Plenoxels/Instant-NGP（附Benchmark原始数据）
  • 面试记录 （2026/5/12）
  • 留学的实用指南：从准备到落地的全流程经验分享
  • 优测全链路压测平台的高并发性能瓶颈定位实践
  • 半导体22nm工艺中的源掩模优化(SMO)技术解析
  • 2026年5月北京十大装修公司排行榜推荐：十大品牌专业评测夜间施工防噪音方案 - 品牌推荐
  • 汽车软件工程转型：从ECU开发到AUTOSAR实践
  • Serverless平台为何总让人“又爱又恨”？揭秘Lovable设计的3层情感化架构（开发者体验×运维韧性×业务敏捷）
  • ComfyUI Impact Pack终极指南：5步掌握AI图像细节增强完整技巧
  • 2025-2026年国内商业医保公司推荐：五家排行产品专业评测中年人加班防突发疾病 - 品牌推荐
  • 基于大语言模型的本地化AI翻译部署实战：从Ollama到Gradio
  • 02数据模型与单词仓库-鸿蒙PC端Electron开发
  • 63-cubemx-FLASH读写
  • 2025-2026年全球沐浴露品牌推荐：十大品牌排名评测解决油性肌肤致后背痘痘问题 - 品牌推荐
  • 新零售2.0收银系统源码为什么适合你？4大客户群体自检
  • Windows命令行集成Claude Code：本地AI编程助手部署与实战指南
  • 毕业答辩 PPT 不再头疼！用百考通AI轻松搞定，把时间留给更重要的准备
  • 2025-2026年国内商业医保公司推荐：五家产品口碑评测家庭投保场景防多人保费高注意事项 - 品牌推荐