WebClone MCP Server

🚀 网络克隆

一个异步优先的网站克隆和渲染捕获工具，用于文档镜像、人工智能知识库和企业RAG管道。

______________________________________________________________________

🎯 为什么选择WebClone

WebClone帮助团队将授权网站和文档转化为人工智能系统的可复制源材料。它可以镜像静态页面，在需要时渲染JavaScript页面，并导出结构化内容以用于下游分块、嵌入、搜索和RAG工作流。

目标很简单：让人工智能助手和聊天机器人更容易从可信的文档中回答问题，而不是猜测。

WebClone设计用于：

• 项目、产品、SDK和API的文档镜像
• 从批准的公共或私人文档生成AI知识库
• 需要可重复源捕获的企业RAG摄入管道
• 可审计的档案，包括保存的HTML、资产、元数据和渲染输出
• 礼貌地爬行，使用保守的默认值、重试/回退和明确的选择加入

______________________________________________________________________

🧠 人工智能知识库与企业RAG

WebClone旨在帮助人工智能团队从他们拥有或授权处理的网站中创建高质量、基于源代码的知识库。

WebClone帮助您构建什么

• RAG语料库 来自文档网站、内部门户、产品手册、SDK参考和知识中心
• 聊天机器人接地数据 因此，助理根据批准的文档进行回答，而不是猜测
• 离线镜像 用于合规性、审查、审计和可重复的人工智能索引
• 结构化内容导出 从渲染页面中提取数据，用于分块、嵌入、矢量数据库和检索管道
• 经过身份验证的捕获 用于使用已保存的浏览器Cookie或会话文件的私营企业文档

企业友好的捕获流程

Authorized website or docs portal
        ↓
WebClone polite crawler / rendered browser capture
        ↓
HTML mirror + assets + structured_content.json + render_debug_report.json
        ↓
Chunking, embeddings, vector database, search index, or RAG pipeline
        ↓
Grounded AI assistants, copilots, support bots, and internal chatbots

一页呈现的知识捕获

使用 clone-knowledge-page 当页面在提取结构化部分之前必须像浏览器一样呈现时：

webclone clone-knowledge-page "https://docs.python.org/3/tutorial/index.html" \
  --render-js \
  --wait-for ".body" \
  --item-selector ".body" \
  --item-text-selector "h1" \
  --detail-selector "p, li, pre" \
  --output ./output/docs-knowledge-page

文中写道：

page.rendered.html          # final browser-rendered DOM
structured_content.json     # generic item/detail/label records for ingestion
render_debug_report.json    # counts, final URL, auth-likelihood diagnostics

RAG文档网站抓取

对于一个普通的文档网站，从礼貌的限制开始，并有意识地扩展：

webclone clone "https://docs.python.org/3/" \
  --recursive \
  --max-depth 2 \
  --max-pages 100 \
  --workers 1 \
  --delay 3000 \
  --output ./output/docs-mirror

将生成的镜像用作索引和嵌入作业的可复制真实源。

______________________________________________________________________

✨ 特性

🚀 礼貌异步爬行引擎

• 使用可配置的worker和保守的默认值进行并发下载
• 具有重复URL抑制功能的智能队列管理
• 使用指数回退、抖动和 Retry-After 处理
• 停止后429保护，以遵守目标速率限制

🎭 动态页面渲染和结构化捕获

• 为JavaScript密集型网站提供完整的Selenium集成
• 为授权的私人文档加载经过身份验证的cookie
• 选择器在保存最终DOM之前等待并配置点击
• RAG和聊天机器人知识库的通用结构化内容提取
• 使用Chrome DevTools协议生成PDF快照
• 用于视觉存档的屏幕截图

🔐 身份验证和负责任的浏览器会话

• 基于Cookie的身份验证：保存和重用授权的浏览器会话
• 渲染的私人文档：捕获需要经过身份验证的浏览器会话的页面
• 浏览器配置：动态页面的实用Selenium默认值
• 限速意识：礼貌操作的重试/回退和停止阈值
• 易于审计的产出：最终URL、计数和身份验证可能性诊断

🎨 世界级的CLI体验

• 漂亮的终端UI由 富有的
• 每个资源状态的实时进度条
• 带表格和面板的彩色、格式化输出
• 用于生产监控的JSON日志

