谷歌自定义搜索API
谷歌自定义搜索API是免费的，有使用限制（例如，每天免费100次查询，额外的查询需要付费）。有关配额、定价和限制的完整详细信息，请参阅 官方文件.
Web卷曲
由Rayss开发
🚀 开源项目\ 🛠️ 使用Node.js和TypeScript构建（需要Node.js v18+）
______________________________________________________________________
](https://nodejs.org/) 
______________________________________________________________________
______________________________________________________________________
🎬 演示视频
单击此处直接在浏览器中观看演示视频。
如果你的平台支持它，你也可以 下载并播放demo/demo1.mp4 直接。
Your browser does not support the video tag.
______________________________________________________________________
📚 目录
______________________________________________________________________
📝 变更日志/更新历史记录
看 更改日志.md 查看更新和新功能的完整历史记录。
📝 概述
Web卷曲 是从网页和API中获取和提取文本内容的强大工具。将其用作独立的CLI或MCP（模型上下文协议）服务器。Web curl利用Puppeteer进行强大的Web抓取，并支持资源阻止、自定义标头、身份验证和Google自定义搜索等高级功能。
______________________________________________________________________
✨ 特性
🚀 深度研究与自动化（v1.4.2）
- 高级浏览器自动化：通过Puppeteer完全控制Chromium（点击、键入、滚动、悬停、按键）。
- 始终在线会话持久性：浏览器配置文件现在总是持久的。登录会话、Cookie和缓存会自动保存在本地
user_data/目录。 - 令牌高效快照:
- 可访问性树：干净、结构化的快照，而不是杂乱的HTML。 - HTML切片模式：原始HTML startIndex/endIndex 在需要时进行安全分块。 - 视口过滤：自动过滤掉屏幕上不可见的元素，在长页面上节省高达90%的上下文标记。
- Chrome DevTools集成（已实现，但隐藏
list_tools):
- 网络监控(browser_network_requests) - 控制台日志(browser_console_messages)
- 并行搜索:
- multi_search：一次运行多个谷歌搜索（唯一公开的搜索工具）。
- 智能资源管理:
- 怠速自动关闭：浏览器在15分钟不活动后自动关闭，以节省RAM/CPU。 - 选项卡旋转：当达到10个选项卡的限制时，自动替换最旧的选项卡。
- 媒体和文件:
- 完整页面截图：通过5天的自动清理生命周期和自定义目标支持捕获高质量的屏幕截图。 - 文档解析：直接从URL中提取PDF和DOCX文件中的文本。
存储和下载详细信息
- 🗂️ 错误日志轮换：
logs/error-log.txt当超过~1MB时旋转（重命名为error-log.txt.bak)以防止无限增长。 - 🧹 日志和临时清理：旧的临时文件
logs/目录在启动时被清理。 - 🛑 浏览器生命周期：Puppeteer浏览器实例在finally块中关闭，以避免Chromium临时文件泄漏。
- 🔎 内容提取：
- 返回原始文本、HTML和可读性“主文章”（如果可用）。易读性试图提取网页的主要内容，删除页眉、页脚、侧边栏和其他非必要元素，提供更清晰、更集中的文本。 - 可读性输出取决于 startIndex/maxLength/chunkSize 根据要求进行切片。
- 🚫 资源阻塞：
blockResources现在总是被迫false，这意味着资源永远不会被阻止，以实现更快的页面加载。 - ⏱️ 超时控制：导航和API请求超时可通过工具参数进行配置。
- 💾 输出：结果可以打印到stdout或通过CLI选项写入文件。
- ⬇️ 下载行为(
download_file):
- destinationFolder 接受相对路径（根据项目根解析）或绝对路径。 - 服务器创建 destinationFolder 如果它不存在。 - 下载使用节点流进行流式传输+ pipeline 以最大限度地减少内存使用并确保可靠的写入。 - 文件名来源于URL路径（例如。， https://.../path/file.jpg -> file.jpg).如果没有文件名，则回退名称为 downloaded_file. - 覆盖语义：默认情况下，实现将覆盖同名的现有文件。
- 🖥️ 使用模式：CLI和MCP服务器（stdin/stdout传输）。
- 🌐 REST客户端：
fetch_api适当时返回JSON/text，二进制响应返回base64。 - 🔍 谷歌自定义搜索：必填
APIKEY_GOOGLE_SEARCH和CX_GOOGLE_SEARCH. - 🤖 智能命令：
- 自动语言检测（最小法郎）和可选翻译（动态 translate 进口）。 - 查询丰富是基于启发式的；结果取决于检测到的意图。
______________________________________________________________________
🏗️ 建筑
本节概述了Web curl的高级架构。
graph TD
A[User/MCP Host] --> B(CLI / MCP Server)
B --> C{Tool Handlers}
C -- browser_flow --> D["Puppeteer (Web Scraping)"]
C -- fetch_api --> E["REST Client"]
C -- multi_search --> F["Google Custom Search API"]
C -- parse_document --> G["Document Parser (PDF/DOCX)"]
C -- download_file --> H["File System (Downloads)"]
D --> I["Web Content"]
E --> J["External APIs"]
F --> K["Google Search Results"]
H --> L["Local Storage"]- CLI和MCP服务器:
src/index.ts
实现CLI入口点和MCP服务器。
- Web剪贴：使用Puppeteer进行无头浏览和内容提取。
- REST客户端:
src/rest-client.ts
为API请求提供灵活的HTTP客户端。
______________________________________________________________________
⚙️ MCP服务器配置示例
要将web curl集成为MCP服务器，请将以下配置添加到您的 mcp_settings.json:
{
"mcpServers": {
"web-curl": {
"command": "node",
"args": [
"build/index.js"
],
"disabled": false,
"alwaysAllow": [
"browser_flow",
"browser_configure",
"browser_close",
"multi_search",
"fetch_api",
"download_file",
"parse_document"
],
"env": {
"APIKEY_GOOGLE_SEARCH": "YOUR_GOOGLE_API_KEY",
"CX_GOOGLE_SEARCH": "YOUR_CX_ID"
}
}
}
}______________________________________________________________________
🔑 如何获取Google API密钥和CX
- 获取Google API密钥：
- 首选 Google 云控制台. - 创建/选择一个项目，然后转到 API和服务>凭据. - 点击 创建凭据>API密钥 并复制它。
- 获取自定义搜索引擎（CX）ID:
- 首选 自定义搜索引擎. - 创建/选择搜索引擎，然后复制 搜索引擎ID （CX）。
- 启用自定义搜索API：
- 在Google Cloud控制台中，转到 API和服务>库. - 搜索 自定义搜索API 并启用它。
替换 YOUR_GOOGLE_API_KEY 和 YOUR_CX_ID 在上面的配置中。
______________________________________________________________________
🛠️ 安装
# Clone the repository
git clone https://github.com/rayss868/MCP-Web-Curl
cd web-curl
# Install dependencies
npm install
# Build the project
npm run build- 先决条件：确保您的系统上安装了Node.js（v18+）和Git。
木偶安装注意事项
- 窗户： 跑
npm install.
- Linux/Ubuntu服务器： 您必须为Chromium安装额外的依赖项，以便在无头环境中处理渲染和屏幕截图。运行：
sudo apt-get update && sudo apt-get install -y \
fonts-liberation \
libasound2 \
libatk-bridge2.0-0 \
libatk1.0-0 \
libc6 \
libcairo2 \
libcups2 \
libdbus-1-3 \
libexpat1 \
libfontconfig1 \
libgbm1 \
libgcc1 \
libglib2.0-0 \
libgtk-3-0 \
libnspr4 \
libnss3 \
libpango-1-0-0 \
libpangocairo-1.0-0 \
libstdc++6 \
libx11-6 \
libx11-xcb1 \
libxcb1 \
libxcomposite1 \
libxcursor1 \
libxdamage1 \
libxext6 \
libxfixes3 \
libxi6 \
libxrandr2 \
libxrender1 \
libxss1 \
libxtst6 \
lsb-release \
wget \
xdg-utils有关更多详细信息，请参阅 Puppeter故障排除指南.
______________________________________________________________________
🚀 用法
CLI使用情况
CLI支持从网页中获取和提取文本内容。
# Basic usage
node build/index.js https://example.com
# With options
node build/index.js --timeout 30000 https://example.com
# Save output to a file
node build/index.js -o result.json https://example.com命令行选项
--timeout：设置导航超时（默认值：60000）-o：将结果输出到指定文件
MCP服务器使用情况
Web curl可以作为MCP服务器运行，以便与Roo Context或其他MCP兼容环境集成。
外露工具（v1.4.2）
只有以下工具通过以下方式暴露 list_tools 减少代理客户端中的工具链。
- 浏览器流：一个呼叫浏览器工作流（可选导航→ 可选操作→ 返回一个结果）。
- 浏览器配置：设置代理/用户代理/视口（会话持久性始终通过
user_data/).
- 浏览器_关闭：关闭浏览器和选项卡（15分钟不活动后也会自动关闭）。
- 多搜索：并行运行多个谷歌搜索（唯一公开的搜索入口点）。
- fetch_api：带有响应截断的REST API请求(
limit).
- 下载文件：从URL下载文件。
- parse_文档：从PDF/DOCX URL中提取文本。
作为MCP服务器运行
npm run start服务器将通过stdin/stdout进行通信，并公开中定义的工具 src/index.ts.
______________________________________________________________________
🚦 HTML切片示例（推荐用于大页面）
使用 browser_flow 随着 result: { type: "snapshot", mode: "html" } 当您需要原始HTML但希望保持较小的响应时。
客户端对第一个切片的请求：
{
"name": "browser_flow",
"arguments": {
"result": {
"type": "snapshot",
"mode": "html",
"startIndex": 0,
"endIndex": 20000
}
}
}响应（示例）：
{
"mode": "html",
"totalLength": 123456,
"startIndex": 0,
"endIndex": 20000,
"remainingCharacters": 103456,
"content": "...first slice..."
}______________________________________________________________________
🧩 配置
- 会话保持：始终启用。登录名和Cookie在重新启动时会自动重复使用。
- 超时：设置导航和API请求超时。
- 环境变量：用于Google Search API集成（由使用
multi_search).
______________________________________________________________________
💡 示例｛#示例｝
Make a REST API Request
{
"name": "fetch_api",
"arguments": {
"url": "https://api.github.com/repos/nodejs/node",
"method": "GET",
"headers": {
"Accept": "application/vnd.github.v3+json"
},
"limit": 10000
}
}Download File
{
"name": "download_file",
"arguments": {
"url": "https://example.com/image.jpg",
"destinationFolder": "downloads"
}
}注： destinationFolder 可以是相对路径（根据项目根解析）或绝对路径。如果目标文件夹不存在，服务器将创建该文件夹。
Configure Browser
{
"name": "browser_configure",
"arguments": {
"proxy": "http://proxy.example.com:8080",
"viewport": { "width": 1920, "height": 1080 }
}
}注意：会话持久性始终处于启用状态。Cookie和登录会话会自动存储在 user_data/ 目录。
______________________________________________________________________
🛠️ 故障排除｛#故障排除｝
- 超时错误：增加
timeout参数if请求超时。 - 谷歌搜索失败：确保
APIKEY_GOOGLE_SEARCH和CX_GOOGLE_SEARCH设置在您的环境中。 - 错误记录：检查
logs/error-log.txt文件以获取详细的错误消息。
______________________________________________________________________
🧠 提示和最佳实践{#Tips-Best Practices}
Click for advanced tips
- 对于大页面，请使用
maxLength和startIndex以获取切片中的内容。 - 始终验证工具参数以避免错误。
- 使用环境变量保护API密钥和敏感数据。
- 查看中的MCP工具模式
src/index.ts所有可用选项。
______________________________________________________________________
🤝 贡献与问题{#贡献-问题}
欢迎投稿！如果你想贡献，请分叉此存储库并提交一个pull请求。\ 如果您发现任何问题或有建议，请在存储库页面上打开问题。
______________________________________________________________________
📄 许可与归因{#License--归因}
该项目由 Rayss.\ 如有疑问、改进或贡献，请联系作者或在存储库中打开问题。
______________________________________________________________________
注： 谷歌搜索API是免费的，有使用限制。有关详细信息，请参阅： Google自定义搜索API概述