Arachne MCP

Arachne MCP adalah web-intelligence server self-hosted untuk Hermes Agent dan klien MCP lain. Proyek ini merupakan penerus web-crawler-mcp versi ringan, dengan arsitektur hybrid HTTP + browser, parser dokumen, crawl budgets, search adapter, structured extraction, browser sessions, dan change detection.

Target proyek ini bukan menjanjikan bahwa semua website pasti dapat diambil. CAPTCHA, login tanpa izin, paywall, anti-bot tingkat lanjut, dan pembatasan hukum tetap harus dihormati. Target yang realistis adalah menjadi crawler self-hosted yang lebih dapat dikendalikan dan lebih cocok untuk agent dibandingkan layanan generik.

Fitur utama

• Auto-escalation HTTP → Chromium: mencoba request HTTP yang cepat, kemudian otomatis memakai Playwright bila HTML terlihat kosong atau bergantung pada JavaScript.

• 13 MCP tools: scrape, crawl, batch, map, parse, search, structured extraction, browser interaction, diff, chunking, dan diagnostics.

• Parser multi-format: HTML, plain text, JSON, XML/RSS/Atom, PDF, DOCX, XLSX, CSV, dan TSV.

• Main-content extraction: Trafilatura sebagai extractor utama, lalu DOM/BeautifulSoup sebagai fallback untuk dokumentasi dan tabel.

• Recursive sitemap discovery: membaca sitemap index bertingkat dan menggabungkannya dengan shallow link discovery.

• Strict crawl budgets: max_pages, max_requests, max_errors, max_depth, max_total_chars, dan max_response_bytes berdiri sendiri.

• Per-host rate limiter: jeda diterapkan sebelum request berikutnya, termasuk crawl delay dari robots.txt.

• Retry yang terkontrol: exponential backoff serta dukungan Retry-After untuk 429 dan error sementara.

• Persistent SQLite cache: mengurangi request dan token untuk halaman yang sama.

• Change detection: menyimpan snapshot dan mengembalikan unified diff.

• Persistent browser session: menyimpan cookie/storage state dengan session_id untuk alur login yang memang diotorisasi.

• Search adapter: SearXNG self-hosted atau Brave Search.

• Structured JSON extraction: memakai endpoint LLM OpenAI-compatible, termasuk 9Router/OpenRouter/OpenAI.

• Agent safety: hasil web ditandai sebagai untrusted content dan dipindai untuk pola prompt injection umum.

• SSRF baseline protection: memblokir localhost, IP privat, link-local, reserved, dan memvalidasi setiap redirect.

• Proxy support: satu proxy HTTP/HTTPS dapat dikonfigurasi untuk HTTP dan browser engine.

• Content deduplication: halaman duplikat dikenali melalui SHA-256 agar output crawl tidak boros konteks.

Related MCP server: servo-fetch

Tool MCP

Instalasi lokal

Persyaratan:

• Python 3.11+

• macOS, Linux, atau Windows

• Chromium Playwright untuk mode browser

unzip arachne-mcp.zip
cd arachne-mcp

cp .env.example .env
python3 -m venv .venv
source .venv/bin/activate

pip install -e '.[full]'
playwright install chromium

arachne-mcp

Default transport adalah STDIO. Untuk Streamable HTTP:

MCP_TRANSPORT=streamable-http MCP_HOST=0.0.0.0 MCP_PORT=8000 arachne-mcp

Endpoint-nya:

http://127.0.0.1:8000/mcp

Menjalankan dengan Docker

Buat external network bersama Hermes sekali saja:

docker network create hermes-net

Kemudian:

cp .env.example .env
docker compose up -d --build

Pemeriksaan:

docker compose ps
docker logs arachne-mcp --tail 100

Port hanya dipublikasikan ke 127.0.0.1. Container Hermes berkomunikasi melalui network internal menggunakan:

http://arachne-mcp:8000/mcp

Hubungkan ke Hermes Agent

Tambahkan pada config.yaml Hermes:

mcp_servers:
  arachne:
    url: "http://arachne-mcp:8000/mcp"
    enabled: true
    connect_timeout: 30
    timeout: 300
    supports_parallel_tool_calls: false
    tools:
      include:
        - health
        - crawl_url
        - parse_url
        - crawl_site
        - batch_scrape
        - map_site
        - extract_links
        - check_robots
        - browser_interact
        - search_web
        - extract_structured
        - crawl_diff
        - chunk_content
      resources: false
      prompts: false

Restart Hermes:

cd /srv/hermes
docker compose up -d
docker logs hermes_container --tail 100

Contoh prompt Telegram:

Gunakan Arachne untuk crawl dokumentasi https://example.com/docs.
Gunakan maksimum 20 halaman, 50 request, kedalaman 3, dan total output 80.000 karakter.
Rangkum hasilnya dan sertakan halaman sumber untuk setiap bagian.

Untuk halaman JavaScript:

Gunakan crawl_url Arachne dengan render_mode browser untuk membuka URL ini.
Tunggu 2 detik, ambil Markdown dan daftar link internalnya.

Browser actions

Contoh input browser_interact:

{
  "url": "https://example.com/products",
  "actions": [
    {"type": "fill", "selector": "input[name=q]", "value": "keyboard"},
    {"type": "press", "selector": "input[name=q]", "key": "Enter"},
    {"type": "wait", "selector": ".results", "state": "visible"},
    {"type": "scroll", "pixels": 1200}
  ],
  "screenshot": false
}

Action yang tersedia:

• click: membutuhkan selector

• fill: selector, value

• press: opsional selector, serta key

• select: selector, value

• wait: selector atau ms

