STARWARCLOUD STARWAR.AI
返回市场
MCP网页请求工具

MCP网页请求工具

作者：rayss8689 星标更新：2025-08-20
安装使用来源：spider==github.com

项目介绍

Google 自定义搜索 API

Google 自定义搜索 API 是免费提供的，但有使用限制（例如，每天免费提供 100 次查询，超出部分需要付费）。关于配额、定价和限制的详细信息，请参阅 官方文档。

Web-curl

<div align="center">

Web-curl Logo

</div>

开发者：Rayss

🚀 开源项目
🛠️ 使用 Node.js 和 TypeScript 构建（需要 Node.js v18+）

<div align="center">

Node.js License Status

</div>
<div align="center"> <a href="https://glama.ai/mcp/servers/@rayss868/MCP-Web-Curl"> <img width="380" height="200" src="https://gips1.baidu.com/it/u=1712960932,2487509771&fm=3081&app=3081&f=PNG?w=760&h=400" alt="Web-curl Server MCP server" /> </a> </div>

🎬 示例视频

观看示例

点击这里在浏览器中直接观看示例视频。

如果您的平台支持，您也可以下载并播放 demo/demo_1.mp4。

<div align="center"> <video width="640" height="360" controls autoplay> <source src="https://assets.rayzs.my.id/MCP-Web-Curl/demo_1.mp4" type="video/mp4"> 您的浏览器不支持 video 标签。 </video> </div>

📚 目录

<a name="changelog"></a>

📝 变更日志 / 更新历史

完整的更新和新功能历史记录，请参阅 CHANGELOG.md。

<a name="overview"></a>

📝 概述

Web-curl 是一个强大的工具，用于从网页和 API 中抓取和提取文本内容。可以作为独立的 CLI 工具或 MCP（模型上下文协议）服务器使用。Web-curl 利用 Puppeteer 进行强大的网络爬虫，并支持高级功能，如资源阻塞、自定义头、身份验证和 Google 自定义搜索。

<a name="features"></a>

✨ 特性

