mcp-retrieval

Was es ist

mcp-retrieval ist ein Model Context Protocol-Server, der in Go geschrieben ist. Er stellt jedem MCP-kompatiblen Client (Claude Desktop, IDE-Agenten, benutzerdefinierte LLM-Apps) Web-Retrieval-Fähigkeiten als drei schreibgeschützte Werkzeuge zur Verfügung. Unter der Haube verwendet er die Bibliothek retrieval-go, um das Web zu durchsuchen und Seiten abzurufen, und liefert die Ergebnisse als sauberes Markdown, das direkt an ein Modell übergeben werden kann.

Die Bibliothek benötigt keine API-Schlüssel: Die Websuche läuft über DuckDuckGo Lite, die Bildersuche über Bing Images, und beim Seitenabruf wird das HTML durch einen Readability-Extraktor geschickt, bevor es in Markdown umgewandelt wird. Um gegen Bot-Schutz zuverlässig zu bleiben, imitiert sie echte Browser auf TLS-Ebene und kann sowohl Browser-Fingerprints als auch Proxys rotieren – siehe Retrieval-Engine.

Beide vom MCP-SDK unterstützten Transporte sind verfügbar und bieten denselben Werkzeugsatz:

• stdio – der Client startet die Binärdatei und kommuniziert über stdin/stdout (Standard, ideal für Desktop-Clients).

• http – ein langlebiger streambarer HTTP-Server (nützlich für Remote-/gemeinsame Bereitstellungen).

Related MCP server: mcp-web-calc

Werkzeuge

Alle drei sind als schreibgeschützt annotiert. Jedes Werkzeug gibt eine strukturierte JSON-Nutzlast zurück, die zu seinem Ausgabeschema passt; das SDK spiegelt dasselbe JSON in den Text-Inhaltsblock für Clients, die structuredContent nicht lesen.

web_search

web_search_images

web_scrape

Sowohl queries- als auch urls-Listen sind auf max_queries (10) Einträge pro Aufruf begrenzt. Abfragen müssen ≤ 512 Zeichen lang sein; URLs ≤ 2048 Zeichen und nur http/https.

Ergebnisse und Zählungen

Jeder Aufruf verteilt sich auf die Eingabeliste und gibt einen Eintrag pro Abfrage/URL zurück, jeweils mit eigenem status – success, failed oder timeout – sodass ein teilweiser Fehler trotzdem die funktionierenden Elemente zurückgibt.

count ist die Anzahl der tatsächlich zurückgegebenen Elemente und kann niedriger sein als das angeforderte max_results / max_images: Duplikate innerhalb der Ergebnisse einer einzelnen Abfrage werden entfernt, bevor das Limit angewendet wird, und der Upstream kann einfach weniger Elemente liefern. Ein kleineres count ist ein normales Ergebnis, kein Fehler.

Die Deduplizierung erfolgt pro Abfrage, nicht über Abfragen hinweg. Jeder Eintrag wird für sich dedupliziert, sodass ein Link, der von zwei Abfragen im selben Aufruf gefunden wird, in beiden Einträgen erscheint – deduplizieren Sie die Vereinigung selbst, wenn Sie das benötigen.

Fehler

Fehler auf Anfrageebene werden als Werkzeugergebnis mit isError: true und einer Klartextnachricht zurückgegeben, nicht als JSON-RPC-Fehler – das Modell liest die Nachricht und kann den Aufruf selbst korrigieren. Fehler pro Element tun dies nie; sie bleiben in der Nutzlast als status: "failed" / "timeout".

Ein Aufruf schlägt nur dann vollständig fehl, wenn die Eingabe abgelehnt wird, bevor irgendeine Arbeit beginnt, oder wenn jedes Element darin fehlschlägt:

Die Alle-fehlgeschlagen-Nachrichten unterscheiden bewusst nicht zwischen Timeouts und anderen Ursachen: Eine gemischte Charge kann aus mehreren Gründen gleichzeitig fehlschlagen, und der status pro Element trägt diese Details bereits, wenn mindestens ein Element überlebt.

Bekannte Einschränkungen

• web_scrape verarbeitet nur HTML. Seiten werden durch einen Readability-Extraktor geschickt, der Artikel-Markup benötigt, daher liefern text/plain-Antworten nichts und kommen als status: "failed" zurück. Rohdatei-Hosts sind der häufige Fall: raw.githubusercontent.com, github.com/.../raw/..., cdn.jsdelivr.net. Scrapen Sie stattdessen die gerenderte Seite, nicht die Rohdatei.

• Die Relevanz von web_search_images ist nicht garantiert. Für einige Abfragen liefert Bing Images eine Seite, die keine Ergebnismenge ist, und sie wird so geparst, als wäre sie eine – das Werkzeug gibt dann nicht zusammenhängende Bilder mit status: "success" zurück. Behandeln Sie Bildergebnisse als Best-Effort und verifizieren Sie sie, bevor Sie sie einem Benutzer zeigen.

