web-search-mcp

Полностью локальный, без внешних API, без ключей универсальный MCP-инструмент, предоставляющий DeepSeek Harness + LM Studio:

1. Поиск в вебе — напрямую парсит страницы результатов поисковых систем, доступных из материкового Китая (Baidu / Bing Китай / 360 / Sogou), без вызова каких-либо поисковых API;

2. Разбор всей страницы — использует Crawl4AI (локальный Chromium) для извлечения структуры страницы + текста + изображений;

3. Описание изображений — использует локальную визуальную модель LM Studio для преобразования изображений в текстовые описания на китайском (понимание изображений происходит на стороне сервера, что обходит ограничение DSH на отбрасывание бинарных изображений).

Пять MCP-инструментов:

Извлечённый markdown по умолчанию проходит тройное шумоподавление: ①версия с фильтром PruningContentFilter (если доступна); ②удаление верхней навигационной панели + удаление строк шума нижнего колонтитула/авторских прав/рекламы; ③лимит max_chars (по умолчанию 20000 символов, обрезка при превышении). Это предотвращает бесполезное занятие контекста рекламой и другим нерелевантным содержимым.

llm_extract использует локальную LLM для полного решения задачи извлечения основного текста: ①фильтрация страницы по правилам → ②SMALL_MODEL (малая модель) быстро извлекает ключевые моменты по частям → ③LARGE_MODEL (большая модель) обобщает в связное резюме.

⚠️ Переключение моделей для экономии видеопамяти (по умолчанию): когда model_switching=true в config.py, последовательное переключение в одном экземпляре — когда нужна малая модель, автоматически переключается на qwen3.5-4b (с отключённым мышлением), после обработки переключается обратно на большую модель qwen/qwen3.8-27b для обобщения, в каждый момент времени загружена только одна модель, что позволяет избежать нехватки видеопамяти. Если установить false, используется двухэкземплярный параллельный режим (требуется достаточный объём видеопамяти).

Файл конфигурации (меняйте здесь)

Все изменяемые параметры сосредоточены в config.py, для дальнейшего обслуживания нужно менять только этот файл:

Переменные окружения (например, секция env в cordis.patch.yml DSH) по-прежнему могут переопределять значения по умолчанию из config.py, но для повседневных изменений достаточно править config.py. После изменений перезапустите DSH.

Архитектура

                    ┌──────────────────────────────┐
                    │  web-search-mcp (本进程)        │
关键词 ─────────────►│  1. 抓取 百度/必应/360/搜狗 结果页 │──► 搜索结果(标题/URL/摘要)
                    │  2. Crawl4AI 整页解析           │──► markdown / links / images
                    │  3. 下载图片 ─► LM Studio 视觉模型 │──► 图片中文描述(文本)
                    └──────────────────────────────┘
                              ▲ MCP stdio
                    ┌─────────┴──────────┐
                    │ DeepSeek Harness    │  (cordis.yml 里的 @deepseek-ai/dsh-mcp-client)
                    │ LM Studio(主模型)    │
                    └────────────────────┘

• Поиск, захват и описание изображений выполняются полностью на локальной машине; единственный сетевой доступ — это «открытие самой веб-страницы» (неизбежно для любого онлайн-поиска), нет сторонних API, нет ключей, данные не покидают локальную машину.

• Описание изображений — это визуализация на стороне сервера: Crawl4AI только извлекает URL изображений, а этот инструмент загружает изображения, вызывает визуальную модель LM Studio, преобразует изображения в текст и возвращает его в DSH. Поэтому мостовой слой MCP в DSH (который отбрасывает бинарные изображения) не является проблемой.

Установка

1. Окружение

• Python 3.10+ (Crawl4AI рекомендует 3.11 / 3.12; при проблемах с зависимостями на 3.13 можно откатиться на 3.12)

• Docker установлен — опционально (этому проекту не нужен Docker; SearXNG также не обязателен, поиск выполняется прямым парсингом)

• LM Studio запущен и загружена модель

2. Установка зависимостей (для материкового Китая используйте зеркала)

cd web-search-mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt

# 下载 Crawl4AI 用的 Chromium(仅抓取功能需要;只用搜索可跳过)
playwright install chromium

Примечание о зависимостях: httpx + beautifulsoup4 обязательны (поиск + транспорт MCP); lxml опционален (если не установлен, автоматически используется стандартная библиотека); crawl4ai нужен только для функции захвата. Транспортный уровень MCP написан вручную только на стандартной библиотеке Python и не зависит от mcp/pydantic, поэтому в худшем случае достаточно установить только httpx + beautifulsoup4 для поиска.

3. Настройка визуальной модели LM Studio (опционально, но обязательно для описания изображений)

