Web Research Stack / Web Araştırma Yığını

English | Türkçe

English

Overview

Web Scraper is a powerful, production-ready web scraping and research tool with full-stack capabilities. It combines a Python FastAPI backend with a modern React Next.js frontend, featuring LLM-powered research capabilities with citation support.

Install

The MCP server for web search and reading that Dot, the always-on agent for macOS, uses ships as a Python package, dotagent-web-research (the import package is web_scraper):

pip install dotagent-web-research
# or, as a command of its own
uv tool install dotagent-web-research

It installs two commands: web-research-mcp, the MCP server over stdio (tools web_search, web_scrape, web_map, web_extract, web_health, web_crawl_start, web_crawl_status, web_crawl_results, web_crawl_cancel), and web-scraper, the CLI and REST server described below. The headless-browser fallbacks are extras: pip install "dotagent-web-research[camoufox]" or "[playwright]".

The tools, and what 1.3.0 added to them

CHANGELOG.md has the decisions; docs/web-tools.md the settings.

How Dot uses it. Dot's package depends on this one, so a fresh Dot install brings it. Dot starts web-research-mcp as one of its MCP servers (named web-research) and its tools reach the agent as mcp__web-research__web_search, mcp__web-research__web_scrape and so on. In Dot's config.toml it is one table; docs/web-tools.md has it and the settings (WEB_TOOLS_*) the server reads.

[[mcp]]
name = "web-research"
command = "web-research-mcp"

Features

• Dual Interface: CLI commands and REST API
• Local Web Research Tools: HTTP-first multi-angle search with field-weighted BM25, weighted angle consensus, freshness filters, caching and provider cooldown, plus scrape, map, background crawl, and structured extract, exposed over REST and a Dot-ready stdio MCP server (headless-only browser fallback)
• LLM Research Tool: AI-powered web research with citations
• Async Architecture: High-performance concurrent scraping
• Production Ready: Docker, monitoring (Prometheus/Grafana), rate limiting, circuit breaker
• Security First: SSRF protection, input validation, security headers
• Multi-language UI: English and Turkish language support
• Streaming Support: Real-time research progress via Server-Sent Events (SSE)
• Code Block Preservation: Scraper preserves code blocks from source pages with syntax highlighting
• Internationalized Status Messages: Research progress messages adapt to query language (TR/EN)
• Resilient JSON Parsing: 3-stage recovery for LLM synthesis output (strict → repair → retry)

Tech Stack

Quick Start

# Clone the repository
git clone https://github.com/senoldogann/web-research-stack.git
cd web-research-stack

# Install dependencies
pip install -e .

# Start the API server
web-scraper serve

# Or use Docker
docker compose up --build

Google search stays off your screen

Google no longer serves results to plain HTTP clients, and headless Chrome is caught within one request. A headed Chrome gets the real page, so the searcher starts Chrome itself, minimises its window over CDP before the first search, and keeps one browser and one tab for the process: ~2 s to start (a brief flash of a small window), then 0.4–1 s per search. If Chrome is missing or refused, Camoufox — a patched headless Firefox — takes over.

pip install -e ".[playwright]"   # the Chrome path
pip install -e ".[camoufox]" && python -m camoufox fetch   # the headless fallback

• GOOGLE_ALLOW_VISIBLE_BROWSER=true — leave the Chrome window on screen (debugging).
• GOOGLE_USE_PLAYWRIGHT=false — skip Google entirely and rely on DuckDuckGo.

API Endpoints

Example: Research Request

curl -X POST "http://127.0.0.1:8000/api/v1/tools/web-research" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "query": "Latest developments in AI",
    "max_sources": 5,
    "deep_mode": false,
    "provider": "ollama"
  }'

Documentation

• Installation Guide
• User Guide
• API Documentation
• LLM Integration
• Local Web Tools
• Production Deployment

License

MIT License

Türkçe

Genel Bakış

Web Scraper, güçlü ve üretim ortamına hazır bir web kazıma ve araştırma aracıdır. Python FastAPI backend ile modern React Next.js frontend'i birleştirir, alıntılı LLM destekli araştırma özelliklerine sahiptir.

Kurulum

Dot'un (macOS için her zaman açık ajan) kullandığı web arama ve okuma MCP sunucusu bir Python paketi olarak gelir: dotagent-web-research (içe aktarılan paket web_scraper):

pip install dotagent-web-research
# veya kendi başına bir komut olarak
uv tool install dotagent-web-research

