Complemento de búsqueda MCP DuckDuckGo

Un complemento de búsqueda de DuckDuckGo para el Protocolo de Contexto de Modelo (MCP), compatible con Claude Code. Ofrece funciones de búsqueda web con navegación avanzada y exploración de contenido.

Descripción

Este proyecto implementa un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona funciones de búsqueda web mediante DuckDuckGo. El complemento está diseñado para funcionar a la perfección con Claude Code o cualquier otro cliente compatible con MCP, ofreciendo no solo funciones básicas de búsqueda, sino también funciones avanzadas de navegación y exploración de resultados.

Características

• Herramienta de búsqueda web : realice búsquedas web con DuckDuckGo
• Resultados detallados : obtenga información detallada sobre resultados de búsqueda específicos
• Búsquedas relacionadas : descubre consultas de búsqueda relacionadas basadas en tu búsqueda original
• Soporte de paginación : navegue por múltiples páginas de resultados de búsqueda
• Extracción de dominio : ver información del dominio para cada resultado de búsqueda
• Filtrado avanzado : Filtrar resultados por sitio y período de tiempo
• Extracción de contenido mejorada : extraiga contenido enriquecido de páginas web, incluidos metadatos, estructura y fragmentos
• Rastreo web básico : siga los enlaces de los resultados de búsqueda para explorar contenido relacionado (profundidad configurable)
• Extracción de metadatos : extraiga títulos, autores, palabras clave, fechas de publicación y más
• Detección de redes sociales : identifique y extraiga enlaces de redes sociales de páginas web
• Análisis de la estructura del contenido : extraiga encabezados y secciones para comprender la estructura de la página web.
• Documentación de búsqueda : acceda a documentación completa sobre la función de búsqueda
• Asistente de búsqueda : obtenga ayuda para formular consultas de búsqueda efectivas
• Recurso parametrizado : recupera resultados de búsqueda formateados para consultas específicas

Requisitos

• Python 3.9 o superior
• pip (administrador de paquetes de Python)
• Paquetes de Python listados en pyproject.toml

Instalación

Desde PyPI

Nota: Este paquete aún no está publicado en PyPI. Instálelo desde el código fuente que aparece a continuación.

En el futuro, una vez publicado, podrás instalarlo con:

De la fuente

1. Clonar este repositorio:
   git clone https://github.com/gianlucamazza/mcp-duckduckgo.git cd mcp-duckduckgo
2. Instalar el paquete en modo de desarrollo:
   pip install -e .
   O utilice el script proporcionado:
   ./scripts/install_dev.sh
   O usa Make:
   make install

Uso

Iniciar el servidor manualmente

Para iniciar el servidor MCP:

O con parámetros personalizados:

O utilice el script proporcionado para el desarrollo:

O usa Make:

Uso con Claude Code

1. Instale el paquete desde la fuente como se describe arriba.
2. Configurar Claude Code para usar el complemento:
   claude mcp add duckduckgo-search -- mcp-duckduckgo
3. Para la configuración global (disponible en todos los proyectos):
   claude mcp add duckduckgo-search --scope global -- mcp-duckduckgo
4. Iniciar código de Claude:
   claude
5. Ahora puedes utilizar la funcionalidad de búsqueda de DuckDuckGo dentro de Claude Code.

Puntos finales disponibles

El complemento proporciona los siguientes puntos finales:

Herramienta: duckduckgo_web_search

Realiza una búsqueda web utilizando DuckDuckGo con los siguientes parámetros:

• query (obligatoria): La consulta de búsqueda (máximo 400 caracteres, 50 palabras)
• count (opcional, predeterminado: 10): Número de resultados por página (1-20)
• page (opcional, predeterminado: 1): Número de página para paginación
• site (opcional): limita los resultados a un sitio específico (por ejemplo, 'ejemplo.com')
• time_period (opcional): Filtrar resultados por período de tiempo ('día', 'semana', 'mes', 'año')

Ejemplo de uso en Claude Code:

Herramienta: duckduckgo_get_details

Recupera información detallada sobre un resultado de búsqueda específico:

• url (obligatorio): URL del resultado del que se obtendrán detalles

Ejemplo de uso en Claude Code:

Herramienta: duckduckgo_related_searches

Sugiere consultas de búsqueda relacionadas según la consulta original:

• query (obligatoria): Consulta de búsqueda original (máximo 400 caracteres)
• count (opcional, predeterminado: 5): Número de búsquedas relacionadas a devolver (1-10)

Ejemplo de uso en Claude Code:

Recurso: docs://search

Proporciona documentación completa sobre la funcionalidad de búsqueda.

Ejemplo de uso en Claude Code:

Indicación: search_assistant

Ayuda a formular consultas de búsqueda efectivas.

Ejemplo de uso en Claude Code:

Recurso: search://{query}

