MCP SearXNG

MCP (Model Context Protocol) сервер для приватного поиска, извлечения контента и интеллектуального анализа веб-страниц с использованием SearXNG и LLM.

Описание

Этот проект представляет собой сервер Model Context Protocol (MCP), который предоставляет три основных инструмента:

1. web/search — Приватный поиск в интернете через SearXNG.
2. web/fetch — Получение и очистка содержимого веб-страниц (HTML → Markdown).
3. web/research — Интеллектуальный анализ страницы с помощью LLM (саммаризация, извлечение фактов, перевод).
4. web/deep_research — Генерация нескольких поисковых запросов с помощью LLM, получение найденных релевантных страниц, их интеллектуальный анализ и в конце общий интеллектуальный анализ всех страниц вместе с помощью LLM (саммаризация, извлечение фактов, перевод).

Особенности

• Приватность: Поиск через SearXNG без трекинга.
• Интеллектуальный анализ: Интеграция с любой OpenAI-compatible LLM (Ollama, vLLM, LM Studio) для глубокого анализа контента.
• Гибкий парсинг: Поддержка легкого режима (net/http) и тяжелого режима (Chromium/Headless Chrome) для сложных JS-сайтов.
• Чистый контент: Автоматическая очистка от рекламы и навигации через go-readability (отключается параметром clean).
• Два режима работы: HTTP (SSE) и Stdio — для Claude Desktop и других клиентов.
• Graceful Shutdown: Корректное завершение при SIGINT/SIGTERM.
• Наблюдаемость: Встроенные метрики Prometheus для мониторинга производительности.

Установка

1. Убедитесь, что у вас установлен Go 1.26.2 или выше.
2. Клонируйте репозиторий:

git clone https://git.ymnuktech.ru/ymnuk/mcp-searxng.git
cd mcp-searxng

Установите зависимости:

go mod download

Соберите проект: bash go build .

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

Сервер настраивается через аргументы командной строки или переменные окружения.

Параметр	Флаг	Переменная окружения	По умолчанию	Описание
Mode	--mode	MODE	http	Режим работы: http или stdio
Port	-p, --port	WEB_PORT	3000	Порт для входящих соединений
HttpTimeout	--http-timeout	HTTP_TIMEOUT	60	Таймаут HTTP-запросов (сек)
TlsVerify	--tls-verify	TLS_VERIFY	true	Проверка TLS-сертификатов
UserAgent	--user-agent	USER_AGENT	Mozilla/5.0...	User Agent для запросов
SearXNGUrl	--searxng-url	SEARXNG_URL	http://localhost:8099	URL экземпляра SearXNG
SearXNGMinScore	--searxng-min-score	SEARXNG_MIN_SCORE	0.8	Минимальная оценка по умолчанию при фильтрации поиска
UseChromium	--use-chromium	USE_CHROMIUM	false	Использовать Chromium для рендеринга
ChromiumPath	--chromium-path	CHROMIUM_PATH	/usr/bin/chromium	Путь к бинарнику Chromium
ChromiumTimeout	--chromium-timeout	CHROMIUM_TIMEOUT	30	Таймаут Chromium (сек)
LLMUrl	--llm-url	LLM_URL	(пусто)	URL LLM-сервера (OpenAI-compatible)
LLMToken	--llm-token	LLM_TOKEN	(пусто)	API Key для LLM
LLMModel	--llm-model	LLM_MODEL	gpt-4o-mini	Модель по умолчанию
LLMTimeout	--llm-timeout	LLM_TIMEOUT	1m	Таймаут запроса к LLM
LLMLang	--llm-lang	LLM_LANG	ru	Язык для LLM

Использование

Базовый запуск (HTTP режим)

./mcp-searxng --searxng-url https://your-searxng-instance.com

Запуск в stdio режиме (для Claude Desktop)

./mcp-searxng --mode=stdio

Запуск с поддержкой Research (LLM) и Chromium

export SEARXNG_URL=http://my-server:8099
export USE_CHROMIUM=true
export CHROMIUM_PATH=/usr/bin/chromium
export LLM_URL=http://localhost:1234/v1
export LLM_MODEL=gemma-4-26b-a4b-it

./mcp-searxng

Инструменты (Tools)

web/search

Поиск информации в интернете через SearXNG. Возвращает агрегированные результаты (заголовки, ссылки, сниппеты) из множества поисковых систем.

• Использовать когда: Нужно найти источники, новости или ответы на вопросы.

web/fetch

Получение содержимого страницы по URL. По умолчанию очищает HTML от мусора и конвертирует в Markdown.

Параметры:

• url (required) — URL страницы
• to_markdown (optional) — конвертировать в Markdown
• clean (optional) — очищать страницу от рекламы и навигации. При clean: false возвращается сырой контент

• Использовать когда: Нужно прочитать статью целиком или получить сырые данные для самостоятельного анализа.

web/research

Комбинированный инструмент: скачивает страницу, очищает её и отправляет в LLM с инструкцией пользователя.

Параметры:

• url (required) — URL страницы
• prompt (optional) — инструкция для LLM (по умолчанию: "Сделай краткую выжимку основных фактов и тезисов")
• clean (optional) — очищать страницу от рекламы и навигации

