SourceWeave Web Search

Servidor MCP y CLI centrados en la búsqueda para investigación web.

[!NOTE] sourceweave-search-mcp es el punto de entrada local predeterminado. Cuando no hay variables de endpoint SOURCEWEAVE_SEARCH_* explícitas, descubre o inicia automáticamente la stack local respaldada por Docker. Si ya ejecutas los servicios tú mismo, define endpoints explícitos y los utilizará en su lugar.

Descripción general • Primeros pasos • Entorno de ejecución local gestionado • Configuración del cliente MCP • CLI • Despliegues en contenedores • OpenWebUI • Configuración del entorno de ejecución • Desarrollo

Descripción general

SourceWeave Web Search ofrece a los clientes MCP un contrato compacto de tres herramientas para la investigación web:

• search_web(query, domains?, urls?, effort?) descubre fuentes y devuelve resultados compactos con identificadores estables page_id.

• read_pages(page_ids, focus?) lee las páginas almacenadas por page_id.

• read_urls(urls, focus?) lee URLs directas sin buscar primero.

Combina:

Related MCP server: Deep Search MCP Server

Primeros pasos

Requisitos

• Python 3.12+

• Docker compatible con Compose para el entorno de ejecución local gestionado predeterminado

• Endpoints SOURCEWEAVE_SEARCH_* explícitos únicamente si quieres servicios alojados o autogestionados

Entorno de ejecución local gestionado

Ejecuta el servidor desde el paquete publicado:

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

O inicia el servidor MCP mediante HTTP:

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

Cuando no hay variables de entorno de endpoint definidas, sourceweave-search-mcp:

El estado gestionado se encuentra en ~/.sourceweave-local/managed-runtime. Varios procesos MCP en la misma máquina comparten una única stack gestionada por directorio de estado.

[!IMPORTANTE] El entorno de ejecución gestionado elimina los contenedores solo cuando finaliza el último proceso activo gestionado por SourceWeave. Los volúmenes con nombre se conservan, por lo que los datos de caché sobreviven a los reinicios. Si falla el proceso propietario original, un proceso posterior puede recuperar la misma stack a partir de la identidad del proyecto Docker y del estado de ejecución persistido.

Modo de endpoint explícito

Si ya ejecutas SearXNG, Crawl4AI y Redis o Valkey, o quieres apuntar a servicios alojados, define endpoints explícitos y el punto de entrada MCP omitirá el inicio de Docker gestionado:

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

CLI directa

sourceweave-search ejecuta la herramienta directamente. Úsalo cuando los servicios de soporte ya estén disponibles o cuando proporciones endpoints explícitos. No inicia Docker.

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

[!TIP] La CLI directa también acepta las anulaciones --searxng-base-url, --crawl4ai-base-url y --cache-redis-url.

Configuración del cliente MCP

OpenCode

Ejemplo de 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
    }
  }
}

Para un endpoint HTTP compartido local en su lugar:

{
  "$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

Ejemplo de .vscode/mcp.json:

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

Para un endpoint HTTP compartido en su lugar:

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

Claude Code

Ejemplo de .mcp.json:

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

Para una configuración compartida de ámbito de proyecto, coloca el mismo bloque en .mcp.json en la raíz del repositorio.

CLI

La CLI directa es útil una vez que los servicios de soporte ya son accesibles. Ofrece el mismo flujo de trabajo de búsqueda en primer lugar sin envoltorio MCP.

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/"

Despliegues en contenedores

El entorno de ejecución local gestionado está pensado para los lanzamientos uvx o uv run en el host. Los despliegues en contenedores siguen usando conexión configurada de endpoints.

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

• Punto de entrada de Compose en el repositorio: docker compose up -d --build mcp

Ejemplo de ejecución en contenedor:

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

Este repositorio también incluye un archivo de herramienta autónomo generado para OpenWebAI en artifacts/sourceweave_web_search.py.

Cuando quieras la ruta de despliegue mediante archivo de herramienta autónomo, pega ese artefacto en OpenWebUI. El archivo generado reescribe los endpoints predeterminados para que correspondan a los servicios compose locales del repositorio y, de este modo, resulta compatible con la ruta de despliegue en contenedor de forma predeterminada.

uv run sourceweave-build-openwebui --check

Configuración del entorno de ejecución

Variables de entorno opcionales:

Si las variables de endpoint no están definidas, sourceweave-search-mcp usa por defecto el entorno de ejecución local gestionado.

• Los endpoints canónicos del host siguen siendo los valores predeterminados preferidos y los destinos de la revisión de reutilización externa.

• Una stack gestionada por SourceWeave puede usar puertos host libres distintos cuando los valores predeterminados canónicos ya están ocupados.

• Varios procesos MCP en la misma máquina comparten una única stack gestionada por directorio de estado local del entorno de ejecución.

Valores de endpoints predeterminados:

• 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

Puertos de host preferidos por defecto para el arranque gestionado:

• SearXNG: 19080

• Crawl4AI: 19235

• Redis: 16379

• MCP: 8000 cuando se ejecuta directamente con uvx; 18000 en /mcp para el servicio compose mcp del repositorio.

Desarrollo

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

Comprobaciones útiles:

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"