Perplexity MCP Server

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview This is a Perplexity MCP (Model Context Protocol) server that provides three main tools with progressive complexity levels: 1. **perplexity_small** - Quick, reliable queries using sonar-pro model (default parameters) 2. **perplexity_medium** - Enhanced reasoning with sonar-reasoning-pro (medium effort, medium search context) 3. **perplexity_large** - Comprehensive research with sonar-deep-research (high effort, high search context, potential timeout risk) ## Development Plan ### Phase 1: Core Implementation ✓ - [x] Set up project structure and pyproject.toml configuration - [x] Create config.py for environment variable validation - [x] Implement Perplexity API client in client.py with configurable parameters - [x] Create FastMCP server with perplexity_small tool (sonar-pro model) - [x] Add perplexity_medium tool (sonar-reasoning-pro, medium settings) - [x] Add perplexity_large tool (sonar-deep-research, high settings) - [x] Update __init__.py with proper exports ### Phase 2: Testing & Integration ✓ - [x] Test each tool independently to validate API integration - [x] Configure Claude Desktop integration and test MCP server - [x] Test various scenarios (simple queries, complex research, timeout behavior) - [x] Validate error handling scenarios (invalid API key, network issues) - [x] Fix response format (simplified to content + citations only) - [x] Implement thinking token removal for medium/large tools - [x] Resolve import path issues and project structure ### Phase 3: Optimization & Polish (Future Scope) - [ ] Implement timeout handling specifically for perplexity_large - [ ] Add caching for repeated queries - [ ] Performance monitoring and optimization - [ ] Enhanced error messages and user guidance ### Phase 4: Distribution & Deployment ✓ - [x] Organize project structure with proper folders (tests/, Notes/) - [x] Create comprehensive documentation and explanations - [x] Set up version control and repository - [ ] **Distribution Strategy**: Currently using local development setup - [ ] **Future Options**: PyPI publication vs local distribution vs hybrid approach - [ ] **Decision Pending**: Will evaluate distribution needs based on usage patterns ## Project Structure ``` Perplexity_MCP/ ├── __init__.py # Package exports and version info ├── server.py # FastMCP server with 3 tools ├── client.py # Perplexity API wrapper with thinking token removal ├── config.py # Environment configuration and tool configs ├── pyproject.toml # UV/Python project configuration ├── uv.lock # Auto-generated dependency lock file ├── CLAUDE.md # Project instructions for Claude ├── README.md # User documentation and setup guide ├── .env # Environment variables (API key) - not in repo ├── .gitignore # Git ignore patterns ├── tests/ │ ├── tests.py # Individual tool testing script │ └── test_logs/ # Test result files with raw/formatted responses └── Notes/ ├── explanations.md # Technical explanations and deep-dives ├── questions.txt # Development questions and requirements ├── claude_mcp_notes.md # Previous MCP development learnings └── reasearch_on_docs.md # Perplexity API research and analysis ``` ## Commands ### Development Setup ```bash # Clone the repository git clone <repository-url> cd Perplexity_MCP # Install dependencies with uv uv sync # Create environment file echo "PERPLEXITY_API_KEY=your_api_key_here" > .env # Test individual tools uv run python tests/tests.py small uv run python tests/tests.py medium uv run python tests/tests.py large ``` ### Claude Desktop Integration ```bash # Run MCP server (for debugging) uv run python server.py # Configure Claude Desktop with full uv path # Edit ~/Library/Application Support/Claude/claude_desktop_config.json ``` ### Testing and Validation ```bash # Test individual API client functions uv run python tests/tests.py small # Test sonar-pro model uv run python tests/tests.py medium # Test sonar-reasoning-pro with thinking removal uv run python tests/tests.py large # Test sonar-deep-research (long runtime) # Results saved to tests/test_logs/ with raw and formatted responses ``` ## Dependencies ### Core Dependencies - `mcp>=1.11.0` - MCP Python SDK with FastMCP - `python-dotenv>=1.1.1` - Environment variable management - `httpx>=0.28.1` - HTTP client for Perplexity API ## Architecture ### Tool Configurations ```python TOOL_CONFIGS = { "small": { "model": "sonar-pro" # All other params use API defaults }, "medium": { "model": "sonar-reasoning-pro", "reasoning_effort": "medium", "web_search_options": {"search_context_size": "medium"} }, "large": { "model": "sonar-deep-research", "reasoning_effort": "high", "web_search_options": {"search_context_size": "high"} } } ``` ### MCP Tools - **`perplexity_small`** - Input: query (string), messages (optional list) - **`perplexity_medium`** - Input: query (string), messages (optional list) - **`perplexity_large`** - Input: query (string), messages (optional list) ### Response Format All tools return simplified, clean responses with: - `content`: The AI response text (with thinking tokens automatically removed for medium/large) - `citations`: Array of source URLs and references **Note**: Raw API responses containing search_results, usage stats, and model info are preserved in test logs for analysis, but the MCP tools return only the essential content and citations for clean integration. ### Error Handling - Multi-layered error handling (input validation → API errors → structured responses) - No exceptions raised to MCP layer (structured error returns) - All debugging output directed to stderr (MCP protocol compliance) - Timeout detection and reporting ### Key Development Challenges Resolved 1. **Thinking Token Removal**: Medium and large models return `<think>...</think>` sections that needed automatic filtering 2. **MCP Protocol Compliance**: Ensuring stdout remains clean for JSON-RPC communication 3. **Import Path Management**: Resolving module imports across different project structures 4. **Response Format Simplification**: Balancing comprehensive API data with clean tool responses 5. **UV Path Resolution**: Claude Desktop requiring full UV binary paths rather than relative commands 6. **Global Client Management**: Implementing singleton pattern for API client to avoid repeated initialization ## Environment Setup ### Required Environment Variables ```bash # Perplexity API Key from https://www.perplexity.ai/settings/api PERPLEXITY_API_KEY=your_api_key_here ``` ### Claude Desktop Configuration For local development, add to `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "perplexity-mcp": { "command": "/Users/username/.local/bin/uv", "args": [ "--directory", "/path/to/your/Perplexity_MCP", "run", "python", "server.py" ] } } } ``` **Important Notes:** - Use full path to uv binary (find with `which uv`) - Update directory path to your actual project location - Restart Claude Desktop completely after configuration changes ## Usage Examples ### Quick Factual Query (perplexity_small) ``` Query: "What is the latest version of Python?" Best for: Fast answers, basic facts, immediate responses ``` ### Enhanced Analysis (perplexity_medium) ``` Query: "Compare the performance characteristics of different database indexing strategies" Best for: Technical explanations, moderate research depth, analytical questions ``` ### Deep Research (perplexity_large) ``` Query: "Provide a comprehensive analysis of emerging trends in quantum computing hardware architectures" Best for: Academic research, comprehensive analysis, complex multi-step reasoning WARNING: May take 10-30 minutes, potential timeout risk ``` ## Key Implementation Details ### MCP Protocol Compliance - All debugging output goes to stderr (never stdout) - Structured error responses instead of exceptions - stdio transport for Claude Desktop integration - FastMCP handles JSON-RPC protocol automatically ### API Integration - Uses Perplexity's `/chat/completions` endpoint - Configurable timeout (default: 5 minutes) - Proper authentication with Bearer token - Comprehensive error handling for HTTP and timeout errors ### Timeout Strategy - No timeout handling initially (let natural behavior emerge for testing) - Future enhancement: Progressive fallback from large → medium → small - Clear warnings about potential timeout for perplexity_large tool ## Distribution Strategy ### Current Status: Local Development This MCP server is currently optimized for local development and personal use: - **Installation**: Manual setup with uv and local Claude Desktop configuration - **Updates**: Git pull + uv sync for dependency updates - **Configuration**: Local .env file and Claude Desktop JSON config ### Future Distribution Options (Decision Pending) #### Option A: PyPI Publication - **Advantages**: Easy installation with `uvx perplexity-mcp`, automatic updates - **Considerations**: Requires packaging, versioning, and maintenance overhead - **Command**: `uvx perplexity-mcp` (would need server daemon mode) #### Option B: Local Distribution - **Advantages**: Full control, easy customization, no external dependencies - **Current State**: Working well for development and testing - **Sharing**: Via Git repository with setup instructions #### Option C: Hybrid Approach - **Development**: Local setup for iteration and customization - **Distribution**: Optional PyPI package for broader adoption - **Timeline**: Evaluate based on usage patterns and community interest **Decision Timeline**: Will assess distribution needs after extended local usage and potential community feedback.