SourceWeave Web Search

Search-first MCP-Server und CLI für die Web-Recherche.

[!NOTE] sourceweave-search-mcp ist der standardmäßige lokale Einstiegspunkt. Wenn explizite SOURCEWEAVE_SEARCH_*-Endpunktvariablen nicht gesetzt sind, erkennt oder startet es den lokalen Docker-gestützten Stack automatisch. Wenn Sie die Dienste bereits selbst betreiben, setzen Sie explizite Endpunkte; dann verwendet es diese stattdessen.

Übersicht • Erste Schritte • Verwaltete lokale Laufzeit • MCP-Clients einrichten • CLI • Container-Deployments • OpenWebUI • Laufzeitkonfiguration • Entwicklung

Übersicht

SourceWeave Web Search stellt MCP-Clients einen kompakten Drei-Tool-Kontrakt für die Web-Recherche bereit:

• search_web(query, domains?, urls?, effort?) ermittelt Quellen und liefert kompakte Ergebnisse mit stabilen page_id-Kennungen.

• read_pages(page_ids, focus?) liest gespeicherte Seiten anhand der page_id.

• read_urls(urls, focus?) liest direkte URLs, ohne vorher zu suchen.

Es kombiniert:

Related MCP server: codex-search-mcp

Erste Schritte

Voraussetzungen

• Python 3.12+

• Docker mit Compose-Unterstützung für die standardmäßige verwaltete lokale Laufzeit

• explizite SOURCEWEAVE_SEARCH_*-Endpunkte nur, wenn Sie gehostete oder selbst verwaltete Dienste verwenden möchten

Verwaltete lokale Laufzeit

Starten Sie den Server aus dem veröffentlichten Paket:

uvx --from sourceweave-web-search sourceweave-search-mcp

Oder starten Sie den MCP-Server über HTTP:

uvx --from sourceweave-web-search sourceweave-search-mcp \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 8000

Wenn keine Endpunkt-Umgebungsvariablen gesetzt sind, gilt für sourceweave-search-mcp:

Der verwaltete Zustand liegt unter ~/.sourceweave-local/managed-runtime. Mehrere MCP-Prozesse auf derselben Maschine teilen sich einen verwalteten Stack pro State-Verzeichnis.

[!IMPORTANT] Die verwaltete Laufzeit entfernt Container nur, wenn der letzte aktive, von SourceWeave verwaltete Prozess beendet wird. Benannte Volumes bleiben erhalten, sodass Cache-Daten Neustarts überleben. Wenn der ursprünglich besitzende Prozess stirbt, kann ein späterer Prozess denselben Stack anhand der Docker-Projektidentität und des persistierten Laufzeitzustands wiederherstellen.

Expliziter Endpunktmodus

Wenn Sie SearXNG, Crawl4AI und Redis oder Valkey bereits selbst betreiben oder auf gehostete Dienste zeigen möchten, setzen Sie explizite Endpunkte; der MCP-Einstiegspunkt umgeht dann den verwalteten Docker-Start:

SOURCEWEAVE_SEARCH_SEARXNG_BASE_URL="http://127.0.0.1:19080/search?format=json&q=<query>" \
SOURCEWEAVE_SEARCH_CRAWL4AI_BASE_URL="http://127.0.0.1:19235" \
SOURCEWEAVE_SEARCH_CACHE_REDIS_URL="redis://127.0.0.1:16379/2" \
uvx --from sourceweave-web-search sourceweave-search-mcp

Direkte CLI

sourceweave-search führt das Tool direkt aus. Verwenden Sie es, wenn die unterstützenden Dienste bereits verfügbar sind oder Sie explizite Endpunkte angeben. Es startet kein Docker.

sourceweave-search --query "python programming" --read-first-pages 2
sourceweave-search --read-url "https://packaging.python.org/en/latest/"

[!TIP] Die direkte CLI akzeptiert auch die Override-Optionen --searxng-base-url, --crawl4ai-base-url und --cache-redis-url.

MCP-Clients einrichten

OpenCode

Beispiel opencode.json / opencode.jsonc / ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sourceweave": {
      "type": "local",
      "command": [
        "uvx",
        "--from",
        "sourceweave-web-search",
        "sourceweave-search-mcp"
      ],
      "enabled": true,
      "timeout": 300000
    }
  }
}

Für einen gemeinsamen HTTP-Endpunkt stattdessen:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sourceweave": {
      "type": "remote",
      "url": "http://127.0.0.1:18000/mcp",
      "enabled": true,
      "timeout": 300000
    }
  }
}