存储与下载详情

  • 🗂️ 错误日志轮换：当 logs/error-log.txt 超过约 1MB 时（重命名为 error-log.txt.bak），以防止无限制增长。
  • 🧹 日志与临时文件清理：启动时会清理 logs/ 目录中的旧临时文件。
  • 🛑 浏览器生命周期：Puppeteer 浏览器实例在 finally 块中关闭，以避免 Chromium 临时文件泄露。
  • 🔎 内容提取：
    • 返回原始文本、HTML 和可读性“主文章”（如果可用）。可读性尝试从网页中提取主要内容，移除页眉、页脚、侧边栏和其他非必要元素，提供更干净、更集中的文本。
    • 当请求时，可读性输出受 startIndex/maxLength/chunkSize 分割的影响。
  • 🚫 资源阻塞：blockResources 现在总是强制为 false，意味着资源永远不会被阻塞，以加快页面加载速度。
  • ⏱️ 超时控制：导航和 API 请求超时可通过工具参数进行配置。
  • 💾 输出：结果可以通过 CLI 选项打印到标准输出或写入文件。
  • ⬇️ 下载行为（download_file）：
    • destinationFolder 接受相对路径（相对于 process.cwd() 解析）或绝对路径。
    • 如果不存在，服务器会创建 destinationFolder。
    • 使用 Node 流 + pipeline 下载，以最小化内存使用并确保稳健的写入。
    • 文件名由 URL 路径派生（例如，https://.../path/file.jpg -> file.jpg）。如果没有文件名，则回退名为 downloaded_file。
    • 覆盖语义：默认情况下，实现会覆盖具有相同名称的现有文件。为了避免覆盖，提供一个唯一的 destinationFolder 或在调用工具之前在 URL 路径或目标中包含唯一文件名（时间戳、UUID）。（可选地，代码可以扩展以支持 noOverwrite 标志以自动重命名文件——如果您希望实现这一点，请询问。）
    • 错误处理：非 2xx 响应会导致抛出错误；通过 pipeline 流式传输以避免部分写入，并仅在成功时返回最终路径。
  • 🖥️ 使用模式：CLI 和 MCP 服务器（标准输入/输出传输）。
  • 🌐 REST 客户端：fetch_api 在适当的情况下返回 JSON/文本，并对二进制响应进行 base64 编码。
  • 注意：fetch_api 现在需要一个数字 limit 参数；响应将被截断至最多 limit 字符。响应对象包括 bodyLength（原始字符长度）和 truncated（布尔值）。
  • fetch_api 在 MCP 工具列表中标记为 autoApprove，因此兼容的 MCP 主机可以在无需交互批准的情况下调用它。此代码库中的内部调用使用合理的默认 limit 为 1000 字符（适用时）。
  • 🔍 Google 自定义搜索：需要 APIKEY_GOOGLE_SEARCH 和 CX_GOOGLE_SEARCH。
  • 🤖 智能命令：
    • 自动语言检测（franc-min）和可选翻译（动态 translate 导入）。翻译是一种尽力而为的后备措施，可能会无声失败；在失败时保留原始文本。
    • 查询增强基于启发式；结果取决于检测到的意图。
  • 📄 fetch_webpage 具体细节：
    • 多页爬取通过 nextPageSelector（首先尝试 href，然后点击元素）。
    • 内容现在从整个 HTML 中删除空白后再进行切片。
    • 返回切片内容、总字符数（删除空白后）、startIndex、maxLength、remainingCharacters 以及一个用于获取更多内容的 instruction（包括如果收集到足够信息则建议停止）。
    • 必需参数：startIndex（或别名 index）和至少一个 chunkSize（首选）、limit（别名）或 maxLength 必须提供且必须是数字。缺少这些必需参数的调用将因无效参数错误而被拒绝。根据需要设置这些值；它们不能为空。
    • 验证行为：在 src/index.ts 中强制执行运行时验证，当缺少或无效的必需参数时，MCP 工具将抛出/拒绝。如果您希望在缺少参数时自动回退而不是拒绝，请修改 src/index.ts 中的验证逻辑。
  • 🛡️ 调试与日志
    • 运行时日志：详细的运行时错误和调试跟踪默认写入 logs/error-log.txt。
    • 调试标志：某些 CLI/工具路径接受 debug 参数，这将启用更详细的控制台日志记录；并非所有代码路径都一致支持 debug 标志。建议检查 logs/error-log.txt 以获得完整的跟踪。
    • 要始终启用控制台级别的调试，可以添加一个小的代码更改来读取 DEBUG=true 环境变量或全局 --debug CLI 选项（推荐用于开发）。
  • ⚙️ 兼容性与构建注意事项
    • 该项目现在利用 Node.js 18+ 中可用的原生全局 fetch API，消除了对 node-fetch 依赖的需求。这简化了依赖树并利用了内置功能。
    • npm run build 运行 tsc 和一个在 Windows 上为空操作的 chmod 步骤；CI 或跨平台脚本应在执行 chmod 时进行平台检查。
  • 🔐 安全注意事项
    • SSRF：如果公开 fetch_api/fetch_webpage，请验证/白名单目标主机。
    • 速率限制与认证：为公共部署添加请求速率限制和访问控制。
    • Puppeteer 标志：--no-sandbox 减少隔离；仅在必要时使用，并了解在多租户系统上的风险。
  • 🧪 测试与代码检查
    • 代码检查：提供了 npm run lint；建议使用预提交钩子（例如，使用 husky 和 lint-staged）在提交前强制执行代码检查标准，以确保代码质量。
    • 测试：目前没有单元测试。未来计划包括为核心功能（如 fetch_api 和 download_file）添加全面的集成测试，以确保可靠性并防止回归。
  • 📑 所有工具模式和文档均为英文，以便清晰表达。

<a name="architecture"></a>

🏗️ 架构

本节概述了 Web-curl 的高层架构。

graph TD
    A[用户/MCP 主机] --> B(CLI / MCP 服务器)
    B --> C{工具处理器}
    C -- fetch_webpage --> D["Puppeteer (网络爬虫)"]
    C -- fetch_api --> E["REST 客户端"]
    C -- google_search --> F["Google 自定义搜索 API"]
    C -- smart_command --> G["语言检测与翻译"]
    C -- download_file --> H["文件系统 (下载)"]
    D --> I["网页内容"]
    E --> J["外部 API"]
    F --> K["Google 搜索结果"]
    H --> L["本地存储"]
  • CLI & MCP 服务器：src/index.ts 实现了 CLI 入口点和 MCP 服务器，暴露了 fetch_webpage、fetch_api、google_search 和 smart_command 工具。
  • 网络爬虫：使用 Puppeteer 进行无头浏览、资源阻塞和内容提取。
  • REST 客户端：src/rest-client.ts 提供了一个灵活的 HTTP 客户端用于 API 请求，被 CLI 和 MCP 工具共同使用。
  • 配置：通过 CLI 选项、环境变量和工具参数管理。
    • 注意：服务器在启动时创建 logs/ 并将相对路径解析为 process.cwd()。暴露的工具包括 download_file（流式写入）、fetch_webpage、fetch_api、google_search 和 smart_command。

<a name="installation"></a>

⚙️ MCP 服务器配置示例