• scroll: pixels

• goto: url

• evaluate: script, tetapi default dinonaktifkan

Arachne tidak menyediakan action untuk melewati CAPTCHA atau access control.

Persistent browser session

Gunakan session_id dan persist_session=true:

{
  "url": "https://portal.example.com/login",
  "session_id": "portal-example",
  "persist_session": true,
  "actions": [
    {"type": "fill", "selector": "#email", "value": "user@example.com"},
    {"type": "fill", "selector": "#password", "value": "..."},
    {"type": "click", "selector": "button[type=submit]"},
    {"type": "wait", "selector": ".dashboard"}
  ]
}

Storage state disimpan di data/browser-sessions. Lindungi folder tersebut karena dapat mengandung cookie autentikasi. Jangan mengirim password melalui prompt pada channel yang tidak privat; lebih aman menyediakan session state secara manual.

Search self-hosted

SearXNG

Atur:

SEARXNG_URL=http://searxng:8080

Arachne memakai output JSON SearXNG, lalu dapat melakukan scrape terhadap hasil yang dipilih.

Brave Search

BRAVE_SEARCH_API_KEY=your-key

SearXNG lebih cocok bila prioritasnya adalah kontrol dan self-hosting penuh.

Structured extraction melalui 9Router

Contoh .env:

LLM_BASE_URL=http://9router:20128/v1
LLM_API_KEY=your-9router-key
LLM_MODEL=kr/qwen3-coder-next

Contoh tool input:

{
  "url": "https://example.com/product/1",
  "instruction": "Ambil informasi produk yang terlihat pada halaman.",
  "schema": {
    "type": "object",
    "properties": {
      "name": {"type": "string"},
      "price": {"type": ["number", "null"]},
      "currency": {"type": ["string", "null"]}
    },
    "required": ["name", "price", "currency"],
    "additionalProperties": false
  }
}

Model harus mendukung endpoint /chat/completions. Jika model tidak mendukung json_schema, Arachne otomatis mencoba ulang tanpa response_format, lalu memvalidasi JSON yang dihasilkan.

Crawl budgets yang disarankan untuk Hermes

Penggunaan interaktif ringan:

max_pages: 10
max_requests: 25
max_errors: 8
max_depth: 2
max_chars_per_page: 5000
max_total_chars: 40000
concurrency: 3

Dokumentasi menengah:

max_pages: 50
max_requests: 120
max_errors: 20
max_depth: 4
max_chars_per_page: 8000
max_total_chars: 200000
concurrency: 6

Jangan menaikkan semua batas sekaligus. Output MCP yang terlalu besar dapat mengurangi kemampuan reasoning model walaupun crawler berhasil.

Konfigurasi penting

Lihat seluruh opsi di .env.example.

Perbandingan sasaran dengan Firecrawl

Arachne sengaja dioptimalkan untuk self-hosted agent stack:

Arachne dapat unggul dalam privasi, kontrol, extensibility, biaya marginal, dan integrasi Hermes. Firecrawl hosted kemungkinan tetap unggul untuk coverage internet luas, managed proxy rotation, anti-bot, SLA, dan skala besar tanpa operasi sendiri.

Benchmark terhadap Firecrawl

Masukkan URL ke file, satu URL per baris:

cat > urls.txt <<'EOF'
https://example.com
https://docs.python.org/3/
EOF

Jalankan benchmark Arachne:

PYTHONPATH=src python scripts/benchmark.py --urls urls.txt --output benchmark.json

Bandingkan dengan Firecrawl bila memiliki API key:

export FIRECRAWL_API_KEY=fc-...
PYTHONPATH=src python scripts/benchmark.py \
  --urls urls.txt \
  --compare-firecrawl \
  --output benchmark.json

Metric yang dicatat:

• keberhasilan per URL

• latency

• panjang konten

• engine HTTP/browser

• status code

• error

Tambahkan dataset website Anda sendiri: docs statis, SPA, blog, PDF, tabel, e-commerce, dan halaman yang sering gagal. Klaim lebih unggul hanya masuk akal setelah hasil pada dataset Anda menunjukkan demikian.

Testing

pytest -q

Pengujian yang disertakan mencakup:

• canonical URL normalization

• private-network blocking

• HTML metadata dan link extraction

• prompt-injection detection/wrapping

• content chunking

• hard request budget

• SQLite cache dan snapshots

• local HTTP crawling dan recursive sitemap

Keterbatasan yang disengaja

Arachne tidak secara otomatis:

• melewati CAPTCHA

• membobol login atau paywall

• mengakali access control

• memakai akun tanpa izin

• menjamin halaman yang memblokir data center IP dapat diambil

• mengabaikan robots.txt kecuali administrator mengaktifkannya

• menjamin DNS-rebinding protection sempurna pada semua network stack

Untuk reliability setara layanan hosted pada web yang sangat protektif, Anda tetap memerlukan proxy pool berkualitas, observability, distributed queue, autoscaling browser workers, dan maintenance selector/anti-bot secara berkelanjutan.

Struktur proyek

src/arachne_mcp/
├── cache.py        # SQLite cache dan snapshots
├── config.py       # Environment settings
├── crawler.py      # Orchestration, crawl, map, search, diff
├── errors.py
├── extractors.py   # HTML dan document extraction
├── fetchers.py     # HTTPX, robots, Playwright, actions
├── models.py
├── rate_limit.py
├── security.py     # URL/IP guard
├── server.py       # MCP tools
└── url_utils.py

Dokumen tambahan:

• docs/ARCHITECTURE.md

• docs/SECURITY.md

• docs/HERMES.md

Lisensi

MIT.