mcp-web-tools-server

Ein benutzerdefinierter Model Context Protocol (MCP)-Server, der einem KI-Agenten echte, funktionierende Werkzeuge zum Abrufen von Webseiten und Extrahieren von Inhalten daraus bietet: sauberer lesbarer Artikelltext, strukturierte Daten per CSS-Selektor und eine robots.txt-Berechtigungsprüfung.

Was ist MCP?

MCP ist ein offenes Protokoll, ursprünglich von Anthropic veröffentlicht, das standardisiert, wie KI-Anwendungen (wie Claude Desktop oder Claude Code) eine Verbindung zu externen Werkzeugen und Datenquellen herstellen. Anstatt dass jede KI-App ihr eigenes Plugin-Format erfindet, stellt ein MCP-Server einen festen Satz von Werkzeugen (und optional Ressourcen und Eingabeaufforderungen) über eine einfache JSON-RPC-Schnittstelle bereit, und jeder MCP-kompatible Client kann sie auf die gleiche Weise entdecken und aufrufen. Dieses Repository ist ein solcher Server: Er läuft als kleiner lokaler Prozess und kommuniziert MCP über stdio, sodass jeder MCP-Client seine Werkzeuge auflisten und aufrufen kann, ohne etwas über die zugrunde liegenden httpx, selectolax oder trafilatura zu wissen.

Warum dies nützlich ist

Standardmäßig kann ein LLM keine Live-Webseite abrufen. Dieser Server schließt diese Lücke mit einem kleinen, getesteten, gut abgegrenzten Werkzeugsatz: Ein Agent kann den lesbaren Text eines Artikels extrahieren, bestimmte Felder einer Seite per CSS-Selektor abrufen (Preis, Titel, Tags, was auch immer die Seitenstruktur hergibt) und prüfen, ob die robots.txt einer Site die Anfrage erlaubt, bevor er sie stellt. Er ist bewusst eng gefasst und kein allgemeines Scraping-Framework, in der Annahme, dass ein paar Werkzeuge, die korrekt funktionieren und vorhersagbar fehlschlagen, für einen Agenten nützlicher sind als eine große Angriffsfläche, die manchmal nicht funktioniert.

Werkzeuge

fetch_and_extract(url: str) -> str

Ruft eine URL ab und gibt sauberen, lesbaren Haupttext zurück: Skripte, Styles, Navigation, Anzeigen und Fußzeilen werden entfernt. Verwendet trafilatura zur Artikelextraktion, mit einer Absatzdichte-Heuristik (basierend auf selectolax) als Fallback für Seiten, die trafilatura nicht sicher verarbeitet.

extract_structured(url: str, css_selectors: dict) -> dict

Ruft eine URL ab und extrahiert Felder per CSS-Selektor, z. B.:

{"title": "h1", "price": ".price", "tags": ".tag-list a"}

gibt zurück:

{"title": "Trail Blazer 29 Mountain Bike", "price": "$1,249.00", "tags": ["mountain", "hardtail", "29er"]}

Ein Selektor, der auf ein Element passt, gibt dessen Text zurück; mehrere Treffer geben eine Liste ihrer Texte zurück; kein Treffer gibt null zurück. Die Analyse erfolgt mit selectolax.

check_robots_txt(url: str) -> dict

Ruft die robots.txt der Zielseite ab und meldet, ob der User-Agent dieses Servers die angegebene URL anfordern darf, unter Verwendung des standardmäßigen urllib.robotparser von Python. Wenn keine robots.txt gefunden wird, wird dies explizit gemeldet (robots_txt_found: false), anstatt stillschweigend anzunehmen, dass die Erlaubnis tatsächlich erteilt wurde.

Dies existiert, weil Scraping-Etikette ein erstklassiges Anliegen sein sollte, kein nachträglicher Gedanke: Ein Agent (oder die Person, die ihn steuert) sollte in der Lage sein, die Berechtigung vor dem Abruf zu prüfen, nicht erst, wenn etwas schief geht.

Entwurfsprinzipien

• Ehrliche Identifikation. Anfragen verwenden einen echten User-Agent-String, der dieses Werkzeug identifiziert und auf dieses Repository verweist, keinen vorgetäuschten Browser-UA.

• Begrenzte Anfragen. Jeder Abruf hat ein festes Timeout (standardmäßig 10 Sekunden), sodass ein langsamer oder hängender Server die gesamte Sitzung nicht blockieren kann.

• robots.txt ist ein Werkzeug, nicht stillschweigend erzwungen. check_robots_txt wird bereitgestellt, damit ein Agent (oder die Person, die ihn steuert) die Berechtigung vor dem Scraping prüfen kann, blockiert aber derzeit nicht automatisch fetch_and_extract oder extract_structured. Siehe Einschränkungen unten.

• Kein Absturz bei fehlerhafter Eingabe. Netzwerkfehler, Timeouts und ungültige URLs werden abgefangen und als sauberer Fehlertext oder ein {"error": ...}-Wörterbuch zurückgegeben, niemals als unbehandelte Ausnahme, die den Serverprozess beendet.

Projektstruktur