🏗️ 生产级建筑

• 类型安全：使用Mypy验证的100%类型提示
• 数据验证：具有严格模式的Pydantic V2模型
• 异步优先：基于 aiohttp 和 asyncio
• 模块化设计：具有依赖注入的干净架构
• 综合录井：带有上下文数据的结构化JSON日志

📦 现代工具

• ⚡ 紫外线：闪电般快速的依赖关系管理
• 🔍 颈毛：超快速装订和格式化
• 🧪 pytest：全面的测试套件，覆盖率>90%
• 🐳 码头工人：使用无发行版基础映像的多阶段构建
• 🔒 安全：Bandit审计和依赖性扫描

______________________________________________________________________

🔒 授权测试和安全默认值

WebClone专为合法归档、课堂实验室和授权安全研究而设计。在抓取目标之前，请确认您拥有该系统或具有测试它的书面权限。

面向安全的默认设置现在包括：

• 默认情况下仅限公共web目标: localhost，阻止环回、链路本地、私有和保留IP目标，以减少SSRF式的误用和意外的内部网络爬行。
• 默认情况下相同的域爬网：递归爬网将保留在起始域上，除非您明确传递 --all-domains.
• 有限的并发性和节奏：工作人员和请求延迟是可配置的，因此授权评估可以最大限度地减少对运营的影响。
• 按资产规模限制: --max-asset-bytes 防止意外的大型资产耗尽磁盘或内存。
• 片段规范化：在爬行之前剥离URL片段以减少重复请求。

对于孤立的实验室或私人文档服务器，请有意选择加入。例如，如果您在以下位置运行本地测试站点 http://127.0.0.1:8000:

webclone clone http://127.0.0.1:8000 \
  --allow-private-networks \
  --max-pages 25 \
  --workers 1 \
  --delay 3000

🚀 快速开始

先决条件

• Python 3.11+
• 紫外线 （推荐）或pip

安装

# Using uv (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv pip install webclone

# Or using pip
pip install webclone

# Or from source
git clone https://github.com/ruslanmv/webclone.git
cd webclone
make install
make run  # verifies the CLI using the project .venv/src checkout

您的第一次知识获取

# Clone a single page with safe defaults
webclone clone https://example.com

# Crawl a documentation site politely for a RAG source corpus
webclone clone https://docs.python.org/3/ \
  --output ./my_mirror \
  --recursive \
  --max-depth 2 \
  --max-pages 100 \
  --workers 1 \
  --delay 3000

# Render one authorized knowledge page and export structured JSON
webclone clone-knowledge-page https://docs.python.org/3/tutorial/index.html \
  --render-js \
  --wait-for ".body" \
  --item-selector ".body section" \
  --item-text-selector "h1, h2" \
  --detail-selector "p, li, pre"

就是这样！WebClone创建可复制的镜像和结构化捕获工件，您可以将其输入到分块、嵌入、搜索和RAG管道中。

🎨 企业桌面图形用户界面（新增！）

WebClone现在包括一个用现代Tkinter构建的专业、原生桌面界面，以实现卓越的性能：

# Install with GUI support
make install-gui

# Launch the Enterprise Desktop GUI
make gui

!

GUI会立即作为本机桌面应用程序打开，其中包含：

• 🏠 主页仪表板 -功能概述和快速入门指南
• 🔐 认证管理器 -基于可视化cookie的身份验证工作流，与浏览器集成
• 🛡️ 下载阻力审计 -角色/访问、JavaScript-rendered预览、HAR/API、content-leak和bulk-fetch检查所拥有的封闭内容
• 📥 爬行配置器 -具有实时进度的点击设置
• 📊 结果分析 -全面的统计数据、表格和导出选项

适合所有人！ 无需命令行-具有即时启动、本机性能和无缝操作系统集成的专业桌面界面。

与基于web的GUI相比的优势： ✅ 即时启动（无需启动服务器） ✅ 原生桌面性能 ✅ 更好的操作系统集成（文件对话框、通知） ✅ 无端口冲突 ✅ 离线友好

🤖 用于AI代理的MCP服务器（新！）

WebClone现在是一个 官方模型上下文协议（MCP）服务器，使Claude、CrewAI和任何兼容MCP的框架等AI代理都可以克隆网站！