VS Code Copilot

Beispiel .vscode/mcp.json:

{
  "servers": {
    "sourceweave": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "sourceweave-web-search",
        "sourceweave-search-mcp"
      ]
    }
  }
}

Für einen gemeinsamen HTTP-Endpunkt stattdessen:

{
  "servers": {
    "sourceweave": {
      "type": "http",
      "url": "http://127.0.0.1:18000/mcp"
    }
  }
}

Claude Code

Beispiel .mcp.json:

{
  "mcpServers": {
    "sourceweave": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "sourceweave-web-search",
        "sourceweave-search-mcp"
      ]
    }
  }
}

Für eine projektbezogene gemeinsame Konfiguration platzieren Sie denselben Block in .mcp.json im Stammverzeichnis des Repositorys.

CLI

Die direkte CLI ist nützlich, sobald die unterstützenden Dienste bereits erreichbar sind. Sie bietet denselben Search-First-Workflow ohne den MCP-Wrapper.

sourceweave-search --query "react useEffect cleanup example" --read-first-page
sourceweave-search --query "HTTP overview" --domain developer.mozilla.org --read-first-page
sourceweave-search --read-url "https://packaging.python.org/en/latest/"

Container-Deployments

Die verwaltete lokale Laufzeit ist für Veranstaltungen mit uvx oder uv run auf der Host-Seite gedacht. Containerisierte Deployments verwenden weiterhin eine explizite Endpunktverkabelung.

• Image: ghcr.io/mrnaqa/sourceweave-web-search-mcp

• Repo-lokaler Compose-Einstiegspunkt: docker compose up -d --build mcp

Beispiel für einen Container-Start:

docker run --rm -p 8000:8000 \
  -e SOURCEWEAVE_SEARCH_SEARXNG_BASE_URL="http://host.docker.internal:19080/search?format=json&q=<query>" \
  -e SOURCEWEAVE_SEARCH_CRAWL4AI_BASE_URL="http://host.docker.internal:19235" \
  -e SOURCEWEAVE_SEARCH_CACHE_REDIS_URL="redis://host.docker.internal:16379/2" \
  ghcr.io/mrnaqa/sourceweave-web-search-mcp:latest

OpenWebUI

Dieses Repository enthält außerdem eine eigenständig generierte OpenWebUI-Tool-Datei unter artifacts/sourceweave_web_search.py.

Überprüfen Sie in einem Repository-Checkout, dass sie mit der kanonischen Implementierung synchron ist:

uv run sourceweave-build-openwebui --check

Fügen Sie dieses Artefakt in OpenWebUI ein, wenn Sie den eigenständigen Tool-Datei-Deployment-Pfad verwenden möchten. Die generierte Datei setzt die Standard-Endpunkte auf die repo-lokalen Compose-Dienstnamen um, sodass sie sofort zum Container-Deployment-Pfad passt.

Laufzeitkonfiguration

Optionale Umgebungsvariablen:

Wenn die Endpunktvariablen nicht gesetzt sind, verwendet sourceweave-search-mcp standardmäßig die verwaltete lokale Laufzeit.

• Die kanonischen Host-Endpunkte bleiben die bevorzugten Standardwerte und die Ziele für die Prüfung der externen Wiederverwendung.

• Ein von SourceWeave verwalteter Stack kann andere freie Host-Ports verwenden, wenn die kanonischen Standardports bereits belegt sind.

• Mehrere MCP-Prozesse auf derselben Maschine teilen sich einen verwalteten Stack pro lokalem Laufzeit-State-Verzeichnis.

Standardende-Werte:

• SearXNG: http://127.0.0.1:19080/search?format=json&q=<query>

• Crawl4AI: http://127.0.0.1:19235

• Redis: redis://127.0.0.1/16379/2

Bevorzugte Standard-Host-Ports für den verwalteten Start:

• SearXNG: 19080

• Crawl4AI: 19235

• Redis: 16379

• MCP: 8000 bei direkter Ausführung mit uvx; 18000 unter /mcp bei Verwendung des mcp-Compose-Diensts des Repositorys

Entwicklung

git clone https://github.com/MRNAQA/sourceweave-web-search.git
cd sourceweave-web-search
uv sync --locked --group dev
uv run sourceweave-search-mcp

Nützliche Prüfungen:

uv run sourceweave-build-openwebui --check
uv run sourceweave-search-mcp --help
uv run pytest tests/test_config.py tests/test_packaging.py tests/test_tool.py tests/test_managed_runtime.py -m "not integration"