mcp-web-tools-server

一个自定义的模型上下文协议 (MCP) 服务器，为AI代理提供真实可用的工具，用于获取网页并从中提取内容：干净的、可读的文章文本、通过CSS选择器提取的结构化数据，以及robots.txt权限检查。

什么是MCP？

MCP是一个开放协议，最初由Anthropic发布，它标准化了AI应用程序（如Claude Desktop或Claude Code）连接到外部工具和数据源的方式。每个AI应用不再需要发明自己的插件格式，MCP服务器通过简单的JSON-RPC接口暴露一组固定的工具（以及可选的资源和提示），任何兼容MCP的客户端都可以以相同的方式发现并调用它们。本仓库就是这样一个服务器：它作为一个小的本地进程运行，通过stdio使用MCP协议通信，因此任何MCP客户端都可以列出其工具并调用它们，而无需了解底层的httpx、selectolax或trafilatura。

为什么这很有用

开箱即用，LLM无法获取实时网页。这个服务器用一个经过测试、范围明确的小工具集填补了这一空白：代理可以提取文章的可读文本，通过CSS选择器提取页面的特定字段（价格、标题、标签等，取决于页面结构），并在发起请求前检查网站的robots.txt是否允许该请求。它故意设计得狭窄，而不是一个通用的抓取框架，其理念是：几个能正确工作且可预测地失败的工具，比一个有时会出问题的大面积工具集对代理更有用。

工具

fetch_and_extract(url: str) -> str

获取一个URL并返回干净、可读的主要文本内容：脚本、样式、导航、广告和页脚都被剥离。使用trafilatura进行文章提取，并采用段落密度启发式方法（基于selectolax）作为trafilatura无法自信处理的页面的后备方案。

extract_structured(url: str, css_selectors: dict) -> dict

获取一个URL并通过CSS选择器提取字段，例如：

{"title": "h1", "price": ".price", "tags": ".tag-list a"}

返回：

{"title": "Trail Blazer 29 Mountain Bike", "price": "$1,249.00", "tags": ["mountain", "hardtail", "29er"]}

匹配一个元素的选择器返回其文本，匹配多个元素返回其文本列表，匹配不到任何元素返回null。解析使用selectolax完成。

check_robots_txt(url: str) -> dict

获取目标网站的robots.txt，并报告此服务器的用户代理是否被允许请求给定的URL，使用Python标准的urllib.robotparser。如果未找到robots.txt，则明确报告（robots_txt_found: false），而不是静默地假设权限实际上已被授予。

这个工具的存在是因为抓取礼仪应该是一个首要关注点，而不是事后才考虑：代理（或驱动它的人）应该在抓取之前检查权限，而不仅仅是在出问题时才检查。

设计原则

• 诚实的标识。 请求使用真实的User-Agent字符串，标识此工具并链接回此仓库，而不是伪造的浏览器UA。

• 有界的请求。 每次获取都有固定的超时时间（默认10秒），因此缓慢或挂起的服务器不会阻塞整个会话。

• robots.txt是一个工具，而不是静默强制执行的。 提供check_robots_txt是为了让代理（或驱动它的人）可以在抓取前检查权限，但它目前不会自动阻止fetch_and_extract或extract_structured。请参阅下面的限制。

• 不会因错误输入而崩溃。 网络故障、超时和无效URL会被捕获并返回为清晰的错误文本或{"error": ...}字典，绝不会出现未处理的异常导致服务器进程崩溃。

项目布局

mcp_web_tools/
  server.py        MCP server definition and the three tool entry points
  extractors.py     Pure HTML-parsing logic (no network), used for readable-text and CSS-selector extraction
  robots.py         robots.txt fetching and permission checking
  http_client.py    Shared httpx fetch helper: user agent, timeout, error handling
tests/
  test_extractors.py    Unit tests against local HTML fixtures, no network
  test_robots.py        Unit tests with the network call mocked out
  test_http_client.py   Unit tests for URL validation
  test_integration.py   Integration tests against live public sites, marked and run separately
  fixtures/              Static HTML used by the unit tests
scripts/
  test_client.py    Standalone script that launches the server and talks real MCP protocol to it

运行服务器

python -m venv venv
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate

pip install -r requirements.txt
python -m mcp_web_tools.server

服务器通过stdio使用MCP协议通信；直接从终端运行它只会静坐等待客户端连接。通过MCP客户端（见下文）或附带的测试客户端脚本来使用它。

在Claude Desktop或Claude Code中将其配置为MCP服务器

在MCP客户端的服务器配置中添加一个条目，将command指向venv的Python解释器，将args指向模块。对于Claude Desktop，这放在claude_desktop_config.json中：

{
  "mcpServers": {
    "web-tools": {
      "command": "C:\\path\\to\\mcp-web-tools-server\\venv\\Scripts\\python.exe",
      "args": ["-m", "mcp_web_tools.server"],
      "cwd": "C:\\path\\to\\mcp-web-tools-server"
    }
  }
}

在macOS/Linux上，command应为/path/to/mcp-web-tools-server/venv/bin/python。

对于Claude Code，运行：

claude mcp add web-tools -- /path/to/mcp-web-tools-server/venv/bin/python -m mcp_web_tools.server

（如果适用，替换为Windows venv路径），或者将等效条目添加到项目的.mcp.json中。

运行测试

单元测试针对本地HTML固定数据运行，不接触网络：

pytest

集成测试访问真实、稳定的公共测试站点（example.com和books.toscrape.com，标准的公共抓取测试/演示目标），默认运行中排除。当你有网络访问权限时显式运行它们：

pytest -m integration

还有一个独立脚本，它将服务器作为真正的子进程启动，并通过实际的MCP客户端/服务器协议驱动它，而不是直接调用Python函数：

python scripts/test_client.py

限制以及我接下来会添加什么

• 无JavaScript渲染。 此服务器使用httpx获取原始HTML。渲染客户端内容（重度React/Vue SPA）的页面将返回很少或没有有用的内容。第四个工具包装Playwright进行无头浏览器获取将是自然的下一步添加，但代价是运行起来更重。

• 无速率限制。 每次工具调用在调用时发出一个请求。如果代理针对同一主机紧密循环调用工具，则没有内置的每域节流或请求队列。check_robots_txt确实会在站点发布crawl_delay_seconds时显示它，但目前没有任何东西强制执行它。

• robots.txt是建议性的，而不是强制执行的。 fetch_and_extract和extract_structured在获取前不会自动查询check_robots_txt。这是此版本有意的范围决策（代理应该先自己调用check_robots_txt），但一个更严格的模式，自动拒绝不允许的获取，将是一个合理的补充。

• 可读性启发式方法很基础。 当trafilatura没有产生可靠结果时使用的selectolax后备方案是一个简单的段落密度评分器。对于典型的文章和博客布局来说足够好，但在不寻常的页面结构上会比专门的可读性库表现更差。

• 无缓存。 每次调用都会重新获取，即使对于片刻之前的相同URL也是如此。对于演示/作品集服务器来说没问题，但对于更重的使用来说不理想。

• 实践中只有单一传输。 服务器设置为使用stdio，这是Claude Desktop和Claude Code使用的。mcp SDK也支持SSE和可流式HTTP传输；如果需要将此服务器作为托管服务而不是本地子进程运行，则需要连接其中一个。