# Install MCP server
make install-mcp

# Use with Claude Desktop - add to config:
# ~/.config/claude/claude_desktop_config.json
{
  "mcpServers": {
    "webclone": {
      "command": "python",
      "args": ["/path/to/webclone/webclone-mcp.py"]
    }
  }
}

AI代理现在可以：

• 🌐 clone_网站 -自动下载整个网站
• 📥 下载文件 -获取特定文件或URL
• 🔐 save_身份验证 -保存登录会话指南
• 📋 list_saved_sessions -查看所有身份验证Cookie
• ℹ️ get_site_info -下载前分析网站

克劳德的例子：

You: Clone the FastAPI documentation website

Claude: I'll clone that for you.
[Uses WebClone MCP tool]

✅ Cloned 127 pages, 543 assets, 45.2 MB total!

兼容：

• ✅ 克劳德桌面
• ✅ 船员AI
• ✅ 链语言
• ✅ 任何与MCP兼容的AI框架

📖 请参阅： docs/MCP_GUIDE.md 和 MCP_QUICKSTART.md

______________________________________________________________________

📖 用法

界面选项

WebClone提供了四种使用方法：

1. 🎨 桌面图形用户界面 （最简单-企业版）

   make gui

- 本机桌面应用程序 - 即时启动，无需浏览器 - 视觉身份验证管理器 - 实时进度跟踪 - 适合所有用户！

1. 🤖 MCP服务器 （适用于AI代理）

   make install-mcp

- Claude桌面集成 - CrewAI兼容 - LangChain准备就绪 - 人工智能驱动的自动化 - 非常适合AI工作流程！

1. 💻 命令行 （最强大）

   webclone clone https://example.com

- 自动化和脚本 - CI/CD管道 - 远程服务器 - 高级用户

1. 🐍 Python API （最灵活）

   from webclone.core import AsyncCrawler
   # ... your code

- 自定义集成 - 高级工作流 - 开发者

基本命令

# Show help
webclone --help

# Clone a website
webclone clone  [OPTIONS]

# Analyze a page without downloading
webclone info 

高级选项

webclone clone https://example.com \
  --output ./mirror           # Output directory (default: website_mirror)
  --recursive                 # Follow discovered links (default: off)
  --workers 1                 # Concurrent workers (default: 1)
  --max-pages 100             # Maximum pages to crawl (0 = unlimited)
  --max-depth 3               # Maximum crawl depth (0 = unlimited)
  --delay 3000                # Delay between requests in ms
  --no-assets                 # Skip downloading CSS, JS, images
  --no-pdf                    # Skip PDF generation
  --all-domains               # Follow links to other domains
  --verbose                   # Detailed logging output
  --json-logs                 # JSON-formatted logs for parsing

对于渲染知识页面提取：

webclone clone-knowledge-page https://docs.python.org/3/tutorial/index.html \
  --render-js \
  --wait-for ".body" \
  --item-selector ".body" \
  --item-text-selector "h1" \
  --detail-selector "p, li, pre" \
  --output ./knowledge-page

真实世界的例子

# Archive a news site politely (limit pages to avoid overload)
webclone clone https://www.python.org/blogs/ --recursive --max-pages 50 --workers 1 --delay 3000

# Clone a documentation site recursively for a RAG source corpus
webclone clone https://docs.python.org/3/ --recursive --max-depth 3 --max-pages 250 --delay 3000

# Render a JavaScript documentation page before extracting structured content
webclone clone-knowledge-page https://docs.python.org/3/tutorial/index.html \
  --render-js \
  --wait-for ".body" \
  --item-selector ".body" \
  --item-text-selector "h1" \
  --detail-selector "p, li, pre"

# Production mode with JSON logs
webclone clone https://example.com --json-logs --output /var/data/mirror

🔐 经过身份验证的浏览器会话

对于您有权访问的私人文档，请保存一次浏览器会话，并重复使用其Cookie以用于以后呈现的捕获。

# Run the interactive authentication examples
python examples/authenticated_crawl.py

保存会话的Python API：

from pathlib import Path
from webclone.models.config import SeleniumConfig
from webclone.services import SeleniumService

