Ollama Deep Researcher

Conduz pesquisas aprofundadas usando LLMs locais do Ollama, aproveitando Tavily e Perplexity para capacidades abrangentes de busca.

GitHub

Experimente este MCPPatrocinado

Documentação

⛔ ARQUIVADO — este código foi movido

Migrado para o monorepo da plataforma mcpcentral em 2026-07-23 (ADR-043).

Trabalhe aqui em vez disso: mcpcentral-io/mcpcentral → apps/deep-researcher/ Worker: mcpcentral-deep-researcher

Este repositório é somente leitura e mantido para histórico. Veja DEPRECATED.md.

Ollama Deep Researcher DXT Extension

Visão Geral

Ollama Deep Researcher é uma Extensão de Desktop (DXT) que permite pesquisa avançada de tópicos usando busca na web e síntese por LLM, alimentada por um servidor MCP local. Ela suporta parâmetros de pesquisa configuráveis, rastreamento de status e acesso a recursos, e é projetada para integração perfeita com o ecossistema DXT.

Pesquise qualquer tópico usando APIs de busca na web (Tavily, Perplexity, Exa) e LLMs (Ollama, DeepSeek, etc.)
Configure loops máximos de pesquisa, modelo LLM e API de busca
Acompanhe o status da pesquisa em andamento
Acesse os resultados da pesquisa como recursos via protocolo MCP

Recursos

Implementa o protocolo MCP sobre stdio para operação local e segura
Programação defensiva: tratamento de erros, timeouts e validação
Registro e depuração via stderr
Compatível com ambientes host DXT

Estrutura de Diretórios

.
├── manifest.json         # DXT manifest (see MANIFEST.md for spec)
├── src/
│   ├── index.ts         # MCP server entrypoint (Node.js, stdio transport)
│   └── assistant/       # Python research logic
│       └── run_research.py
├── README.md            # This documentation
└── ...

Instalação e Configuração

Clone o repositório e instale as dependências:

git clone <your-repo-url>
cd mcp-server-ollama-deep-researcher
npm install

Instale as dependências Python para o assistente:

cd src/assistant
pip install -r requirements.txt
# or use pyproject.toml/uv if preferred

