Perplexity MCP Server

Realize pesquisas na internet em tempo real com citações de fontes usando a API do Perplexity.

Documentação

Servidor MCP Perplexity

Um servidor MCP (Model Context Protocol) que fornece acesso aos poderosos recursos de busca da Perplexity AI, incluindo busca na web, pesquisa acadêmica, dados financeiros e opções avançadas de filtragem.

Recursos

O servidor MCP Perplexity oferece seis funções para busca abrangente e gerenciamento de resultados:

Funções de Busca (4)

Cada uma otimizada para diferentes casos de uso. Todas as funções retornam automaticamente URLs das fontes e salvam os resultados localmente se o cache estiver habilitado.

perplexity_search: Busca geral na web com informações em tempo real. Ideal para eventos atuais, conhecimento geral e fatos rápidos.
perplexity_academic_search: Filtra automaticamente para fontes acadêmicas (arxiv.org, pubmed, periódicos). Ideal para artigos de pesquisa, estudos científicos e conteúdo acadêmico.
perplexity_financial_search: Otimizada para domínios financeiros e dados recentes. Ideal para análise de ações, relatórios de lucros, arquivamentos na SEC e tendências de mercado.
perplexity_filtered_search: Busca avançada com múltiplas opções de filtragem. Ideal quando você precisa de filtragem específica de domínio, tipos de conteúdo ou resultados baseados em localização.

Funções de Gerenciamento de Cache (2)

Gerencie resultados de busca salvos anteriormente para fácil referência e reutilização.

list_previous: Lista todas as consultas de busca anteriores com IDs únicos, ordenadas por recência. Retorna um array JSON com detalhes da consulta.
get_previous_result: Recupera um resultado de busca em cache anterior pelo seu ID único de 10 caracteres.

Instalação

Certifique-se de ter o Go 1.23 ou superior instalado
Clone este repositório
Compile o servidor:
```
./run.sh build
```

Configuração

O servidor requer uma chave de API da Perplexity e suporta várias opções de configuração através de variáveis de ambiente:

Obrigatório

PERPLEXITY_API_KEY: Sua chave de API da Perplexity AI

Opcional

PERPLEXITY_DEFAULT_MODEL: Modelo padrão a ser usado (padrão: "sonar")
- sonar: Busca rápida e econômica para fatos rápidos
- sonar-pro: Busca abrangente com melhor profundidade e cobertura
PERPLEXITY_MAX_TOKENS: Máximo de tokens na resposta (padrão: 1024)
PERPLEXITY_TEMPERATURE: Aleatoriedade da resposta 0-2 (padrão: 0.2)
PERPLEXITY_TOP_P: Parâmetro de amostragem de núcleo (padrão: 0.9)
PERPLEXITY_TOP_K: Parâmetro de amostragem top-k (padrão: 0)
PERPLEXITY_TIMEOUT: Duração do tempo limite da solicitação (padrão: 30s)
PERPLEXITY_RETURN_IMAGES: Incluir imagens por padrão (padrão: false)
PERPLEXITY_RETURN_RELATED: Incluir perguntas relacionadas por padrão (padrão: false)
PERPLEXITY_RESULTS_ROOT_FOLDER: Diretório para armazenar resultados de busca em cache (padrão: vazio/desabilitado)

Uso

Modo Servidor MCP

Execute o servidor em modo MCP (padrão):

export PERPLEXITY_API_KEY="your-api-key"
./run.sh run
# or directly: ./perplexity

Modo Terminal (Teste CLI)

Teste funções individuais diretamente da linha de comando:

export PERPLEXITY_API_KEY="your-api-key"

# Test different search types
./run.sh search "latest AI news" sonar-pro
./run.sh academic "quantum computing" sonar-pro
./run.sh financial "AAPL earnings" sonar-pro
./run.sh filtered "renewable energy" sonar-pro

# Cache management
./run.sh list                    # List previous queries
./run.sh get ABC123XYZ0         # Get cached result by ID

Testes de Integração

Execute testes de integração contra a API real da Perplexity:

export PERPLEXITY_API_KEY="your-api-key"
./run.sh integration-test

Configuração do Cliente MCP

