scrapling-mcp

Scrapling MCP — Web スクレイピングガイダンス

ソースリポジトリ：https://github.com/DevBD1/skills/tree/main/openclaw-skill-scrapling-mcp

ガイダンスレイヤー + MCP 統合
戦略とパターンには、このスキルを使用してください。実行には、mcporter 経由で Scrapling の MCP サーバーを呼び出してください。

クイックスタート（MCP）

1. MCP サポート付きで Scrapling をインストールする

pip install scrapling[mcp]
# Or for full features:
pip install scrapling[mcp,playwright]
python -m playwright install chromium

2. OpenClaw の MCP 設定に追加する

{
  "mcpServers": {
    "scrapling": {
      "command": "python",
      "args": ["-m", "scrapling.mcp"]
    }
  }
}

3. mcporter 経由で呼び出す

mcporter call scrapling fetch_page --url "https://example.com"

実行とガイダンス

タスク	ツール	例
ページを取得する	mcporter	mcporter call scrapling fetch_page --url URL
CSS で抽出する	mcporter	mcporter call scrapling css_select --selector ".title::text"
どのフェッチャーを使うか？	このスキル	下記の「フェッチャー選択ガイド」を参照
ボット対策の戦略は？	このスキル	「ボット対策の段階的エスカレーション」を参照
複雑なクロールのパターンは？	このスキル	「スパイダーのレシピ」を参照

フェッチャー選択ガイド

┌─────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│   Fetcher       │────▶│ DynamicFetcher   │────▶│ StealthyFetcher  │
│   (HTTP)        │     │ (Browser/JS)     │     │ (Anti-bot)       │
└─────────────────┘     └──────────────────┘     └──────────────────┘
     Fastest              JS-rendered               Cloudflare, 
     Static pages         SPAs, React/Vue          Turnstile, etc.

判断フロー

1. 静的 HTML ですか？ → Fetcher（10～100 倍高速）
2. JS の実行が必要ですか？ → DynamicFetcher
3. ブロックされていますか？ → StealthyFetcher
4. 複雑なセッションですか？ → Session の各バリアントを使用

MCP のフェッチモード

• fetch_page — HTTP フェッチャー
• fetch_dynamic — Playwright を使ったブラウザベースのフェッチャー
• fetch_stealthy — ボット対策の回避モード

ボット対策の段階的エスカレーション

レベル 1：丁寧な HTTP

# MCP call: fetch_page with options
{
  "url": "https://example.com",
  "headers": {"User-Agent": "..."},
  "delay": 2.0
}

レベル 2：セッションの維持

# Use sessions for cookie/state across requests
FetcherSession(impersonate="chrome")  # TLS fingerprint spoofing

レベル 3：ステルスモード

# MCP: fetch_stealthy
StealthyFetcher.fetch(
    url,
    headless=True,
    solve_cloudflare=True,  # Auto-solve Turnstile
    network_idle=True
)

レベル 4：プロキシローテーション

references/proxy-rotation.md を参照してください

アダプティブスクレイピング（壊れにくい設計）

Scrapling は、アダプティブセレクターを使ってウェブサイトのリデザイン後も動作を維持できます。

# First run — save fingerprints
products = page.css('.product', auto_save=True)

# Later runs — auto-relocate if DOM changed
products = page.css('.product', adaptive=True)

MCP の使用方法：

mcporter call scrapling css_select \\
  --selector ".product" \\
  --adaptive true \\
  --auto-save true

スパイダーフレームワーク（大規模クロール）

スパイダーと直接フェッチを使い分ける基準：

• ✅ スパイダー：10 ページ以上、並行処理が必要、再開機能、プロキシローテーション
• ✅ 直接フェッチ：1～5 ページ、素早い抽出、シンプルな処理フロー

基本的なスパイダーパターン

from scrapling.spiders import Spider, Response

class ProductSpider(Spider):
    name = "products"
    start_urls = ["https://example.com/products"]
    concurrent_requests = 10
    download_delay = 1.0
    
    async def parse(self, response: Response):
        for product in response.css('.product'):
            yield {
                "name": product.css('h2::text').get(),
                "price": product.css('.price::text').get(),
                "url": response.url
            }
        
        # Follow pagination
        next_page = response.css('.next a::attr(href)').get()
        if next_page:
            yield response.follow(next_page)

# Run with resume capability
result = ProductSpider(crawldir="./crawl_data").start()
result.items.to_jsonl("products.jsonl")

上級：マルチセッションスパイダー

from scrapling.spiders import Spider, Request, Response
from scrapling.fetchers import FetcherSession, AsyncStealthySession

class MultiSessionSpider(Spider):
    name = "multi"
    start_urls = ["https://example.com/"]
    
    def configure_sessions(self, manager):
        manager.add("fast", FetcherSession(impersonate="chrome"))
        manager.add("stealth", AsyncStealthySession(headless=True), lazy=True)
    
    async def parse(self, response: Response):
        for link in response.css('a::attr(href)').getall():
            if "/protected/" in link:
                yield Request(link, sid="stealth")
            else:
                yield Request(link, sid="fast")

