web-search-mcp

Una herramienta MCP completamente local, cero API externas, cero claves, que proporciona a DeepSeek Harness + LM Studio:

1. Búsqueda web — extrae directamente las páginas de resultados de motores de búsqueda accesibles desde China continental (Baidu / Bing China / 360 / Sogou), sin llamar a ninguna API de búsqueda;

2. Análisis de página completa — usa Crawl4AI (Chromium local) para extraer estructura de la página + texto + imágenes;

3. Descripción de imágenes — usa el modelo de visión local de LM Studio para convertir imágenes en descripciones de texto en chino (el entendimiento de imágenes ocurre en el lado del servidor, por lo que se evita la limitación de DSH de descartar imágenes binarias).

Cinco herramientas MCP:

El markdown extraído tiene por defecto una triple reducción de ruido: ① filtro PruningContentFilter (cuando esté disponible); ② eliminación de la barra de navegación superior + eliminación de líneas de ruido de pie de página/derechos de autor/anuncios; ③ límite max_chars (por defecto 20000 caracteres, se trunca si se excede). Evita que anuncios y contenido no válido ocupen innecesariamente el contexto.

llm_extract usa el LLM local para resolver completamente la extracción del cuerpo: ① filtrado por reglas de la página web → ② SMALL_MODEL (modelo pequeño) extrae rápidamente los puntos clave por bloques → ③ LARGE_MODEL (modelo grande) resume en un resumen coherente.

⚠️ Cambio de modelo para ahorrar memoria de video (por defecto): cuando model_switching=true en config.py, se cambia secuencialmente en una sola instancia — cuando se necesita el modelo pequeño, se cambia automáticamente a qwen3.5-4b (y se desactiva el razonamiento), y después de procesar se vuelve al modelo grande qwen/qwen3.8-27b para resumir, solo se carga un modelo a la vez, evitando falta de memoria de video. Si se establece en false, se usa doble instancia en paralelo (requiere suficiente memoria de video).

Archivo de configuración (cambia aquí)

Toda la configuración variable se concentra en config.py, para mantenimiento futuro solo se modifica este archivo:

Las variables de entorno (como la sección env de cordis.patch.yml de DSH) aún pueden sobrescribir los valores predeterminados de config.py, pero para el uso diario basta con modificar config.py. Después de cambiar, reinicia DSH para que surta efecto.

Arquitectura

                    ┌──────────────────────────────┐
                    │  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(主模型)    │
                    └────────────────────┘

• La búsqueda, extracción y descripción de imágenes se realizan completamente en la máquina local; el único acceso a la red es "abrir la página web en sí" (inevitable en cualquier búsqueda en línea), sin APIs de terceros, sin claves, los datos no salen de la máquina.

• La descripción de imágenes es visión del lado del servidor: Crawl4AI solo extrae las URLs de las imágenes, esta herramienta descarga las imágenes, llama al modelo de visión de LM Studio, convierte las imágenes en texto y lo devuelve a DSH. Por lo tanto, la capa de puente MCP de DSH (que descarta imágenes binarias) no es un problema.

Instalación

1. Entorno

• Python 3.10+ (Crawl4AI recomienda 3.11 / 3.12; si encuentras problemas de dependencias con 3.13, puedes volver a 3.12)

• Docker instalado es opcional (este proyecto no requiere Docker; SearXNG tampoco es necesario, la búsqueda se hace por extracción directa)

• LM Studio iniciado y con modelos cargados

2. Instalar dependencias (usar espejo para China continental)

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

Nota de dependencias: httpx + beautifulsoup4 son necesarios (búsqueda + transporte MCP); lxml es opcional (si no está instalado, se usa automáticamente la biblioteca estándar); crawl4ai solo se necesita para la función de extracción. La capa de transporte MCP está escrita a mano solo con la biblioteca estándar de Python, no depende de mcp/pydantic, por lo que en el peor caso, solo con httpx + beautifulsoup4 también se puede buscar.

3. Configurar el modelo de visión de LM Studio (opcional, pero necesario para descripción de imágenes)

Carga un modelo de visión que admita entrada de imágenes en LM Studio, como Qwen2.5-VL-7B-Instruct, MiniCPM-V, LLaVA.

