Local Web Search MCP Server

Офлайн-ориентированный MCP-сервер для веб-поиска и получения контента. Он не требует внешних API-ключей и использует локальные модели для классификации намерений, опционального кросс-языкового поиска, семантического реранжирования и извлекающих ответов глубокого поиска.

Возможности

• Пулинг контекстов браузера с постоянным экземпляром Playwright.

• Веб-поиск через настраиваемых провайдеров с отслеживанием работоспособности и упорядоченным фолбэком.

• Опциональный федеративный поиск по всем настроенным провайдерам с нормализацией URL, дедупликацией между провайдерами и слиянием по методу Reciprocal Rank Fusion (RRF).

• Опциональная маршрутизация поиска с учётом намерений: консервативные эвристики, локальный классификатор как запасной вариант и версионированные профили провайдеров.

• Поиск по домену для целевых запросов по сайтам.

• Получение страниц через HTTP в первую очередь с быстрыми путями GitHub Raw и RSS, плюс фолбэк на Playwright для отрендеренных страниц.

• Защита от SSRF для fetch_content путём блокировки localhost и целей в частных сетях.

• Ограничение скорости по алгоритму токен-бакета для инструментов поиска и получения.

• Семантический кэш на основе SQLite и sqlite-vec.

• Опциональное кросс-языковое расширение запросов с локальными моделями Transformers.js.

• Чистое извлечение Markdown через Readability, JSDOM и Turndown.

Related MCP server: searxng-mcp

Требования

• Node.js 20.9.0 или новее.

• npm.

• Сетевой доступ при установке для npm-пакетов, Playwright Chromium и первой загрузки моделей.

Установка

npm install
npm run build

Скрипт postinstall загружает Playwright Chromium. При первом использовании функций на основе моделей Transformers.js загружает необходимые файлы моделей в локальный кэш Hugging Face. Первый запрос, загружающий модель, может быть медленным; последующие запросы используют локальный кэш. Оставьте ENABLE_CROSSLINGUAL=false для максимально лёгкого первого запуска. Очевидные намерения strategy=auto распознаются эвристиками без загрузки классификатора намерений; неоднозначные auto-запросы могут вызвать первую загрузку классификатора.

Конфигурация MCP-клиента

Добавьте собранный сервер в конфигурацию вашего MCP-клиента:

{
  "mcpServers": {
    "websearch": {
      "command": "node",
      "args": ["path/to/local-websearch-mcp/build/index.js"],
      "env": {
        "RATE_LIMIT_SEARCH_PER_MIN": "10",
        "RATE_LIMIT_FETCH_PER_MIN": "20",
        "SEARCH_PROVIDERS": "duckduckgo,bing",
        "ENABLE_CROSSLINGUAL": "false",
        "CACHE_DB_PATH": "websearch_cache.db"
      }
    }
  }
}

Если пакет установлен глобально или через package runner, используйте бинарную точку входа:

{
  "mcpServers": {
    "websearch": {
      "command": "local-websearch-mcp",
      "args": [],
      "env": {
        "SEARCH_PROVIDERS": "duckduckgo,bing",
        "ENABLE_CROSSLINGUAL": "false"
      }
    }
  }
}

Для клиентов на основе package-runner команда может быть npx с args, установленными в ["-y", "local-websearch-mcp"], как только пакет станет доступен из настроенного npm-реестра.

Инструменты

Стратегии поиска

auto намеренно реализован как опция; если не указывать strategy, по-прежнему используется fallback для обратной совместимости. Семантический кэш запросов пропускается для aggregate и auto, потому что ключи кэша запросов ещё не разделены по пространствам имён согласно стратегии выполнения/плану провайдеров. Контент страниц глубокого поиска по-прежнему использует обычный кэш контента.

SEARCH_PROVIDERS — это разрешительный список, а также набор настроенных провайдеров. Автомаршрутизация никогда не активирует провайдера, отсутствующего в SEARCH_PROVIDERS; профиль маршрутизации изменяет только порядок и количество настроенных провайдеров, выбираемых в качестве основных кандидатов.