要将 web-curl 作为 MCP 服务器集成，请在 mcp_settings.json 中添加以下配置：

{
  "mcpServers": {
    "web-curl": {
      "command": "node",
      "args": [
        "build/index.js"
      ],
      "disabled": false,
      "alwaysAllow": [
        "fetch_webpage",
        "fetch_api",
        "google_search",
        "smart_command",
        "download_file"
      ],
      "env": {
        "APIKEY_GOOGLE_SEARCH": "YOUR_GOOGLE_API_KEY",
        "CX_GOOGLE_SEARCH": "YOUR_CX_ID"
      }
    }
  }
}

🔑 如何获取 Google API 密钥和 CX

  1. 获取 Google API 密钥：

    • 访问 Google Cloud 控制台。
    • 创建/选择一个项目，然后转到 APIs & Services > 凭据。
    • 单击 创建凭据 > API 密钥 并复制它。
    • 注意：API 密钥激活可能需要一些时间。另外请注意 Google 免费层级的使用配额。

  2. 获取自定义搜索引擎（CX）ID：

  3. 启用自定义搜索 API：

    • 在 Google Cloud 控制台中，转到 APIs & Services > 库。
    • 搜索 Custom Search API 并启用它。

替换上述配置中的 YOUR_GOOGLE_API_KEY 和 YOUR_CX_ID。

<a name="installation"></a>

🛠️ 安装

# 克隆仓库
git clone https://github.com/rayss868/MCP-Web-Curl
cd web-curl

# 安装依赖
npm install

# 构建项目
npm run build
  • 前提条件：确保您的系统上已安装 Node.js（v18+）和 Git。

Puppeteer 安装说明

  • Windows：只需运行 npm install。

  • Linux：您必须安装 Chromium 的额外依赖项。运行：

    sudo apt-get install -y \
  ca-certificates fonts-liberation libappindicator3-1 libasound2 libatk-bridge2.0-0 \
  libatk1.0-0 libcups2 libdbus-1-3 libdrm2 libgbm1 libnspr4 libnss3 \
  libx11-xcb1 libxcomposite1 libxdamage1 libxrandr2 xdg-utils

    更多详细信息，请参阅 Puppeteer 故障排除指南。

<a name="usage"></a>

🚀 使用

CLI 使用

CLI 支持从网页中抓取和提取文本内容。

# 基本用法
node build/index.js https://example.com

# 带选项
node build/index.js --timeout 30000 --no-block-resources https://example.com

# 将输出保存到文件
node build/index.js -o result.json https://example.com

命令行选项

  • --timeout <ms>：设置导航超时（默认：60000）
  • --no-block-resources：此选项现在已弃用，因为默认情况下资源阻塞总是禁用的。
  • -o <file>：将结果输出到指定文件

MCP 服务器使用

Web-curl 可以作为 MCP 服务器运行，以与 Roo Context 或其他 MCP 兼容环境集成。

暴露的工具

  • fetch_webpage：从网页中检索文本、HTML、主文章内容和元数据。支持多页爬取（分页）和调试模式。
  • fetch_api：使用自定义方法、头、正文、超时和调试模式进行 REST API 请求。
  • google_search：使用 Google 自定义搜索 API 搜索网络，带有高级过滤器（语言、区域、站点、日期限制）和调试模式。
  • smart_command：自由形式命令，带有自动语言检测、翻译、查询增强和调试模式。
  • download_file：从给定 URL 下载文件到指定文件夹。

作为 MCP 服务器运行

npm run start

服务器将通过标准输入/输出通信，并在 src/index.ts 中定义的工具中暴露。

MCP 工具示例（fetch_webpage）

{
  "name": "fetch_webpage",
  "arguments": {
    "url": "https://example.com",
    "timeout": 60000,
    "maxLength": 10000
  }
}

🚦 内容切片示例（推荐用于大页面）

对于大型文档，您可以使用 startIndex 和 maxLength 来切片获取内容。服务器将返回切片的内容、总字符数（删除空白后）以及获取下一部分的指令。

客户端请求第一部分：

{
  "name": "fetch_webpage",
  "arguments": {
    "url": "https://example.com/long-article",
    "blockResources": false,
    "timeout": 60000,
    "maxLength": 2000,     // 本次切片的最大字符数
    "startIndex": 0
  }
}

服务器响应（示例）：

{
  "url": "https://example.com/long-article",
  "title": "长文章标题",
  "content": "前 2000 个删除空白后的 HTML 字符...",
  "fetchedAt": "2025-08-19T15:00:00.000Z",
  "startIndex": 0,
  "maxLength": 2000,
  "remainingCharacters": 8000, // 总字符数 - (startIndex + content.length)