Defina as variáveis de ambiente necessárias para as APIs de busca na web:
- Para Tavily: TAVILY_API_KEY
- Para Perplexity: PERPLEXITY_API_KEY
- Para Exa: EXA_API_KEY (Obtenha o seu em https://dashboard.exa.ai/api-keys)
- Opcional: LANGSMITH_API_KEY, LANGSMITH_TRACING=true, OLLAMA_BASE_URL (padrão é http://localhost:11434)
- Exemplo:
```
export TAVILY_API_KEY=your_tavily_key
export PERPLEXITY_API_KEY=your_perplexity_key
export EXA_API_KEY=your_exa_key
```
- Prefere não manter chaves em texto puro no disco? Veja Opcional: segredos seguros com 1Password abaixo.
Compile o servidor TypeScript (se necessário):
```
npm run build
```

Execute a extensão localmente para teste:

node dist/index.js
# Or use the DXT host to load the extension per DXT documentation

Uso

Pesquise um tópico:
- Use a ferramenta research com { "topic": "Your subject" }
Obtenha o status da pesquisa:
- Use a ferramenta get_status
Configure os parâmetros de pesquisa:
- Use a ferramenta configure com qualquer um de: maxLoops, llmModel, searchApi

Manifesto

Veja manifest.json para o manifesto DXT completo, incluindo esquemas de ferramentas e modelos de recursos. Segue DXT MANIFEST.md.

Registro e Depuração

Todos os logs e erros do servidor são enviados para stderr para depuração.
Subprocessos de pesquisa são encerrados após 30 minutos para evitar travamentos.
Solicitações inválidas e erros de configuração retornam mensagens de erro claras e estruturadas.

Segurança e Boas Práticas

Todos os esquemas de ferramentas são validados antes da execução.
Chaves de API são necessárias para as APIs de busca na web e nunca são registradas.
O protocolo MCP é usado sobre stdio para comunicação local e segura.

Teste e Validação

Valide a extensão carregando-a em um host compatível com DXT.
Garanta que todas as chamadas de ferramentas retornem respostas JSON válidas e estruturadas.
Verifique se o manifesto carrega e se a extensão se registra como um DXT.

Solução de Problemas

Chave de API ausente: Garanta que TAVILY_API_KEY, PERPLEXITY_API_KEY ou EXA_API_KEY esteja definida no seu ambiente, dependendo de qual API de busca você está usando.
Erros Python: Verifique as dependências Python e os logs em stderr.
Timeouts: Subprocessos de pesquisa são limitados a 30 minutos.

Comparação de APIs de Busca

Tavily: Busca na web rápida e abrangente com extração de conteúdo bruto
Perplexity: Busca com IA que fornece resumos em linguagem natural e citações
Exa: Mecanismo de busca neural otimizado para busca semântica com destaques

Opcional: segredos seguros com 1Password

Se você usa 1Password, pode manter as chaves de API em texto puro fora do disco e do contexto do seu agente de codificação de IA. Isso é opcional e aditivo — a configuração em texto puro acima continua funcionando sem alterações. Pré-requisitos: 1Password para Mac ou Linux, o CLI op (brew install --cask 1password-cli) e sqlite3.

Crie um Ambiente 1Password contendo essas oito variáveis (as quatro chaves são secretas; o restante é configuração não secreta):

Variável	Secreta?
`TAVILY_API_KEY`, `PERPLEXITY_API_KEY`, `EXA_API_KEY`, `LANGSMITH_API_KEY`	sim
`OLLAMA_BASE_URL`, `LANGSMITH_TRACING`, `LANGSMITH_ENDPOINT`, `LANGSMITH_PROJECT`	não

Você pode importar um .env existente diretamente ao criar o Ambiente. Depois que ele existir, escolha qualquer um dos três mecanismos abaixo (A é o padrão de codificação com IA; B é o lançamento MCP recomendado pelo 1Password; C é um fallback para hosts que não podem executar op).

A. `.env` montado + hook de validação (mantém texto puro fora do contexto do LLM)

Ambientes 1Password montam um .env local como um pipe nomeado UNIX (FIFO): o conteúdo é transmitido sob demanda para leitores autorizados e nunca é armazenado em disco. Um hook PreToolUse do Claude Code valida a montagem antes que o agente execute comandos shell.

No aplicativo de desktop do 1Password, abra seu Ambiente → Destinos → Arquivo .env local → Escolha o caminho do arquivo → .env → Montar. Verifique com cat .env (aprova via Touch ID; a autenticação dura até o 1Password bloquear).
.1password/environments.toml (commitado) informa ao hook quais caminhos validar — já definido para mount_paths = [".env"].
Instale o hook de validação localmente:
```
git clone https://github.com/1Password/agent-hooks /tmp/agent-hooks
/tmp/agent-hooks/install.sh --agent claude-code --target-dir .
```
Isso cria .claude/claude-code-1password-hooks-bundle/ e .claude/settings.json (ambos ignorados pelo git). O hook é fail-open: se o 1Password ou sqlite3 estiver indisponível, ele permite a execução, então contribuidores que não usam 1Password não são afetados.
Teste: echo '{"command":"echo test","workspace_roots":["'"$PWD"'"]}' | .claude/claude-code-1password-hooks-bundle/bin/run-hook.sh 1password-validate-mounted-env-files → {"permission":"allow"} enquanto desbloqueado, deny com instruções de correção quando bloqueado.

B. `op run --environment` para o lançamento do servidor MCP

Copie .mcp.json.1password.example → .mcp.json (ignorado pelo git), substitua <ENVIRONMENT_ID> pelo seu ID de Ambiente, e seu host MCP resolverá os segredos no lançamento via op run. A configuração não secreta permanece no bloco env; os segredos são injetados do Ambiente. O modelo usa o caminho completo /opt/homebrew/bin/op porque hosts iniciados por GUI (ex.: Claude Desktop) não herdam seu $PATH do shell — ajuste se o seu op estiver em outro lugar (which op).

Fallback se o seu CLI op não tiver --environment (o subcomando environment faz parte do beta de Ambientes do 1Password e está ausente em algumas versões, ex.: op v2.34.x): use op run --env-file .env contra um .env simples de referências op:// em vez disso. Crie o item uma vez (op item create --vault "Your Vault" --category "Login" --title "ollama-deep-researcher" "TAVILY_API_KEY[concealed]=..." …), depois escreva um .env de referências ignorado pelo git e aponte o lançador para ele:
# .env (gitignored) — references only, no plaintext
# TAVILY_API_KEY=op://Your Vault/ollama-deep-researcher/TAVILY_API_KEY
# …
op run --env-file .env -- node build/index.js
O mesmo .env também alimenta o Docker (veja abaixo), então um arquivo de referências cobre ambos os caminhos de lançamento. op run solicita Touch ID uma vez por lançamento.

C. Modelo `op inject` para `.mcp.json`

Para hosts MCP que não podem usar op run, copie .mcp.json.template → um arquivo de trabalho, substitua <vault> pelo nome do seu cofre e então materialize as referências {{ op://... }} em valores reais:

op inject -i .mcp.json.template -o .mcp.json

op inject escreve a saída com modo de arquivo 0600. .mcp.json é ignorado pelo git. Recompile após rotacionar segredos no 1Password. (Requer CLI op com suporte padrão a itens/cofres; a forma op run --environment na opção B adicionalmente requer o beta de Ambientes do 1Password.)

Docker

docker-compose.yml interpola todas as oito variáveis do ambiente. Execute o compose através de op run --env-file para que as referências op:// em .env (ou a montagem FIFO, se você configurou uma em A) sejam resolvidas e encaminhadas para o contêiner:

op run --env-file .env -- docker compose up