İki komut kurar: stdio üzerinden MCP sunucusu web-research-mcp ve aşağıda anlatılan CLI ile REST sunucusu web-scraper. Araçlar: web_search, web_scrape, web_map, web_extract, web_health (1.3.0: her sağlayıcının durumu), web_crawl_start, web_crawl_status, web_crawl_results, web_crawl_cancel. 1.3.0 tarihleri güvenilir kılar (date_confidence, date_conflicts; resolve_dates, strict_dates), engellenen sayfayı başka yoldan okur (recover: arşiv, AMP/yazdırma biçimi, besleme, başka yayıncı), çıktıyı küçültür (compact, lean, content_id ile offset) ve sağlayıcıları iyileştirir (10 dakikalık soğuma, isteğe bağlı Brave ve Serper anahtarları). Headless tarayıcı yedekleri ek pakettir: pip install "dotagent-web-research[camoufox]" veya "[playwright]".

Dot bunu nasıl kullanır. Dot'un paketi buna bağlıdır; yeni bir Dot kurulumu bunu da getirir. Dot web-research-mcp'yi MCP sunucularından biri olarak (web-research adıyla) başlatır; araçlar ajana mcp__web-research__web_search, mcp__web-research__web_scrape gibi görünür. Ayrıntı ve ayarlar için docs/web-tools.md.

Özellikler

• Çift Arayüz: CLI komutları ve REST API
• Yerel Web Araştırma Araçları: Alan ağırlıklı BM25, ağırlıklı açı uzlaşması, güncellik filtreleri, önbellek ve sağlayıcı soğuması içeren çok açılı HTTP öncelikli arama; kazıma, haritalama, arka plan taraması ve yapılandırılmış çıkarım; REST ve Dot'a hazır stdio MCP sunucusu (yalnızca headless tarayıcı yedeği)
• LLM Araştırma Aracı: Alıntılı AI destekli web araştırması
• Asenkron Mimari: Yüksek performanslı eşzamanlı kazıma
• Üretim Hazır: Docker, izleme (Prometheus/Grafana), hız sınırlama, circuit breaker
• Güvenlik Öncelikli: SSRF koruması, giriş doğrulama, güvenlik başlıkları
• Çok Dilli UI: İngilizce ve Türkçe dil desteği
• Yayın Akışı: Sunucu Tarafından Gönderilen Olaylar (SSE) ile gerçek zamanlı araştırma ilerlemesi
• Kod Bloğu Koruma: Kaynak sayfalardan kod blokları söz dizimi vurgulamasıyla korunur
• Uluslararasılaştırılmış Durum Mesajları: Araştırma ilerleme mesajları sorgu diline göre uyarlanır (TR/EN)
• Dayanıklı JSON Ayrıştırma: LLM sentez çıktısı için 3 aşamalı kurtarma (katı → onarım → yeniden deneme)

Teknoloji Yığını

Hızlı Başlangıç

# Depoyu klonla
git clone https://github.com/senoldogann/web-research-stack.git
cd web-research-stack

# Bağımlılıkları yükle
pip install -e .

# API sunucusunu başlat
web-scraper serve

# Veya Docker kullan
docker compose up --build

Google araması ekranda görünmez

Google artık düz HTTP istemcilerine sonuç döndürmüyor ve headless Chrome tek istekte yakalanıyor. Başlı (headed) Chrome gerçek sayfayı alıyor; bu yüzden arayıcı Chrome'u kendisi başlatıp penceresini ilk aramadan önce CDP ile küçültüyor ve süreç boyunca tek tarayıcı + tek sekme kullanıyor: başlatma ~2 sn (küçük bir pencere kısa süre görünür), sonrası arama başına 0,4–1 sn. Chrome yoksa ya da reddederse Camoufox — yamalı, headless Firefox — devralıyor.

pip install -e ".[playwright]"   # Chrome yolu
pip install -e ".[camoufox]" && python -m camoufox fetch   # görünmez yedek

• GOOGLE_ALLOW_VISIBLE_BROWSER=true — Chrome penceresi ekranda kalsın (hata ayıklama).
• GOOGLE_USE_PLAYWRIGHT=false — Google'ı tamamen atla, DuckDuckGo kullan.

API Uç Noktaları

Örnek: Araştırma İsteği

curl -X POST "http://127.0.0.1:8000/api/v1/tools/web-research" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sizin-api-anahtariniz" \
  -d '{
    "query": "Yapay zeka son gelişmeler",
    "max_sources": 5,
    "deep_mode": false,
    "provider": "ollama"
  }'

Dokümantasyon

• Kurulum Rehberi
• Kullanım Kılavuzu
• API Dokümantasyonu
• LLM Entegrasyonu
• Yerel Web Araçları
• Üretim Dağıtımı

Lisans

MIT Lisansı

Contributing / Katkıda Bulunma

Contributions are welcome! Please read our Contributing Guide.

Katkılarınızı bekliyoruz! Lütfen Katkı Rehberimizi okuyun.

© 2026 Senol Dogan. MIT License.