Web Fetch

@pipeworx/web-fetch

从源站实时获取一个公开 URL 的确切内容，并返回字节（或从字节解码的文本），以及针对源站发送的确切内容计算的 SHA-256 哈希、重定向链和响应标头。

属于 Pipeworx — 一个将 AI Agent 连接到 1855+ 个实时数据源的 MCP 网关。这是一个独立的非官方集成，与上游提供方无关，未获其认可，也非由其发布。

工具

• fetch_url(url, format?, max_bytes?, offset?) — 对一个公开的 http(s) URL 发起一次 GET 请求。返回 status、url_final、仅在 URL 发生重定向时才会出现的 redirects、headers（content-type、content-length、last-modified、etag、 content-language、date）、content_family（text | pdf | archive | binary）、bytes_total、针对完整正文计算的 sha256，以及正文的一个窗口：

  • format: "auto"（默认）— HTML 和 PDF 返回可读文本，其他内容返回 原始正文。
  • format: "raw" — 正文本身：文本类型返回解码后的文本，二进制类型（zip、xlsx、gzip、PDF）返回 base64。sha256_returned 对窗口中的确切字节计算哈希。
  • format: "text" — 提取的文本（text_extraction：html | pdf | none | failed）。PDF 提取警告会通过 warnings 返回。
  • max_bytes（默认 100,000；文本最多 1,000,000，base64 最多 512,000）和 offset 用于分页读取较大的正文；请跟进 next_offset。

  文本直接从字节解码，绝不猜测：字符集依次取自 BOM、 Content-Type 标头、页面自身的 <meta charset> 或 XML 声明；若字节是有效的 UTF-8，则使用 UTF-8，否则使用 windows-1252。 charset_source 会说明采用了哪条规则，decode_replacements 会统计解码时丢失的字符数（0 表示没有）。

自行检查“逐字原文”

sha256 基于移除传输压缩后的实体正文计算 — 与 curl --compressed -s <url> | shasum -a 256 写入的字节相同。需要注意两点： 动态页面在稍后再次请求时哈希可能合理地不同；某些网站会根据位置提供不同内容，因此返回内容是本次抓取实际获取到的 原文（已知时，colo 会标明边缘位置）。

拒绝请求 — 始终明确返回，绝不返回空正文

error	触发条件
blocked_url	rule：scheme（不是 http/https）、port（不是 80/443）、userinfo（user:pass@）、private_address、dns_private（名称解析到私有地址）、denylisted_host、too_many_redirects、invalid_redirect。会检查 URL 以及每一次重定向跳转。
upstream_refused	401 / 402 / 403 / 407 / 429 / 451，或机器人拦截页面（reason: "bot_wall"）。包含 status、简短的 body_summary，以及指向 archive_evidence 的 hint；该工具不会自动运行。
upstream_down	5xx、超时、连接或 DNS 故障（phase）。
upstream_status	其他任何非 2xx 状态，例如 404。
unsupported_content_type	图像、音频、视频、字体和可执行文件（依据声明的类型或魔数判断）。
too_large	对不支持字节范围请求的源站，offset 超出 10 MB 读取限制。
budget_exhausted	超出下方的单站点或每小时限制；包含 retry_after_s。
invalid_argument	参数格式错误。

限制

• 每次仅发起一次 GET 请求，不使用 Cookie、无需登录、不发送调用方请求头、不执行 JavaScript。 likely_needs_js: true 表示页面使用脚本呈现内容。
• 每次调用最多读取 10 MB；如果正文更大，则返回开头部分，并设置 truncated: true、body_complete: false 和 sha256: null。
• 每次调用最多 25 秒，最多重定向 4 次。
• 按站点（可注册域名）统计，所有调用方共享配额：每分钟 30 次、每天 1,000 次（sec.gov 为每分钟 5 次）。200 响应会复用 10 分钟（served_from: "cache"、cache_age_s）。
• 如实标识自身为 Pipeworx/1.0 (pipeworx.io)；遇到 403 时，会以 Pipeworx/1.0 (+https://pipeworx.io; [email protected]) 重试一次，并通过 user_agent_used 报告所用标识。

身份验证

无需密钥。

数据来源

• 调用方指定的任何公开 URL。除该 URL 及其重定向外，不会获取任何内容；另外会通过 DNS-over-HTTPS 查询 https://cloudflare-dns.com/dns-query，以拒绝解析到私有地址的名称。

快速开始

添加到你的 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "web-fetch": {
      "url": "https://gateway.pipeworx.io/web-fetch/mcp"
    }
  }
}

此端点实际提供的内容

https://gateway.pipeworx.io/web-fetch/mcp 上的 tools/list 会返回上表中的工具，以及 Pipeworx 的共享元工具——ask_pipeworx、 discover_tools、search_within、remember/recall 和网关范围内的其他工具。因此，你看到的工具数量会多于此表：目前，单个工具包端点除了列出该工具包自己的工具，还会列出约 30 个共享工具。连接的 initialize 响应会说明其确切范围，是针对特定日期的权威答案。

这是有意为之，并非意外的多路复用。元工具让范围受限的连接也能回答此工具包未涵盖的问题——通过可在整个目录中路由的 ask_pipeworx——而无需你再添加第二个 MCP 服务。目前无法挂载不带这些元工具的工具包端点；如果额外的 schema 占用的上下文多于路由带来的价值，请连接一次完整网关，而不是连接多个工具包端点。

或者连接完整的 Pipeworx 网关，直接获取所有工具包列出的工具，而不只是此工具包的工具：

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

两个 URL 都会连接到同一个网关和相同的 1855+ 个数据源。唯一的区别是直接列出哪个工具包的工具；无论使用哪个 URL，ask_pipeworx 都能访问所有工具包的工具。

没有 MCP 客户端？通过 HTTP 调用

curl -X POST https://gateway.pipeworx.io/v1/tools/fetch_url \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://data.giss.nasa.gov/gistemp/tabledata_v4/GLB.Ts+dSST.csv","max_bytes":2000}'

首次调用无需账户。查看任意工具：GET https://gateway.pipeworx.io/v1/tools/fetch_url。查找工具：使用 {"query":"..."} 调用 POST https://gateway.pipeworx.io/v1/tools/search_packs。

独立运行（无需网关账户）

此软件包也可作为本地 stdio MCP 服务运行——无需 Pipeworx 账户，也无需通过网关中转：

{
  "mcpServers": {
    "web-fetch": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-web-fetch"]
    }
  }
}

或者直接运行，确认它能够启动：

npx -y @pipeworx/mcp-web-fetch

它通过 stdin/stdout 使用 MCP，并响应 initialize/tools/list/tools/call，仅提供此工具包的工具——不包含上述网关连接额外提供的任何共享元工具。来源相同，工具相同，但没有 ask_pipeworx 路由。

使用 ask_pipeworx

你可以用通俗易懂的语言提问，而不是直接调用工具——此方法既适用于上面的工具包端点，也适用于完整网关：

ask_pipeworx({ question: "your question about Web Fetch data" })

网关会选择合适的工具并自动填充参数。

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT