mcp-retrieval

Что это

mcp-retrieval — это сервер Model Context Protocol, написанный на Go. Он предоставляет возможности веб-поиска любому MCP-совместимому клиенту (Claude Desktop, IDE-агентам, пользовательским LLM-приложениям) в виде трёх инструментов только для чтения. Под капотом используется библиотека retrieval-go для поиска в вебе и получения страниц, возвращая результаты в виде чистого Markdown, готового для передачи модели.

Библиотеке не нужны API-ключи: веб-поиск идёт через DuckDuckGo Lite, поиск изображений — через Bing Images, а получение страниц прогоняет HTML через экстрактор читаемости перед преобразованием в Markdown. Чтобы оставаться надёжным против защиты от ботов, она имитирует реальные браузеры на уровне TLS и может ротировать как отпечатки браузеров, так и прокси — см. Поисковый движок.

Оба транспорта, поддерживаемые MCP SDK, доступны и предоставляют идентичный набор инструментов:

• stdio — клиент запускает бинарник и общается через stdin/stdout (по умолчанию, идеально для десктопных клиентов).

• http — долгоживущий потоковый HTTP-сервер (полезен для удалённых/общих развёртываний).

Related MCP server: mcp-web-calc

Инструменты

Все три аннотированы как только для чтения. Каждый инструмент возвращает структурированный JSON-ответ, соответствующий его схеме вывода; SDK зеркалирует тот же JSON в текстовый блок содержимого для клиентов, которые не читают structuredContent.

web_search

web_search_images

web_scrape

Списки queries/urls ограничены max_queries (10) элементами на вызов. Запросы должны быть ≤ 512 символов; URL ≤ 2048 символов и только http/https.

Результаты и счётчики

Каждый вызов разворачивается по входному списку и возвращает по одной записи на запрос/URL, каждая со своим status — success, failed или timeout — так что частичный сбой всё равно возвращает элементы, которые сработали.

count — это количество фактически возвращённых элементов, и оно может быть меньше запрошенного max_results / max_images: дубликаты в результатах одного запроса удаляются до применения лимита, а вышестоящий сервис может просто иметь меньше элементов. Меньший count — это нормальный результат, а не ошибка.

Дедупликация выполняется по запросу, а не между запросами. Каждая запись дедуплицируется отдельно, поэтому ссылка, найденная двумя запросами в одном вызове, появляется в обеих записях — если нужно, дедуплицируйте объединение самостоятельно.

Ошибки

Сбои на уровне запроса возвращаются как результат инструмента с isError: true и текстовым сообщением, а не как ошибка JSON-RPC — модель читает сообщение и может сама исправить вызов. Сбои по отдельным элементам никогда так не делают; они остаются внутри полезной нагрузки как status: "failed" / "timeout".

Вызов полностью проваливается только тогда, когда входные данные отклоняются до начала работы, или когда каждый элемент в нём проваливается:

Сообщения о полном провале намеренно не различают таймауты и другие причины: смешанный пакет может провалиться по нескольким причинам одновременно, а статус по каждому элементу уже несёт эту деталь, когда выживает хотя бы один элемент.

Известные ограничения

• web_scrape обрабатывает только HTML. Страницы прогоняются через экстрактор читаемости, которому нужна разметка статьи, поэтому ответы text/plain ничего не дают и возвращаются как status: "failed". Обычный случай — хостинг сырых файлов: raw.githubusercontent.com, github.com/.../raw/..., cdn.jsdelivr.net. Извлекайте отрендеренную страницу, а не сырой файл.

• Релевантность web_search_images не гарантируется. Для некоторых запросов Bing Images отдаёт страницу, которая не является набором результатов, и она парсится как таковая — инструмент тогда возвращает несвязанные изображения с status: "success". Относитесь к результатам изображений как к лучшим усилиям и проверяйте их перед показом пользователю.

• Нет JavaScript. Страницы загружаются как есть; контент, отрендеренный на стороне клиента, невидим для экстрактора.

Быстрый старт

Установка

Выбирайте любой вариант — все дают идентичный сервер.

Контейнер (не нужен Go toolchain):

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

Готовый бинарник — возьмите архив для вашей платформы из последнего релиза, распакуйте его и поместите mcp-retrieval в ваш PATH.

MCP Bundle — для клиентов, которые устанавливают файлы .mcpb, скачайте mcp-retrieval_<version>_<os>_<arch>.mcpb из последнего релиза и откройте его своим клиентом. Пакет содержит скомпилированный бинарник, поэтому ему не нужны ни Docker, ни Go. Выберите файл, соответствующий вашей ОС и архитектуре CPU: пакет содержит один нативный бинарник.

Из исходников:

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

Или соберите бинарник на месте (модуль Go находится в app/):

make build          # -> bin/mcp-retrieval

Запуск

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

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

Единственный флаг необязателен:

Подключение MCP-клиента (stdio)

Укажите вашему клиенту на собранный бинарник. Пример конфигурации Claude Desktop:

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

Блок env необязателен — одного "command" достаточно.

Подключение MCP-клиента (контейнер)