• Kein JavaScript. Seiten werden unverändert abgerufen; clientseitig gerenderter Inhalt ist für den Extraktor unsichtbar.

Schnellstart

Installation

Wählen Sie, was passt – alle ergeben denselben Server.

Container (keine Go-Toolchain erforderlich):

docker pull ghcr.io/role1776/mcp-retrieval:latest

Vorgefertigte Binärdatei – Holen Sie sich das Archiv für Ihre Plattform aus dem letzten Release, entpacken Sie es und legen Sie mcp-retrieval in Ihren PATH.

MCP-Bundle – Für Clients, die .mcpb-Dateien installieren, laden Sie mcp-retrieval_<version>_<os>_<arch>.mcpb aus dem letzten Release herunter und öffnen Sie es mit Ihrem Client. Das Bundle enthält die kompilierte Binärdatei, benötigt also weder Docker noch Go. Wählen Sie die Datei, die zu Ihrem Betriebssystem und Ihrer CPU-Architektur passt: Ein Bundle enthält eine native Binärdatei.

Aus dem Quellcode:

go install github.com/Role1776/mcp-retrieval/app/cmd/mcp-retrieval@latest   # needs Go 1.25.5+

Oder bauen Sie die Binärdatei direkt (das Go-Modul befindet sich in app/):

make build          # -> bin/mcp-retrieval

Ausführen

# defaults: stdio transport, no configuration needed
./bin/mcp-retrieval

# with an explicit env file
./bin/mcp-retrieval -env /absolute/path/to/.env

Das eine Flag ist optional:

Verbinden eines MCP-Clients (stdio)

Richten Sie Ihren Client auf das gebaute Binary aus. Beispiel für eine Claude-Desktop-Konfiguration:

{
  "mcpServers": {
    "retrieval": {
      "command": "/absolute/path/to/mcp-retrieval",
      "env": {
        "MAX_RESULTS": "20"
      }
    }
  }
}

Der env-Block ist optional — "command" allein genügt.

Verbinden eines MCP-Clients (Container)

Führen Sie das Image über stdio aus. Die Konfiguration wird weiterhin über den env-Block übertragen, aber Docker benötigt jede Variable mit -e in der Befehlszeile, damit sie den Prozess erreicht:

{
  "mcpServers": {
    "retrieval": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MAX_RESULTS",
        "-e", "DEFAULT_TIMEOUT_MS",
        "ghcr.io/role1776/mcp-retrieval:latest"
      ],
      "env": {
        "MAX_RESULTS": "20",
        "DEFAULT_TIMEOUT_MS": "5000"
      }
    }
  }
}

-i ist erforderlich — ohne sie erhält der Container kein stdin und der Client sieht den Server sofort sterben. Clients, die aus dem MCP-Registry installieren, erstellen diesen Aufruf selbst und fragen nach den in server.json deklarierten Variablen.

Ausführung über HTTP

