WebSearch Forge MCP

Ein leichtgewichtiger, einheitlicher WebSearch-MCP für KI-Agenten.

Durchsuchen, lesen, crawlen, parsen und recherchieren Sie das öffentliche Web über einen einzigen MCP-Server.

Quick Start · Tools · Architektur · Suchmaschinen konfigurieren · 中文文档

Was es ist

WebSearch Forge MCP ist ein eigenständiger MCP-Dienst für agentengesteuerte Web-Recherche:

Question → search sources → fetch pages → extract content → crawl related pages → compile evidence

Er ist in klare Schichten unterteilt:

• transports stellt MCP stdio und den optionalen FastAPI-Adapter bereit.

• core übernimmt Konfiguration, Caching, Sicherheitsprüfungen, Orchestrierung und Recherche-Workflows.

• providers implementiert Such-, Abruf-, Extraktions-, Crawl- und Medienfunktionen.

• SearXNG ist das einzige Such-Gateway für Bing, Baidu, Brave, DuckDuckGo und andere konfigurierte Suchmaschinen.

Related MCP server: hidrix-tools

Highlights

Ein MCP-Server, sechs Fähigkeiten

Einmal mit transports/mcp_stdio.py verbinden:

Einheitliches Such-Gateway

Das Argument engines wird als Filter an SearXNG übergeben. WebSearch Forge verteilt nicht unabhängig auf Suchwebsites:

WebSearch Forge MCP → SearXNG → Bing / Baidu / Brave / DuckDuckGo

Standardmäßig leichtgewichtig

MCP stdio benötigt keinen offenen Anwendungsport oder Datenbankserver. Der Cache ist SQLite. Optionale Pakete fügen Trafilatura, Readability, Stealth-Requests, Playwright, Office/PDF-Parsing, Scrapy, YouTube-Untertitel und FastAPI hinzu, ohne den MCP-Vertrag zu ändern.

Begrenztes Crawling

crawl_site unterstützt ein natives Backend ohne Abhängigkeiten und ein optionales Scrapy-Backend. Es erzwingt Seiten- und Tiefenlimits, bleibt auf dem Start-Host, löst relative Links auf und isoliert Seitenfehler.

Quick Start

Die folgenden Befehle sind für Windows PowerShell.

Installieren

cd D:\my-websearch\my_websearch
py -3.12 -m pip install -r requirements.txt

SearXNG starten

docker version
cd D:\my-websearch\my_websearch
docker compose up -d searxng
docker compose ps

Das Standard-Gateway ist http://127.0.0.1:8080. Die Konfiguration befindet sich in config/searxng/settings.yml.

MCP-Client konfigurieren

Verwenden Sie mcp_config.example.json und behalten Sie einen absoluten Pfad bei:

{
  "mcpServers": {
    "websearch-forge": {
      "command": "py",
      "args": [
        "-3.12",
        "D:\\my-websearch\\my_websearch\\transports\\mcp_stdio.py"
      ],
      "env": {
        "SEARXNG_URL": "http://127.0.0.1:8080",
        "CACHE_TTL": "300"
      }
    }
  }
}

Der stdio-Adapter erzwingt UTF-8 unter Windows. Loopback-Verkehr umgeht standardmäßig maschinenweite Proxy-Variablen; setzen Sie PROXY_URL bei Bedarf explizit.

Tools

search_web

Suchen Sie über SearXNG, ohne Seiteninhalte herunterzuladen.

{
  "name": "search_web",
  "arguments": {
    "query": "Python 3.14 new features",
    "engines": ["bing", "baidu", "brave"],
    "limit": 5,
    "time_range": "month"
  }
}

fetch_web_content

Rufen Sie eine öffentliche URL ab und extrahieren Sie sie. HTML, PDF, DOCX, XLSX, PPTX, CSV, Markdown und Klartext werden unterstützt.

{
  "name": "fetch_web_content",
  "arguments": {
    "url": "https://www.python.org",
    "max_chars": 10000,
    "stealth_mode": "off",
    "render_mode": "auto",
    "extraction_mode": "auto"
  }
}

Die Antwort enthält die endgültige URL, den HTTP-Status, den Titel, die Extraktionsmethode, die Wortanzahl, den Inhalt und entdeckte Links.

search_and_fetch

Zuerst suchen, dann die Top-Ergebnisse unabhängig abrufen. Eine fehlgeschlagene Seite wird auf diesem Element vermerkt und bricht den Batch nicht ab.

{
  "name": "search_and_fetch",
  "arguments": {
    "query": "FastAPI MCP server",
    "limit": 3,
    "max_chars": 12000
  }
}

deep_research

Führen Sie verwandte Abfragen gleichzeitig aus, rufen Sie die stärksten Ergebnisse ab und geben Sie einen Markdown-Bericht mit Fehlern auf Quellenebene zurück.

