Tavily MCP Server

Pesquisa na web usando a API do Tavily.

Documentação

Tavily MCP Server

Um servidor MCP (Model Context Protocol) pronto para produção que fornece recursos de busca na web usando a API Tavily. Este servidor integra-se perfeitamente com Roo e outros assistentes de IA compatíveis com MCP.

Recursos

🔍 Busca na Web: Busca poderosa na web usando a API de busca otimizada por IA da Tavily
🎯 Respostas Diretas: Obtenha respostas imediatas para consultas quando disponíveis
📊 Resultados Configuráveis: Controle a profundidade da busca, o número de resultados e a filtragem por domínio
🚀 Pronto para Produção: Construído com TypeScript, testes abrangentes e implantação com PM2
🔒 Seguro: Gerenciamento de chave de API baseado em ambiente
📈 Monitoramento: Registro completo e monitoramento de processos com PM2
🧪 Bem Testado: Cobertura abrangente de testes unitários e de integração

Início Rápido

Pré-requisitos

Node.js 18+
npm ou yarn
Chave da API Tavily (Obtenha uma aqui)
PM2 (para implantação em produção)

Instalação e Implantação

Clone e configure:
```
cd tavily-mcp-server
npm install
```

Defina sua chave de API:

export TAVILY_API_KEY="your-api-key-here"

Execute os testes:
```
npm test
npm run test:coverage
```
Implante com PM2:
```
./deploy.sh
```

É isso! O servidor está agora em execução e pronto para conexões MCP.

Desenvolvimento

Compilação e Testes

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Run unit tests
npm test

# Run tests with coverage
npm run test:coverage

# Run integration tests
./test-mcp.js

# Lint code
npm run lint
npm run lint:fix

Testes

O projeto inclui testes abrangentes:

Testes Unitários: Testam componentes e funções individuais
Testes de Integração: Testam a funcionalidade completa do servidor MCP
Testes de Protocolo MCP: Validam a conformidade com o protocolo MCP
Testes de API: Testam a integração com a API Tavily (requer chave de API válida)

# Run all tests
npm test

# Run with coverage report
npm run test:coverage

# Test the actual MCP server
./test-mcp.js

Configuração

Variáveis de Ambiente

TAVILY_API_KEY (obrigatório): Sua chave de API Tavily
NODE_ENV (opcional): Defina como "production" para implantação em produção

Configuração do PM2

O arquivo pm2-apps.json contém a configuração de produção:

{
  "apps": [{
    "name": "tavily-mcp-server",
    "script": "dist/index.js",
    "instances": 1,
    "exec_mode": "fork",
    "env": {
      "NODE_ENV": "production",
      "TAVILY_API_KEY": "your-api-key"
    }
  }]
}

Uso com Roo

Instalação Global

Adicione às suas configurações globais de MCP (~/.roo/mcp_settings.json):

{
  "mcpServers": {
    "tavily-search": {
      "command": "node",
      "args": ["/home/ubuntu/roo-tavily/tavily-mcp-server/dist/index.js"],
      "env": {
        "TAVILY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Instalação Específica do Projeto

Adicione às configurações de MCP do seu projeto (.roo/mcp.json):

{
  "mcpServers": {
    "tavily-search": {
      "command": "node",
      "args": ["./tavily-mcp-server/dist/index.js"],
      "env": {
        "TAVILY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Usando a Ferramenta de Busca na Web

Uma vez configurado, você pode usar a ferramenta de busca na web no Roo:

<use_mcp_tool>
<server_name>tavily-search</server_name>
<tool_name>web_search</tool_name>
<arguments>
{
  "query": "latest developments in AI",
  "search_depth": "advanced",
  "max_results": 10,
  "include_answer": true
}
</arguments>
</use_mcp_tool>

Referência da API

Ferramenta web_search

Busque na web usando a API de busca otimizada por IA da Tavily.

Parâmetros

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`query`	string	✅	-	A consulta de busca a ser executada
`search_depth`	string	❌	"basic"	Profundidade da busca: "basic" ou "advanced"
`include_answer`	boolean	❌	true	Se deve incluir uma resposta direta
`max_results`	number	❌	5	Número de resultados (1-20)
`include_domains`	string[]	❌	-	Domínios a incluir na busca
`exclude_domains`	string[]	❌	-	Domínios a excluir da busca

Formato da Resposta

A ferramenta retorna resultados de busca formatados, incluindo:

Resposta Direta: Resposta gerada por IA para a consulta (se disponível)
Resultados da Busca: Lista de páginas da web relevantes com:
- Título e URL
- Trecho do conteúdo
- Pontuação de relevância
- Data de publicação (se disponível)
Perguntas de Acompanhamento: Consultas relacionadas sugeridas

Exemplo de Resposta

# Search Results for: "latest developments in AI"

## Direct Answer
Recent AI developments include advances in large language models, 
multimodal AI systems, and improved reasoning capabilities...

## Search Results

### 1. Major AI Breakthroughs in 2024
**URL:** https://example.com/ai-breakthroughs
**Published:** 2024-01-15
**Score:** 0.95

Recent developments in artificial intelligence have shown remarkable 
progress in areas such as natural language processing...

---

### 2. OpenAI Announces GPT-5
**URL:** https://example.com/gpt5-announcement
**Score:** 0.92

OpenAI has announced the development of GPT-5, promising significant 
improvements in reasoning and multimodal capabilities...

---

## Follow-up Questions
1. What are the implications of these AI developments?
2. How do these advances compare to previous years?
3. What challenges remain in AI development?

Implantação em Produção

Gerenciamento do PM2

# Start the server
pm2 start pm2-apps.json

# View status
pm2 status

# View logs
pm2 logs tavily-mcp-server

# Restart server
pm2 restart tavily-mcp-server

# Stop server
pm2 stop tavily-mcp-server

# Monitor all processes
pm2 monit

Proxy Reverso Nginx (Opcional)

Se você precisar de acesso HTTP, pode configurar um proxy reverso Nginx:

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Monitoramento e Registros

Registros do Aplicativo: /var/log/pm2/tavily-mcp-server.log
Registros de Erros: /var/log/pm2/tavily-mcp-server-error.log
Monitoramento do PM2: pm2 monit

Solução de Problemas

Problemas Comuns

"A variável de ambiente TAVILY_API_KEY é obrigatória"
- Certifique-se de que sua chave de API está definida: export TAVILY_API_KEY="your-key"
- Verifique se a configuração do PM2 tem a chave de API correta
Erros de "Cannot find module"
- Execute npm install para instalar as dependências
- Certifique-se de que você compilou o projeto: npm run build
O servidor não inicia
- Verifique os registros: pm2 logs tavily-mcp-server
- Verifique se a chave de API é válida
- Certifique-se de que a porta não está em uso
Solicitações de busca falhando
- Verifique se a chave de API é válida e tem créditos
- Verifique a conectividade de rede
- Revise os registros de erros para erros específicos da API

Modo de Depuração

Execute o servidor em modo de depuração:

NODE_ENV=development npm run dev

Testando a Conexão

Teste o servidor MCP diretamente:

./test-mcp.js

Contribuindo

Faça um fork do repositório
Crie um branch de recurso: git checkout -b feature-name
Faça suas alterações
Adicione testes para a nova funcionalidade
Certifique-se de que todos os testes passam: npm test
Envie um pull request

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

Suporte

📧 Email: support@roo.com
🐛 Problemas: GitHub Issues
📖 Documentação: Documentação do Roo

Construído com ❤️ pela equipe Roo