Deep Research

Servidor MCP Deep Research

Deep Research é uma ferramenta baseada em agentes que fornece recursos de pesquisa na web e pesquisa avançada. Ela utiliza o smolagents da HuggingFace e é implementada como um servidor MCP.

Este projeto é baseado no exemplo open_deep_research da HuggingFace.

Recursos

• Pesquisa na web e coleta de informações
• Análise de PDF e documentos
• Análise e descrição de imagens
• Recuperação de transcrições do YouTube
• Pesquisa em sites de arquivo

Requisitos

• Python 3.11 ou superior
• Gerenciador de pacotes uv
• As seguintes chaves de API:
  • Chave da API OpenAI
  • Token da HuggingFace
  • Chave da SerpAPI

Instalação

1. Clone o repositório:

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

2. Crie um ambiente virtual e instale as dependências:

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

Variáveis de Ambiente

Crie um arquivo .env no diretório raiz do projeto e defina as seguintes variáveis de ambiente:

OPENAI_API_KEY=your_openai_api_key
HF_TOKEN=your_huggingface_token
SERPER_API_KEY=your_serper_api_key

Você pode obter uma SERPER_API_KEY cadastrando-se em Serper.dev.

Uso

Inicie o servidor MCP:

uv run deep_research.py

Isso iniciará o agente deep_research como um servidor MCP.

Uso com Docker

Você também pode executar este servidor MCP em um contêiner 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 em Clientes MCP

Para registrar este contêiner Docker como um servidor MCP em diferentes clientes:

Claude Desktop

Adicione o seguinte ao arquivo de configuração do Claude Desktop (normalmente localizado em ~/.config/Claude/claude_desktop_config.json no Linux, ~/Library/Application Support/Claude/claude_desktop_config.json no macOS ou %APPDATA%\Claude\claude_desktop_config.json no 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"
      ]
    }
  }
}

IDE Cursor

Para o IDE Cursor, adicione a seguinte configuração:

{
  "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 com Servidor MCP Remoto

Se você estiver executando o servidor MCP em uma máquina remota ou expondo-o como um serviço, você pode usar a configuração baseada em URL:

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

Componentes Principais

• deep_research.py: Ponto de entrada do servidor MCP
• create_agent.py: Criação e configuração do agente
• scripts/: Várias ferramentas e utilitários
  • text_web_browser.py: Navegador web baseado em texto
  • text_inspector_tool.py: Ferramenta de inspeção de arquivos
  • visual_qa.py: Ferramenta de análise de imagens
  • mdconvert.py: Converte vários formatos de arquivo para Markdown

Licença

Este projeto é fornecido sob a Licença Apache 2.0.

Agradecimentos

Este projeto utiliza código dos projetos smolagents da HuggingFace e autogen da Microsoft.