BasicWebCrawler

一个简单但功能强大的网页爬虫工具，可以将网页内容转换为Markdown格式，并自动下载和保存图片。特别优化了对知乎等特定网站的支持。

功能特点

• 将网页内容转换为Markdown格式
• 自动下载和本地化图片资源
• 智能提取网页主要内容
• 支持网站特定的爬取配置
• 支持需要登录的网站（通过cookies）
• 自动处理相对路径和绝对路径的图片URL
• 智能过滤广告和无关内容
• 支持自定义图片保存目录
• 自动从文本中提取URL并批量爬取
• 支持B站、知乎、AI Base等多个平台
• 新增：基于 FastMCP 的 MCP 服务器支持
• AI 助手集成：可通过 Claude Desktop、Cursor 等 AI 工具直接调用
• 交互式浏览器抓取：集成 Playwright 动作序列（默认头显模式），支持登录、点击、滚动、等待渲染后抓取并生成 Markdown

项目结构

BasicWebCrawler/
├── crawler.py                      # 核心爬虫模块，包含网页抓取和转换功能
├── cookie_helper.py                # Cookie获取助手，用于需要登录的网站
├── requirements.txt                # Python依赖包列表
├── README.md                       # 项目说明文档
├── zhihu_cookies.json             # 知乎网站的cookies文件（自动生成）
├── assets/                        # 文档资源文件夹
│   └── image.png                  # 说明图片
├── mcp_server/                    # MCP服务器模块
│   ├── mcp_server.py              # 核心MCP服务器实现，提供AI助手集成（含 interactive_crawl）
│   ├── start_mcp_server.py        # 统一启动脚本，支持多传输方式和依赖检查
│   ├── debug_mcp.py               # MCP服务器调试脚本，用于功能测试
│   └── MCP_USAGE_EXAMPLES.md      # MCP使用示例和详细说明文档
└── tests/                         # 测试模块
    ├── __init__.py                # 测试包初始化文件
    ├── test_url_extraction.py     # URL提取功能测试
    ├── test_site_configs.py       # 网站配置测试
    └── test_mcp_server.py          # MCP服务器完整功能测试

核心文件说明

• crawler.py - 主要爬虫逻辑，包含网页内容提取、图片下载、Markdown转换等核心功能
• cookie_helper.py - 辅助工具，帮助用户获取和管理网站cookies，特别适用于需要登录的网站
• mcp_server/mcp_server.py - 基于 FastMCP 的服务器实现，提供 6 个工具（含交互抓取）、1 个资源、2 个提示模板
• mcp_server/start_mcp_server.py - 统一启动脚本，集成依赖检查、多传输方式支持、配置示例显示
• mcp_server/debug_mcp.py - 开发调试工具，用于测试MCP服务器各项功能是否正常
• mcp_server/MCP_USAGE_EXAMPLES.md - 详细的MCP使用文档，包含配置方法和使用示例
• tests/test_mcp_server.py - 全面的MCP服务器测试套件，验证所有工具和功能

安装要求

• Python 3.8+
• 依赖包：

  requests
  beautifulsoup4
  markdownify
  fastmcp
  playwright
  

安装步骤

1. 克隆项目到本地
2. 安装依赖：

   pip install requests beautifulsoup4 markdownify fastmcp

🔧（可选）启用JS渲染以抓取SPA文档站

部分文档网站（如 mineru.net）采用单页应用（SPA）架构，主要内容通过JavaScript在客户端渲染。为确保可以抓取完整内容，建议安装 Playwright：

pip install playwright
python -m playwright install

安装后，爬虫会在检测到页面需要JS渲染时自动使用Playwright获取完整HTML（无需额外配置）。如果未安装Playwright，爬虫会输出提示并退回到未渲染的HTML进行提取，可能导致内容不完整。

另外，爬虫已支持处理URL中的锚点（如 #single-file-parsing），会尽量抽取对应标题下的段落内容。

使用方法

MCP服务器模式（推荐）

MCP服务器模式允许AI助手（如Claude Desktop、Cursor等）直接调用爬虫功能。

启动MCP服务器

MCP服务器支持三种传输方式，每种适用于不同的场景：

方式一：STDIO 传输（推荐，本地集成）

特点：

• 通过标准输入输出通信，无需网络端口
• 延迟最低，最适合本地AI助手集成
• Claude Desktop官方推荐方式

启动方法：

