perplexity-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Common Commands

Build and Development

• npm run build - Build the TypeScript project (compiles to build/ directory and sets executable permissions)
• npm start - Run the built server from build/index.js
• npm install - Install dependencies

Testing and Linting

This project does not currently have automated tests or linting configured.

Architecture Overview

This is a Model Context Protocol (MCP) server that provides Perplexity AI web search capabilities to Claude. The server acts as a bridge between Claude and Perplexity's search API with intelligent model selection and filtering capabilities.

Core Architecture Pattern

The codebase follows a modular, handler-based architecture:

• Server Layer (src/server/): Main MCP server implementation and capabilities
• Services Layer (src/services/): Business logic for API communication and model selection
• Handlers Layer (src/handlers/): Request handlers for different tool operations
• Models Layer (src/models/): State management classes
• Configuration (src/config/): Environment and constant configuration

Key Components

PerplexityMcpServer (src/server/PerplexityMcpServer.ts):

• Main server class that orchestrates all handlers and services
• Manages state including current model and filter settings
• Recreates SearchHandler on each request to ensure fresh state

ModelSelectionService (src/services/ModelSelectionService.ts):

• Implements intelligent model selection based on query keywords
• Maps queries to appropriate Perplexity models (sonar, sonar-pro, sonar-reasoning, etc.)
• Falls back to default model when no keywords match

FilterState (src/models/FilterState.ts):

• Manages domain and recency filtering state
• Enforces API limits (max 20 domains)

Handler Pattern: Each tool operation has a dedicated handler class:

• SearchHandler - Main search functionality with model selection
• RawSearchHandler - Raw ranked results via /search endpoint (no LLM)
• AsyncResearchHandler - Submit/poll/list async deep-research jobs (client.async.chat.completions.*)
• AgentHandler - Agent API via client.responses.create (third-party models, built-in tools, structured output, background runs); exports the shared renderAgentResponse formatter
• AgentRetrieveHandler - Poll a background agent run via client.responses.retrieve
• EmbeddingsHandler - Embeddings API via client.embeddings.create
• DomainFilterHandler - Domain allow/block management
• RecencyFilterHandler - Time window filtering
• FilterManagementHandler - Clear and list filters
• ModelInfoHandler - Model information and manual selection
• ModelListHandler - Dynamic model discovery via GET /v1/models (no typed SDK resource; uses the generic client.get()); groups the live catalog by provider