# Perplexity MCP Server

MCP server that exposes Perplexity AI's search capabilities to Claude, enabling seamless research integration during conversations.

## 🚧 Development Status

**Current Version:** v0.1.0-alpha (In Active Development)

### ✅ Completed
- Project foundation and security setup
- Configuration management with API key validation
- Perplexity API client with retry logic and error handling
- MCP server implementation with FastMCP
- Comprehensive testing suite
- Security validation and sanitisation

### 🔮 Planned (Future Phases)
- Perplexity Spaces integration
- Memory and context management
- Thread summarisation across Spaces
- Cross-platform data synthesis
- Document generation from multi-source data

**Note:** This project is in early development. The API and features may change.

---

## Installation

### Prerequisites

- Python 3.10 or higher
- Perplexity API key ([Get one here](https://www.perplexity.ai/settings/api))
- Claude Desktop or Claude Code with MCP support

### Step-by-Step Setup

1. **Clone the repository**
   ```bash
   git clone https://github.com/yourusername/claude-perplexity-mcp-server.git
   cd claude-perplexity-mcp-server
   ```

2. **Create a virtual environment** (recommended)
   ```bash
   python -m venv venv
   
   # On Windows
   venv\Scripts\activate
   
   # On macOS/Linux
   source venv/bin/activate
   ```

3. **Install dependencies**
   ```bash
   pip install -r requirements.txt
   ```

4. **Configure environment variables**
   ```bash
   # Copy the example file
   cp .env.example .env
   
   # Edit .env and add your Perplexity API key
   # PERPLEXITY_API_KEY=pplx-your-actual-api-key-here
   ```

5. **Verify configuration**
   ```bash
   python -c "from config import get_config; print('Configuration loaded successfully')"
   ```

6. **Test the server** (optional)
   ```bash
   python server.py
   ```

## Configuration

All configuration is managed through environment variables in the `.env` file. See `.env.example` for the template.

### Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `PERPLEXITY_API_KEY` | Yes | - | Your Perplexity API key (starts with `pplx-`) |
| `DEFAULT_MODEL` | No | `sonar-pro` | Default Perplexity model to use |
| `CACHE_ENABLED` | No | `false` | Enable caching (future feature) |
| `LOG_LEVEL` | No | `INFO` | Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR` |

### Model Options

- `sonar` - Standard model
- `sonar-pro` - Enhanced model with better reasoning (recommended)

### Search Focus Options

- `web` - General web search (default)
- `academic` - Academic and research sources
- `sec` - Security-focused sources

### Recency Filters

- `hour` - Last hour
- `day` - Last day
- `week` - Last week
- `month` - Last month
- `year` - Last year

## Usage

### Setting Up Claude Desktop

1. **Locate Claude Desktop configuration**
   - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

2. **Add MCP server configuration**
   ```json
   {
     "mcpServers": {
       "perplexity-search": {
         "command": "python",
         "args": ["C:/path/to/claude-perplexity-mcp-server/server.py"],
         "env": {
           "PERPLEXITY_API_KEY": "pplx-your-key-here"
         }
       }
     }
   }
   ```

   **Note:** For Windows, use forward slashes or escaped backslashes in the path:
   ```json
   "args": ["C:\\Users\\YourName\\path\\to\\server.py"]
   ```

3. **Restart Claude Desktop**

4. **Verify the tool is available**
   - The `perplexity_search` tool should appear in Claude's available tools
   - You can ask Claude: "What tools do you have available?"

### Using the Tool

Simply ask Claude to search for information:

```
"Search Perplexity for the latest developments in quantum computing"
```

Or be more specific:

```
"Use perplexity_search to find recent news about Python 3.12 features"
```

### Tool Parameters

Claude can use these parameters when calling the tool:

- **query** (required): Your search question
- **model** (optional): Override default model (`sonar` or `sonar-pro`)
- **search_focus** (optional): `web`, `academic`, or `sec`
- **recency** (optional): `hour`, `day`, `week`, `month`, or `year`

### Example Queries

- "What are the latest AI developments?"
- "Search for recent research on climate change solutions"
- "Find current information about the Python programming language"

## Known Limitations

### Citation Display Issues

**Current Status:** Citations are included in the tool response but may not display correctly in Claude Desktop's UI.

- **Raw JSON:** Citations appear correctly in the raw tool response JSON
- **Text Display:** Citation markers and links may not render in Claude Desktop's text output
- **Workaround:** Check the raw tool response in Claude Desktop's developer tools or JSON view

**We are actively working on resolving this limitation.** This is a known issue with how Claude Desktop handles MCP tool responses and citation formatting.

### Other Limitations

- Rate limits apply based on your Perplexity API tier
- Network timeouts may occur with slow connections (automatic retry with backoff)
- Very long queries (>10,000 characters) are rejected for safety

## Troubleshooting

### Server Won't Start

**Problem:** `ModuleNotFoundError: No module named 'mcp'`

**Solution:**
```bash
pip install -r requirements.txt
```

**Problem:** `ValueError: PERPLEXITY_API_KEY not found`

**Solution:**
- Ensure `.env` file exists in the project root
- Verify `PERPLEXITY_API_KEY` is set in `.env`
- Check that the API key starts with `pplx-`

### Tool Not Appearing in Claude Desktop

**Problem:** Tool doesn't show up in Claude Desktop

**Solutions:**
1. Verify the path in `claude_desktop_config.json` is correct
2. Ensure Python is in your system PATH
3. Check that `server.py` is executable
4. Restart Claude Desktop completely
5. Check Claude Desktop logs for errors

### API Errors

**Problem:** `API authentication failed`

**Solution:**
- Verify your API key is correct in `.env`
- Ensure the API key hasn't expired
- Check your Perplexity account for API usage limits

**Problem:** `Rate limit exceeded`

**Solution:**
- Wait a few moments and try again
- Check your Perplexity API tier and rate limits
- Consider upgrading your Perplexity plan if needed

### Network Issues

**Problem:** `Request timed out`

**Solution:**
- Check your internet connection
- Verify Perplexity API is accessible from your network
- Try again (automatic retry with exponential backoff)

### Configuration Issues

**Problem:** Invalid model or parameter errors

**Solution:**
- Check `.env.example` for valid options
- Verify `DEFAULT_MODEL` is set to `sonar` or `sonar-pro`
- Ensure `search_focus` values are: `web`, `academic`, or `sec`
- Ensure `recency` values are: `hour`, `day`, `week`, `month`, or `year`

## Security

### Best Practices

- **Never commit `.env` files** - They contain sensitive API keys
- **Use environment variables** - All secrets are loaded from `.env`
- **Sanitised logging** - API keys are never logged in full
- **URL validation** - Citations are validated to prevent malicious URLs

### Security Checklist Before Committing

Run this before every commit:

- [ ] `.env` is in `.gitignore` and NOT staged
- [ ] No API keys in code, comments, or documentation
- [ ] `.env.example` contains only placeholder values
- [ ] Error messages don't expose secrets
- [ ] Logs are sanitised
- [ ] All secrets use environment variables

**Quick check:** `git diff --cached` and search for `pplx-`

See [SECURITY.md](SECURITY.md) for detailed security policies and responsible disclosure guidelines.

## Development

### Running Tests

```bash
python test_phase5.py
```

### Project Structure

```
claude-perplexity-mcp-server/
├── .env.example          # Configuration template
├── .gitignore           # Git ignore rules
├── README.md            # This file
├── SECURITY.md          # Security policy
├── requirements.txt     # Python dependencies
├── config.py           # Configuration management
├── perplexity_client.py # Perplexity API client
├── server.py           # MCP server implementation
└── test_phase5.py      # Test suite
```

### Code Quality

- Type hints throughout
- Comprehensive error handling
- Security-first design
- PEP 8 compliant
- Docstrings for all public functions

## Contributing

Contributions are welcome! Please ensure:

1. Code follows existing style and patterns
2. All tests pass
3. Security checklist is followed
4. Documentation is updated
5. Type hints are included

## License

Apache 2.0 License - see LICENSE file for details.

## Support

For issues, questions, or contributions:

- **Security issues:** See [SECURITY.md](SECURITY.md)
- **Bug reports:** Open an issue on GitHub
- **Feature requests:** Open an issue with the `enhancement` label

## Acknowledgements

- Built with [FastMCP](https://gofastmcp.com/) - High-level MCP SDK
- Powered by [Perplexity AI](https://www.perplexity.ai/) - AI-powered search
- Designed for [Claude Desktop](https://claude.ai/) - Anthropic's AI assistant