使用说明

🕷️ Selenium MCP Server

MCP server (stdio) sử dụng Selenium để crawl và trích xuất dữ liệu từ web pages bằng CSS/XPath selectors.

✨ Tính Năng

MCP Tools (17 tools)

Tool	Mô Tả
`extract`	Trích xuất dữ liệu cơ bản với CSS/XPath selectors
`analyze_page`	Phân tích cấu trúc trang trước khi extract
`smart_extract`	Tự động detect loại trang và extract (products, article, all)
`crawl_all_pages`	Crawl nhiều trang với pagination
`crawl_infinite_scroll`	Xử lý lazy loading/infinite scroll
`discover_site`	Khám phá sitemap, categories, navigation
`crawl_category_list`	Crawl nhiều category URLs
`deep_crawl`	Crawl listing + chi tiết từng sản phẩm
`extract_product_details`	Extract chi tiết từ danh sách URLs
`export_results`	Xuất CSV/JSON
`take_screenshot`	Chụp full-page screenshot
`take_element_screenshot`	Chụp screenshot của element cụ thể
`manage_cookies`	Get/Set/Clear browser cookies
`login_and_extract`	Đăng nhập và extract từ trang protected
`execute_javascript`	Thực thi JavaScript tùy chỉnh
`get_page_metrics`	Lấy performance metrics của trang

REST API Endpoints

Server cũng cung cấp REST API đầy đủ qua FastAPI:

POST /extract - Basic extraction
POST /smart-extract - Smart extraction
POST /analyze - Analyze page
POST /crawl/pages - Crawl with pagination
POST /crawl/infinite-scroll - Handle infinite scroll
POST /crawl/categories - Crawl categories
POST /crawl/deep - Deep crawl
POST /discover - Discover site
POST /products/details - Product details
POST /screenshot - Capture screenshot
POST /export - Export data
GET /jobs - List jobs
GET /outputs - List output files

🚀 Cài Đặt

# Clone repo
git clone https://github.com/Tai-DT/mcp-crawler.git
cd mcp-crawler

# Tạo virtual environment
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# hoặc: venv\Scripts\activate  # Windows

# Cài đặt dependencies
pip install -r requirements.txt

📦 Chạy Server

MCP Server (cho AI clients)

# Stdio mode (mặc định, cho MCP clients)
python3 selenium_mcp_server.py

# HTTP mode (cho debugging)
python3 selenium_mcp_server.py --transport streamable-http --host 127.0.0.1 --port 8000

REST API Server

python3 server_api.py
# API sẽ chạy tại http://localhost:8000

Docker

docker-compose up -d
# API: http://localhost:8000

⚙️ Cấu Hình MCP Client

VS Code (mcp.json)

{
  "servers": {
    "local/selenium-crawler": {
      "type": "stdio",
      "command": "/path/to/mcp-crawler/venv/bin/python",
      "args": ["/path/to/mcp-crawler/selenium_mcp_server.py"],
      "env": {}
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "selenium-crawler": {
      "command": "python3",
      "args": ["/path/to/mcp-crawler/selenium_mcp_server.py"]
    }
  }
}

📖 Ví Dụ Sử Dụng

Basic Extract

{
  "url": "https://example.com",
  "fields": {
    "title": "css:h1",
    "description": "css:p",
    "links": {"selector": "css:a", "attribute": "href", "multiple": true}
  }
}

Smart Extract Products

{
  "url": "https://shop.example.com/category",
  "extract_type": "products",
  "limit": 50,
  "normalize_prices": true
}

Deep Crawl

{
  "url": "https://shop.example.com/products",
  "follow_links": "products",
  "max_links": 20,
  "normalize_prices": true
}

Screenshot

{
  "url": "https://example.com",
  "full_page": true,
  "width": 1920,
  "height": 1080
}

Login and Extract

{
  "login_url": "https://example.com/login",
  "target_url": "https://example.com/dashboard",
  "username_selector": "css:#email",
  "password_selector": "css:#password",
  "submit_selector": "css:button[type='submit']",
  "username": "user@example.com",
  "password": "password123",
  "fields": {
    "welcome_message": "css:.welcome",
    "account_name": "css:.account-name"
  }
}

🔄 Retry & Error Handling

Server có built-in retry với exponential backoff:

Max Retries: 3 lần
Initial Delay: 1 giây
Backoff Factor: 2x
Rate Limiting: 30 requests/phút

📁 Cấu Trúc Dự Án

mcp-crawler/
├── selenium_mcp_server.py  # MCP Server chính (17 tools)
├── server_api.py           # REST API (FastAPI)
├── crawler_engine.py       # Crawler engine core
├── extraction_utils.py     # Tiện ích xử lý dữ liệu
├── config.py               # Configuration management
├── retry_handler.py        # Retry & rate limiting
├── job_manager.py          # Job tracking & persistence
├── requirements.txt        # Python dependencies
├── Dockerfile              # Docker image
├── docker-compose.yml      # Docker Compose
├── outputs/                # Extracted data
│   └── screenshots/        # Captured screenshots
├── jobs/                   # Job history
└── scripts/                # Test scripts

🧪 Testing

# Test crawler engine
python3 test_mcp.py

# Smoke test MCP server
python3 scripts/smoke_test_stdio.py

📝 License

MIT