スパイダーの機能

• 一時停止／再開：crawldir パラメーターでチェックポイントを保存
• ストリーミング：リアルタイム処理には async for item in spider.stream() を使用
• 自動再試行：ブロックされたリクエストに対する再試行を設定可能
• エクスポート：組み込みの to_json()、to_jsonl()

CLI とインタラクティブシェル

ターミナルでの抽出（コード不要）

# Extract to markdown
scrapling extract get 'https://example.com' content.md

# Extract specific element
scrapling extract get 'https://example.com' content.txt \\
  --css-selector '.article' \\
  --impersonate 'chrome'

# Stealth mode
scrapling extract stealthy-fetch 'https://protected.com' content.md \\
  --no-headless \\
  --solve-cloudflare

インタラクティブシェル

scrapling shell

# Inside shell:
>>> page = Fetcher.get('https://example.com')
>>> page.css('h1::text').get()
>>> page.find_all('div', class_='item')

パーサー API（CSS／XPath 以外）

BeautifulSoup 風のメソッド

# Find by attributes
page.find_all('div', {'class': 'product', 'data-id': True})
page.find_all('div', class_='product', id=re.compile(r'item-\\d+'))

# Text search
page.find_by_text('Add to Cart', tag='button')
page.find_by_regex(r'\\$\\d+\\.\\d{2}')

# Navigation
first = page.css('.product')[0]
parent = first.parent
siblings = first.next_siblings
children = first.children

# Similarity
similar = first.find_similar()  # Find visually/structurally similar elements
below = first.below_elements()  # Elements below in DOM

自動生成セレクター

# Get robust selector for any element
element = page.css('.product')[0]
selector = element.auto_css_selector()  # Returns stable CSS path
xpath = element.auto_xpath()

プロキシローテーション

from scrapling.spiders import ProxyRotator

# Cyclic rotation
rotator = ProxyRotator([
    "http://proxy1:8080",
    "http://proxy2:8080",
    "http://user:pass@proxy3:8080"
], strategy="cyclic")

# Use with any session
with FetcherSession(proxy=rotator.next()) as session:
    page = session.get('https://example.com')

よく使うレシピ

ページネーションのパターン

# Page numbers
for page_num in range(1, 11):
    url = f"https://example.com/products?page={page_num}"
    ...

# Next button
while next_page := response.css('.next a::attr(href)').get():
    yield response.follow(next_page)

# Infinite scroll (DynamicFetcher)
with DynamicSession() as session:
    page = session.fetch(url)
    page.scroll_to_bottom()
    items = page.css('.item').getall()

ログインセッション

with StealthySession(headless=False) as session:
    # Login
    login_page = session.fetch('https://example.com/login')
    login_page.fill('input[name="username"]', 'user')
    login_page.fill('input[name="password"]', 'pass')
    login_page.click('button[type="submit"]')
    
    # Now session has cookies
    protected_page = session.fetch('https://example.com/dashboard')

Next.js データの抽出

# Extract JSON from __NEXT_DATA__
import json
import re

next_data = json.loads(
    re.search(
        r'__NEXT_DATA__" type="application/json">(.*?)</script>',
        page.html_content,
        re.S
    ).group(1)
)
props = next_data['props']['pageProps']

出力形式

# JSON (pretty)
result.items.to_json('output.json')

# JSONL (streaming, one per line)
result.items.to_jsonl('output.jsonl')

# Python objects
for item in result.items:
    print(item['title'])

パフォーマンスのヒント

1. 可能な場合は HTTP フェッチャーを使用する — ブラウザより 10～100 倍高速
2. ブラウザーになりすます — TLS フィンガープリントには impersonate='chrome' を使用
3. HTTP/3 をサポート — FetcherSession(http3=True)
4. リソースを制限する — Dynamic／Stealthy では disable_resources=True を設定
5. 接続プーリング — リクエスト間でセッションを再利用

ガードレール（必ず守ること）

• アクセスを許可されているコンテンツのみをスクレイピングしてください
• robots.txt と利用規約を尊重してください
• 大規模なクロールでは遅延（download_delay）を追加してください
• 許可なくペイウォールや認証を回避しないでください
• 個人データや機密データを決してスクレイピングしないでください

参考資料

• references/mcp-setup.md — MCP の詳細な設定
• references/anti-bot.md — ボット対策の手法
• references/proxy-rotation.md — プロキシの設定とローテーション
• references/spider-recipes.md — 高度なクロールパターン
• references/api-reference.md — API クイックリファレンス
• references/links.md — 公式ドキュメントへのリンク

スクリプト

• scripts/scrapling_scrape.py — 単発の抽出をすばやく実行
• scripts/scrapling_smoke_test.py — 接続とボット対策の兆候をテスト