# MCP Perplexity Server

MCP server for Perplexity.ai that provides AI-powered search, research, and reasoning capabilities.

## 🚀 Features

- **Perplexity AI Integration**: Three specialized tools for different use cases
  - `perplexity_ask`: General conversational AI using sonar-pro model
  - `perplexity_research`: Deep research with citations using sonar-deep-research model
  - `perplexity_reason`: Advanced reasoning using sonar-reasoning-pro model
- **TypeScript**: Full type safety with modern TypeScript patterns
- **HTTP Transport**: RESTful API with Express.js server
- **Session Management**: Stateful connections with proper session handling
- **Configuration Management**: Environment-based configuration with validation
- **Error Handling**: Comprehensive error handling and logging
- **Health Checks**: Built-in health monitoring endpoints
- **Docker Support**: Production-ready containerization
- **Development Tools**: ESLint, Prettier, and testing setup
- **Production Ready**: Optimized for scalability and security

## 📋 Prerequisites

- Node.js 20+
- npm or yarn
- Docker (optional, for containerization)

## 🛠️ Quick Start

### Option 1: Use the Project Generator (Recommended)

```bash
# Clone the template
git clone <your-repo-url>
cd mcp-perplexity


# Create a new project using the generator
./create-mcp-project your-project-name --description "Your project description" --author "Your Name"

# Or use the Node.js script directly
node setup-new-project.js your-project-name --description "Your project description" --author "Your Name"
```

#### Generator Options:

- `--description <desc>`: Project description
- `--author <name>`: Author name
- `--target-dir <dir>`: Target directory (default: mcp-<project-name>)
- `--install-deps`: Install npm dependencies automatically
- `--no-git`: Skip git repository initialization

### Option 2: Manual Setup

```bash
# Clone the template
git clone <your-repo-url>
cd mcp-template

# Install dependencies
npm install

# Copy environment configuration
cp .env.example .env  # Create this file with your settings
```

### 2. Environment Configuration

Create a `.env` file in the root directory:

```env
# Server Configuration
PORT=3000
LOG_LEVEL=info

# Perplexity API Configuration
PERPLEXITY_API_KEY=your_perplexity_api_key_here
```

### 3. Development

```bash
# Start development server with hot reload
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Run tests
npm test

# Lint and format code
npm run lint
npm run lint:fix
```

## 🏗️ Project Structure

```
mcp-perplexity/
├── src/
│   ├── config/           # Configuration management
│   │   └── index.ts      # Main config file
│   ├── services/         # Service layer
│   │   └── perplexity.ts # Perplexity API service
│   ├── utils/            # Utility functions
│   └── index.ts          # Main server application
├── create-mcp-project    # Bash script for project generation
├── setup-new-project.js  # Node.js project generator
├── Dockerfile            # Docker configuration
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file
```

## 🔧 Project Generator

This template includes powerful project generation tools to quickly create new MCP servers:

### Features:

- **Automatic Name Conversion**: Converts kebab-case names to all required formats (camelCase, PascalCase, etc.)
- **File Templating**: Updates all files with the new project name and details
- **Git Integration**: Optionally initializes a new git repository
- **Dependency Management**: Can automatically install npm dependencies
- **Smart Copy Logic**: Excludes development files and prevents infinite recursion

### Usage Examples:

```bash
# Basic usage
./create-mcp-project weather-service

# With full options
./create-mcp-project task-manager \
  --description "AI-powered task management MCP server" \
  --author "Your Name" \
  --install-deps

# Custom target directory
./create-mcp-project file-processor --target-dir ./my-custom-server

# Skip git initialization
./create-mcp-project data-analyzer --no-git
```

## 🔧 Architecture

### Core Components

1. **McpServerApp**: Main application class that orchestrates the MCP server
2. **Configuration**: Environment-based configuration with type safety
3. **Session Management**: HTTP-based stateful sessions with cleanup
4. **Transport Layer**: StreamableHTTPServerTransport for MCP communication
5. **Error Handling**: Comprehensive error handling with proper HTTP responses

### HTTP Endpoints

- `GET /health` - Health check endpoint
- `POST /mcp` - Main MCP communication endpoint
- `GET /mcp` - Server-to-client notifications via SSE
- `DELETE /mcp` - Session termination

## 🛠️ Customization Guide

### Using Perplexity Tools

The server provides three Perplexity AI tools:

#### 1. perplexity_ask
General conversational AI using the sonar-pro model.

```json
{
  "name": "perplexity_ask",
  "arguments": {
    "messages": [
      {
        "role": "user",
        "content": "What are the latest developments in AI?"
      }
    ]
  }
}
```

#### 2. perplexity_research
Deep research with citations using the sonar-deep-research model.

```json
{
  "name": "perplexity_research",
  "arguments": {
    "messages": [
      {
        "role": "user",
        "content": "Research the current state of quantum computing and its applications"
      }
    ]
  }
}
```

#### 3. perplexity_reason
Advanced reasoning using the sonar-reasoning-pro model.

