Deep Research

Deep Research MCP Server

Deep Research es una herramienta basada en agentes que proporciona capacidades de búsqueda web e investigación avanzada. Utiliza el smolagents de HuggingFace y está implementado como un servidor MCP.

Este proyecto se basa en el ejemplo open_deep_research de HuggingFace.

Características

• Búsqueda web y recopilación de información
• Análisis de PDF y documentos
• Análisis y descripción de imágenes
• Recuperación de transcripciones de YouTube
• Búsqueda en sitios de archivo

Requisitos

• Python 3.11 o superior
• Gestor de paquetes uv
• Las siguientes claves de API:
  • Clave de API de OpenAI
  • Token de HuggingFace
  • Clave de SerpAPI

Instalación

1. Clona el repositorio:

git clone https://github.com/Hajime-Y/deep-research-mcp.git
cd deep-research-mcp

2. Crea un entorno virtual e instala las dependencias:

uv venv
source .venv/bin/activate # For Linux or Mac
# .venv\Scripts\activate # For Windows
uv sync

Variables de Entorno

Crea un archivo .env en el directorio raíz del proyecto y establece las siguientes variables de entorno:

OPENAI_API_KEY=your_openai_api_key
HF_TOKEN=your_huggingface_token
SERPER_API_KEY=your_serper_api_key

Puedes obtener una SERPER_API_KEY registrándote en Serper.dev.

Uso

Inicia el servidor MCP:

uv run deep_research.py

Esto lanzará el agente deep_research como un servidor MCP.

Uso con Docker

También puedes ejecutar este servidor MCP en un contenedor Docker:

# Build the Docker image
docker build -t deep-research-mcp .

# Run with required API keys
docker run -p 8080:8080 \
  -e OPENAI_API_KEY=your_openai_api_key \
  -e HF_TOKEN=your_huggingface_token \
  -e SERPER_API_KEY=your_serper_api_key \
  deep-research-mcp

Registro con Clientes MCP

Para registrar este contenedor Docker como un servidor MCP en diferentes clientes:

Claude Desktop

Añade lo siguiente a tu archivo de configuración de Claude Desktop (normalmente ubicado en ~/.config/Claude/claude_desktop_config.json en Linux, ~/Library/Application Support/Claude/claude_desktop_config.json en macOS, o %APPDATA%\Claude\claude_desktop_config.json en Windows):

{
  "mcpServers": {
    "deep-research-mcp": {
      "command": "docker",
      "args": [
        "run", 
        "-i", 
        "--rm", 
        "-e", "OPENAI_API_KEY=your_openai_api_key",
        "-e", "HF_TOKEN=your_huggingface_token", 
        "-e", "SERPER_API_KEY=your_serper_api_key",
        "deep-research-mcp"
      ]
    }
  }
}

Cursor IDE

Para Cursor IDE, añade la siguiente configuración:

{
  "mcpServers": {
    "deep-research-mcp": {
      "command": "docker",
      "args": [
        "run", 
        "-i", 
        "--rm", 
        "-e", "OPENAI_API_KEY=your_openai_api_key",
        "-e", "HF_TOKEN=your_huggingface_token", 
        "-e", "SERPER_API_KEY=your_serper_api_key",
        "deep-research-mcp"
      ]
    }
  }
}

Uso con Servidor MCP Remoto

Si estás ejecutando el servidor MCP en una máquina remota o exponiéndolo como un servicio, puedes usar la configuración basada en URL:

{
  "mcpServers": {
    "deep-research-mcp": {
      "url": "http://your-server-address:8080/mcp",
      "type": "sse"
    }
  }
}

Componentes Clave

• deep_research.py: Punto de entrada para el servidor MCP
• create_agent.py: Creación y configuración del agente
• scripts/: Varias herramientas y utilidades
  • text_web_browser.py: Navegador web basado en texto
  • text_inspector_tool.py: Herramienta de inspección de archivos
  • visual_qa.py: Herramienta de análisis de imágenes
  • mdconvert.py: Convierte varios formatos de archivo a Markdown

Licencia

Este proyecto se proporciona bajo la Licencia Apache 2.0.

Agradecimientos

Este proyecto utiliza código de los proyectos smolagents de HuggingFace y autogen de Microsoft.