README.md•11.4 kB
# Secure MCP Server
## Enterprise-Grade Model Context Protocol Implementation
A production-ready, secure, and scalable Model Context Protocol (MCP) server designed for enterprise deployments with advanced security features, comprehensive monitoring, and high availability.
## Features
### Core Capabilities
- **Model Context Protocol (MCP) v0.5.0** - Full implementation of the MCP specification
- **WebSocket & HTTP Transport** - Dual transport layer support for flexible client connectivity
- **Tool Management** - Dynamic tool registration, validation, and execution
- **Context Management** - Efficient context handling with configurable limits and caching
### Security Features
- **Multi-Factor Authentication** - JWT + TOTP/SMS-based 2FA
- **SAML 2.0 Integration** - Enterprise SSO support
- **End-to-End Encryption** - TLS 1.3 with certificate pinning
- **Vault Integration** - HashiCorp Vault for secrets management
- **Rate Limiting** - Configurable per-endpoint and per-user limits
- **RBAC** - Role-based access control with granular permissions
### Enterprise Features
- **High Availability** - Multi-region deployment with automatic failover
- **Horizontal Scaling** - Kubernetes-native with auto-scaling
- **Monitoring & Observability** - Prometheus, Grafana, and distributed tracing
- **Audit Logging** - Comprehensive audit trails for compliance
- **Database Support** - PostgreSQL with read replicas and Redis caching
- **Message Queue Integration** - RabbitMQ/Kafka for async processing
## Installation
### NPM Package Installation
#### Server Package
```bash
npm install @perfecxion/secure-mcp-server
```
#### Client SDK
```bash
npm install @perfecxion/secure-mcp-client
```
### Docker Installation
```bash
docker pull perfecxion/secure-mcp-server:latest
```
## Quick Start
### Prerequisites
- Node.js >= 20.0.0
- Docker & Docker Compose
- PostgreSQL 15+
- Redis 7+
- (Optional) Kubernetes cluster for production deployment
### Using NPM Package
```javascript
import { SecureMCPServer } from '@perfecxion/secure-mcp-server';
const server = new SecureMCPServer({
port: 3000,
auth: {
jwt: { secret: process.env.JWT_SECRET },
apiKeys: true
}
});
await server.start();
```
### Using Client SDK
```javascript
import { SecureMCPClient } from '@perfecxion/secure-mcp-client';
const client = new SecureMCPClient({
serverUrl: 'https://mcp.example.com',
apiKey: 'your-api-key'
});
await client.connect();
const tools = await client.listTools();
```
### Local Development
1. **Clone the repository**
```bash
git clone https://github.com/perfecxion-ai/secure-mcp.git
cd secure-mcp
```
2. **Install dependencies**
```bash
npm install
```
3. **Configure environment**
```bash
cp .env.example .env
# Edit .env with your configuration
```
4. **Start dependencies**
```bash
docker-compose up -d postgres redis vault
```
5. **Initialize database**
```bash
npm run db:migrate
npm run db:generate
```
6. **Initialize Vault**
```bash
npm run vault:init
```
7. **Start the server**
```bash
npm run dev
```
The server will be available at:
- WebSocket: `ws://localhost:3000`
- HTTP API: `http://localhost:3000/api`
- Health Check: `http://localhost:3000/health`
- Metrics: `http://localhost:3000/metrics`
### Docker Deployment
```bash
# Build the image
npm run docker:build
# Run with docker-compose
npm run docker:run
```
### Kubernetes Deployment
```bash
# Deploy to development environment
npm run k8s:deploy
# Deploy to production (requires kubectl context)
kubectl apply -k kubernetes/overlays/production
```
## Architecture Overview
```mermaid
graph TB
subgraph "Client Layer"
C1[MCP Client]
C2[Web Client]
C3[Mobile App]
end
subgraph "Gateway Layer"
LB[Load Balancer]
WAF[Web Application Firewall]
end
subgraph "Application Layer"
API[API Server]
WS[WebSocket Server]
AUTH[Auth Service]
end
subgraph "Data Layer"
PG[(PostgreSQL)]
REDIS[(Redis Cache)]
VAULT[(HashiCorp Vault)]
end
subgraph "Monitoring"
PROM[Prometheus]
GRAF[Grafana]
LOG[ELK Stack]
end
C1 & C2 & C3 --> LB
LB --> WAF
WAF --> API & WS
API & WS --> AUTH
API --> PG & REDIS
AUTH --> VAULT
API & WS --> PROM
PROM --> GRAF
API & WS --> LOG
```
## Project Structure
```
secure-mcp-server/
├── src/ # Source code
│ ├── auth/ # Authentication & authorization
│ ├── config/ # Configuration management
│ ├── database/ # Database models & migrations
│ ├── monitoring/ # Metrics & health checks
│ ├── security/ # Security middleware & utilities
│ ├── server/ # WebSocket & HTTP servers
│ ├── tools/ # MCP tool implementations
│ └── utils/ # Utility functions
├── tests/ # Test suites
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests
│ ├── security/ # Security tests
│ └── performance/ # Performance tests
├── docker/ # Docker configurations
├── kubernetes/ # Kubernetes manifests
│ ├── base/ # Base configurations
│ └── overlays/ # Environment-specific overlays
├── scripts/ # Deployment & utility scripts
├── docs/ # Documentation
└── monitoring/ # Monitoring configurations
```
## Configuration
The server uses a hierarchical configuration system with environment-specific overrides:
1. **Base Configuration** - `src/config/default.ts`
2. **Environment Variables** - `.env` file
3. **Secrets Management** - HashiCorp Vault
4. **Runtime Configuration** - Kubernetes ConfigMaps
### Key Configuration Options
```typescript
{
server: {
port: 3000,
host: "0.0.0.0",
corsOrigins: ["http://localhost:*"],
maxRequestSize: "10mb",
timeout: 30000
},
auth: {
jwtSecret: process.env.JWT_SECRET,
jwtExpiry: "1h",
refreshExpiry: "7d",
mfaRequired: true,
sessionTimeout: 3600000
},
database: {
url: process.env.DATABASE_URL,
maxConnections: 20,
ssl: { rejectUnauthorized: true }
},
redis: {
host: process.env.REDIS_HOST,
port: 6379,
password: process.env.REDIS_PASSWORD,
tls: true
},
security: {
rateLimit: {
windowMs: 60000,
maxRequests: 100
},
helmet: {
contentSecurityPolicy: true,
hsts: { maxAge: 31536000 }
}
}
}
```
## API Documentation
### Authentication Endpoints
#### POST /api/auth/register
Register a new user account.
```bash
curl -X POST http://localhost:3000/api/auth/register \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "SecureP@ssw0rd!",
"name": "John Doe"
}'
```
#### POST /api/auth/login
Authenticate and receive JWT tokens.
```bash
curl -X POST http://localhost:3000/api/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "SecureP@ssw0rd!"
}'
```
#### POST /api/auth/refresh
Refresh access token using refresh token.
```bash
curl -X POST http://localhost:3000/api/auth/refresh \
-H "Authorization: Bearer <refresh_token>"
```
### WebSocket Connection
```javascript
const WebSocket = require('ws');
const ws = new WebSocket('ws://localhost:3000', {
headers: {
'Authorization': 'Bearer <access_token>'
}
});
ws.on('open', () => {
// Send MCP request
ws.send(JSON.stringify({
jsonrpc: '2.0',
method: 'tools/list',
id: 1
}));
});
ws.on('message', (data) => {
console.log('Received:', JSON.parse(data));
});
```
## Testing
### Run All Tests
```bash
npm test
```
### Test Categories
```bash
npm run test:unit # Unit tests
npm run test:integration # Integration tests
npm run test:security # Security tests
npm run test:performance # Performance tests
npm run test:coverage # Coverage report
```
### Load Testing
```bash
npm run load-test # Artillery load test
npm run stress-test # Artillery stress test
npm run benchmark # Autocannon benchmark
```
## Monitoring
The server exposes comprehensive metrics and health endpoints:
- **Metrics**: `http://localhost:3000/metrics` (Prometheus format)
- **Health**: `http://localhost:3000/health`
- **Ready**: `http://localhost:3000/ready`
### Grafana Dashboards
Access pre-configured dashboards:
```bash
npm run monitor:start
# Open http://localhost:3001 (admin/admin)
```
Available dashboards:
- System Overview
- API Performance
- WebSocket Connections
- Database Performance
- Security Events
- Error Tracking
## Security
### Security Features
1. **Authentication & Authorization**
- JWT-based authentication with refresh tokens
- Multi-factor authentication (TOTP/SMS)
- SAML 2.0 SSO integration
- Session management with Redis
2. **Data Protection**
- TLS 1.3 encryption in transit
- AES-256-GCM encryption at rest
- Certificate pinning for critical endpoints
- Secure key rotation
3. **Access Control**
- Role-based access control (RBAC)
- Attribute-based access control (ABAC)
- API key management
- IP whitelisting
4. **Security Monitoring**
- Real-time threat detection
- Audit logging
- Anomaly detection
- Security event correlation
### Security Best Practices
- Regular dependency updates via Dependabot
- Security scanning with Snyk
- Penetration testing suite included
- OWASP Top 10 compliance
- SOC 2 Type II ready
- ISO 27001 compliant
## Performance
### Benchmarks
| Metric | Value | Conditions |
|--------|-------|------------|
| Requests/sec | 10,000+ | Single instance, 4 vCPU |
| WebSocket Connections | 50,000+ | Single instance, 8GB RAM |
| P95 Latency | <50ms | Normal load |
| P99 Latency | <100ms | Normal load |
| Throughput | 1GB/s | Data transfer |
### Optimization Features
- Connection pooling
- Redis caching layer
- Database query optimization
- Lazy loading
- Request batching
- Response compression
## Contributing
Please read our [Developer Guide](./docs/DEVELOPER_GUIDE.md) for details on our code of conduct and the process for submitting pull requests.
### Development Workflow
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
### Code Standards
- TypeScript strict mode
- ESLint configuration
- Prettier formatting
- 95% test coverage requirement
- Security review required for auth changes
## Support
- **Documentation**: [Full Documentation](./docs/)
- **Issues**: [GitHub Issues](https://github.com/enterprise/secure-mcp-server/issues)
- **Security**: security@enterprise.com
- **Enterprise Support**: support@enterprise.com
## License
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- Model Context Protocol specification by Anthropic
- Open source community contributors
- Security researchers and pen testers
- Enterprise customers for feedback and requirements