web/deep_research

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

Параметры:

• prompt (required) — тема исследования и инструкция для LLM
• clean (optional) — очищать страницы от рекламы и навигации

Использовать когда:

• Нужна краткая выжимка (summary) длинной статьи.
• Нужно извлечь конкретные факты, код или данные.
• Нужно перевести контент или структурировать его.

Мониторинг

Сервер отдает метрики Prometheus по адресу /metrics.

Ключевые метрики:

• mcp_tool_calls_total{tool="search|fetch|research|deep_research", status="success|error"} — количество вызовов инструментов.
• mcp_tool_call_duration_seconds — время выполнения операций.
• http_requests_total — общие HTTP-запросы к серверу.

Endpoints

• /mcp — Основная точка входа для MCP-клиентов (SSE/Stdio).
• /metrics — Метрики Prometheus.
• /health — Health-check (возвращает 200 OK).

🚀 Запуск и подключение

1. Быстрый старт с Docker

Самый простой способ запустить сервер — использовать Docker. Убедитесь, что у вас установлен Docker и Docker Compose.

Создайте файл docker-compose.yml:

version: '3.8'

services:
  mcp-searxng:
    image: git.ymnuktech.ru/ymnuk/mcp-searxng:latest
    container_name: mcp-searxng
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      # Основные настройки
      - WEB_PORT=3000
      - SEARXNG_URL=http://searxng:8080
      - LLM_URL=http://host.docker.internal:1234/v1 # Для локального LLM (Ollama/LM Studio)
      - LLM_MODEL=gemma-4-26b-a4b-it
      
      # Настройки Chromium (для рендеринга сложных сайтов)
      - USE_CHROMIUM=true
      - CHROMIUM_PATH=/usr/bin/chromium
      - CHROMIUM_TIMEOUT=60
      
      # Опционально: токен для LLM, если требуется
      # - LLM_TOKEN=your-token-here
    depends_on:
      - searxng

  searxng:
    image: searxng/searxng:latest
    container_name: searxng
    restart: unless-stopped
    volumes:
      - ./searxng:/etc/searxng:rw
    environment:
      - BASE_URL=http://localhost:8099
      - INSTANCE_NAME=my-searxng
    ports:
      - "8099:8080"

Примечание: Если вы используете Linux, замените host.docker.internal на IP-адрес вашего хоста (например, 172.17.0.1) или используйте сеть host для доступа к локальному LLM-серверу.

Запустите сервисы:

docker compose up -d

Проверьте работоспособность:

curl http://localhost:3000/health

---

2. Подключение к VS Code (и другим редакторам)

Для использования инструментов в VS Code вам потребуется расширение Model Context Protocol (или аналогичное, поддерживающее HTTP/SSE транспорт).

Шаг 1: Настройка MCP Client

Откройте настройки MCP в VS Code (Ctrl+Shift+P -> MCP: Open Configuration) или отредактируйте файл mcp.json в вашем проекте/глобально.

Добавьте конфигурацию для вашего сервера:

{
  "mcpServers": {
    "searxng-research": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer optional-token-if-needed" 
      }
    }
  }
}

Шаг 2: Использование

После перезагрузки окна VS Code или перезапуска расширения, инструменты web/search, web/fetch, web/research и web/deep_research станут доступны агенту (например, Copilot Chat, Cursor или другому AI-ассистенту, интегрированному в IDE).

---

3. Подключение к другим агентам

Cursor / Windsurf

В настройках агента найдите раздел MCP Servers и добавьте новый сервер с типом HTTP/SSE:

• Name: SearXNG Research
• URL: http://localhost:3000/mcp

Open WebUI

1. Перейдите в Admin Panel -> Settings -> Connections.
2. В разделе MCP Servers добавьте новый endpoint:
   • Name: SearXNG
   • URL: http://host.docker.internal:3000/mcp (или IP вашего сервера)
3. Сохраните настройки и перезагрузите страницу. Теперь вы можете выбирать инструменты поиска прямо в чате.

Claude Desktop

Сервер поддерживает режим stdio для прямого подключения без мостов:

./mcp-searxng --mode=stdio

В Claude Desktop добавьте в mcp_settings.json:

{
  "mcpServers": {
    "searxng": {
      "command": "/path/to/mcp-searxng",
      "args": ["--mode=stdio"]
    }
  }
}

---

🔧 Troubleshooting

• Ошибка подключения к LLM: Убедитесь, что контейнер имеет доступ к хост-машине. Для Docker Desktop на Mac/Windows используйте host.docker.internal. На Linux может потребоваться запуск с --network host или указание конкретного IP.
• Chromium падает: Проверьте логи контейнера (docker logs mcp-searxng). Убедитесь, что переменная CHROMIUM_PATH указывает на существующий бинарник внутри контейнера (в официальном образе он обычно уже есть, если вы используете кастомный Dockerfile).
• Таймауты поиска: Если SearXNG отвечает медленно, увеличьте HTTP_TIMEOUT в переменных окружения.

Лицензия

Этот проект распространяется под лицензией MIT, подробности см. в файле LICENSE.