{"id":30586109,"url":"https://github.com/cfdude/mcp-perplexity-pro","last_synced_at":"2025-08-29T11:43:26.262Z","repository":{"id":311712825,"uuid":"1041771448","full_name":"cfdude/mcp-perplexity-pro","owner":"cfdude","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-26T04:37:23.000Z","size":169,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-26T06:21:52.032Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cfdude.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-21T01:44:12.000Z","updated_at":"2025-08-26T04:37:26.000Z","dependencies_parsed_at":"2025-08-26T06:21:55.567Z","dependency_job_id":"4b171877-74fe-4510-bb72-003715c0d23e","html_url":"https://github.com/cfdude/mcp-perplexity-pro","commit_stats":null,"previous_names":["cfdude/mcp-perplexity-pro"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/cfdude/mcp-perplexity-pro","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfdude%2Fmcp-perplexity-pro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfdude%2Fmcp-perplexity-pro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfdude%2Fmcp-perplexity-pro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfdude%2Fmcp-perplexity-pro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cfdude","download_url":"https://codeload.github.com/cfdude/mcp-perplexity-pro/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfdude%2Fmcp-perplexity-pro/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272679261,"owners_count":24975253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-29T02:00:10.610Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-29T11:43:25.658Z","updated_at":"2025-08-29T11:43:26.223Z","avatar_url":"https://github.com/cfdude.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Perplexity Pro\n\nA comprehensive Model Context Protocol (MCP) server for the Perplexity API, featuring intelligent model selection, conversation management, and project-aware storage.\n\n[![npm version](https://badge.fury.io/js/mcp-perplexity-pro.svg)](https://badge.fury.io/js/mcp-perplexity-pro)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)\n\n## ✨ Features\n\n- **🧠 Intelligent Model Selection**: Automatically chooses the optimal Perplexity model based on query analysis\n- **💬 Conversation Management**: Stateful chat sessions with full conversation history\n- **🔍 Comprehensive Search**: Access to all Perplexity models (sonar, sonar-pro, sonar-reasoning, sonar-reasoning-pro, sonar-deep-research)\n- **📊 Async Operations**: Support for long-running research tasks\n- **🗂️ Project-Aware Storage**: Conversations and reports stored in your project directory\n- **🔒 Thread-Safe**: Concurrent access with file locking\n- **🐳 Docker Ready**: Full Docker and Docker Compose support\n- **📈 Production Ready**: Comprehensive error handling, logging, and monitoring\n- **🧪 Well Tested**: Extensive unit and integration test coverage\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Node.js 20+\n- Perplexity API key ([Get one here](https://perplexity.ai/))\n\n### Installation\n\n```bash\nnpm install -g mcp-perplexity-pro\n```\n\n### Configuration\n\n#### HTTP-Only Transport (Aligned with Anthropic's Direction)\n\nFollowing Anthropic's deprecation of stdio transport in favor of HTTP, this server uses HTTP transport exclusively for both Claude Code and Claude Desktop.\n\n**For Claude Code** (`.mcp.json`):\n```json\n{\n  \"mcpServers\": {\n    \"perplexity\": {\n      \"command\": \"node\",\n      \"args\": [\"dist/launcher.js\", \"--http-port=8124\"],\n      \"env\": {\n        \"PERPLEXITY_API_KEY\": \"your-api-key-here\"\n      }\n    }\n  }\n}\n```\n\n**For Claude Desktop** (`claude_desktop_config.json`):\n```json\n{\n  \"mcpServers\": {\n    \"perplexity\": {\n      \"command\": \"node\", \n      \"args\": [\"dist/launcher.js\", \"--http-port=8125\"],\n      \"env\": {\n        \"PERPLEXITY_API_KEY\": \"your-api-key-here\"\n      }\n    }\n  }\n}\n```\n\n**Default Ports:**\n- Claude Code: 8124 (default when no port specified)\n- Claude Desktop: 8125 (recommended)\n\n**Environment Variables:**\n- `PERPLEXITY_API_KEY` (required): Your Perplexity API key\n- `DEFAULT_MODEL` (optional): Default model (default: sonar-reasoning-pro)\n- `PROJECT_ROOT` (optional): Project root directory for storage\n- `STORAGE_PATH` (optional): Storage subdirectory (default: .perplexity)\n\nThe launcher automatically:\n- Detects if a build is needed and rebuilds if necessary\n- Starts HTTP server with streamable transport\n- No manual build or start commands required\n\n## 📋 Available Tools\n\n### Query Tools\n\n#### `ask_perplexity`\n\nAsk questions with intelligent model selection based on query type.\n\n**Parameters:**\n\n- `query` (required): Your question or prompt\n- `model` (optional): Specific model to use\n- `temperature` (optional): Response creativity (0.0-2.0)\n- `max_tokens` (optional): Maximum response length\n\n**Example:**\n\n```\nAsk Perplexity: \"What are the latest developments in quantum computing?\"\n```\n\n#### `research_perplexity`\n\nConduct comprehensive research with detailed reports saved to your project.\n\n**Parameters:**\n\n- `query` (required): Research topic or question\n- `model` (optional): Defaults to `sonar-deep-research`\n- `save_report` (optional): Save detailed report to project\n\n**Example:**\n\n```\nResearch: \"Market analysis of renewable energy trends in 2024\"\n```\n\n### Chat Tools\n\n#### `chat_perplexity`\n\nStart or continue conversations with full context.\n\n**Parameters:**\n\n- `message` (required): Your message\n- `chat_id` (optional): Continue existing conversation\n- `title` (optional): Title for new conversation\n- `model` (optional): Model selection\n\n**Example:**\n\n```\nChat: \"Hello, I'd like to discuss AI ethics\" (title: \"AI Ethics Discussion\")\n```\n\n#### `list_chats_perplexity`\n\nList all conversations in your project.\n\n#### `read_chat_perplexity`\n\nRetrieve full conversation history.\n\n**Parameters:**\n\n- `chat_id` (required): Conversation ID\n\n### Async Tools\n\n#### `async_perplexity`\n\nCreate long-running research jobs for complex queries.\n\n**Parameters:**\n\n- `query` (required): Research question\n- `model` (optional): Defaults to `sonar-deep-research`\n\n#### `check_async_perplexity`\n\nCheck status of async research job.\n\n**Parameters:**\n\n- `job_id` (required): Job identifier\n\n#### `list_async_jobs`\n\nList all async jobs in your project.\n\n### Utility Tools\n\n#### `storage_stats_perplexity`\n\nGet storage statistics and usage information.\n\n#### `model_info_perplexity`\n\nGet information about available models and their capabilities.\n\n## 🧠 Intelligent Model Selection\n\nThe server automatically selects the optimal model based on query analysis:\n\n| Query Type        | Selected Model        | Use Case                                                    |\n| ----------------- | --------------------- | ----------------------------------------------------------- |\n| Research requests | `sonar-deep-research` | \"I need comprehensive research on...\"                       |\n| Real-time queries | `sonar-pro`           | \"What's the current price of...\", \"Latest news...\"          |\n| Complex reasoning | `sonar-reasoning-pro` | \"Analyze the implications of...\", \"Compare and contrast...\" |\n| Simple questions  | `sonar-reasoning`     | General questions                                           |\n| Default           | `sonar-reasoning-pro` | Fallback for all other queries                              |\n\n### Model Capabilities\n\n```typescript\n{\n  \"sonar\": {\n    search: true, reasoning: false, realTime: false, research: false\n  },\n  \"sonar-pro\": {\n    search: true, reasoning: false, realTime: true, research: false\n  },\n  \"sonar-reasoning\": {\n    search: true, reasoning: true, realTime: false, research: false\n  },\n  \"sonar-reasoning-pro\": {\n    search: true, reasoning: true, realTime: true, research: false\n  },\n  \"sonar-deep-research\": {\n    search: true, reasoning: true, realTime: false, research: true\n  }\n}\n```\n\n## 🗂️ Project-Aware Storage\n\nAll conversations and research reports are stored in your project directory:\n\n```\nyour-project/\n├── .perplexity/\n│   ├── chats/\n│   │   ├── chat-uuid-1.json\n│   │   └── chat-uuid-2.json\n│   ├── reports/\n│   │   ├── research-report-1.json\n│   │   └── research-report-2.json\n│   └── async-jobs/\n│       ├── job-uuid-1.json\n│       └── job-uuid-2.json\n```\n\n### Storage Features\n\n- **Thread-safe**: File locking prevents concurrent access issues\n- **Session-aware**: Multiple sessions can work with the same project\n- **Organized**: Separate directories for different content types\n- **Persistent**: All data survives server restarts\n- **Portable**: Easy to backup, move, or version control\n\n## 🐳 Docker Deployment\n\n### Development\n\n```bash\n# Clone repository\ngit clone https://github.com/cfdude/mcp-perplexity-pro.git\ncd mcp-perplexity-pro\n\n# Start development environment\ndocker-compose --profile dev up -d\n```\n\n### Production\n\n```bash\n# Set environment variables\nexport PROJECT_ROOT=/path/to/your/project\n\n# Start production environment\ndocker-compose up -d\n```\n\n### Custom Docker\n\n```dockerfile\nFROM mcp-perplexity-pro:latest\n\n# Custom configuration\nCOPY my-config.json /app/config.json\n\n# Custom entrypoint\nCMD [\"node\", \"dist/index.js\", \"--config\", \"config.json\"]\n```\n\n## ⚙️ Configuration\n\n### Environment Variables\n\n| Variable             | Description          | Default               |\n| -------------------- | -------------------- | --------------------- |\n| `NODE_ENV`           | Environment mode     | `development`         |\n| `PERPLEXITY_API_KEY` | Your API key         | Required              |\n| `PROJECT_ROOT`       | Project directory    | Current directory     |\n| `STORAGE_PATH`       | Storage subdirectory | `.perplexity`         |\n| `DEFAULT_MODEL`      | Default model        | `sonar-reasoning-pro` |\n| `SESSION_ID`         | Session identifier   | Auto-generated        |\n\n### Advanced Configuration\n\n```json\n{\n  \"api_key\": \"your-key\",\n  \"default_model\": \"sonar-reasoning-pro\",\n  \"project_root\": \"/workspace\",\n  \"storage_path\": \".perplexity\",\n  \"session_id\": \"unique-session\",\n  \"request_timeout\": 30000,\n  \"max_retries\": 3,\n  \"rate_limit\": {\n    \"requests_per_minute\": 60,\n    \"concurrent_requests\": 5\n  }\n}\n```\n\n## 🧪 Development\n\n### Setup\n\n```bash\n# Clone and install\ngit clone https://github.com/cfdude/mcp-perplexity-pro.git\ncd mcp-perplexity-pro\nnpm install\n\n# Development mode\nnpm run dev\n\n# Run tests\nnpm test\nnpm run test:coverage\n\n# Linting and formatting\nnpm run lint\nnpm run format\n```\n\n### Project Structure\n\n```\nsrc/\n├── index.ts              # Main MCP server\n├── types.ts              # TypeScript definitions\n├── models.ts             # Model registry \u0026 selection\n├── perplexity-api.ts     # API client wrapper\n├── storage.ts            # Storage management\n└── tools/\n    ├── query.ts          # Query tools\n    ├── chat.ts           # Chat tools\n    └── async.ts          # Async tools\n\ntests/\n├── models.test.ts        # Model selection tests\n├── storage.test.ts       # Storage tests\n├── perplexity-api.test.ts # API tests\n└── integration.test.ts   # End-to-end tests\n```\n\n### Testing\n\n```bash\n# Run all tests\nnpm test\n\n# Watch mode\nnpm run test:watch\n\n# Coverage report\nnpm run test:coverage\n\n# Specific test file\nnpm test -- models.test.ts\n```\n\n## 📊 API Usage Examples\n\n### Basic Query\n\n```javascript\n// Simple question\nconst result = await askPerplexity({\n  query: 'What is machine learning?',\n});\n\n// With specific model\nconst result = await askPerplexity({\n  query: 'Current Bitcoin price',\n  model: 'sonar-pro',\n});\n```\n\n### Conversation\n\n```javascript\n// Start new conversation\nconst chat = await chatPerplexity({\n  message: 'Hello!',\n  title: 'General Discussion',\n});\n\n// Continue conversation\nconst response = await chatPerplexity({\n  chat_id: chat.id,\n  message: 'Tell me about quantum computing',\n});\n```\n\n### Research\n\n```javascript\n// Comprehensive research\nconst research = await researchPerplexity({\n  query: 'Impact of AI on healthcare industry',\n  save_report: true,\n});\n\n// Async research for complex topics\nconst job = await asyncPerplexity({\n  query: 'Detailed analysis of climate change solutions',\n});\n\n// Check job status\nconst status = await checkAsync({\n  job_id: job.id,\n});\n```\n\n## 🔒 Security\n\n### API Key Management\n\n- Store API keys securely using environment variables\n- Never commit API keys to version control\n- Rotate keys regularly\n- Use different keys for different environments\n\n### Network Security\n\n- HTTPS in production\n- Rate limiting implemented\n- Input validation and sanitization\n- Error handling without information leakage\n\n### Container Security\n\n- Non-root user execution\n- Minimal base images\n- Regular security updates\n- Vulnerability scanning\n\n## 📈 Monitoring\n\n### Health Checks\n\n```bash\n# Basic health check\ncurl http://localhost:3000/health\n\n# Detailed status\ncurl http://localhost:3000/status\n```\n\n### Metrics\n\nThe server exposes Prometheus-compatible metrics:\n\n- Request count and duration\n- Error rates by endpoint\n- Storage usage statistics\n- Model usage distribution\n\n### Logging\n\nStructured JSON logging with configurable levels:\n\n```json\n{\n  \"timestamp\": \"2024-08-20T19:00:00.000Z\",\n  \"level\": \"info\",\n  \"message\": \"Query processed successfully\",\n  \"model\": \"sonar-reasoning-pro\",\n  \"duration\": 1250,\n  \"session_id\": \"session-123\"\n}\n```\n\n## 🚨 Troubleshooting\n\n### Common Issues\n\n**API Key Errors**\n\n```bash\nError: Invalid API key\nSolution: Verify PERPLEXITY_API_KEY is set correctly\n```\n\n**Storage Permission Errors**\n\n```bash\nError: EACCES: permission denied\nSolution: Ensure storage directory is writable\n```\n\n**Model Selection Issues**\n\n```bash\nError: Model not available\nSolution: Check model name spelling and availability\n```\n\n### Debug Mode\n\n```bash\nDEBUG=mcp-perplexity:* npm start\n```\n\n### Support\n\n- 📚 [Documentation](https://github.com/cfdude/mcp-perplexity-pro/wiki)\n- 🐛 [Issues](https://github.com/cfdude/mcp-perplexity-pro/issues)\n- 💬 [Discussions](https://github.com/cfdude/mcp-perplexity-pro/discussions)\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Workflow\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Ensure all tests pass\n6. Submit a pull request\n\n### Code Standards\n\n- TypeScript with strict mode\n- ESLint + Prettier formatting\n- 100% test coverage for new features\n- Conventional commit messages\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Perplexity AI](https://perplexity.ai/) for providing the excellent API\n- [Model Context Protocol](https://github.com/modelcontextprotocol) for the MCP specification\n- [Smithery](https://smithery.ai/) for MCP development tools\n- The open-source community for inspiration and contributions\n\n## 📊 Project Stats\n\n![GitHub stars](https://img.shields.io/github/stars/cfdude/mcp-perplexity-pro)\n![GitHub forks](https://img.shields.io/github/forks/cfdude/mcp-perplexity-pro)\n![GitHub issues](https://img.shields.io/github/issues/cfdude/mcp-perplexity-pro)\n![GitHub pull requests](https://img.shields.io/github/issues-pr/cfdude/mcp-perplexity-pro)\n\n---\n\n**Built with ❤️ for the MCP community**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcfdude%2Fmcp-perplexity-pro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcfdude%2Fmcp-perplexity-pro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcfdude%2Fmcp-perplexity-pro/lists"}