Perplexity MCP Server

An MCP server providing tools to interact with the Perplexity AI API, built using the mcp-ts-template. This server allows AI agents compatible with the Model Context Protocol (MCP) to leverage Perplexity's search-augmented query capabilities. Includes a showThinking parameter to enable reasoning models to show its internal reasoning process.

Core Features

• Utilities: Reusable components for logging, error handling, ID generation, rate limiting, and request context management.
• Type Safety: Strong typing with TypeScript.
• Error Handling: Robust error handling system.
• Security: Basic security features like input sanitization.
• Perplexity Tool: A ready-to-use tool for interacting with the Perplexity Search API.

.clinerules: This repository includes a .clinerules file that serves as a developer cheat sheet for LLM coding agents (like Cline) providing quick references for codebase patterns, file locations, and code snippets specific to this project.

Table of Contents

• Overview
  • What is Model Context Protocol?
  • Architecture & Components
• Features
  • Core Utilities
  • Type Safety
  • Error Handling
  • Security
  • Perplexity Search Tool
• Installation
• Configuration
• Project Structure
• Tool Documentation
  • perplexity_search
• Development Guidelines
  • Adding a New Tool
  • Adding a New Resource
• License

Overview

What is Model Context Protocol?

Model Context Protocol (MCP) is a framework that enables AI systems to interact with external tools and resources. It allows language models to:

• Execute tools that perform actions and return results
• Access structured resources that provide information
• Create contextual workflows through standardized interfaces

This server allows AI systems to use the Perplexity API via MCP.

Architecture & Components

The server is based on the mcp-ts-template and follows its modular architecture:

flowchart TB
    subgraph API["API Layer"]
        direction LR
        MCP["MCP Protocol"]
        Val["Validation"]
        San["Sanitization"]

        MCP --> Val --> San
    end

    subgraph Core["Core Components"]
        direction LR
        Config["Configuration"]
        Logger["Logging System"]
        Error["Error Handling"]
        Server["MCP Server"]

        Config --> Server
        Logger --> Server
        Error --> Server
    end

    subgraph Implementation["Implementation Layer"]
        direction LR
        Tool["Tools (Perplexity)"]
        Util["Utilities"]

        Tool --> Server
        Util --> Tool
    end

    San --> Config
    San --> Server

    classDef layer fill:#2d3748,stroke:#4299e1,stroke-width:3px,rx:5,color:#fff
    classDef component fill:#1a202c,stroke:#a0aec0,stroke-width:2px,rx:3,color:#fff
    class API,Core,Implementation layer
    class MCP,Val,San,Config,Logger,Error,Server,Tool,Util component

Core Components:

• Configuration System: Environment-aware configuration with validation
• Logging System: Structured logging with sensitive data redaction
• Error Handling: Centralized error processing with consistent patterns
• MCP Server: Protocol implementation for tools
• Validation Layer: Input validation and sanitization using validator and sanitize-html.
• Utilities: Reusable utility functions for common operations

Features

Core Utilities

• Logging: Configurable logging with file rotation and sensitive data redaction
• Error Handling: Pattern-based error classification and standardized reporting
• ID Generation: Secure unique identifier creation with prefix support
• Rate Limiting: Request throttling to prevent API abuse
• Request Context: Request tracking and correlation
• Sanitization: Input validation and cleaning using validator and sanitize-html.
• Cost Tracking: Estimation of Perplexity API costs based on model and token usage

Type Safety

• Global Types: Shared type definitions for consistent interfaces
• Error Types: Standardized error codes and structures
• MCP Protocol Types: Type definitions for the MCP protocol
• Tool Types: Interfaces for tool registration and configuration

Error Handling

• Pattern-Based Classification: Automatically categorize errors based on message patterns
• Consistent Formatting: Standardized error responses with additional context
• Error Mapping: Custom error transformation for domain-specific errors
• Safe Try/Catch Patterns: Centralized error processing helpers

Security

