README.md•15 kB
# MCP Perplexity Pro
A comprehensive Model Context Protocol (MCP) server for the Perplexity API, featuring intelligent model selection, conversation management, and project-aware storage.
[](https://badge.fury.io/js/mcp-perplexity-pro)
[](https://opensource.org/licenses/MIT)
[](http://www.typescriptlang.org/)
## ✨ Features
- **🧠 Intelligent Model Selection**: Automatically chooses the optimal Perplexity model based on query analysis
- **💬 Conversation Management**: Stateful chat sessions with full conversation history
- **🔍 Comprehensive Search**: Access to all Perplexity models (sonar, sonar-pro, sonar-reasoning, sonar-reasoning-pro, sonar-deep-research)
- **📊 Async Operations**: Support for long-running research tasks
- **🗂️ Project-Aware Storage**: Conversations and reports stored in your project directory
- **🔒 Thread-Safe**: Concurrent access with file locking
- **🐳 Docker Ready**: Full Docker and Docker Compose support
- **📈 Production Ready**: Comprehensive error handling, logging, and monitoring
- **🧪 Well Tested**: Extensive unit and integration test coverage
## 🚀 Quick Start
### Prerequisites
- Node.js 20+
- Perplexity API key ([Get one here](https://perplexity.ai/))
### Installation
```bash
npm install -g mcp-perplexity-pro
```
## 🚀 Deployment Options
### 1. NPX Deployment (stdio-npx)
The simplest way to use the MCP server with stdio transport:
**For Claude Desktop** (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"perplexity": {
"command": "npx",
"args": ["mcp-perplexity-pro-stdio"],
"env": {
"PERPLEXITY_API_KEY": "your-api-key-here"
}
}
}
}
```
**For Claude Code** (`.mcp.json`):
```json
{
"mcpServers": {
"perplexity": {
"command": "npx",
"args": ["mcp-perplexity-pro-stdio"],
"env": {
"PERPLEXITY_API_KEY": "your-api-key-here"
}
}
}
}
```
### 2. Docker Deployment (stdio-docker)
Run the MCP server in a Docker container with stdio transport:
**Using Docker Compose:**
```bash
# Set your API key
export PERPLEXITY_API_KEY="your-api-key-here"
# Start the stdio service
docker-compose --profile stdio up -d mcp-perplexity-pro-stdio
```
**For Claude Desktop** (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"perplexity": {
"command": "docker",
"args": ["exec", "-i", "mcp-perplexity-pro-stdio", "node", "/app/dist/stdio-server.js"],
"env": {
"PERPLEXITY_API_KEY": "your-api-key-here"
}
}
}
}
```
**Direct Docker Run:**
```bash
docker run -it --rm \
-e PERPLEXITY_API_KEY="your-api-key-here" \
-v "$(pwd)/data:/app/data" \
mcp-perplexity-pro:stdio
```
### 3. HTTP Transport (Legacy)
**For Claude Code** (`.mcp.json`):
```json
{
"mcpServers": {
"perplexity": {
"command": "node",
"args": ["dist/launcher.js", "--http-port=8124"],
"env": {
"PERPLEXITY_API_KEY": "your-api-key-here"
}
}
}
}
```
**For Claude Desktop** (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"perplexity": {
"command": "node",
"args": ["dist/launcher.js", "--http-port=8125"],
"env": {
"PERPLEXITY_API_KEY": "your-api-key-here"
}
}
}
}
```
**Default Ports:**
- Claude Code: 8124 (default when no port specified)
- Claude Desktop: 8125 (recommended)
**Environment Variables:**
- `PERPLEXITY_API_KEY` (required): Your Perplexity API key
- `DEFAULT_MODEL` (optional): Default model (default: sonar-reasoning-pro)
- `PROJECT_ROOT` (optional): Project root directory for storage
- `STORAGE_PATH` (optional): Storage subdirectory (default: .perplexity)
The launcher automatically:
- Detects if a build is needed and rebuilds if necessary
- Starts HTTP server with streamable transport
- No manual build or start commands required
## 📋 Available Tools
### Query Tools
#### `ask_perplexity`
Ask questions with intelligent model selection based on query type.
**Parameters:**
- `query` (required): Your question or prompt
- `model` (optional): Specific model to use
- `temperature` (optional): Response creativity (0.0-2.0)
- `max_tokens` (optional): Maximum response length
**Example:**
```
Ask Perplexity: "What are the latest developments in quantum computing?"
```
#### `research_perplexity`
Conduct comprehensive research with detailed reports saved to your project.
**Parameters:**
- `query` (required): Research topic or question
- `model` (optional): Defaults to `sonar-deep-research`
- `save_report` (optional): Save detailed report to project
**Example:**
```
Research: "Market analysis of renewable energy trends in 2024"
```
### Chat Tools
#### `chat_perplexity`
Start or continue conversations with full context.
**Parameters:**
- `message` (required): Your message
- `chat_id` (optional): Continue existing conversation
- `title` (optional): Title for new conversation
- `model` (optional): Model selection
**Example:**
```
Chat: "Hello, I'd like to discuss AI ethics" (title: "AI Ethics Discussion")
```
#### `list_chats_perplexity`
List all conversations in your project.
#### `read_chat_perplexity`
Retrieve full conversation history.
**Parameters:**
- `chat_id` (required): Conversation ID
### Async Tools
#### `async_perplexity`
Create long-running research jobs for complex queries.
**Parameters:**
- `query` (required): Research question
- `model` (optional): Defaults to `sonar-deep-research`
#### `check_async_perplexity`
Check status of async research job.
**Parameters:**
- `job_id` (required): Job identifier
#### `list_async_jobs`
List all async jobs in your project.
### Utility Tools
#### `storage_stats_perplexity`
Get storage statistics and usage information.
#### `model_info_perplexity`
Get information about available models and their capabilities.
## 🧠 Intelligent Model Selection
The server automatically selects the optimal model based on query analysis:
| Query Type | Selected Model | Use Case |
| ----------------- | --------------------- | ----------------------------------------------------------- |
| Research requests | `sonar-deep-research` | "I need comprehensive research on..." |
| Real-time queries | `sonar-pro` | "What's the current price of...", "Latest news..." |
| Complex reasoning | `sonar-reasoning-pro` | "Analyze the implications of...", "Compare and contrast..." |
| Simple questions | `sonar-reasoning` | General questions |
| Default | `sonar-reasoning-pro` | Fallback for all other queries |
### Model Capabilities
```typescript
{
"sonar": {
search: true, reasoning: false, realTime: false, research: false
},
"sonar-pro": {
search: true, reasoning: false, realTime: true, research: false
},
"sonar-reasoning": {
search: true, reasoning: true, realTime: false, research: false
},
"sonar-reasoning-pro": {
search: true, reasoning: true, realTime: true, research: false
},
"sonar-deep-research": {
search: true, reasoning: true, realTime: false, research: true
}
}
```
## 🗂️ Project-Aware Storage
All conversations and research reports are stored in your project directory:
```
your-project/
├── .perplexity/
│ ├── chats/
│ │ ├── chat-uuid-1.json
│ │ └── chat-uuid-2.json
│ ├── reports/
│ │ ├── research-report-1.json
│ │ └── research-report-2.json
│ └── async-jobs/
│ ├── job-uuid-1.json
│ └── job-uuid-2.json
```
### Storage Features
- **Thread-safe**: File locking prevents concurrent access issues
- **Session-aware**: Multiple sessions can work with the same project
- **Organized**: Separate directories for different content types
- **Persistent**: All data survives server restarts
- **Portable**: Easy to backup, move, or version control
## 🐳 Docker Deployment
### Development
```bash
# Clone repository
git clone https://github.com/cfdude/mcp-perplexity-pro.git
cd mcp-perplexity-pro
# Start development environment
docker-compose --profile dev up -d
```
### Production
```bash
# Set environment variables
export PROJECT_ROOT=/path/to/your/project
# Start production environment
docker-compose up -d
```
### Custom Docker
```dockerfile
FROM mcp-perplexity-pro:latest
# Custom configuration
COPY my-config.json /app/config.json
# Custom entrypoint
CMD ["node", "dist/index.js", "--config", "config.json"]
```
## ⚙️ Configuration
### Environment Variables
| Variable | Description | Default |
| -------------------- | -------------------- | --------------------- |
| `NODE_ENV` | Environment mode | `development` |
| `PERPLEXITY_API_KEY` | Your API key | Required |
| `PROJECT_ROOT` | Project directory | Current directory |
| `STORAGE_PATH` | Storage subdirectory | `.perplexity` |
| `DEFAULT_MODEL` | Default model | `sonar-reasoning-pro` |
| `SESSION_ID` | Session identifier | Auto-generated |
### Advanced Configuration
```json
{
"api_key": "your-key",
"default_model": "sonar-reasoning-pro",
"project_root": "/workspace",
"storage_path": ".perplexity",
"session_id": "unique-session",
"request_timeout": 30000,
"max_retries": 3,
"rate_limit": {
"requests_per_minute": 60,
"concurrent_requests": 5
}
}
```
## 🧪 Development
### Setup
```bash
# Clone and install
git clone https://github.com/cfdude/mcp-perplexity-pro.git
cd mcp-perplexity-pro
npm install
# Development mode
npm run dev
# Run tests
npm test
npm run test:coverage
# Linting and formatting
npm run lint
npm run format
```
### Project Structure
```
src/
├── index.ts # Main MCP server
├── types.ts # TypeScript definitions
├── models.ts # Model registry & selection
├── perplexity-api.ts # API client wrapper
├── storage.ts # Storage management
└── tools/
├── query.ts # Query tools
├── chat.ts # Chat tools
└── async.ts # Async tools
tests/
├── models.test.ts # Model selection tests
├── storage.test.ts # Storage tests
├── perplexity-api.test.ts # API tests
└── integration.test.ts # End-to-end tests
```
### Testing
```bash
# Run all tests
npm test
# Watch mode
npm run test:watch
# Coverage report
npm run test:coverage
# Specific test file
npm test -- models.test.ts
```
## 📊 API Usage Examples
### Basic Query
```javascript
// Simple question
const result = await askPerplexity({
query: 'What is machine learning?',
});
// With specific model
const result = await askPerplexity({
query: 'Current Bitcoin price',
model: 'sonar-pro',
});
```
### Conversation
```javascript
// Start new conversation
const chat = await chatPerplexity({
message: 'Hello!',
title: 'General Discussion',
});
// Continue conversation
const response = await chatPerplexity({
chat_id: chat.id,
message: 'Tell me about quantum computing',
});
```
### Research
```javascript
// Comprehensive research
const research = await researchPerplexity({
query: 'Impact of AI on healthcare industry',
save_report: true,
});
// Async research for complex topics
const job = await asyncPerplexity({
query: 'Detailed analysis of climate change solutions',
});
// Check job status
const status = await checkAsync({
job_id: job.id,
});
```
## 🔒 Security
### API Key Management
- Store API keys securely using environment variables
- Never commit API keys to version control
- Rotate keys regularly
- Use different keys for different environments
### Network Security
- HTTPS in production
- Rate limiting implemented
- Input validation and sanitization
- Error handling without information leakage
### Container Security
- Non-root user execution
- Minimal base images
- Regular security updates
- Vulnerability scanning
## 📈 Monitoring
### Health Checks
```bash
# Basic health check
curl http://localhost:3000/health
# Detailed status
curl http://localhost:3000/status
```
### Metrics
The server exposes Prometheus-compatible metrics:
- Request count and duration
- Error rates by endpoint
- Storage usage statistics
- Model usage distribution
### Logging
Structured JSON logging with configurable levels:
```json
{
"timestamp": "2024-08-20T19:00:00.000Z",
"level": "info",
"message": "Query processed successfully",
"model": "sonar-reasoning-pro",
"duration": 1250,
"session_id": "session-123"
}
```
## 🚨 Troubleshooting
### Common Issues
**API Key Errors**
```bash
Error: Invalid API key
Solution: Verify PERPLEXITY_API_KEY is set correctly
```
**Storage Permission Errors**
```bash
Error: EACCES: permission denied
Solution: Ensure storage directory is writable
```
**Model Selection Issues**
```bash
Error: Model not available
Solution: Check model name spelling and availability
```
### Debug Mode
```bash
DEBUG=mcp-perplexity:* npm start
```
### Support
- 📚 [Documentation](https://github.com/cfdude/mcp-perplexity-pro/wiki)
- 🐛 [Issues](https://github.com/cfdude/mcp-perplexity-pro/issues)
- 💬 [Discussions](https://github.com/cfdude/mcp-perplexity-pro/discussions)
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
### Development Workflow
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request
### Code Standards
- TypeScript with strict mode
- ESLint + Prettier formatting
- 100% test coverage for new features
- Conventional commit messages
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- [Perplexity AI](https://perplexity.ai/) for providing the excellent API
- [Model Context Protocol](https://github.com/modelcontextprotocol) for the MCP specification
- [Smithery](https://smithery.ai/) for MCP development tools
- The open-source community for inspiration and contributions
## 📊 Project Stats
---
**Built with ❤️ for the MCP community**