Загрузите в LM Studio визуальную модель, поддерживающую ввод изображений, например Qwen2.5-VL-7B-Instruct, MiniCPM-V, LLaVA.

Установите переменные окружения (или запишите в .env, но этот инструмент не читает .env автоматически — задавайте в команде запуска):

⚠️ Один экземпляр vs два экземпляра: LM Studio обычно загружает только одну модель в каждый момент времени. Если ваша основная модель для диалога не является визуальной, рекомендуется запустить ещё один экземпляр LM Studio (другой порт, например 1235) специально для визуальной модели, а затем указать VISION_BASE_URL на http://localhost:1235/v1.

Подключение к DeepSeek Harness

Добавьте блок в список плагинов в cordis.yml (пример см. в cordis.example.yml):

- id: mcp-websearch
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: websearch
    transport: stdio
    command: python
    args: ['C:/Users/LiangYuelin/Desktop/workspace/web-search-mcp/server.py']
    cwd: 'C:/Users/LiangYuelin/Desktop/workspace/web-search-mcp'
    env:
      VISION_BASE_URL: 'http://localhost:1234/v1'
      VISION_MODEL: 'qwen2.5-vl-7b-instruct'
      VISION_API_KEY: 'lm-studio'
    toolCallTimeoutMs: 300000   # 抓取 + 图片描述较慢,务必调大

• Если используется venv, измените command на .venv/Scripts/python.exe (абсолютный путь).

• После подключения модель увидит три инструмента: mcp__websearch__search_web, mcp__websearch__scrape_url, mcp__websearch__search_and_extract.

Примеры использования

Модель будет естественным образом вызывать инструменты, например:

• «Найди "последние достижения RAG для больших моделей"» → search_web(query="大模型 RAG 最新进展", engine="bing")

• «Захвати и разбери эту веб-страницу и скажи мне, что на изображениях» → scrape_url(url="https://...", describe_images=true)

• «Найди "курс биткоина" и обобщи первые 3 статьи» → search_and_extract(query="比特币 行情", engine="bing", max_results=3)

Выбор поискового движка:

Статус развёртывания (локальная машина)

Завершено и протестировано на локальной машине:

• Зависимости установлены: crawl4ai 0.9.2 + playwright + lxml + Chromium (через китайские зеркала);

• Конфигурация DSH записана в ~/.dsh/profiles/web/cordis.patch.yml;

• Все четыре поисковых движка (Baidu/Bing/360/Sogou) возвращают результаты;

• Ссылки-редиректы Baidu корректно восстанавливаются;

• Протокол MCP stdio полностью работает (initialize / tools/list / tools/call / обработка ошибок / китайский UTF-8);

• scrape_url (весь markdown страницы + links + изображения) и search_and_extract (поиск → восстановление → захват → извлечение изображений) протестированы сквозным образом.

Единственный оставшийся ручной шаг (требуется для описания изображений):

1. Откройте LM Studio → включите локальный сервис (порт 1234);

2. Загрузите визуальную модель qwen/qwen3.8-27b (с mmproj, поддерживает ввод изображений);

3. Перезапустите DSH (dsh web), и в модели появятся три инструмента mcp__websearch__*.

Описание файлов

• server.py — точка входа MCP-сервиса (ручной MCP stdio, нулевая зависимость от mcp/pydantic)

• engines.py — модуль захвата поисковых движков (Baidu/Bing/360/Sogou)

• vision.py — описание изображений визуальной моделью LM Studio

• cache.py — модуль дискового кэша (результаты захвата / повторное использование описаний изображений, только стандартная библиотека)

• config.py — централизованная конфигурация (все изменяемые параметры)

• requirements.txt — зависимости

• .env.example — пример переменных окружения для визуальной модели

• cordis.example.yml — пример конфигурации подключения к DSH

Оптимизация производительности (маршрут A · реализовано)

Для локальной среды с 20GB видеопамяти + 32GB ОЗУ выполнены четыре оптимизации без добавления новых больших моделей:

Для F5 требуется опциональная зависимость Pillow (уже в requirements.txt); если не установлена, даунсэмплинг автоматически пропускается, остальные функции не затрагиваются. Каталог кэша по умолчанию — .cache/ внутри проекта; установка CACHE_ENABLED=false полностью отключает кэширование.

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

• Результаты поиска иногда содержат рекламу (в Baidu baidu.php?url=... — это рекламные ссылки, их невозможно восстановить, при захвате они пропускаются/выдают ошибку, это нормально);

• Защита поисковых движков от парсинга может вызывать случайные сбои — просто смените движок;

• Захват больших страниц / множества изображений медленный, обязательно увеличьте toolCallTimeoutMs в конфигурации DSH;

• Качество описания изображений зависит от самой локальной визуальной модели.