# 方法1：使用统一启动脚本（推荐）
python mcp_server/start_mcp_server.py

# 方法2：使用统一启动脚本 + 命令行参数
python mcp_server/start_mcp_server.py --transport stdio --auto

# 方法3：直接运行Python脚本
python mcp_server/mcp_server.py

# 方法4：使用FastMCP CLI
fastmcp run mcp_server/mcp_server.py

方式二：SSE 传输（Server-Sent Events）

特点：

• 基于HTTP的服务器推送事件
• 支持远程访问和多客户端连接
• 适合Web应用和分布式系统

启动方法：

# 方法1：使用统一启动脚本（推荐）
python mcp_server/start_mcp_server.py --transport sse --host 127.0.0.1 --port 8000 --auto

# 方法2：使用FastMCP CLI
fastmcp run mcp_server/mcp_server.py --transport sse --host 127.0.0.1 --port 8000

# 方法3：修改mcp_server.py中的main函数：
# mcp.run(transport="sse", host="127.0.0.1", port=8000)

访问地址：http://127.0.0.1:8000/sse

方式三：HTTP 传输（Streamable HTTP）

特点：

• 基于HTTP流的双向通信
• 更现代的网络协议支持
• 适合云部署和企业级应用

启动方法：

# 方法1：使用统一启动脚本（推荐）
python mcp_server/start_mcp_server.py --transport http --host 127.0.0.1 --port 8000 --auto

# 方法2：使用FastMCP CLI
fastmcp run mcp_server/mcp_server.py --transport http --host 127.0.0.1 --port 8000

# 方法3：修改mcp_server.py中的main函数：
# mcp.run(transport="http", host="127.0.0.1", port=8000, path="/mcp")

访问地址：http://127.0.0.1:8000/mcp

传输方式选择指南

传输方式	使用场景	优点	缺点	推荐度
STDIO	本地AI助手集成	延迟低、配置简单、安全性较高	仅支持本地连接	推荐度：高
SSE	Web应用、远程访问	支持多客户端、可远程访问	需要端口、延迟略高	推荐度：较高
HTTP	云部署、企业应用	现代协议、双向通信	配置复杂、需要端口	推荐度：中

推荐选择：

• 🏠 本地使用：选择 STDIO 传输
• 🌐 远程访问：选择 SSE 传输
• ☁️ 云部署：选择 HTTP 传输

快速启动示例

# STDIO 传输（本地AI助手）
python mcp_server/start_mcp_server.py --transport stdio --auto

# SSE 传输（远程访问，端口8000）
python mcp_server/start_mcp_server.py --transport sse --port 8000 --auto

# HTTP 传输（云部署，自定义端口）
python mcp_server/start_mcp_server.py --transport http --host 0.0.0.0 --port 9000 --auto

# 交互式启动（显示配置示例）
python mcp_server/start_mcp_server.py --transport sse --port 8000

# 查看帮助信息
python mcp_server/start_mcp_server.py --help

提示：start_mcp_server.py 是统一的启动入口，集成了依赖检查、配置示例显示、多传输方式支持等功能。推荐使用此脚本启动 MCP 服务器。

配置AI助手

根据选择的传输方式，需要不同的配置方法：

STDIO 传输配置

Claude Desktop 配置：

打开 Claude Desktop → Settings → Developer → Edit Config，添加：

{
  "mcpServers": {
    "basic-web-crawler": {
      "command": "python",
      "args": ["D:/myWorks/BasicWebCrawler/mcp_server/mcp_server.py"],
      "cwd": "D:/myWorks/BasicWebCrawler"
    }
  }
}

Cursor 配置：

在 ~/.cursor/mcp.json 文件中添加：

{
  "mcpServers": {
    "basic-web-crawler": {
      "command": "python", 
      "args": ["D:/myWorks/BasicWebCrawler/mcp_server/mcp_server.py"],
      "cwd": "D:/myWorks/BasicWebCrawler"
    }
  }
}

SSE/HTTP 传输配置

Cherry Stuidio 配置：