{
  "name": "deep_research",
  "arguments": {
    "queries": ["SearXNG engine configuration", "MCP stdio deployment"],
    "breadth": 3,
    "max_chars": 12000
  }
}

crawl_site

Crawlen Sie eine gleichnamige Website mit harten Seiten- und Tiefenlimits.

{
  "name": "crawl_site",
  "arguments": {
    "url": "https://www.python.org",
    "max_pages": 10,
    "max_depth": 2,
    "backend": "native",
    "stealth_mode": "off"
  }
}

native ist die Standardeinstellung. Installieren Sie Scrapy und setzen Sie backend auf scrapy, um das optionale Backend zu verwenden. Jede Seite meldet URL, Tiefe, Status, Abrufmethode, Titel, Inhalt und Wortanzahl.

youtube_transcript

Rufen Sie YouTube-Untertitel mit optionalen Quell- und Übersetzungssprachen ab.

Antwortformat

{
  "query": "OpenAI",
  "provider": "searxng",
  "engines": ["bing", "baidu", "brave"],
  "total_results": 3,
  "results": [
    {
      "title": "OpenAI | Research & Deployment",
      "url": "https://openai.com/",
      "description": "...",
      "source": "openai.com",
      "engine": "bing",
      "score": 1.0
    }
  ],
  "partial_failures": []
}

Erfolgreiche Teilergebnisse werden beibehalten. Suchmaschinen-, Seiten- und Dokumentfehler werden als strukturierte Fehlereinträge zurückgegeben.

Architektur

flowchart LR
    A[Agent / MCP Client] -->|stdio JSON-RPC| B[transports/mcp_stdio.py]
    B --> C[core/service.py]
    C --> D[providers/search]
    D --> E[SearXNG]
    E --> F[Bing / Baidu / Brave / DDG]
    C --> G[providers/content]
    G --> H[HTTP / stealth / Playwright]
    C --> I[providers/crawl]
    C --> J[providers/media]
    C --> K[(SQLite TTL cache)]

• transports passt Protokolle an; MCP und FastAPI teilen sich denselben Dienst.

• core besitzt Orchestrierung, Cache-Richtlinie, Konfiguration und URL-Sicherheit.

• providers/search kommuniziert mit SearXNG und validiert Suchmaschinennamen.

• providers/content behandelt HTTP, Stealth-Transport, Rendering und Extraktion.

• providers/crawl enthält native und Scrapy-Crawl-Backends.

• providers/media enthält den YouTube-Transkript-Provider.

Suchmaschinen konfigurieren

Die projekt eigene SearXNG-Quelle ist:

config/searxng/settings.yml

Zwei Einstellungen entscheiden, ob eine Suchmaschine aufgerufen werden kann:

1. settings.yml aktiviert die Suchmaschine innerhalb von SearXNG.

2. providers/search/registry.py listet den akzeptierten Namen in SUPPORTED_ENGINES auf.

Nach Änderungen neu starten:

cd D:\my-websearch\my_websearch
docker compose up -d --force-recreate searxng

Wenn SearXNG die Suchmaschine noch nicht bereitstellt, implementieren Sie zuerst diese SearXNG-Suchmaschine.

Sicherheit und Zuverlässigkeit

• Nur HTTP- und HTTPS-URLs werden akzeptiert.

• Localhost-, Loopback-, private IPv4-, Link-Local- und private IPv6-Ziele werden abgelehnt.

• Weiterleitungsziele werden erneut validiert.

• Such- und Abrufvorgänge verwenden einen SQLite-TTL-Cache, standardmäßig 300 Sekunden.

• Teilfehler verwerfen keine erfolgreichen Arbeiten.

• stdout ist für MCP JSON-RPC reserviert.

Optionale Fähigkeiten

Projektstruktur

my_websearch/
├── assets/                     # Project logo
├── config/searxng/             # SearXNG settings.yml
├── core/                       # Config, cache, security, orchestration
├── providers/
│   ├── search/                 # SearXNG gateway and engine allow-list
│   ├── content/                # Requests, rendering, extraction
│   ├── crawl/                  # Native and Scrapy backends
│   └── media/                  # YouTube transcript provider
├── transports/                 # MCP stdio and FastAPI adapters
├── tests/                      # Dependency-free self-checks
├── docker-compose.yml          # Local SearXNG gateway
├── mcp_config.example.json     # MCP client template
├── requirements.txt            # Dependency entry point
├── README.md                  # English documentation
└── README.zh-CN.md            # 中文文档

Entwicklungstest

cd D:\my-websearch
py -3.12 -m my_websearch.tests.test_server

Erwartete Ausgabe:

my_websearch self-check: ok

Optionaler FastAPI-Dienst:

cd D:\my-websearch\my_websearch
py -3.12 -m transports.api

Öffnen Sie dann http://127.0.0.1:8787/docs.

Lizenz

Es ist noch keine Lizenz festgelegt. Fügen Sie vor der öffentlichen Verteilung eine LICENSE-Datei auf Root-Ebene hinzu.