Para usar este servidor com um cliente MCP, adicione-o à configuração do seu cliente:

{
  "servers": {
    "perplexity": {
      "command": "path/to/perplexity",
      "env": {
        "PERPLEXITY_API_KEY": "your-api-key"
      }
    }
  }
}

Cache Local de Resultados

O servidor armazena automaticamente em cache os resultados de busca quando PERPLEXITY_RESULTS_ROOT_FOLDER está configurado:

Armazenamento: Cada resultado é salvo em /unique_id/result.md com metadados em /unique_id/metadata.yaml
IDs Únicos: Identificadores alfanuméricos de 10 caracteres (ex.: A1B2C3D4E5)
ID do Resultado: Quando o cache está habilitado, as respostas de busca incluem **Result ID:** ABC123XYZ0
Sem Reutilização: Cada busca cria uma nova entrada em cache, mesmo para consultas idênticas
Integração com LLM: Perfeito para LLMs referenciarem buscas anteriores em conversas

Exemplos de Gerenciamento de Cache

# List previous searches
echo '{"method": "tools/call", "params": {"name": "list_previous", "arguments": {}}}' | ./perplexity

# Get specific result
echo '{"method": "tools/call", "params": {"name": "get_previous_result", "arguments": {"unique_id": "A1B2C3D4E5"}}}' | ./perplexity

Referência de Funções

perplexity_search

Realiza uma busca geral na web.

Parâmetros:

query (obrigatório): A consulta de busca
model: Escolha 'sonar' para buscas rápidas ou 'sonar-pro' para resultados abrangentes (padrão: sonar)
search_domain_filter: Array de domínios a incluir
search_exclude_domains: Array de domínios a excluir
search_recency_filter: Filtro de tempo (hora, dia, semana, mês, ano)
return_images: Incluir imagens
return_related_questions: Incluir perguntas relacionadas
max_tokens: Máximo de tokens na resposta
temperature: Aleatoriedade da resposta (0-2)
date_range_start: Data de início (AAAA-MM-DD)
date_range_end: Data de término (AAAA-MM-DD)
location: Localização específica para busca geográfica

Exemplo:

{
  "query": "latest AI developments",
  "model": "sonar-pro",
  "search_recency_filter": "week",
  "return_citations": true
}

perplexity_academic_search

Busca artigos acadêmicos e conteúdo científico.

Parâmetros:

query (obrigatório): A consulta de busca acadêmica
subject_area: Assunto acadêmico (ex.: "Física", "Ciência da Computação")
model: Padrão é 'sonar-pro' para resultados acadêmicos abrangentes
search_domain_filter: Array de domínios acadêmicos
search_recency_filter: Filtro de tempo
max_tokens: Máximo de tokens na resposta
temperature: Aleatoriedade da resposta

Exemplo:

{
  "query": "quantum computing applications",
  "subject_area": "Physics",
  "search_recency_filter": "year"
}

perplexity_financial_search

Busca dados financeiros e arquivamentos na SEC.

Parâmetros:

query (obrigatório): A consulta de busca financeira
ticker: Símbolo da ação (ex.: "AAPL")
company_name: Nome da empresa
report_type: Tipo de relatório financeiro (ex.: "10-K", "10-Q", "8-K")
model: Padrão é 'sonar-pro' para dados financeiros abrangentes
search_recency_filter: Filtro de tempo
date_range_start: Data de início do relatório
date_range_end: Data de término do relatório
max_tokens: Máximo de tokens na resposta

Exemplo:

{
  "query": "quarterly earnings",
  "ticker": "MSFT",
  "report_type": "10-Q",
  "search_recency_filter": "month"
}

perplexity_filtered_search

Busca avançada com filtragem abrangente.

Parâmetros:

query (obrigatório): A consulta de busca
model: Escolha com base nas necessidades (padrão: sonar-pro)
search_domain_filter: Array de domínios a incluir
search_exclude_domains: Array de domínios a excluir
search_recency_filter: Filtro de tempo
content_type: Tipo de conteúdo (notícias, acadêmico, blog, etc.)
file_type: Filtro de tipo de arquivo (pdf, doc, html, etc.)
language: Filtro de idioma
country: País para busca geográfica específica
date_range_start: Data de início
date_range_end: Data de término
return_citations: Incluir citações
return_images: Incluir imagens
return_related_questions: Incluir perguntas relacionadas
max_tokens: Máximo de tokens na resposta
temperature: Aleatoriedade da resposta
custom_filters: Objeto com filtros adicionais de chave-valor