Для авто-профилей с агрегацией вторичные настроенные провайдеры запрашиваются только в том случае, если все выбранные основные провайдеры не вернули пригодного результата. Частичный успех основных провайдеров принимается вместо расширения запроса только ради увеличения числа результатов. Это ограничивает нагрузку на скрейпинг и снижает излишнее воздействие блокировок/CAPTCHA.

Текущий профиль маршрутизации: v1.

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

Пример аргументов поиска с учётом намерения:

{
  "query": "PostgreSQL connection pooling best practices",
  "strategy": "auto",
  "max_results": 5
}

Используйте domain для целевых поисков, например react.dev или github.com. Определение намерения всегда получает исходный запрос; site:<domain> добавляется только после, для выполнения провайдером.

{
  "query": "server components reference",
  "domain": "react.dev",
  "strategy": "auto",
  "max_results": 5
}

Используйте deep=true только тогда, когда клиенту нужно, чтобы сервер загрузил топ-страницы и извлёк вероятный ответ из текста страницы. LLM MCP-клиента по-прежнему отвечает за финальные рассуждения и обобщение.

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

Пример аргументов федеративного поиска:

{
  "query": "postgres connection pooling strategies",
  "strategy": "aggregate",
  "max_results": 5
}

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

• URL репозиториев GitHub, а также blob, tree и raw читаются с raw.githubusercontent.com, когда это возможно.

• URL RSS- или Atom-лент, а также типичные пути блогов/новостных лент преобразуются в список последних элементов в Markdown.

• Обычные HTML-страницы по-прежнему используют парсинг Readability через HTTP в первую очередь с фолбэком на Playwright.

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

Docker

npm run docker:build
npm run docker:up

Docker Compose хранит кэш SQLite в именованном томе, смонтированном в /app/data, а модели Hugging Face — в отдельном именованном томе. Контейнер задаёт CACHE_DB_PATH=/app/data/websearch_cache.db.

Разработка

npm run build
npm run typecheck
npm test
npm run smoke:mcp
npm audit --audit-level=moderate
npm pack --dry-run --json

npm run smoke:mcp запускает скомпилированный сервер через stdio, проверяет три значения стратегии web_search (fallback, aggregate, auto), проверяет диагностику маршрутизации из server_status и подтверждает, что fetch_content блокирует localhost. Он не выполняет живой поиск у провайдера, что сохраняет независимость CI от HTML/сетевой доступности поисковых систем.

Детерминированные TR/EN-фикстуры маршрутизации находятся в evals/search-routing/queries.jsonl и проверяются обычным набором тестов Vitest. Они проверяют покрытие намерений, консервативное поведение эвристик, случаи откладывания неоднозначных запросов и соблюдение разрешительного списка провайдеров без загрузки реального классификатора или обращения к провайдерам.

Устранение неполадок

• Если после установки запуск не удается, выполните npx playwright install chromium.

• Если первый запрос с использованием модели выполняется медленно, дождитесь завершения загрузки модели Transformers.js и повторите попытку.

• Если поиск не возвращает результатов, измените порядок/набор SEARCH_PROVIDERS или попробуйте прямой URL fetch_content.

• Если режим aggregate слишком медленный или вызывает блокировку провайдера, используйте стратегию fallback по умолчанию.

• Если auto выбирает слишком широкий план поиска для вашего сценария, используйте явные fallback или aggregate; явные стратегии обходят автоматический планировщик.

• Если Docker не может найти Chromium, пересоберите образ с помощью npm run docker:build.

• Если файлы кэша появляются в корне проекта, укажите CACHE_DB_PATH на отдельный каталог данных.

Упаковка npm

npm-пакет включает только build/, README.md, LICENSE и SECURITY.md. Команда npm pack запускает npm run build через prepack, поэтому пакет содержит скомпилированный JavaScript, а не локальные файлы планирования, тесты, кэши или артефакты, содержащие только исходный код.

Безопасность

См. SECURITY.md для получения инструкций по сообщению об уязвимостях и текущих примечаний по аудиту зависимостей.

Лицензия

ISC