Запустите образ на stdio. Конфигурация по-прежнему передаётся через блок env, но Docker требует, чтобы каждая переменная была указана в командной строке с -e, чтобы она достигла процесса:

{
  "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 обязателен — без него контейнер не получает stdin, и клиент видит, что сервер немедленно умирает. Клиенты, устанавливаемые из MCP Registry, сами собирают этот вызов и запрашивают переменные, объявленные в server.json.

Запуск через HTTP

Установите MCP_TRANSPORT=http, и сервер будет слушать SERVER_PORT по пути MCP_PATH (по умолчанию http://localhost:8080/mcp).

Конфигурация

Всё настраивается через переменные окружения, и каждое значение проверяется перед запуском: нечисловое или неположительное значение является ошибкой запуска. Связи между лимитами не проверяются при запуске — см. Limits. Переменные, уже присутствующие в окружении, имеют приоритет над файлом .env, поэтому блок env MCP-клиента всегда действует. Каждое поле имеет разумное значение по умолчанию, так что сервер работает без какой-либо конфигурации (транспорт stdio).

См. .env.example для полного списка со значениями по умолчанию, готового для копирования в .env.

MCP-сервер

Версия, сообщаемая клиентам, не настраивается: она встраивается в бинарник при сборке из git-тега.

HTTP-сервер (только для http-транспорта)

HTTP-клиент и прокси

Когда прокси настроен, каждый исходящий запрос получает уникальный идентификатор сессии, добавляемый к логину, поэтому вышестоящий провайдер ротирует исходящий IP для каждого запроса.

Лимиты

Каждое значение проверяется отдельно — оно должно быть больше нуля, — но тройки DEFAULT_*, MIN_* и MAX_* не перекрёстно проверяются друг с другом при запуске. Несогласованный набор не останавливает сервер; вместо этого он согласуется для каждого запроса:

• значение, которое вызывающий опускает или передаёт как ноль или отрицательное, откатывается к соответствующему DEFAULT_*;

• затем результат ограничивается диапазоном [MIN_*, MAX_*], так что DEFAULT_*, превышающий свой MAX_*, просто даёт MAX_*;

• если MIN_* превышает MAX_*, побеждает максимум.

Таким образом, эффективный лимит всегда находится в пределах настроенного максимума, и неправильная конфигурация приводит к работающему серверу, а не к неудачному запуску. Обратная сторона — деградация происходит молча: опечатка, например MAX_RESULTS=2 вместо 20, не вызывает предупреждений, только тихо уменьшает ответы. Стоит перепроверять эти значения, когда результаты выглядят усечёнными.

Логирование

Архитектура

Проект следует чистой многослойной структуре. Зависимости направлены внутрь к домену, и каждый слой общается со следующим через интерфейсы.

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)

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

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

Поиск и скрейпинг оба разворачиваются по списку входных данных конкурентно и агрегируют результаты по каждому элементу, каждый со своим статусом (success, failed, timeout). Вызов полностью завершается ошибкой только тогда, когда каждый элемент в нём терпит неудачу.

Поисковый движок

Вся сетевая работа делегируется retrieval-go, настраиваемому в app/internal/adapter/web. Полезно знать:

• Источники. Веб-поиск использует DuckDuckGo Lite; поиск изображений — Bing Images; при получении страницы необработанный HTML пропускается через экстрактор readability и преобразуется в Markdown (включая таблицы). Ключи API поисковых систем не требуются.

• Имитация браузера. Адаптер включает WithBrowserRotation(), поэтому каждый запрос отправляется из одного из ~11 реальных профилей браузера, выбранных случайным образом. Каждый профиль сочетает подлинный TLS/JA3-отпечаток (через uTLS) с соответствующим User-Agent и заголовками client-hint — Chrome 133/131/120 (Windows/macOS/Linux), Edge 131, Firefox 120 (Windows/macOS), Safari 18.4 (macOS) и iOS 18.4 Safari. Это делает трафик похожим на обычные браузеры, а не на Go HTTP-клиент, что и позволяет обращаться к бесплатным источникам.

• Ротация прокси. Когда задан PROXY_HOST, адаптер устанавливает фабрику прокси, которая добавляет уникальный session-<id> к имени пользователя прокси в каждом запросе. С провайдером резидентных/ротационных прокси на основе сессий это даёт новый исходящий IP для каждого запроса, распределяя нагрузку и избегая ограничений скорости. Без прокси запросы идут напрямую.

• Обработка ответов. Ответы прозрачно распаковываются (gzip, br, zstd, deflate), и keep-alive отключён (WithDisableKeepAlive()), чтобы пул соединений не закреплял один отпечаток/IP между запросами.

Ничто из этого не требует настройки для работы — указанные выше значения по умолчанию применяются автоматически. Только учётные данные прокси являются необязательными дополнениями.

Разработка

Весь код на Go находится в app/, поэтому либо используйте makefile из корня репозитория, либо передайте -C app в инструментарий:

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

См. CONTRIBUTING.md для руководства по pull-request.

Лицензия

Выпущено под лицензией MIT.