```json
{
  "name": "perplexity_reason",
  "arguments": {
    "messages": [
      {
        "role": "user",
        "content": "Analyze the pros and cons of different renewable energy sources"
      }
    ]
  }
}
```

### Adding New Tools

To add a new MCP tool, modify the `createServer()` method in `src/index.ts`:

```typescript
// Register your custom tool
server.tool(
  'your-tool-name',
  'Description of your tool',
  {
    // Define input schema using Zod
    parameter1: z.string().describe('Parameter description'),
    parameter2: z.number().optional().describe('Optional parameter'),
  },
  async ({ parameter1, parameter2 }) => {
    try {
      // Your tool implementation here
      const result = await yourCustomLogic(parameter1, parameter2);

      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(result, null, 2),
          } as TextContent,
        ],
      };
    } catch (error) {
      const errorMessage =
        error instanceof Error ? error.message : String(error);
      throw new Error(`Error in your-tool-name: ${errorMessage}`);
    }
  }
);
```

### Configuration Management

Add new configuration options in `src/config/index.ts`:

```typescript
interface Config {
  logging: LoggingConfig;
  server: ServerConfig;
  // Add your custom config sections
  database: {
    url: string;
    timeout: number;
  };
  external: {
    apiKey: string;
    baseUrl: string;
  };
}

const config: Config = {
  // ... existing config
  database: {
    url: process.env.DATABASE_URL || 'sqlite://memory',
    timeout: parseInt(process.env.DB_TIMEOUT || '5000', 10),
  },
  external: {
    apiKey: process.env.EXTERNAL_API_KEY || '',
    baseUrl: process.env.EXTERNAL_BASE_URL || 'https://api.example.com',
  },
};
```

### Adding Middleware

Add Express middleware in the `run()` method:

```typescript
async run() {
  const app = express();
  app.use(express.json());

  // Add your custom middleware
  app.use(cors()); // CORS support
  app.use(helmet()); // Security headers
  app.use(morgan('combined')); // Request logging

  // ... rest of the setup
}
```

## 🐳 Docker Deployment

### Build and Run

```bash
# Build Docker image
docker build -t mcp-perplexity-server .

# Run container
docker run -p 3000:3000 --env-file .env mcp-perplexity-server
```

### Docker Compose (Recommended)

Create a `docker-compose.yml`:

```yaml
version: '3.8'
services:
  mcp-server:
    build: .
    ports:
      - '3000:3000'
    environment:
      - NODE_ENV=production
      - PORT=3000
      - LOG_LEVEL=info
    restart: unless-stopped
    healthcheck:
      test: ['CMD', 'curl', '-f', 'http://localhost:3000/health']
      interval: 30s
      timeout: 10s
      retries: 3
```

Run with:

```bash
docker-compose up -d
```

## 🔒 Security Best Practices

This template implements several security measures:

- **Input Validation**: Zod schema validation for all tool parameters
- **Error Handling**: Safe error responses without information leakage
- **Session Management**: Proper session cleanup and validation
- **HTTP Security**: Ready for security headers and CORS configuration
- **Environment Variables**: Secure configuration management

### Recommended Additional Security

```typescript
// Add security middleware
import helmet from 'helmet';
import cors from 'cors';
import rateLimit from 'express-rate-limit';

app.use(helmet());
app.use(
  cors({
    origin: process.env.ALLOWED_ORIGINS?.split(',') || false,
  })
);

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // Limit each IP to 100 requests per windowMs
});
app.use('/mcp', limiter);
```

## 📊 Monitoring and Logging

The template includes basic logging setup. For production, consider adding:

- **Structured Logging**: Winston with JSON format
- **Metrics Collection**: Prometheus metrics
- **Health Checks**: Comprehensive health endpoints
- **APM Integration**: Application Performance Monitoring

## 🧪 Testing

```bash
# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage
```

### Writing Tests

Create test files in `src/**/*.test.ts`:

```typescript
import { describe, test, expect } from '@jest/globals';
// Your test imports

describe('YourComponent', () => {
  test('should handle valid input', async () => {
    // Test implementation
  });
});
```

## 🚀 Production Deployment

### Environment Variables

```env
NODE_ENV=production
PORT=3000
LOG_LEVEL=warn

# Add your production-specific variables
DATABASE_URL=postgresql://...
REDIS_URL=redis://...
API_KEYS=...
```

### Performance Optimization

- Enable gzip compression
- Implement proper caching headers
- Use connection pooling for databases
- Monitor memory usage and implement limits
- Set up log rotation

### Scaling Considerations

- Load balancing across multiple instances
- Database connection pooling
- Session store externalization (Redis)
- Horizontal pod autoscaling in Kubernetes

## 📚 References

- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
- [MCP SDK Documentation](https://github.com/modelcontextprotocol/typescript-sdk)
- [Express.js Documentation](https://expressjs.com/)
- [TypeScript Documentation](https://www.typescriptlang.org/)

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

## 📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 🆘 Support

For questions and support:

- Check the [MCP Documentation](https://modelcontextprotocol.io/)
- Review existing issues
- Create a new issue with detailed information

---

**Happy coding! 🎉**