Exemplo:

{
  "query": "renewable energy innovations",
  "content_type": "news",
  "language": "English",
  "country": "Germany",
  "search_recency_filter": "month",
  "custom_filters": {
    "industry": "energy",
    "technology": "solar"
  }
}

list_previous

Lista todas as consultas de busca anteriores com metadados.

Parâmetros: Nenhum

Resposta: Array JSON com histórico de consultas, ordenado por recência (mais recente primeiro).

Exemplo:

[
  {
    "query": "latest AI developments",
    "unique_id": "A1B2C3D4E5",
    "datetime": "2025-01-15T10:30:45Z",
    "search_type": "general"
  },
  {
    "query": "quantum computing research",
    "unique_id": "X9Y8Z7W6V5",
    "datetime": "2025-01-15T09:15:30Z",
    "search_type": "academic"
  }
]

get_previous_result

Recupera um resultado de busca em cache por ID único.

Parâmetros:

unique_id (obrigatório): O ID alfanumérico de 10 caracteres do resultado em cache

Retorna: O resultado completo em markdown da busca em cache.

Exemplo:

{
  "unique_id": "A1B2C3D4E5"
}

Formato de Resposta

Todas as funções de busca retornam respostas no seguinte formato:

Conteúdo Principal: Os resultados da busca e a resposta
URLs das Fontes: Uma lista de URLs das fontes que o LLM pode acessar para mais detalhes
Fontes Detalhadas (se disponível): Título, URL e trecho para cada fonte
Perguntas Relacionadas (se solicitado): Perguntas de acompanhamento sugeridas
ID do Resultado (se cache habilitado): ID único de 10 caracteres para recuperar este resultado posteriormente

Exemplo de estrutura de resposta:

[Main search results content...]

## Source URLs
1. https://example.com/article1
2. https://example.com/article2
3. https://example.com/article3

## Detailed Sources
1. **Article Title**
   URL: https://example.com/article1
   Snippet: Brief excerpt from the article...

## Related Questions
- What are the latest developments?
- How does this compare to...?

**Result ID:** A1B2C3D4E5

Desenvolvimento

Executando Testes

Execute testes unitários:

./run.sh test

Execute testes de integração com API real:

./run.sh integration-test

Estrutura do Projeto

O servidor segue princípios de arquitetura limpa com separação de responsabilidades:

perplexity/
├── cmd/
│   └── main.go              # Thin entry point with terminal mode (~200 lines)
├── pkg/
│   ├── handler/             # MCP protocol layer
│   │   ├── handler.go       # Main MCP handler  
│   │   ├── tools.go         # Tool definitions
│   │   └── search_handlers.go # Parameter extraction
│   ├── search/              # Core business logic
│   │   ├── types.go         # Local search types
│   │   ├── search.go        # Strongly-typed search functions
│   │   └── client.go        # Perplexity API client
│   ├── cache/               # Result caching system
│   ├── config/              # Configuration management
│   └── types/               # Perplexity API types
├── test/
│   └── test.go             # Integration tests
└── README.md

Benefícios da Arquitetura

main.go enxuto: Reduzido de 360 para 197 linhas (redução de 45%)
Modo terminal: Teste CLI direto sem sobrecarga do protocolo MCP
Separação de responsabilidades: Tratamento do protocolo MCP separado da lógica de negócio
Fortemente tipado: Funções principais usam structs Go adequados em vez de map[string]interface{}
Tipos locais: Cada pacote possui seus próprios tipos, prevenindo dependências circulares
Teste fácil: A lógica de negócio pode ser testada independentemente

Tratamento de Erros

O servidor trata várias condições de erro:

Chave de API inválida ou ausente (401)
Limitação de taxa (429)
Parâmetros inválidos (400)
Erros do servidor (500)

Os erros são retornados com mensagens descritivas para ajudar no diagnóstico de problemas.

Licença

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