Perplexity MCP Server

Realiza investigaciones en internet en tiempo real con citas de fuentes utilizando la API de Perplexity.

Documentación

Servidor MCP de Perplexity

Un servidor MCP (Model Context Protocol) que proporciona acceso a las potentes capacidades de búsqueda de Perplexity AI, incluyendo búsqueda web, investigación académica, datos financieros y opciones avanzadas de filtrado.

Características

El servidor MCP de Perplexity ofrece seis funciones para búsqueda integral y gestión de resultados:

Funciones de Búsqueda (4)

Cada una optimizada para diferentes casos de uso. Todas las funciones devuelven automáticamente las URL de las fuentes y guardan los resultados localmente si el caché está habilitado.

perplexity_search: Búsqueda web general con información en tiempo real. Ideal para eventos actuales, conocimiento general y datos rápidos.
perplexity_academic_search: Filtra automáticamente a fuentes académicas (arxiv.org, pubmed, revistas). Ideal para artículos de investigación, estudios científicos y contenido académico.
perplexity_financial_search: Optimizada para dominios financieros y datos recientes. Ideal para análisis de acciones, informes de ganancias, presentaciones ante la SEC y tendencias del mercado.
perplexity_filtered_search: Búsqueda avanzada con múltiples opciones de filtrado. Ideal cuando necesitas filtrado específico por dominio, tipos de contenido o resultados basados en ubicación.

Funciones de Gestión de Caché (2)

Gestionan resultados de búsqueda previamente guardados para facilitar su consulta y reutilización.

list_previous: Lista todas las consultas de búsqueda anteriores con identificadores únicos, ordenadas por fecha. Devuelve un array JSON con los detalles de las consultas.
get_previous_result: Recupera un resultado de búsqueda previamente almacenado en caché mediante su identificador único de 10 caracteres.

Instalación

Asegúrate de tener Go 1.23 o posterior instalado
Clona este repositorio
Compila el servidor:
```
./run.sh build
```

Configuración

El servidor requiere una clave API de Perplexity y admite varias opciones de configuración mediante variables de entorno:

Requerido

PERPLEXITY_API_KEY: Tu clave API de Perplexity AI

Opcional

PERPLEXITY_DEFAULT_MODEL: Modelo predeterminado a utilizar (predeterminado: "sonar")
- sonar: Búsqueda rápida y rentable para datos rápidos
- sonar-pro: Búsqueda integral con mejor profundidad y cobertura
PERPLEXITY_MAX_TOKENS: Máximo de tokens en la respuesta (predeterminado: 1024)
PERPLEXITY_TEMPERATURE: Aleatoriedad de la respuesta 0-2 (predeterminado: 0.2)
PERPLEXITY_TOP_P: Parámetro de muestreo de núcleo (predeterminado: 0.9)
PERPLEXITY_TOP_K: Parámetro de muestreo top-k (predeterminado: 0)
PERPLEXITY_TIMEOUT: Duración del tiempo de espera de la solicitud (predeterminado: 30s)
PERPLEXITY_RETURN_IMAGES: Incluir imágenes de forma predeterminada (predeterminado: false)
PERPLEXITY_RETURN_RELATED: Incluir preguntas relacionadas de forma predeterminada (predeterminado: false)
PERPLEXITY_RESULTS_ROOT_FOLDER: Directorio para almacenar resultados de búsqueda en caché (predeterminado: vacío/deshabilitado)

Uso

Modo Servidor MCP

Ejecuta el servidor en modo MCP (predeterminado):

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

Modo Terminal (Pruebas CLI)

Prueba funciones individuales directamente desde la línea de comandos:

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

Pruebas de Integración

Ejecuta pruebas de integración contra la API real de Perplexity:

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

Configuración del Cliente MCP

Para usar este servidor con un cliente MCP, agrégalo a la configuración de tu cliente:

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

Caché Local de Resultados

El servidor almacena automáticamente en caché los resultados de búsqueda cuando PERPLEXITY_RESULTS_ROOT_FOLDER está configurado:

Almacenamiento: Cada resultado se guarda en /unique_id/result.md con metadatos en /unique_id/metadata.yaml
Identificadores únicos: Identificadores alfanuméricos de 10 caracteres (por ejemplo, A1B2C3D4E5)
ID de resultado: Cuando el caché está habilitado, las respuestas de búsqueda incluyen **Result ID:** ABC123XYZ0
Sin reutilización: Cada búsqueda crea una nueva entrada en caché, incluso para consultas idénticas
Integración con LLM: Perfecto para que los LLM hagan referencia a búsquedas anteriores en conversaciones

Ejemplos de Gestión de Caché

# 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

Referencia de Funciones

perplexity_search

Realiza una búsqueda web general.

Parámetros:

