# Perplexity MCP Server

A Model Context Protocol (MCP) server that integrates Perplexity AI's search-enhanced language models with Claude Desktop, providing three tools with progressive complexity for different use cases.

## Features

🔍 **Three Complexity Levels**
- `perplexity_small`: Fast queries with sonar-pro model
- `perplexity_medium`: Enhanced reasoning with sonar-reasoning-pro  
- `perplexity_large`: Deep research with sonar-deep-research

🚀 **Optimized for Development**
- Clean responses (thinking tokens automatically removed)
- Comprehensive error handling
- Detailed logging for debugging
- Built with FastMCP for reliability

🔧 **Modern Python Stack**
- UV for fast dependency management
- HTTPX for modern HTTP client capabilities  
- Type hints throughout codebase
- Comprehensive testing suite

## Quick Start

### Prerequisites
- Python 3.11+
- [UV package manager](https://docs.astral.sh/uv/)
- [Perplexity API key](https://www.perplexity.ai/settings/api)
- [Claude Desktop](https://claude.ai/download)

### Installation

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd Perplexity_MCP
   ```

2. **Install dependencies**
   ```bash
   uv sync
   ```

3. **Set up environment**
   ```bash
   echo "PERPLEXITY_API_KEY=your_api_key_here" > .env
   ```

4. **Test the installation**
   ```bash
   uv run python tests/tests.py small
   ```

### Claude Desktop Integration

1. **Find your UV path**
   ```bash
   which uv
   # Example output: /Users/username/.local/bin/uv
   ```

2. **Configure Claude Desktop**
   
   Edit `~/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"
         ]
       }
     }
   }
   ```

3. **Restart Claude Desktop**
   
   Completely quit and restart Claude Desktop to load the new MCP server.

## Usage

### In Claude Desktop

Once configured, you can use these tools in your conversations:

**Quick factual queries:**
```
Use perplexity_small to find: "What is the latest Python version?"
```

**Technical analysis:**
```
Use perplexity_medium to explain: "Compare REST vs GraphQL performance characteristics"
```

**Deep research:**
```
Use perplexity_large to research: "Comprehensive analysis of quantum computing trends in 2024"
```

### Tool Specifications

| Tool | Model | Use Case | Response Time | Features |
|------|-------|----------|---------------|----------|
| `perplexity_small` | sonar-pro | Quick facts, basic queries | ~3-10 seconds | Fast, reliable |
| `perplexity_medium` | sonar-reasoning-pro | Technical explanations | ~10-30 seconds | Enhanced reasoning |
| `perplexity_large` | sonar-deep-research | Comprehensive research | ~5-30 minutes | Deep analysis, high quality |

### Response Format

All tools return clean, structured responses:
```json
{
  "content": "The AI response with thinking tokens removed",
  "citations": ["https://source1.com", "https://source2.com"]
}
```

## Development

### Project Structure

```
Perplexity_MCP/
├── server.py                # FastMCP server with 3 tools
├── client.py                # Perplexity API wrapper  
├── config.py                # Configuration and tool settings
├── __init__.py              # Package exports
├── pyproject.toml           # UV project configuration
├── tests/
│   ├── tests.py             # Test script for individual tools
│   └── test_logs/           # Test results and logs
└── Notes/
    ├── explanations.md      # Technical deep-dives
    └── questions.txt        # Development questions
```

### Running Tests

Test individual tools to validate API integration:

```bash
# Test each tool independently
uv run python tests/tests.py small    # Test sonar-pro model
uv run python tests/tests.py medium   # Test sonar-reasoning-pro
uv run python tests/tests.py large    # Test sonar-deep-research (long runtime)

# Results saved to tests/test_logs/ with detailed response analysis
```

### Development Setup

1. **Install development dependencies**
   ```bash
   uv sync --all-groups
   ```

2. **Run the MCP server locally** (for debugging)
   ```bash
   uv run python server.py
   ```

3. **Check code quality**
   ```bash
   uv run ruff check .
   uv run black .
   ```

## Configuration

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `PERPLEXITY_API_KEY` | Yes | Your Perplexity API key from [settings page](https://www.perplexity.ai/settings/api) |

### Tool Configuration

The tools are configured in `config.py`:

```python
TOOL_CONFIGS = {
    "small": {
        "model": "sonar-pro"
    },
    "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"}
    }
}
```

## Troubleshooting

### Common Issues

**Import Errors**
```
ModuleNotFoundError: No module named 'client'
```
- Ensure you're running from the project root directory
- Check that UV is using the correct virtual environment

**API Key Issues**
```
Error: PERPLEXITY_API_KEY environment variable is required
```
- Verify your `.env` file exists and contains the API key
- Check that the API key is valid on [Perplexity's settings page](https://www.perplexity.ai/settings/api)

**Claude Desktop Connection Issues**
- Verify the UV path in your configuration: `which uv`
- Ensure the project directory path is absolute and correct
- Check Claude Desktop logs for specific error messages
- Restart Claude Desktop completely after configuration changes

**Long Response Times**
- `perplexity_large` can take 10-30 minutes for complex queries
- Use `perplexity_small` or `perplexity_medium` for faster responses
- Consider the complexity of your query when choosing tools

### Debug Mode

Enable verbose logging by running the server directly:

```bash
uv run python server.py
# Check stderr output for detailed logging information
```

### Test Individual Components

```bash
# Test API connection
uv run python -c "from client import PerplexityClient; print('✅ Client OK')"

# Test configuration
uv run python -c "from config import get_api_key; print('✅ API Key OK')"

# Test server startup
timeout 10s uv run python server.py || echo "Server started successfully"
```

## Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes and test thoroughly
4. Update documentation as needed
5. Submit a pull request

### Development Guidelines

- Follow existing code style (Black formatting, type hints)
- Add tests for new functionality
- Update `CLAUDE.md` for any architectural changes
- Test with all three Perplexity models
- Ensure MCP protocol compliance (clean stdout)

## Architecture

### Key Design Decisions

- **Class-based client**: Singleton pattern for efficient resource management
- **Thinking token removal**: Automatic filtering of `<think>...</think>` sections
- **Simplified responses**: Only content and citations for clean integration
- **Error isolation**: No exceptions propagated to MCP layer
- **Logging strategy**: All debug output to stderr for MCP compliance

### Dependencies

- `mcp>=1.11.0` - MCP Python SDK with FastMCP
- `python-dotenv>=1.1.1` - Environment variable management
- `httpx>=0.28.1` - Modern HTTP client with timeout handling

## License

[MIT License](LICENSE) - see LICENSE file for details.

## Acknowledgments

- [Perplexity AI](https://www.perplexity.ai/) for the powerful search-enhanced language models
- [Anthropic](https://www.anthropic.com/) for Claude and the MCP protocol
- [FastMCP](https://github.com/jlowin/fastmcp) for the excellent MCP framework

## Support

- For API issues: [Perplexity Support](https://www.perplexity.ai/support)
- For MCP protocol questions: [MCP Documentation](https://modelcontextprotocol.io/)
- For Claude Desktop issues: [Claude Support](https://support.anthropic.com/)

---

**Note**: This MCP server is currently optimized for local development and personal use. Future versions may include PyPI distribution options for easier installation and sharing.