WebSearch Forge MCP

Un MCP de WebSearch ligero y unificado para agentes de IA.

Busca, lee, rastrea, analiza e investiga la web pública a través de un único servidor MCP.

Inicio rápido · Herramientas · Arquitectura · Configurar motores de búsqueda · 中文文档

Qué es

WebSearch Forge MCP es un servicio MCP autónomo para investigación web impulsada por agentes:

Question → search sources → fetch pages → extract content → crawl related pages → compile evidence

Se divide en capas claras:

• transports expone MCP stdio y el adaptador opcional FastAPI.

• core gestiona configuración, caché, comprobaciones de seguridad, orquestación y flujos de investigación.

• providers implementa funciones de búsqueda, obtención, extracción, rastreo y medios.

• SearXNG es la única puerta de enlace de búsqueda para Bing, Baidu, Brave, DuckDuckGo y otros motores configurados.

Related MCP server: hidrix-tools

Destacados

Un servidor MCP, seis capacidades

Conéctate una vez a transports/mcp_stdio.py:

Puerta de enlace de búsqueda unificada

El argumento engines se pasa a SearXNG como filtro. WebSearch Forge no se distribuye de forma independiente a los sitios de búsqueda:

WebSearch Forge MCP → SearXNG → Bing / Baidu / Brave / DuckDuckGo

Ligero por defecto

MCP stdio no necesita un puerto de aplicación expuesto ni un servidor de base de datos. La caché es SQLite. Los paquetes opcionales añaden Trafilatura, Readability, solicitudes sigilosas, Playwright, análisis de Office/PDF, Scrapy, subtítulos de YouTube y FastAPI sin cambiar el contrato MCP.

Rastreo limitado

crawl_site admite un backend nativo sin dependencias y un backend opcional de Scrapy. Aplica límites de páginas y profundidad, permanece en el host inicial, resuelve enlaces relativos y aísla los fallos de página.

Inicio rápido

Los siguientes comandos son para Windows PowerShell.

Instalación

cd D:\my-websearch\my_websearch
py -3.12 -m pip install -r requirements.txt

Iniciar SearXNG

docker version
cd D:\my-websearch\my_websearch
docker compose up -d searxng
docker compose ps

La puerta de enlace predeterminada es http://127.0.0.1:8080. La configuración se encuentra en config/searxng/settings.yml.

Configurar el cliente MCP

Usa mcp_config.example.json y mantén una ruta absoluta:

{
  "mcpServers": {
    "websearch-forge": {
      "command": "py",
      "args": [
        "-3.12",
        "D:\\my-websearch\\my_websearch\\transports\\mcp_stdio.py"
      ],
      "env": {
        "SEARXNG_URL": "http://127.0.0.1:8080",
        "CACHE_TTL": "300"
      }
    }
  }
}

El adaptador stdio fuerza UTF-8 en Windows. El tráfico de bucle local omite las variables de proxy de toda la máquina por defecto; establece PROXY_URL explícitamente cuando sea necesario.

Herramientas

search_web

Busca a través de SearXNG sin descargar los cuerpos de las páginas.

{
  "name": "search_web",
  "arguments": {
    "query": "Python 3.14 new features",
    "engines": ["bing", "baidu", "brave"],
    "limit": 5,
    "time_range": "month"
  }
}

fetch_web_content

Obtiene y extrae una URL pública. Se admiten HTML, PDF, DOCX, XLSX, PPTX, CSV, Markdown y texto plano.

{
  "name": "fetch_web_content",
  "arguments": {
    "url": "https://www.python.org",
    "max_chars": 10000,
    "stealth_mode": "off",
    "render_mode": "auto",
    "extraction_mode": "auto"
  }
}

La respuesta incluye URL final, estado HTTP, título, método de extracción, recuento de palabras, contenido y enlaces descubiertos.

search_and_fetch

Primero busca y luego obtiene los mejores resultados de forma independiente. Una página fallida se registra en ese elemento y no cancela el lote.

{
  "name": "search_and_fetch",
  "arguments": {
    "query": "FastAPI MCP server",
    "limit": 3,
    "max_chars": 12000
  }
}

deep_research

Ejecuta consultas relacionadas de forma concurrente, obtiene los resultados más sólidos y devuelve un informe en Markdown con fallos a nivel de fuente.

{
  "name": "deep_research",
  "arguments": {
    "queries": ["SearXNG engine configuration", "MCP stdio deployment"],
    "breadth": 3,
    "max_chars": 12000
  }
}