query (requerido): La consulta de búsqueda
model: Elige 'sonar' para búsquedas rápidas o 'sonar-pro' para resultados integrales (predeterminado: sonar)
search_domain_filter: Array de dominios a incluir
search_exclude_domains: Array de dominios a excluir
search_recency_filter: Filtro de tiempo (hora, día, semana, mes, año)
return_images: Incluir imágenes
return_related_questions: Incluir preguntas relacionadas
max_tokens: Máximo de tokens en la respuesta
temperature: Aleatoriedad de la respuesta (0-2)
date_range_start: Fecha de inicio (AAAA-MM-DD)
date_range_end: Fecha de fin (AAAA-MM-DD)
location: Ubicación de búsqueda específica por geografía

Ejemplo:

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

perplexity_academic_search

Busca artículos académicos y contenido académico.

Parámetros:

query (requerido): La consulta de búsqueda académica
subject_area: Materia académica (por ejemplo, "Física", "Ciencias de la Computación")
model: Se establece en 'sonar-pro' de forma predeterminada para resultados académicos integrales
search_domain_filter: Array de dominios académicos
search_recency_filter: Filtro de tiempo
max_tokens: Máximo de tokens en la respuesta
temperature: Aleatoriedad de la respuesta

Ejemplo:

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

perplexity_financial_search

Busca datos financieros y presentaciones ante la SEC.

Parámetros:

query (requerido): La consulta de búsqueda financiera
ticker: Símbolo bursátil (por ejemplo, "AAPL")
company_name: Nombre de la empresa
report_type: Tipo de informe financiero (por ejemplo, "10-K", "10-Q", "8-K")
model: Se establece en 'sonar-pro' de forma predeterminada para datos financieros integrales
search_recency_filter: Filtro de tiempo
date_range_start: Fecha de inicio del informe
date_range_end: Fecha de fin del informe
max_tokens: Máximo de tokens en la respuesta

Ejemplo:

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

perplexity_filtered_search

Búsqueda avanzada con filtrado integral.

Parámetros:

query (requerido): La consulta de búsqueda
model: Elige según tus necesidades (se establece en sonar-pro de forma predeterminada)
search_domain_filter: Array de dominios a incluir
search_exclude_domains: Array de dominios a excluir
search_recency_filter: Filtro de tiempo
content_type: Tipo de contenido (noticias, académico, blog, etc.)
file_type: Filtro de tipo de archivo (pdf, doc, html, etc.)
language: Filtro de idioma
country: País para búsqueda específica por geografía
date_range_start: Fecha de inicio
date_range_end: Fecha de fin
return_citations: Incluir citas
return_images: Incluir imágenes
return_related_questions: Incluir preguntas relacionadas
max_tokens: Máximo de tokens en la respuesta
temperature: Aleatoriedad de la respuesta
custom_filters: Objeto con filtros adicionales de clave-valor

Ejemplo:

{
  "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 las consultas de búsqueda anteriores con metadatos.

Parámetros: Ninguno

Respuesta: Array JSON con el historial de consultas, ordenado por fecha (más recientes primero).

Ejemplo:

[
  {
    "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 un resultado de búsqueda almacenado en caché por identificador único.

Parámetros:

unique_id (requerido): El identificador alfanumérico de 10 caracteres del resultado almacenado en caché

Devuelve: El resultado completo en formato markdown de la búsqueda almacenada en caché.

Ejemplo:

{
  "unique_id": "A1B2C3D4E5"
}

Formato de Respuesta

Todas las funciones de búsqueda devuelven respuestas en el siguiente formato:

Contenido principal: Los resultados de búsqueda y la respuesta
URL de fuentes: Una lista de URL de fuentes que el LLM puede consultar para obtener más detalles
Fuentes detalladas (si están disponibles): Título, URL y fragmento de cada fuente
Preguntas relacionadas (si se solicitan): Preguntas de seguimiento sugeridas
ID de resultado (si el caché está habilitado): Identificador único de 10 caracteres para recuperar este resultado más adelante

Estructura de respuesta de ejemplo:

[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

Desarrollo

Ejecución de Pruebas

Ejecuta pruebas unitarias:

./run.sh test

Ejecuta pruebas de integración con la API real:

./run.sh integration-test

Estructura del Proyecto

El servidor sigue principios de arquitectura limpia con separación 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

Beneficios de la Arquitectura

main.go reducido: Reducido de 360 a 197 líneas (reducción del 45%)
Modo terminal: Pruebas CLI directas sin la sobrecarga del protocolo MCP
Separación de responsabilidades: El manejo del protocolo MCP está separado de la lógica de negocio
Fuertemente tipado: Las funciones principales usan estructuras Go adecuadas en lugar de map[string]interface{}
Tipos locales: Cada paquete es dueño de sus tipos, evitando dependencias circulares
Pruebas fáciles: La lógica de negocio se puede probar de forma independiente

Manejo de Errores

El servidor maneja varias condiciones de error:

Clave API inválida o faltante (401)
Límite de velocidad (429)
Parámetros inválidos (400)
Errores del servidor (500)

Los errores se devuelven con mensajes descriptivos para ayudar a diagnosticar problemas.

Licencia

Licencia MIT: consulta el archivo LICENSE para obtener más detalles.