DEPLOYMENT.md•12.6 kB
# MCP Self-Learning Server - Deployment Guide
## 🚀 Production Deployment
### Prerequisites
- **Node.js**: Version 18.0.0 or higher
- **NPM**: Latest stable version
- **System Access**: User-level systemd access for Linux
- **Memory**: Minimum 256MB RAM (512MB recommended)
- **Storage**: 100MB+ free space for learning data
## 📦 Installation Methods
### Method 1: Global NPM Installation (Recommended)
```bash
# Navigate to project directory
cd /path/to/MCPSelfLearningServer
# Install dependencies and link globally
npm install
npm link
# Verify installation
mcp-learn --version
mcp-learn health
```
### Method 2: Direct Installation
```bash
# Clone repository
git clone https://github.com/saralegui-solutions/mcp-self-learning-server.git
cd mcp-self-learning-server
# Install and setup
npm install
chmod +x bin/mcp-learn.js
# Create symlink (optional)
sudo ln -s $(pwd)/bin/mcp-learn.js /usr/local/bin/mcp-learn
```
## 🔧 Configuration
### System Configuration
The post-install script automatically creates:
- `~/.mcp-learning/config.json` - Main configuration
- `~/.mcp-learning/logs/` - Log directory
- `~/.mcp-learning/data/` - Data directory
- `~/.config/systemd/user/mcp-self-learning.service` - Systemd service
### Configuration File (`~/.mcp-learning/config.json`)
```json
{
"version": "1.0.0",
"server": {
"port": 8765,
"host": "localhost",
"autoStart": false
},
"learning": {
"maxMemorySize": 1000,
"autoSaveInterval": 300000,
"persistenceEnabled": true
},
"api": {
"authentication": false,
"corsEnabled": true,
"rateLimit": {
"enabled": false,
"max": 100,
"windowMs": 900000
}
},
"integrations": {
"claudio": {
"enabled": false,
"path": "/home/ben/saralegui-solutions-llc/claude-assistant"
},
"claudia": {
"enabled": false,
"path": "/home/ben/claudia"
}
},
"logging": {
"level": "info",
"console": true,
"file": true
}
}
```
### Environment Variables
```bash
# Optional environment variables
export MCP_LEARN_PORT=8765
export MCP_LEARN_LOG_LEVEL=info
export MCP_LEARN_AUTO_START=true
export MCP_LEARN_DATA_DIR=~/.mcp-learning/data
```
## 🔄 Service Management
### Systemd Service (Linux - Recommended)
#### Enable & Start Service
```bash
# Reload systemd configuration
systemctl --user daemon-reload
# Enable auto-start on boot
systemctl --user enable mcp-self-learning.service
# Start service immediately
systemctl --user start mcp-self-learning.service
# Check service status
systemctl --user status mcp-self-learning.service
```
#### Service Management Commands
```bash
# Start service
systemctl --user start mcp-self-learning.service
# Stop service
systemctl --user stop mcp-self-learning.service
# Restart service
systemctl --user restart mcp-self-learning.service
# Disable auto-start
systemctl --user disable mcp-self-learning.service
# View logs
journalctl --user -u mcp-self-learning.service -f
```
#### Service Configuration
Located at: `~/.config/systemd/user/mcp-self-learning.service`
```ini
[Unit]
Description=MCP Self-Learning Server
Documentation=https://github.com/saralegui-solutions/mcp-self-learning-server
After=network.target
Wants=network-online.target
StartLimitIntervalSec=300
StartLimitBurst=5
[Service]
Type=simple
WorkingDirectory=/path/to/MCPSelfLearningServer
Environment=HOME=/home/ben
Environment=NODE_ENV=production
Environment=MCP_LEARN_AUTO_START=true
ExecStart=/path/to/node mcp-self-learning-server.js
ExecReload=/bin/kill -HUP $MAINPID
ExecStop=/bin/kill -TERM $MAINPID
Restart=on-failure
RestartSec=10
KillMode=mixed
TimeoutStartSec=30
TimeoutStopSec=10
[Install]
WantedBy=default.target
```
### Manual Service Management
#### Start Server Directly
```bash
# Start MCP server
mcp-learn start
# Start with API server
mcp-learn api
# Start in development mode
NODE_ENV=development mcp-learn start
```
#### Process Management
```bash
# Find running processes
pgrep -f mcp-self-learning
# Stop all processes
pkill -f mcp-self-learning
# Check if running
curl -s http://localhost:8765/health
```
## 🐳 Docker Deployment
### Dockerfile
```dockerfile
FROM node:18-alpine
# Set working directory
WORKDIR /app
# Copy package files
COPY package*.json ./
# Install dependencies
RUN npm ci --only=production
# Copy application code
COPY . .
# Create data directories
RUN mkdir -p /app/data /app/logs
# Expose port
EXPOSE 8765
# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
CMD curl -f http://localhost:8765/health || exit 1
# Start server
CMD ["node", "mcp-self-learning-server.js"]
```
### Build & Run
```bash
# Build image
docker build -t saralegui-solutions/mcp-self-learning-server:latest .
# Run container
docker run -d \
--name mcp-learning-server \
-p 8765:8765 \
-v mcp-learning-data:/app/data \
-v mcp-learning-logs:/app/logs \
--restart unless-stopped \
saralegui-solutions/mcp-self-learning-server:latest
# Check status
docker logs mcp-learning-server
docker exec mcp-learning-server curl http://localhost:8765/health
```
### Docker Compose
```yaml
# docker-compose.yml
version: '3.8'
services:
mcp-learning-server:
build: .
container_name: mcp-learning-server
ports:
- "8765:8765"
volumes:
- mcp-learning-data:/app/data
- mcp-learning-logs:/app/logs
environment:
- NODE_ENV=production
- MCP_LEARN_LOG_LEVEL=info
restart: unless-stopped
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8765/health"]
interval: 30s
timeout: 10s
retries: 3
volumes:
mcp-learning-data:
mcp-learning-logs:
```
```bash
# Deploy with Docker Compose
docker-compose up -d
# View logs
docker-compose logs -f
# Scale (if needed)
docker-compose up -d --scale mcp-learning-server=2
```
## ☸️ Kubernetes Deployment
### Namespace & ConfigMap
```yaml
# namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
name: mcp-learning
---
# configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: mcp-learning-config
namespace: mcp-learning
data:
config.json: |
{
"server": { "port": 8765, "host": "0.0.0.0" },
"learning": { "maxMemorySize": 1000, "persistenceEnabled": true },
"logging": { "level": "info", "console": true, "file": true }
}
```
### Deployment & Service
```yaml
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: mcp-learning-server
namespace: mcp-learning
spec:
replicas: 2
selector:
matchLabels:
app: mcp-learning-server
template:
metadata:
labels:
app: mcp-learning-server
spec:
containers:
- name: mcp-learning-server
image: saralegui-solutions/mcp-self-learning-server:latest
ports:
- containerPort: 8765
env:
- name: NODE_ENV
value: "production"
volumeMounts:
- name: config
mountPath: /app/config
- name: data
mountPath: /app/data
livenessProbe:
httpGet:
path: /health
port: 8765
initialDelaySeconds: 30
periodSeconds: 10
readinessProbe:
httpGet:
path: /health
port: 8765
initialDelaySeconds: 5
periodSeconds: 5
resources:
requests:
memory: "256Mi"
cpu: "100m"
limits:
memory: "512Mi"
cpu: "500m"
volumes:
- name: config
configMap:
name: mcp-learning-config
- name: data
persistentVolumeClaim:
claimName: mcp-learning-data
---
# service.yaml
apiVersion: v1
kind: Service
metadata:
name: mcp-learning-service
namespace: mcp-learning
spec:
selector:
app: mcp-learning-server
ports:
- port: 8765
targetPort: 8765
type: ClusterIP
---
# pvc.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: mcp-learning-data
namespace: mcp-learning
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 1Gi
```
### Deploy to Kubernetes
```bash
# Apply manifests
kubectl apply -f namespace.yaml
kubectl apply -f configmap.yaml
kubectl apply -f deployment.yaml
# Check deployment
kubectl get pods -n mcp-learning
kubectl logs -f deployment/mcp-learning-server -n mcp-learning
# Port forward for local access
kubectl port-forward service/mcp-learning-service 8765:8765 -n mcp-learning
```
## 📊 Monitoring & Observability
### Health Monitoring
```bash
# Built-in health check
curl http://localhost:8765/health
# Detailed status
curl http://localhost:8765/status
# Performance metrics
curl http://localhost:8765/metrics
```
### Logging
#### Log Locations
- **Systemd**: `journalctl --user -u mcp-self-learning.service`
- **File Logs**: `~/.mcp-learning/logs/server.log`
- **Docker**: `docker logs mcp-learning-server`
- **Kubernetes**: `kubectl logs deployment/mcp-learning-server -n mcp-learning`
#### Log Levels
- `error`: Critical errors only
- `warn`: Warnings and errors
- `info`: General information (default)
- `debug`: Detailed debugging information
### Monitoring Tools
#### Prometheus Integration
```yaml
# prometheus.yml
scrape_configs:
- job_name: 'mcp-learning-server'
static_configs:
- targets: ['localhost:8765']
metrics_path: '/metrics'
```
#### Grafana Dashboard
Key metrics to monitor:
- Request rate and response time
- Memory usage and pattern count
- Learning cycle frequency
- Error rates by endpoint
- WebSocket connection count
## 🔐 Security Considerations
### Network Security
```bash
# Bind to localhost only (default)
HOST=localhost PORT=8765 node mcp-self-learning-server.js
# Enable authentication
export MCP_LEARN_AUTH_ENABLED=true
export MCP_LEARN_AUTH_TOKEN=your-secure-token
```
### Process Security
```bash
# Run as non-root user (recommended)
useradd -r -s /bin/false mcp-learning
chown -R mcp-learning:mcp-learning /app
# Set appropriate permissions
chmod 750 /app
chmod 640 /app/config/*.json
```
### Data Security
- All learning data stored locally
- No external network calls for core functionality
- Optional HTTPS/TLS for API endpoints
- Configurable CORS policies
## 🚨 Troubleshooting
### Common Issues
#### Service Won't Start
```bash
# Check service status
systemctl --user status mcp-self-learning.service
# Check logs
journalctl --user -u mcp-self-learning.service -n 50
# Check port availability
netstat -tlnp | grep 8765
```
#### Permission Issues
```bash
# Fix data directory permissions
chmod -R 755 ~/.mcp-learning/
chown -R $USER:$USER ~/.mcp-learning/
```
#### Memory Issues
```bash
# Check memory usage
curl http://localhost:8765/status | jq '.memory'
# Adjust memory limits in config
vim ~/.mcp-learning/config.json
```
#### Integration Issues
```bash
# Test CLI tools
mcp-learn health
mcp-learn status
# Test API directly
curl http://localhost:8765/health
# Check client connections
curl http://localhost:8765/status | jq '.websocketConnections'
```
### Performance Tuning
#### Memory Optimization
```json
{
"learning": {
"maxMemorySize": 500, // Reduce for low-memory systems
"autoSaveInterval": 600000 // Increase save interval
}
}
```
#### Network Optimization
```json
{
"api": {
"rateLimit": {
"enabled": true,
"max": 200, // Increase for high-load
"windowMs": 60000
}
}
}
```
## 🔄 Updates & Maintenance
### Update Process
```bash
# Stop service
systemctl --user stop mcp-self-learning.service
# Update code
git pull origin main
npm install
# Restart service
systemctl --user start mcp-self-learning.service
# Verify update
mcp-learn --version
curl http://localhost:8765/health
```
### Backup & Recovery
#### Backup Learning Data
```bash
# Create backup
cp -r ~/.mcp-learning/data/ ~/mcp-learning-backup-$(date +%Y%m%d)
# Automated backup script
#!/bin/bash
BACKUP_DIR=~/mcp-learning-backups
mkdir -p $BACKUP_DIR
tar -czf $BACKUP_DIR/mcp-learning-$(date +%Y%m%d-%H%M%S).tar.gz ~/.mcp-learning/
find $BACKUP_DIR -name "*.tar.gz" -mtime +7 -delete
```
#### Restore Data
```bash
# Stop service
systemctl --user stop mcp-self-learning.service
# Restore backup
rm -rf ~/.mcp-learning/data/
tar -xzf ~/mcp-learning-backup.tar.gz -C ~/
# Start service
systemctl --user start mcp-self-learning.service
```
This deployment guide provides comprehensive instructions for running the MCP Self-Learning Server in various environments from development to production-scale Kubernetes deployments.