Setzen Sie MCP_TRANSPORT=http und der Server lauscht auf SERVER_PORT unter MCP_PATH (Standard: http://localhost:8080/mcp).

Konfiguration

Alles wird über Umgebungsvariablen konfiguriert, und jeder Wert wird vor dem Start validiert: ein nicht-numerischer oder nicht-positiver Wert ist ein Startfehler. Beziehungen zwischen Limits werden beim Start nicht geprüft — siehe Limits. Bereits in der Umgebung vorhandene Variablen haben Vorrang vor einer .env-Datei, sodass der env-Block eines MCP-Clients immer wirksam wird. Jedes Feld hat einen sinnvollen Standardwert, sodass der Server ohne jegliche Konfiguration läuft (stdio-Transport).

Siehe .env.example für die vollständige Liste mit ihren Standardwerten, bereit zum Kopieren in .env.

MCP-Server

Die den Clients angezeigte Version ist nicht konfigurierbar: Sie wird zur Build-Zeit aus dem Git-Tag in das Binary eingestanzt.

HTTP-Server (nur http-Transport)

HTTP-Client und Proxy

Wenn ein Proxy konfiguriert ist, erhält jede ausgehende Anfrage eine eindeutige Sitzungs-ID, die an den Login angehängt wird, sodass der Upstream-Anbieter die Exit-IP pro Anfrage rotiert.

Limits

Jeder Wert wird für sich geprüft — er muss größer als null sein —, aber die DEFAULT_*-, MIN_*- und MAX_*-Tripel werden beim Start nicht gegeneinander geprüft. Ein inkonsistenter Satz stoppt den Server nicht; er wird stattdessen pro Anfrage abgeglichen:

• ein Wert, den der Aufrufer weglässt oder als null oder negativ übergibt, fällt auf das passende DEFAULT_* zurück;

• das Ergebnis wird dann in [MIN_*, MAX_*] geklemmt, sodass ein DEFAULT_*, das größer als sein MAX_* ist, einfach MAX_* ergibt;

• wenn MIN_* größer als MAX_* ist, gewinnt das Maximum.

Das effektive Limit liegt daher immer innerhalb des konfigurierten Maximums, und eine Fehlkonfiguration führt zu einem funktionierenden Server statt zu einem fehlgeschlagenen Start. Der Kompromiss ist, dass sie still degradiert: ein Tippfehler wie MAX_RESULTS=2 statt 20 erzeugt keine Warnung, nur leise kleinere Antworten. Es lohnt sich, diese Werte zu überprüfen, wenn Ergebnisse abgeschnitten wirken.

Protokollierung

Architektur

Das Projekt folgt einer sauberen, geschichteten Struktur. Abhängigkeiten zeigen nach innen zur Domäne, und jede Schicht kommuniziert über Schnittstellen mit der nächsten.

app/                       the Go module: sources plus its build files
                           (Dockerfile, .dockerignore, .goreleaser.yaml)

cmd/mcp-retrieval/main.go  entry point: parse flags, load config, run app

internal/
  app/                     wiring + lifecycle (build server, run, graceful shutdown)
  config/                  config loading (.env → env vars → validate)
  domain/                  core types (Query, Link, Document, Snippet, Image) and errors
  dto/web/                 request/response shapes for the MCP tools
  transport/mcp/           MCP layer
    router/                registers every tool group on the MCP server
    web/                   tool handlers
    utils/                 schema helpers and error → tool-result mapping
  usecase/web/             business logic: validation, parallelism, timeouts, dedupe/limit/rerank
  adapter/web/             retrieval-go client wiring (search, images, scrape, proxy)
  pkg/                     reusable building blocks (mcpserver, server, logger, validator)

Anfragefluss für einen Tool-Aufruf:

MCP client → transport/mcp/web (handler) → usecase/web → adapter/web → retrieval-go → the web
                     ↑ maps errors               ↑ validates, fans out, limits results

Suche und Scraping verzweigen sich beide gleichzeitig über die Eingabeliste und aggregieren Ergebnisse pro Element, jeweils mit eigenem Status (success, failed, timeout). Ein Aufruf schlägt nur dann vollständig fehl, wenn jedes Element darin fehlschlägt.

Abruf-Engine

Die gesamte Netzwerkarbeit wird an retrieval-go delegiert, konfiguriert in app/internal/adapter/web. Wissenswert:

• Quellen. Die Websuche verwendet DuckDuckGo Lite; die Bildersuche verwendet Bing Images; beim Seitenabruf wird das rohe HTML durch einen Readability-Extraktor geführt und der Hauptartikel in Markdown konvertiert (Tabellen inklusive). Es sind keine Suchmaschinen-API-Schlüssel erforderlich.

• Browser-Imitation. Der Adapter aktiviert WithBrowserRotation(), sodass jede Anfrage von einem von ~11 echten Browserprofilen gesendet wird, die zufällig ausgewählt werden. Jedes Profil kombiniert einen echten TLS/JA3-Fingerabdruck (über uTLS) mit einem passenden User-Agent und Client-Hint-Headern — Chrome 133/131/120 (Windows/macOS/Linux), Edge 131, Firefox 120 (Windows/macOS), Safari 18.4 (macOS) und iOS 18.4 Safari. Dadurch sieht der Datenverkehr wie gewöhnliche Browser aus und nicht wie ein Go-HTTP-Client, was die freien Quellen erreichbar hält.

• Proxy-Rotation. Wenn PROXY_HOST konfiguriert ist, installiert der Adapter eine Proxy-Factory, die bei jeder Anfrage eine eindeutige session-<id> an den Proxy-Benutzernamen anhängt. Mit einem sitzungsbasierten Residential-/Rotating-Proxy-Anbieter ergibt das eine frische Exit-IP pro Anfrage, was die Last verteilt und Ratenlimits vermeidet. Ohne Proxy gehen Anfragen direkt hinaus.

• Antwortverarbeitung. Antworten werden transparent dekomprimiert (gzip, br, zstd, deflate), und Keep-Alive ist deaktiviert (WithDisableKeepAlive()), sodass gepoolte Verbindungen keinen einzelnen Fingerabdruck/eine einzelne IP über Anfragen hinweg fixieren.

Nichts davon benötigt Konfiguration, um zu funktionieren — die obigen Standardwerte werden automatisch angewendet. Nur Proxy-Anmeldedaten sind optionale Extras.

Entwicklung

Alles, was Go betrifft, liegt in app/, also verwenden Sie entweder das Makefile aus dem Repository-Stamm oder übergeben Sie -C app an die Toolchain:

make build          # compile the binary
make test           # run tests

go -C app build ./...      # compile everything
go -C app test ./...       # run tests
go -C app vet ./...        # static checks

Siehe CONTRIBUTING.md für Pull-Request-Richtlinien.

Lizenz

Veröffentlicht unter der MIT-Lizenz.