# Open a visible browser and save cookies after manual sign-in.
config = SeleniumConfig(headless=False)
service = SeleniumService(config)
service.start_driver()
service.manual_login_session(
    "https://example.com",
    Path("./cookies/example.json"),
)

# Later, reuse the cookies for an authorized browser session.
config = SeleniumConfig(headless=True)
service = SeleniumService(config)
service.start_driver()
service.navigate_to("https://example.com")
service.load_cookies(Path("./cookies/example.json"))

看 身份验证指南 详细说明。

______________________________________________________________________

🐳 码头工人

在容器化环境中运行WebClone：

# Build the image
make docker-build

# Or manually
docker build -t webclone:latest .

# Run a clone
docker run --rm -v $(pwd)/output:/data webclone:latest \
  clone https://example.com --max-pages 10

# Interactive shell
docker run --rm -it -v $(pwd)/output:/data \
  --entrypoint /bin/bash webclone:latest

Docker编写示例

version: '3.8'
services:
  webclone:
    image: webclone:latest
    volumes:
      - ./output:/data
    command: clone https://example.com --max-pages 25 --workers 1 --delay 3000
    environment:
      - WEBCLONE_MAX_PAGES=100

______________________________________________________________________

🏗️ 建筑

WebClone紧随其后 整洁架构 原则：

src/webclone/
├── cli.py              # Typer CLI interface
├── core/               # Core business logic
│   ├── crawler.py           # Async web crawler
│   ├── downloader.py        # Asset downloader
│   ├── rendered_fetcher.py  # Selenium rendered capture
│   └── content_extractor.py # Structured content extraction for RAG
├── models/             # Pydantic data models
│   ├── config.py       # Configuration schemas
│   └── metadata.py     # Result metadata
├── services/           # External service integrations
│   └── selenium_service.py
└── utils/              # Shared utilities
    ├── logger.py
    └── helpers.py

关键设计决策

1. 异步优先：所有I/O操作都使用 asyncio 实现最大并发性
2. 类型安全：100%类型覆盖率，严格Mypy检查
3. Pydantic V2：系统边界的数据验证
4. 负责任的爬行：更安全的默认设置、处理后重试以及更广泛的爬网的明确选择
5. RAG就绪输出：渲染HTML加结构化JSON，用于下游分块、嵌入和检索
6. 依赖注入：服务通过构造函数接收依赖关系
7. 单一责任：每个模块都有一个明确的目的

______________________________________________________________________

🧪 发展

设置开发环境

# Clone the repository
git clone https://github.com/ruslanmv/webclone.git
cd webclone

# Install with dev dependencies
make dev

# Run tests
make test

# Run linter and type checker
make audit

# Format code
make format

运行测试

# Full test suite with coverage
make test

# Fast tests without coverage
make test-fast

# Generate HTML coverage report
make coverage

代码质量

# Lint with ruff
make lint

# Type check with mypy
make typecheck

# Format code
make format

# Run all quality checks
make audit

______________________________________________________________________

🤝 贡献

我们欢迎捐款！请看 贡献.md 作为指导方针。

快速贡献工作流程

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 进行更改
4. 进行质量检查(make audit)
5. 提交您的更改(git commit -m 'Add amazing feature')
6. 推到分支(git push origin feature/amazing-feature)
7. 打开拉取请求

______________________________________________________________________

📊 基准测试

在具有100 Mbps连接的标准4核机器上进行了测试：

\*wget无法渲染基于JavaScript的SPA

______________________________________________________________________

📄 许可证

该项目根据 Apache许可证2.0 -看看 许可证 文件以获取详细信息。

______________________________________________________________________

👤 作者

鲁斯兰 马加纳

• 网站： ruslanmv.com
• github： @ruslanmv
• 电子邮件：contact@ruslanmv.com

______________________________________________________________________

🌟 明星历史

如果你觉得WebClone有用，请考虑给它一颗星！ ⭐

______________________________________________________________________

🙏 致谢

• 类型 -漂亮的CLI框架
• 富有的 -丰富的终端格式化
• 派丹蒂克 -数据验证
• 意图tp -异步HTTP客户端
• 紫外线 -闪电般快速的软件包安装程序

______________________________________________________________________

制作❤️ 通过 鲁斯兰 马加纳