Establece las variables de entorno (o escríbelas en .env, pero esta herramienta no lee .env automáticamente, configúralas en el comando de inicio):

⚠️ Instancia única vs doble instancia: LM Studio normalmente solo carga un modelo a la vez. Si tu modelo principal de conversación no es de visión, se recomienda abrir otra instancia de LM Studio (cambia el puerto, por ejemplo 1235) dedicada al modelo de visión, y luego apunta VISION_BASE_URL a http://localhost:1235/v1.

Integración con DeepSeek Harness

Agrega una sección en la lista de plugins de cordis.yml (ejemplo en 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   # 抓取 + 图片描述较慢,务必调大

• Si usas venv, cambia command a .venv/Scripts/python.exe (ruta absoluta).

• Después de la integración, el modelo verá tres herramientas: mcp__websearch__search_web, mcp__websearch__scrape_url, mcp__websearch__search_and_extract.

Ejemplos de uso

El modelo llamará naturalmente a las herramientas, por ejemplo:

• "Busca 'últimos avances en RAG de modelos grandes'" → search_web(query="大模型 RAG 最新进展", engine="bing")

• "Extrae y analiza esta página web, y dime qué hay en las imágenes" → scrape_url(url="https://...", describe_images=true)

• "Ayúdame a buscar 'precio de Bitcoin' y resume los primeros 3 artículos" → search_and_extract(query="比特币 行情", engine="bing", max_results=3)

Selección de motor de búsqueda:

Estado de despliegue (máquina local)

Completado y probado en esta máquina:

• Dependencias instaladas: crawl4ai 0.9.2 + playwright + lxml + Chromium (a través de espejo nacional);

• Configuración de DSH escrita en ~/.dsh/profiles/web/cordis.patch.yml;

• Los cuatro motores de búsqueda (Baidu/Bing/360/Sogou) devuelven resultados;

• Los enlaces de redirección de Baidu se restauran correctamente;

• Protocolo MCP stdio completamente funcional (initialize / tools/list / tools/call / manejo de errores / UTF-8 chino);

• scrape_url (markdown de página completa + enlaces + imágenes) y search_and_extract (búsqueda → restauración → extracción → extracción de imágenes) de extremo a extremo.

Único paso manual restante (necesario para descripción de imágenes):

1. Abre LM Studio → inicia el servicio local (puerto 1234);

2. Carga el modelo de visión qwen/qwen3.8-27b (con mmproj, admite entrada de imágenes);

3. Reinicia DSH (dsh web), y verás las tres herramientas mcp__websearch__* en el modelo.

Descripción de archivos

• server.py — Punto de entrada del servicio MCP (MCP stdio escrito a mano, cero dependencias de mcp/pydantic)

• engines.py — Módulo de extracción de motores de búsqueda (Baidu/Bing/360/Sogou)

• vision.py — Descripción de imágenes con modelo de visión de LM Studio

• cache.py — Módulo de caché en disco (reutilización de resultados de extracción / descripciones de imágenes, solo biblioteca estándar)

• config.py — Configuración centralizada (todos los elementos variables)

• requirements.txt — Dependencias

• .env.example — Ejemplo de variables de entorno para el modelo de visión

• cordis.example.yml — Ejemplo de configuración de integración con DSH

Optimización de rendimiento (Ruta A · implementada)

Para el entorno local de 20GB de memoria de video + 32GB de RAM, se han realizado cuatro optimizaciones sin agregar nuevos modelos grandes:

F5 requiere la dependencia opcional Pillow (ya incluida en requirements.txt); si no está instalada, se omite automáticamente la reducción de muestreo, el resto de funciones no se ven afectadas. El directorio de caché por defecto está en .cache/ dentro del proyecto; establece CACHE_ENABLED=false para desactivarlo por completo.

Limitaciones conocidas

• Los resultados de búsqueda ocasionalmente incluyen anuncios (los enlaces baidu.php?url=... de Baidu son enlaces de anuncios, no se pueden restaurar, se omiten/errores al extraer, es normal);

• El anti-scraping de los motores de búsqueda puede causar fallos ocasionales, cambia de motor;

• Extraer páginas grandes / con muchas imágenes es lento, asegúrate de aumentar toolCallTimeoutMs en la configuración de DSH;

• La calidad de la descripción de imágenes depende del modelo de visión local en sí.