mcp_web_tools/
  server.py        MCP server definition and the three tool entry points
  extractors.py     Pure HTML-parsing logic (no network), used for readable-text and CSS-selector extraction
  robots.py         robots.txt fetching and permission checking
  http_client.py    Shared httpx fetch helper: user agent, timeout, error handling
tests/
  test_extractors.py    Unit tests against local HTML fixtures, no network
  test_robots.py        Unit tests with the network call mocked out
  test_http_client.py   Unit tests for URL validation
  test_integration.py   Integration tests against live public sites, marked and run separately
  fixtures/              Static HTML used by the unit tests
scripts/
  test_client.py    Standalone script that launches the server and talks real MCP protocol to it

Server ausführen

python -m venv venv
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate

pip install -r requirements.txt
python -m mcp_web_tools.server

Der Server kommuniziert über stdio mit dem MCP-Protokoll; wenn Sie ihn direkt von einem Terminal aus ausführen, wartet er nur darauf, dass ein Client eine Verbindung herstellt. Verwenden Sie ihn über einen MCP-Client (siehe unten) oder das mitgelieferte Test-Client-Skript.

Konfiguration als MCP-Server in Claude Desktop oder Claude Code

Fügen Sie einen Eintrag zur Serverkonfiguration Ihres MCP-Clients hinzu, wobei command auf den Python-Interpreter der venv und args auf das Modul zeigt. Für Claude Desktop kommt dies in die claude_desktop_config.json:

{
  "mcpServers": {
    "web-tools": {
      "command": "C:\\path\\to\\mcp-web-tools-server\\venv\\Scripts\\python.exe",
      "args": ["-m", "mcp_web_tools.server"],
      "cwd": "C:\\path\\to\\mcp-web-tools-server"
    }
  }
}

Unter macOS/Linux wäre command /pfad/zu/mcp-web-tools-server/venv/bin/python.

Für Claude Code führen Sie aus:

claude mcp add web-tools -- /path/to/mcp-web-tools-server/venv/bin/python -m mcp_web_tools.server

(ersetzen Sie den Windows-venv-Pfad falls zutreffend) oder fügen Sie den entsprechenden Eintrag zur .mcp.json Ihres Projekts hinzu.

Tests ausführen

Komponententests laufen gegen lokale HTML-Fixtures und greifen nicht auf das Netzwerk zu:

pytest

Integrationstests greifen auf echte, stabile, öffentliche Testseiten zu (example.com und books.toscrape.com, standardmäßige öffentliche Scraping-Test-/Demoziele) und sind von der Standardausführung ausgeschlossen. Führen Sie sie explizit aus, wenn Sie Netzwerkzugriff haben:

pytest -m integration

Es gibt auch ein eigenständiges Skript, das den Server als echten Unterprozess startet und ihn über das tatsächliche MCP-Client/Server-Protokoll steuert, anstatt die Python-Funktionen direkt aufzurufen:

python scripts/test_client.py

Einschränkungen und was ich als Nächstes hinzufügen würde

• Kein JavaScript-Rendering. Dieser Server ruft rohes HTML mit httpx ab. Seiten, die ihren Inhalt clientseitig rendern (schwere React/Vue-SPAs), liefern wenig oder nichts Brauchbares. Ein viertes Werkzeug, das Playwright für einen Headless-Browser-Abruf einbindet, wäre die natürliche nächste Ergänzung, auf Kosten eines deutlich höheren Aufwands beim Ausführen.

• Keine Ratenbegrenzung. Jeder Werkzeugaufruf tätigt bei Aufruf eine Anfrage. Es gibt keine integrierte Drosselung pro Domain oder Anforderungswarteschlange, wenn ein Agent die Werkzeuge in einer engen Schleife gegen denselben Host aufruft. check_robots_txt gibt zwar crawl_delay_seconds aus, wenn eine Site eine solche veröffentlicht, aber derzeit erzwingt nichts diese.

• robots.txt ist beratend, nicht erzwungen. fetch_and_extract und extract_structured konsultieren nicht automatisch check_robots_txt vor dem Abruf. Dies ist eine bewusste Entscheidung über den Umfang dieser Version (ein Agent sollte zuerst selbst check_robots_txt aufrufen), aber ein strengerer Modus, der nicht erlaubte Abrufe automatisch ablehnt, wäre eine sinnvolle Ergänzung.

• Lesbarkeitsheuristik ist einfach. Der selectolax-Fallback, der verwendet wird, wenn trafilatura kein sicheres Ergebnis liefert, ist ein einfacher Absatzdichte-Scorer. Er ist für typische Artikel- und Blog-Layouts gut genug, schneidet aber bei ungewöhnlichen Seitenstrukturen schlechter ab als eine speziell entwickelte Lesbarkeitsbibliothek.

• Kein Caching. Jeder Aufruf ruft erneut ab, selbst für dieselbe URL Sekunden später. In Ordnung für einen Demo-/Portfolio-Server, nicht ideal für intensivere Nutzung.

• Einzeltransport in der Praxis. Der Server ist für stdio eingerichtet, was Claude Desktop und Claude Code verwenden. Das mcp-SDK unterstützt auch SSE- und streamable-HTTP-Transporte; die Einrichtung eines solchen wäre erforderlich, um diesen Server als gehosteten Dienst und nicht als lokalen Unterprozess zu betreiben.