{
  "mcpServers": {
    "basic-web-crawler": {
      "type": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}

HTTP 传输配置：

{
  "mcpServers": {
    "basic-web-crawler": {
      "type": "streamableHttp",
      "url": "http://localhost:9000/mcp"
    }
  }
}

使用 mcp-proxy 转换（SSE转STDIO）：

如果你的MCP服务器运行在SSE模式，但AI助手只支持STDIO，可以使用 mcp-proxy：

# 安装 mcp-proxy
uv tool install mcp-proxy

# Claude Desktop 配置
{
  "mcpServers": {
      "basic-web-crawler": {
         "command": "mcp-proxy",
         "args": ["http://127.0.0.1:8000/sse"]
      }
   }
}

MCP 工具说明

MCP服务器提供以下工具：

1. crawl_single_url - 爬取单个网页

   • 参数：url, img_folder, use_cookies, cookies_file
   • 功能：爬取指定URL并转换为Markdown

2. crawl_urls_from_text - 批量爬取 URL

   • 参数：text, img_folder, use_cookies, cookies_file
   • 功能：从文本中提取URL并批量爬取

3. extract_urls - 提取 URL 列表

   • 参数：text
   • 功能：从文本中提取所有有效URL

4. check_site_config - 检查网站配置

   • 参数：url
   • 功能：查看特定网站的爬取配置信息

5. get_supported_sites - 获取支持的网站

6. interactive_crawl - 交互式抓取（默认头显模式）

   • 参数：
     • url 初始页面地址
     • actions 动作数组（支持 goto、wait、click、type、scroll、sleep、screenshot、evaluate）
     • output_dir 可选，保存目录；未传则为仓库根目录
     • img_folder 可选，默认 images（最终为 output_dir/images）
     • use_cookies、cookies_file 可选，用于需要登录站点
     • headers 合并站点配置的请求头
     • headless 是否无头，默认 False
     • timeout_ms 默认 15000
   • 行为：执行动作序列完成交互后，获取页面 HTML，进行内容抽取与图片本地化，生成 Markdown 保存到 output_dir
   • 功能：列出所有预配置的网站

MCP 资源

• crawler://config - 爬虫配置信息（JSON格式）

MCP 提示模板

• crawl_webpage_prompt - 爬取网页的标准提示
• batch_crawl_prompt - 批量爬取的标准提示

AI助手使用示例

在AI助手中，你可以这样使用：

请帮我爬取这个网页的内容：https://www.example.com

我有一段包含多个URL的文本，请帮我批量爬取：
这里有一些有趣的链接：
https://www.github.com
https://www.stackoverflow.com

命令行模式

基本使用

1. 运行爬虫程序：

   python crawler.py

2. 选择运行模式：
   • 模式1：直接爬取单个URL
   • 模式2：从文本中提取URL并批量爬取
3. 根据提示输入内容
4. 程序会自动将内容保存为Markdown文件，并下载相关图片

从文本中提取URL并批量爬取

1. 运行爬虫程序并选择模式2：

   python crawler.py
   # 然后选择"2"

2. 输入包含URL的文本，每行输入完成后按回车
3. 输入完成后按Ctrl+Z（Windows）或Ctrl+D结束输入
4. 程序会自动从文本中提取URL，并依次爬取每个URL的内容
5. 最终生成一个包含所有爬取结果的合并Markdown文件

示例文本输入格式:

这是一个介绍文章，里面有几个链接：https://www.example.com 和 https://blog.example.org
还有一些其他网站 www.another-example.net

CLI 快捷模式（非交互）

支持通过命令行参数直接抓取，无需交互：

可用参数：

• --url, -u 目标链接
• --out, -o 输出文件路径
• --anchor section|full 控制锚点策略；full 抓取整页
• --js auto|on|off JS渲染策略；on 强制使用 Playwright
• --wait 可选，传入一个或多个 CSS 选择器，等待元素渲染

示例：

• 整页抓取（推荐）：

python3 BasicWebCrawler/crawler.py -u "https://mineru.net/doc/docs/index_en.html?theme=dark&v=1.0#single-file-parsing" --js on --anchor full --wait .theme-default-content .content__default main -o BasicWebCrawler/mineru_full_cli.md

• 单章节抓取（从 #fragment 标题到下一个同级标题）：

python3 BasicWebCrawler/crawler.py -u "https://mineru.net/doc/docs/index_en.html?theme=dark&v=1.0#single-file-parsing" --js on --anchor section -o BasicWebCrawler/mineru_section_cli.md

Mineru 文档站适配与解析改进

• 站点配置：为 mineru.net 增加选择器 ['main', '.theme-default-content', '.content__default', '.theme-container .page .content', 'div.VPDoc .VPDocContent', '#app']，并设置 wait_selectors 以确保 JS 完成渲染。
• JS 渲染：新增 Playwright 回退；可通过 --js on 强制启用，或 --js auto 自动判断。
• 锚点解析：增强章节抽取策略，只在遇到“同级或更高层级标题”时停止收集，避免只输出标题。
• 效果验证：对链接 https://mineru.net/doc/docs/index_en.html?theme=dark&v=1.0#single-file-parsing 使用整页抓取，产出约 589 行 Markdown，相比此前约 100 行显著提升。
• 清理：已移除临时脚本 run_once.py，统一使用 crawler.py 的 CLI 模式。

爬取需要登录的网站（如知乎）

1. 首先运行cookie助手获取cookies：

   python cookie_helper.py

2. 按照提示获取cookies：

   • 使用Chrome浏览器登录目标网站
   • 按F12打开开发者工具
   • 切换到"Network"(网络)标签
   • 刷新页面
   • 在请求列表中找到主域名请求
   • 在Headers中找到"Cookie:"开头的行
   • 复制完整的cookie值

   参考下图：

3. 将复制的cookies粘贴到程序中，它会自动生成zhihu_cookies.json文件

4. 运行爬虫程序并使用cookies文件：

   python crawler.py

测试

项目包含完整的单元测试，确保功能的稳定性和可靠性。

运行测试

运行所有测试：

python -m unittest discover tests

运行特定测试：

# 测试URL提取功能
python -m unittest tests.test_url_extraction

# 测试网站配置功能
python -m unittest tests.test_site_configs

测试MCP服务器

测试MCP服务器功能：

python test_mcp_server.py

测试覆盖

• URL提取测试：验证从文本中提取URL的准确性
• 批量爬取测试：测试批量处理多个URL的功能
• 网站配置测试：确保各网站特定配置的正确性
• URL清理测试：验证URL标点符号清理功能
• MCP服务器测试：验证MCP工具、资源和提示的正确性

输出说明

• Markdown文件：保存在运行目录下，文件名格式为{页面标题}_{时间戳}.md
• 图片文件：默认保存在 ./images/ 目录下；若指定了 output_dir，则保存在 output_dir/images/。图片文件名使用 MD5 哈希值。

支持的网站

• 通用网站：自动识别主要内容区域
• 知乎 (zhihu.com)：优化了内容提取和反爬处理，支持cookies认证
• 哔哩哔哩 (bilibili.com)：针对视频页面优化的内容选择器
• AI Base (aibase.com)：专门针对AI工具页面的内容提取
• 可扩展：通过修改SITE_CONFIGS配置支持更多特定网站

网站配置示例

每个网站都有专门的配置，包括：

• 特定的HTTP请求头
• 针对性的内容选择器
• Cookie需求设置

MCP服务器架构

MCP服务器基于FastMCP框架构建，提供以下特性：

• 工具(Tools)：可执行的爬虫功能
• 资源(Resources)：配置信息和元数据
• 提示(Prompts)：标准化的交互模板
• 异步支持：高性能的并发处理
• 类型安全：完整的类型注解和验证

部署选项

1. 本地部署：直接运行Python脚本
2. 容器部署：使用Docker容器化部署
3. 云服务：部署到云平台提供API服务

注意事项

1. 对于需要登录的网站，cookies可能会定期失效，需要重新获取
2. 部分网站可能有反爬虫机制，建议控制爬取频率
3. 图片下载可能受网络条件影响
4. 确保有足够的磁盘空间存储图片
5. MCP服务器需要保持运行状态以供AI助手调用

自定义配置

可以通过修改crawler.py中的SITE_CONFIGS字典来添加新的网站配置：

SITE_CONFIGS = {
    'example.com': {
        'headers': {
            'Referer': 'https://example.com',
            # 其他请求头
        },
        'main_content_selectors': ['.article', '#main-content'],
        'needs_cookies': False
    }
}

常见问题

1. 403错误

   • 检查cookies是否有效
   • 确认是否需要登录
   • 检查网站是否有反爬虫机制

2. 图片下载失败

   • 检查网络连接
   • 确认图片URL是否有效
   • 检查是否有足够的存储空间

3. 内容提取不完整

   • 可能需要调整内容选择器
   • 检查网页结构是否符合预期

4. MCP服务器连接失败

   • 确认服务器正在运行
   • 检查配置文件路径是否正确
   • 验证Python环境和依赖是否安装

微信公众号定向采集系统（wechat_collector）

基于 BasicWebCrawler 延伸的采集子系统，对 3000+ 组织做「搜狗 Playwright 自动发现 + Worker 抓取入库 + 浏览器插件补采 + 覆盖率监控」。

完整使用手册（小白请从这里读）：wechat_collector/README.md 第 2 节

快速启动（全自动，推荐）

cd BasicWebCrawler

# 1. 依赖 + Playwright 浏览器
pip install -r requirements-collector.txt
playwright install chromium

# 2. 配置（至少改 Token，并开启 SOGOU_PLAYWRIGHT_ENABLED=true）
cp .env.example .env

# 3. 数据库 + 公众号
alembic upgrade head
python -m wechat_collector.io.import_wechat_accounts samples/pilot_wechat_accounts.csv

# 4. 三个终端分别运行：
#    终端 1 — API
uvicorn wechat_collector.api.app:app --reload --port 8787
#    终端 2 — 搜狗发现（首次建议 SOGOU_HEADLESS=false ... sogou_poller --once 养 cookie）
python -m wechat_collector.worker.sogou_poller
#    终端 3 — 抓取入库
python -m wechat_collector.worker

• 阅读台：http://127.0.0.1:8787/admin（粘贴 .env 里的 Token）
• 管理配置：http://127.0.0.1:8787/admin/manage
• 接口文档：http://127.0.0.1:8787/docs

快速启动（仅插件，可选）

pip install -r requirements-collector.txt
cp .env.example .env   # 设置 COLLECTOR_API_TOKEN
alembic upgrade head
python -m wechat_collector.io.import_wechat_accounts samples/pilot_wechat_accounts.csv
uvicorn wechat_collector.api.app:app --reload --port 8787
# Chrome 加载 extension/ 目录，打开微信文章后点「采集当前文章」

目录结构

wechat_collector/
├── api/               # FastAPI 路由（articles / candidates / accounts / admin 等）
├── db/                # SQLAlchemy ORM + SessionLocal
├── discovery/         # 多源发现层
│   └── providers/     # bing / baidu / sogou / sogou_playwright
├── io/                # 命令行工具脚本
│   ├── import_wechat_accounts.py   # 批量导入公众号 CSV
│   ├── enqueue_wechat_urls.py      # URL 批量入候选池
│   └── show_biz_status.py          # 查看 __biz 填充进度
├── migrations/        # Alembic 迁移脚本（001~004）
├── parsers/           # 微信文章 HTML 解析
├── services/          # 业务逻辑（article / candidate / org）
├── worker/
│   ├── fetch_worker.py   # 候选池消费 Worker（fetch + parse + 入库）
│   └── sogou_poller.py   # Playwright 搜狗发现 Worker
└── README.md          # 完整使用手册
extension/             # Chrome MV3 插件（手动 M1 + 自动队列 M2）
samples/               # 示例 CSV 和 HTML 快照

主要 API 接口

接口	说明
POST /api/articles	插件推送文章入库
GET /api/crawl/tasks/next	插件拉取下一个抓取任务
GET /api/accounts	查看所有公众号
POST /api/discovery/run	手动触发多源发现
GET /api/coverage/report	覆盖率报表
POST /api/monitoring/refresh	刷新账号健康度
GET /admin	文章后台（浏览器打开）

后台 Worker 进程

# Worker 1：处理候选池（fetch + parse + 入库），随机间隔防反爬
python -m wechat_collector.worker

# Worker 2：Playwright 搜狗发现（推荐，需 SOGOU_PLAYWRIGHT_ENABLED=true）
SOGOU_PLAYWRIGHT_ENABLED=true python -m wechat_collector.worker.sogou_poller

数据表

表	说明
organizations	组织主数据
wechat_accounts	公众号账号（含 biz）
article_candidates	文章候选池（队列，含状态机）
articles	已采集正文
account_health	公众号健康度统计
discovery_source_stats	发现源运行统计

调度与重试

• 任务失败退避：10min → 1h → 6h，第 4 次升级 manual 人工处理
• 账号限频：同一账号 SCHEDULER_MAX_ACCOUNT_INTERVAL_SECONDS（默认 60s）内不重复取任务
• 发现源健康：连续空结果达阈值自动标 warning

贡献指南

欢迎提交Issue和Pull Request来改进项目。在提交代码前，请确保：

1. 代码符合Python代码规范
2. 添加了必要的注释
3. 更新了相关文档
4. 通过了所有测试

许可证

MIT License