• Input Validation: Using validator for various data type checks.
• Input Sanitization: Using sanitize-html to prevent injection attacks.
• Parameter Bounds: Enforced limits within sanitization logic to prevent abuse.
• Sensitive Data Redaction: Automatic redaction in logs.

Perplexity Search Tool

• perplexity_search: The core tool provided by this server, enabling interaction with the Perplexity Search API.

Installation

Prerequisites

• Node.js (v18+)
• npm or yarn
• A Perplexity API Key (see Configuration)

Setup

1. Clone this repository:

   # Replace with the actual repository URL if different
   git clone https://github.com/casey/perplexity-mcp-server.git
   cd perplexity-mcp-server

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

Configuration

Environment Variables

This server requires the following environment variables:

MCP Client Settings

Add this server to your MCP client settings (e.g., in VS Code or Claude Desktop):

{
  "mcpServers": {
    "perplexity": {
      "command": "node",
      "args": ["/path/to/perplexity-mcp-server/dist/index.js"],
      "env": {
        "PERPLEXITY_API_KEY": "YOUR_PERPLEXITY_API_KEY"
      }
    }
  }
}

Replace /path/to/perplexity-mcp-server/dist/index.js with the actual path to the built server file and YOUR_PERPLEXITY_API_KEY with your key.

Configuration System (Internal)

The internal configuration system manages settings:

• Environment Config: Loads settings like the API key from environment variables.
• Validation: Validates configuration values (e.g., search context size).
• Logging: Logs warnings for missing or invalid configuration.

Project Structure

The codebase follows a modular structure within the src/ directory:

src/
├── config/           # Configuration management
├── index.ts          # Main entry point
├── mcp-server/       # MCP server implementation
│   ├── server.ts     # Server setup and registration
│   └── tools/        # Tool implementations
│       └── perplexitySearch/
│           ├── index.ts
│           ├── logic.ts
│           └── registration.ts
├── services/         # External service integrations
│   ├── index.ts
│   └── perplexityApi.ts
├── types-global/     # Global type definitions
│   ├── errors.ts
│   ├── mcp.ts
│   └── tool.ts
└── utils/            # Utility functions
    ├── costTracker.ts
    ├── errorHandler.ts
    ├── idGenerator.ts
    ├── index.ts
    ├── logger.ts
    ├── rateLimiter.ts
    ├── requestContext.ts
    └── sanitization.ts

For a detailed, up-to-date view of the project structure, run:

npm run tree

Tool Documentation

perplexity_search

The perplexity_search tool performs search-augmented queries using the Perplexity API. It takes a natural language query, performs a web search using Perplexity's backend, and then uses an LLM to synthesize an answer based on the search results.

Input Parameters

Examples

Basic usage:

{
  "query": "What are the latest developments in quantum computing?"
}

Advanced usage:

{
  "query": "What are the latest developments in quantum computing?",
  "return_related_questions": true,
  "search_recency_filter": "month",
  "search_domain_filter": ["nature.com", "science.org", "arxiv.org"],
  "showThinking": true
}

Development Guidelines

This project uses the structure and guidelines from the mcp-ts-template.

Adding a New Tool

Follow the template's guidelines:

1. Create Directory: src/mcp-server/tools/yourNewTool/
2. Define Logic & Schema: logic.ts (Input/Output types, validation schema, core function).
3. Implement Registration: registration.ts (Import logic, schema, use ErrorHandler.tryCatch and server.tool()).
4. Export Registration: index.ts (Export registration function).
5. Register in Server: src/mcp-server/server.ts (Import and call registration function).

Adding a New Resource

Resources are not the primary focus of this server, but if needed, follow the template's guidelines:

1. Create Directory: src/mcp-server/resources/yourNewResource/
2. Define Logic & Schema: logic.ts (Param types, query schema, core function).
3. Implement Registration: registration.ts (Import logic, schema, define ResourceTemplate, use ErrorHandler.tryCatch and server.resource()).
4. Export Registration: index.ts (Export registration function).
5. Register in Server: src/mcp-server/server.ts (Import and call registration function).

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.