SourceWeave Web Search

Поисковый MCP-сервер и CLI для веб-исследований.

[!ПРИМЕЧАНИЕ] sourceweave-search-mcp — это локальная точка входа по умолчанию. Если явные переменные конечных точек SOURCEWEAVE_SEARCH_* отсутствуют, он автоматически обнаруживает или запускает локальный стек на базе Docker. Если вы уже запускаете сервисы самостоятельно, укажите явные конечные точки, и он будет использовать их.

Обзор • Начало работы • Управляемый локальный рантайм • Настройка MCP-клиента • CLI • Контейнерные развёртывания • OpenWebUI • Конфигурация рантайма • Разработка

Обзор

SourceWeave Web Search предоставляет MCP-клиентам компактный контракт из трёх инструментов для веб-исследований:

• search_web(query, domains?, urls?, effort?) — обнаруживает источники и возвращает компактные результаты со стабильными идентификаторами page_id.

• read_pages(page_ids, focus?) — читает сохранённые страницы по page_id.

• read_urls(urls, focus?) — читает прямые URL без предварительного поиска.

Он объединяет:

Related MCP server: Deep Search MCP Server

Начало работы

Требования

• Python 3.12+

• Docker с поддержкой Compose для управляемого локального рантайма по умолчанию

• Явные конечные точки SOURCEWEAVE_SEARCH_* только если вам нужны размещённые или самостоятельно управляемые сервисы

Управляемый локальный рантайм

Запустите сервер из опубликованного пакета:

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

Или запустите MCP-сервер через HTTP:

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

Когда переменные окружения конечных точек не заданы, sourceweave-search-mcp:

Управляемое состояние хранится в ~/.sourceweave-local/managed-runtime. Несколько MCP-процессов на одной машине используют один управляемый стек на каталог состояния.

[!ВАЖНО] Управляемый рантайм удаляет контейнеры только когда завершается последний активный процесс, управляемый SourceWeave. Именованные тома сохраняются, поэтому данные кэша переживают перезапуски. Если исходный владеющий процесс умирает, более поздний процесс может восстановить тот же стек по идентичности проекта Docker и сохранённому состоянию рантайма.

Режим явных конечных точек

Если вы уже запускаете SearXNG, Crawl4AI и Redis или Valkey самостоятельно, или хотите указать на размещённые сервисы, задайте явные конечные точки, и точка входа MCP обойдёт управляемый запуск Docker:

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

sourceweave-search запускает инструмент напрямую. Используйте его, когда вспомогательные сервисы уже доступны или когда вы предоставляете явные конечные точки. Он не запускает Docker.

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

[!СОВЕТ] Прямой CLI также принимает переопределения --searxng-base-url, --crawl4ai-base-url и --cache-redis-url.

Настройка MCP-клиента

OpenCode

Пример 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
    }
  }
}

Для общего HTTP-конечной точки вместо этого:

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

Пример .vscode/mcp.json:

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

Для общего HTTP-конечной точки вместо этого:

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

Claude Code

Пример .mcp.json:

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

Для общей конфигурации в рамках проекта поместите тот же блок в .mcp.json в корне репозитория.

CLI

Прямой CLI полезен, когда вспомогательные сервисы уже доступны. Он даёт тот же рабочий процесс с приоритетом поиска без обёртки 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/"

Контейнерные развёртывания

Управляемый локальный рантайм предназначен для запусков на стороне хоста через uvx или uv run. Контейнерные развёртывания по-прежнему используют явное подключение конечных точек.

• Образ: ghcr.io/mrnaqa/sourceweave-web-search-mcp

• Локальная точка входа compose из репозитория: docker compose up -d --build mcp

Пример запуска контейнера:

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

Этот репозиторий также включает сгенерированный автономный файл инструмента OpenWebUI по пути artifacts/sourceweave_web_search.py.

Из клонированного репозитория проверьте, что он синхронизирован с канонической реализацией:

uv run sourceweave-build-openwebui --check

Вставьте этот артефакт в OpenWebUI, если хотите использовать автономный путь развёртывания через файл инструмента. Сгенерированный файл переписывает конечные точки по умолчанию на имена сервисов compose из репозитория, чтобы он из коробки соответствовал пути развёртывания контейнера.

Конфигурация рантайма

Необязательные переменные окружения:

Если переменные конечных точек не заданы, sourceweave-search-mcp по умолчанию использует управляемый локальный рантайм.

• Канонические конечные точки хоста остаются предпочтительными по умолчанию и целями проверки внешнего переиспользования.

• Управляемый стек SourceWeave может использовать другие свободные порты хоста, если канонические порты по умолчанию уже заняты.

• Несколько MCP-процессов на одной машине используют один управляемый стек на каталог состояния локального рантайма.

Значения конечных точек по умолчанию:

• 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

Предпочтительные порты хоста по умолчанию для управляемого запуска:

• SearXNG: 19080

• Crawl4AI: 19235

• Redis: 16379

• MCP: 8000 при прямом запуске через uvx; 18000 на /mcp при использовании compose-сервиса mcp из репозитория

Разработка

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

Полезные проверки:

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"