crawl_site

Rastrea un sitio del mismo host con límites estrictos de páginas y profundidad.

{
  "name": "crawl_site",
  "arguments": {
    "url": "https://www.python.org",
    "max_pages": 10,
    "max_depth": 2,
    "backend": "native",
    "stealth_mode": "off"
  }
}

native es el predeterminado. Instala Scrapy y establece backend en scrapy para usar el backend opcional. Cada página informa URL, profundidad, estado, método de obtención, título, contenido y recuento de palabras.

youtube_transcript

Recupera subtítulos de YouTube con idiomas de origen y traducción opcionales.

Forma de la respuesta

{
  "query": "OpenAI",
  "provider": "searxng",
  "engines": ["bing", "baidu", "brave"],
  "total_results": 3,
  "results": [
    {
      "title": "OpenAI | Research & Deployment",
      "url": "https://openai.com/",
      "description": "...",
      "source": "openai.com",
      "engine": "bing",
      "score": 1.0
    }
  ],
  "partial_failures": []
}

Los resultados parciales exitosos se conservan. Los errores de motor, página y documento se devuelven como entradas de fallo estructuradas.

Arquitectura

flowchart LR
    A[Agent / MCP Client] -->|stdio JSON-RPC| B[transports/mcp_stdio.py]
    B --> C[core/service.py]
    C --> D[providers/search]
    D --> E[SearXNG]
    E --> F[Bing / Baidu / Brave / DDG]
    C --> G[providers/content]
    G --> H[HTTP / stealth / Playwright]
    C --> I[providers/crawl]
    C --> J[providers/media]
    C --> K[(SQLite TTL cache)]

• transports adapta protocolos; MCP y FastAPI comparten el mismo servicio.

• core posee la orquestación, la política de caché, la configuración y la seguridad de URL.

• providers/search se comunica con SearXNG y valida los nombres de los motores.

• providers/content maneja HTTP, transporte sigiloso, renderizado y extracción.

• providers/crawl contiene los backends de rastreo nativo y Scrapy.

• providers/media contiene el proveedor de transcripciones de YouTube.

Configurar motores de búsqueda

La fuente SearXNG propiedad del proyecto es:

config/searxng/settings.yml

Dos ajustes deciden si se puede llamar a un motor:

1. settings.yml habilita el motor dentro de SearXNG.

2. providers/search/registry.py lista el nombre aceptado en SUPPORTED_ENGINES.

Reinicia después de los cambios:

cd D:\my-websearch\my_websearch
docker compose up -d --force-recreate searxng

Si SearXNG aún no proporciona el motor, implementa primero ese motor de SearXNG.

Seguridad y fiabilidad

• Solo se aceptan URLs HTTP y HTTPS.

• Se rechazan destinos localhost, bucle local, IPv4 privada, enlace local e IPv6 privada.

• Los destinos de redirección se validan de nuevo.

• Las operaciones de búsqueda y obtención usan una caché TTL SQLite, 300 segundos por defecto.

• Los fallos parciales no descartan el trabajo exitoso.

• stdout está reservado para MCP JSON-RPC.

Capacidades opcionales

Estructura del proyecto

my_websearch/
├── assets/                     # Project logo
├── config/searxng/             # SearXNG settings.yml
├── core/                       # Config, cache, security, orchestration
├── providers/
│   ├── search/                 # SearXNG gateway and engine allow-list
│   ├── content/                # Requests, rendering, extraction
│   ├── crawl/                  # Native and Scrapy backends
│   └── media/                  # YouTube transcript provider
├── transports/                 # MCP stdio and FastAPI adapters
├── tests/                      # Dependency-free self-checks
├── docker-compose.yml          # Local SearXNG gateway
├── mcp_config.example.json     # MCP client template
├── requirements.txt            # Dependency entry point
├── README.md                  # English documentation
└── README.zh-CN.md            # 中文文档

Comprobación de desarrollo

cd D:\my-websearch
py -3.12 -m my_websearch.tests.test_server

Salida esperada:

my_websearch self-check: ok

Servicio FastAPI opcional:

cd D:\my-websearch\my_websearch
py -3.12 -m transports.api

Luego abre http://127.0.0.1:8787/docs.

Licencia

Aún no se impone ninguna licencia. Añade un archivo LICENSE en la raíz antes de la distribución pública.