Recupera resultados de búsqueda formateados para una consulta específica.

Ejemplo de uso en Claude Code:

Uso de las funciones de navegación

El complemento proporciona varias funciones para ayudar a navegar y explorar los resultados de búsqueda:

Paginación

Para navegar por varias páginas de resultados de búsqueda:

Filtrar resultados

Para filtrar los resultados por sitio específico:

Para filtrar los resultados por período de tiempo:

Explorando los detalles de los resultados

Para obtener más información sobre un resultado de búsqueda específico:

Encontrar búsquedas relacionadas

Para descubrir consultas de búsqueda relacionadas:

Estas funciones de navegación se pueden combinar con las capacidades de lenguaje natural de Claude para crear una potente experiencia de búsqueda y exploración. Por ejemplo:

Notas de implementación

Esta implementación utiliza la interfaz web pública de DuckDuckGo y analiza la respuesta HTML para extraer resultados. Este enfoque se utiliza con fines de demostración, ya que DuckDuckGo no ofrece una API de búsqueda oficial. En un entorno de producción, se recomienda usar un servicio de búsqueda con una API oficial.

Extracción de contenido mejorada

El complemento DuckDuckGo incluye capacidades avanzadas de extracción de contenido que van más allá de los simples resultados de búsqueda:

Funciones de extracción de contenido

• Análisis completo de la página web : extraiga y analice el contenido HTML de las URL de los resultados de búsqueda
• Segmentación inteligente de contenido : identifique y extraiga las principales áreas de contenido de diferentes tipos de sitios web
• Extracción de metadatos enriquecidos : extraiga títulos, descripciones, autores, palabras clave y fechas de publicación.
• Detección de imágenes : identifica y extrae imágenes y medios principales de páginas web
• Integración de redes sociales : detecta y extrae enlaces a perfiles de redes sociales
• Análisis de la estructura del contenido : extraiga encabezados y secciones para comprender la organización de la página web
• Detección de fuente oficial : identifica si una fuente es oficial según señales de dominio y contenido

Capacidades de rastreo web

El complemento incluye funcionalidad básica de rastreo web:

• Profundidad configurable : siga enlaces de 0 a 3 niveles de profundidad desde la URL original
• Limitación de enlaces : controla el número máximo de enlaces a seguir por página (1-5)
• Restricción de dominio : opción para seguir únicamente enlaces dentro del mismo dominio
• Descubrimiento de contenido relacionado : encuentre y analice contenido relacionado con la búsqueda original

Uso de la extracción de contenido mejorada

Para utilizar las funciones mejoradas de extracción de contenido:

Para controlar el comportamiento de las arañas:

Desarrollo

El proyecto incluye varios scripts de utilidad en el directorio scripts para ayudar con el desarrollo:

• install_dev.sh : configura el entorno de desarrollo
• run.sh : ejecuta el servidor MCP con configuraciones de desarrollo
• test.sh : ejecuta pruebas con informes de cobertura
• lint.sh : ejecuta el linting y el formateo del código
• publish.sh : crea y publica el paquete en PyPI

Para mayor comodidad, también se proporciona un Makefile con los siguientes objetivos:

Pruebas

El proyecto incluye un conjunto completo de pruebas que abarca todas las funciones principales. Las pruebas se encuentran en el directorio tests/ .

Instalación de dependencias de prueba

Antes de ejecutar las pruebas, instale las dependencias de prueba:

Ejecución de pruebas

Puedes ejecutar todas las pruebas con:

Para ejecutar pruebas con informes de cobertura:

Para ejecutar un archivo de prueba específico:

Para ejecutar pruebas con salida detallada:

O utilice el script proporcionado:

O usa Make:

Estructura de la prueba

El conjunto de pruebas está organizado de la siguiente manera:

• conftest.py - Accesorios y configuraciones compartidas para pruebas
• test_models.py - Pruebas para modelos de datos
• test_search.py - Pruebas para la funcionalidad de búsqueda
• test_tools.py - Pruebas para herramientas MCP
• test_resources.py - Pruebas para recursos MCP
• test_integration.py - Pruebas de integración de extremo a extremo
• test_server.py - Pruebas del ciclo de vida del servidor

Para obtener más detalles sobre las pruebas, consulte el archivo tests/README.md .

Formato de código y linting

O utilice el script proporcionado:

O usa Make:

Publicación en PyPI

Si desea publicar el paquete en PyPI:

1. Actualice la versión en pyproject.toml
2. Asegúrese de tener las credenciales y herramientas necesarias:
   pip install build twine
3. Construir y publicar:
   python -m build twine upload dist/*

O utilice el script proporcionado si está disponible:

O usa Make:

Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.

Licencia

Instituto Tecnológico de Massachusetts (MIT)

Repositorio

https://github.com/gianlucamazza/mcp-duckduckgo