Enhanced Crawl MCP

爬行MCP（或“漫游MCP”，具体翻译取决于上下文，MCP可能指某种特定的系统、协议或概念）

  

一个基于FastAPI的高性能微服务，专为网页爬取优化，以满足AI和大型语言模型（LLM）的需求。它能将网页转换成简洁、结构化的Markdown格式，非常适合用于检索增强生成（RAG）系统、AI代理和数据管道。

特性/功能

✨（这个表情符号通常表示闪耀、光芒或兴奋，没有直接对应的中文翻译，但可以意译为“闪闪发光”或根据上下文用类似的情感表达） 核心能力

• 🌐 单个URL爬取并转换为Markdown格式
• 📦 批量URL抓取并使用并发处理
• 🔗 链接和图片提取
• ⚡ 高性能的异步/等待架构
• 🔄 带指数退避的自动重试逻辑
• 📊 实时作业状态追踪

🛡️ 翻译为中文是：“护盾”或“防御”。这个符号通常用来表示保护、防御或抵御的意象。 可靠性与安全性

• ⏱️ 可配置的超时和速率限制
• 🚫 域名屏蔽和URL验证
• 🔒 方案验证（仅限http/https）
• 📝 结构化日志记录（JSON/文本格式）
• 🎯 请求ID追踪

🚀 表情符号“🚀”通常表示火箭、快速前进或快速上升等含义，没有直接的中文翻译，但可以根据上下文理解为“火箭”、“飞速前进”或“快速提升”等。 开发者体验

• 📖 自动生成的OpenAPI文档
• 🐳 支持 Docker 和 Docker Compose
• 🧪 全面的测试套件（覆盖率80%+）
• 🔧 基于环境的配置
• 🎨 提交前钩子和代码质量工具

快速入门

先决条件

• Python 3.10或更高版本
• pip 和 virtualenv

安装

1. 克隆仓库

git clone 
cd crawl-mcp

1. 创建并激活虚拟环境

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

1. 安装依赖项

pip install -r requirements.txt

1. 配置环境（可选）

cp .env.example .env
# Edit .env with your preferences

1. 运行服务器

# Option 1: Direct
python -m uvicorn app.main:app --host 0.0.0.0 --port 8012

# Option 2: Using script
./run_crawler.sh

# Option 3: Using tmux (recommended for persistent sessions)
./start_crawl_mcp_tmux.sh

API将可用 http://localhost:8012

Docker 部署

# Build and run with Docker Compose
docker-compose up -d

# Or build manually
docker build -t crawl-mcp .
docker run -p 8012:8012 crawl-mcp

使用方法

基本爬行

curl -X POST http://localhost:8012/api/v1/crawl \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

高级爬取功能（含选项）

curl -X POST http://localhost:8012/api/v1/crawl \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "include_links": true,
    "include_images": true,
    "timeout": 30
  }'

批量抓取

curl -X POST http://localhost:8012/api/v1/crawl/batch \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://example.com",
      "https://example.org"
    ],
    "include_links": true
  }'

检查作业状态

curl http://localhost:8012/api/v1/crawl/status/{job_id}

验证URL

curl -X POST http://localhost:8012/api/v1/crawl/validate \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

服务器统计

curl http://localhost:8012/api/v1/stats

API 文档

交互式API文档可在以下位置获取：

• Swagger UI： http://localhost:8012/docs
• ReDoc（注：这是一个专有名词或特定项目/工具的名称，在中文中通常直接保留原名，不进行翻译，但根据语境，有时也可根据其功能或特性进行意译，不过在此处直接给出原名更为准确。）： http://localhost:8012/redoc
• OpenAPI JSON： http://localhost:8012/openapi.json

如需详细的API参考，请参阅 根据上面的信息，执行如下指令：

配置

该应用程序可以通过环境变量进行配置。请参阅 .env.example 对于所有可用选项。

关键配置选项

发展

设置开发环境

# Install dev dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Run tests
pytest

# Run tests with coverage
pytest --cov=app --cov-report=html

# Format code
black app/ tests/
isort app/ tests/

# Lint
ruff check app/
mypy app/

运行测试

# All tests
pytest

# Unit tests only
pytest tests/unit/

# Integration tests
pytest tests/integration/

# E2E tests
pytest tests/e2e/

# With coverage report
pytest --cov=app --cov-report=term-missing

项目结构

crawl-mcp/
├── app/                    # Application code
│   ├── api/               # API routes and dependencies
│   ├── core/              # Core business logic
│   ├── utils/             # Utilities (logging, validators)
│   ├── config.py          # Configuration
│   ├── models.py          # Pydantic models
│   └── main.py            # FastAPI app
├── tests/                 # Test suite
│   ├── unit/              # Unit tests
│   ├── integration/       # Integration tests
│   └── e2e/               # End-to-end tests
├── docs/                  # Documentation
├── scripts/               # Utility scripts
├── .github/workflows/     # CI/CD workflows
├── Dockerfile             # Docker configuration
├── docker-compose.yml     # Docker Compose config
├── pyproject.toml         # Project metadata
└── requirements.txt       # Python dependencies

建筑

如需详细的架构文档，请参阅 ARCHITECTURE.md 翻译为中文是：“架构.md”（其中“.md”通常表示Markdown格式文件）

部署

如需生产部署指南，请参阅 DEPLOYMENT.md 翻译为中文是：“部署说明.md” 或 “部署文档.md”，具体取决于上下文，但通常“DEPLOYMENT”指的是与部署相关的说明或文档，而“.md”表示这是一个Markdown格式的文件

做出贡献

1. 为仓库创建分支（或“克隆仓库”）
2. 创建一个特性分支（git checkout -b feature/amazing-feature)
3. 提交您的更改（git commit -m 'Add some amazing feature')
4. 推送到分支（git push origin feature/amazing-feature）
5. 提交一个拉取请求（或合并请求）

请阅读 DEVELOPMENT.md 翻译为中文是：“开发指南.md” 或 “开发文档.md”（具体翻译可能根据上下文有所调整，但基本意思是指一个关于开发的Markdown文件） 作为开发指南。

许可证

此项目采用MIT许可证授权——详情请参阅LICENSE文件。

致谢

• 构建于 FastAPI
• 由……提供支持/驱动 Crawl4AI（可译为“针对AI的爬虫”或根据具体语境意译为“AI专用爬虫工具/系统”等）
• 受人工智能友好型网页内容提取需求的启发

支持

• 📖 书籍 文档
• 🐛（这个符号在中文里通常被理解为“虫子”或“错误”的意思，但直接翻译可能无法准确传达其在特定语境下的含义，所以这里保留原样，若需具体语境下的翻译，请提供更多上下文） 问题追踪器
• 💬 讨论

______________________________________________________________________

为AI/LLM社区倾心打造

重要提示

这个（或“该”） libs/crawl4ai 目录未包含在仓库中。crawl4ai 库是通过 pip 安装的：

pip install crawl4ai

这保持了仓库大小的可控性，并确保您始终获取到与最新版本兼容的 crawl4ai。