Add comprehensive documentation for BZZZ MCP Server
- Complete API reference with all interfaces and examples - Detailed deployment guide for development and production - Main README with architecture overview and usage instructions 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
anthonyrawlins
640
mcp-server/docs/DEPLOYMENT.md
Normal file
640
mcp-server/docs/DEPLOYMENT.md
Normal file
@@ -0,0 +1,640 @@
|
||||
# BZZZ MCP Server Deployment Guide
|
||||
|
||||
Complete deployment guide for the BZZZ MCP Server in various environments.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Environment Configuration](#environment-configuration)
|
||||
- [Development Deployment](#development-deployment)
|
||||
- [Production Deployment](#production-deployment)
|
||||
- [Docker Deployment](#docker-deployment)
|
||||
- [Systemd Service](#systemd-service)
|
||||
- [Monitoring and Health Checks](#monitoring-and-health-checks)
|
||||
- [Backup and Recovery](#backup-and-recovery)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### System Requirements
|
||||
|
||||
**Minimum Requirements:**
|
||||
- Node.js 18.0 or higher
|
||||
- 2 CPU cores
|
||||
- 4GB RAM
|
||||
- 10GB disk space
|
||||
- Network access to OpenAI API
|
||||
- Network access to BZZZ Go service
|
||||
|
||||
**Recommended Requirements:**
|
||||
- Node.js 20.0 or higher
|
||||
- 4 CPU cores
|
||||
- 8GB RAM
|
||||
- 50GB disk space
|
||||
- High-speed internet connection
|
||||
- Load balancer for multiple instances
|
||||
|
||||
### External Dependencies
|
||||
|
||||
1. **OpenAI API Access**
|
||||
- Valid OpenAI API key
|
||||
- GPT-5 model access
|
||||
- Sufficient API credits
|
||||
|
||||
2. **BZZZ Go Service**
|
||||
- Running BZZZ Go service instance
|
||||
- Network connectivity to BZZZ service
|
||||
- Compatible BZZZ API version
|
||||
|
||||
3. **Network Configuration**
|
||||
- Outbound HTTPS access (port 443) for OpenAI
|
||||
- HTTP/WebSocket access to BZZZ service
|
||||
- Optionally: Inbound access for health checks
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Create a `.env` file or set system environment variables:
|
||||
|
||||
```bash
|
||||
# OpenAI Configuration
|
||||
OPENAI_MODEL=gpt-5
|
||||
OPENAI_MAX_TOKENS=4000
|
||||
OPENAI_TEMPERATURE=0.7
|
||||
|
||||
# BZZZ Configuration
|
||||
BZZZ_NODE_URL=http://localhost:8080
|
||||
BZZZ_NETWORK_ID=bzzz-production
|
||||
|
||||
# Cost Management
|
||||
DAILY_COST_LIMIT=100.0
|
||||
MONTHLY_COST_LIMIT=1000.0
|
||||
COST_WARNING_THRESHOLD=0.8
|
||||
|
||||
# Performance Settings
|
||||
MAX_ACTIVE_THREADS=10
|
||||
MAX_AGENTS=5
|
||||
THREAD_TIMEOUT=3600
|
||||
|
||||
# Logging
|
||||
LOG_LEVEL=info
|
||||
LOG_FILE=/var/log/bzzz-mcp/server.log
|
||||
|
||||
# Node.js Settings
|
||||
NODE_ENV=production
|
||||
```
|
||||
|
||||
### Security Configuration
|
||||
|
||||
1. **API Key Management**
|
||||
```bash
|
||||
# Create secure directory
|
||||
sudo mkdir -p /opt/bzzz-mcp/secrets
|
||||
sudo chown bzzz:bzzz /opt/bzzz-mcp/secrets
|
||||
sudo chmod 700 /opt/bzzz-mcp/secrets
|
||||
|
||||
# Store OpenAI API key
|
||||
echo "your-openai-api-key" | sudo tee /opt/bzzz-mcp/secrets/openai-api-key.txt
|
||||
sudo chown bzzz:bzzz /opt/bzzz-mcp/secrets/openai-api-key.txt
|
||||
sudo chmod 600 /opt/bzzz-mcp/secrets/openai-api-key.txt
|
||||
```
|
||||
|
||||
2. **Network Security**
|
||||
```bash
|
||||
# Configure firewall (Ubuntu/Debian)
|
||||
sudo ufw allow out 443/tcp # OpenAI API
|
||||
sudo ufw allow out 8080/tcp # BZZZ Go service
|
||||
sudo ufw allow in 3000/tcp # Health checks (optional)
|
||||
```
|
||||
|
||||
## Development Deployment
|
||||
|
||||
### Local Development Setup
|
||||
|
||||
1. **Clone and Install**
|
||||
```bash
|
||||
cd /path/to/BZZZ/mcp-server
|
||||
npm install
|
||||
```
|
||||
|
||||
2. **Configure Development Environment**
|
||||
```bash
|
||||
# Copy example environment file
|
||||
cp .env.example .env
|
||||
|
||||
# Edit configuration
|
||||
nano .env
|
||||
```
|
||||
|
||||
3. **Start Development Server**
|
||||
```bash
|
||||
# With hot reload
|
||||
npm run dev
|
||||
|
||||
# Or build and run
|
||||
npm run build
|
||||
npm start
|
||||
```
|
||||
|
||||
### Development Docker Setup
|
||||
|
||||
```dockerfile
|
||||
# Dockerfile.dev
|
||||
FROM node:20-alpine
|
||||
|
||||
WORKDIR /app
|
||||
|
||||
# Install dependencies
|
||||
COPY package*.json ./
|
||||
RUN npm ci
|
||||
|
||||
# Copy source
|
||||
COPY . .
|
||||
|
||||
# Development command
|
||||
CMD ["npm", "run", "dev"]
|
||||
```
|
||||
|
||||
```bash
|
||||
# Build and run development container
|
||||
docker build -f Dockerfile.dev -t bzzz-mcp:dev .
|
||||
docker run -p 3000:3000 -v $(pwd):/app bzzz-mcp:dev
|
||||
```
|
||||
|
||||
## Production Deployment
|
||||
|
||||
### Manual Production Setup
|
||||
|
||||
1. **Create Application User**
|
||||
```bash
|
||||
sudo useradd -r -s /bin/false bzzz
|
||||
sudo mkdir -p /opt/bzzz-mcp
|
||||
sudo chown bzzz:bzzz /opt/bzzz-mcp
|
||||
```
|
||||
|
||||
2. **Install Application**
|
||||
```bash
|
||||
# Copy built application
|
||||
sudo cp -r dist/ /opt/bzzz-mcp/
|
||||
sudo cp package*.json /opt/bzzz-mcp/
|
||||
sudo chown -R bzzz:bzzz /opt/bzzz-mcp
|
||||
|
||||
# Install production dependencies
|
||||
cd /opt/bzzz-mcp
|
||||
sudo -u bzzz npm ci --only=production
|
||||
```
|
||||
|
||||
3. **Configure Logging**
|
||||
```bash
|
||||
sudo mkdir -p /var/log/bzzz-mcp
|
||||
sudo chown bzzz:bzzz /var/log/bzzz-mcp
|
||||
sudo chmod 755 /var/log/bzzz-mcp
|
||||
|
||||
# Setup log rotation
|
||||
sudo tee /etc/logrotate.d/bzzz-mcp << EOF
|
||||
/var/log/bzzz-mcp/*.log {
|
||||
daily
|
||||
rotate 30
|
||||
compress
|
||||
delaycompress
|
||||
missingok
|
||||
notifempty
|
||||
create 644 bzzz bzzz
|
||||
postrotate
|
||||
systemctl reload bzzz-mcp
|
||||
endscript
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
## Docker Deployment
|
||||
|
||||
### Production Dockerfile
|
||||
|
||||
```dockerfile
|
||||
FROM node:20-alpine AS builder
|
||||
|
||||
WORKDIR /app
|
||||
|
||||
# Copy package files
|
||||
COPY package*.json ./
|
||||
|
||||
# Install all dependencies
|
||||
RUN npm ci
|
||||
|
||||
# Copy source code
|
||||
COPY . .
|
||||
|
||||
# Build application
|
||||
RUN npm run build
|
||||
|
||||
# Production stage
|
||||
FROM node:20-alpine AS production
|
||||
|
||||
# Create app user
|
||||
RUN addgroup -g 1001 -S bzzz && \
|
||||
adduser -S bzzz -u 1001
|
||||
|
||||
# Create app directory
|
||||
WORKDIR /opt/bzzz-mcp
|
||||
|
||||
# Copy built application
|
||||
COPY --from=builder --chown=bzzz:bzzz /app/dist ./dist
|
||||
COPY --from=builder --chown=bzzz:bzzz /app/package*.json ./
|
||||
|
||||
# Install only production dependencies
|
||||
RUN npm ci --only=production && npm cache clean --force
|
||||
|
||||
# Create directories
|
||||
RUN mkdir -p /var/log/bzzz-mcp && \
|
||||
chown bzzz:bzzz /var/log/bzzz-mcp
|
||||
|
||||
# Switch to app user
|
||||
USER bzzz
|
||||
|
||||
# Health check
|
||||
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
|
||||
CMD node dist/health-check.js || exit 1
|
||||
|
||||
EXPOSE 3000
|
||||
|
||||
CMD ["node", "dist/index.js"]
|
||||
```
|
||||
|
||||
### Docker Compose Setup
|
||||
|
||||
```yaml
|
||||
version: '3.8'
|
||||
|
||||
services:
|
||||
bzzz-mcp:
|
||||
build: .
|
||||
container_name: bzzz-mcp-server
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
- NODE_ENV=production
|
||||
- LOG_LEVEL=info
|
||||
- BZZZ_NODE_URL=http://bzzz-go:8080
|
||||
- DAILY_COST_LIMIT=100.0
|
||||
- MONTHLY_COST_LIMIT=1000.0
|
||||
volumes:
|
||||
- ./secrets:/opt/bzzz-mcp/secrets:ro
|
||||
- bzzz-mcp-logs:/var/log/bzzz-mcp
|
||||
networks:
|
||||
- bzzz-network
|
||||
depends_on:
|
||||
- bzzz-go
|
||||
labels:
|
||||
- "traefik.enable=true"
|
||||
- "traefik.http.routers.bzzz-mcp.rule=Host(`bzzz-mcp.local`)"
|
||||
- "traefik.http.services.bzzz-mcp.loadbalancer.server.port=3000"
|
||||
|
||||
bzzz-go:
|
||||
image: bzzz-go:latest
|
||||
container_name: bzzz-go-service
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "8080:8080"
|
||||
networks:
|
||||
- bzzz-network
|
||||
|
||||
volumes:
|
||||
bzzz-mcp-logs:
|
||||
|
||||
networks:
|
||||
bzzz-network:
|
||||
driver: bridge
|
||||
```
|
||||
|
||||
### Deployment Commands
|
||||
|
||||
```bash
|
||||
# Build and start services
|
||||
docker-compose up -d
|
||||
|
||||
# View logs
|
||||
docker-compose logs -f bzzz-mcp
|
||||
|
||||
# Update application
|
||||
docker-compose pull
|
||||
docker-compose up -d --force-recreate
|
||||
|
||||
# Stop services
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
## Systemd Service
|
||||
|
||||
### Service Configuration
|
||||
|
||||
```ini
|
||||
# /etc/systemd/system/bzzz-mcp.service
|
||||
[Unit]
|
||||
Description=BZZZ MCP Server
|
||||
Documentation=https://docs.bzzz.local/mcp-server
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=bzzz
|
||||
Group=bzzz
|
||||
WorkingDirectory=/opt/bzzz-mcp
|
||||
|
||||
# Environment
|
||||
Environment=NODE_ENV=production
|
||||
Environment=LOG_LEVEL=info
|
||||
EnvironmentFile=-/etc/bzzz-mcp/environment
|
||||
|
||||
# Execution
|
||||
ExecStart=/usr/bin/node dist/index.js
|
||||
ExecReload=/bin/kill -HUP $MAINPID
|
||||
|
||||
# Process management
|
||||
Restart=always
|
||||
RestartSec=10
|
||||
KillMode=mixed
|
||||
KillSignal=SIGTERM
|
||||
TimeoutSec=30
|
||||
|
||||
# Security
|
||||
NoNewPrivileges=yes
|
||||
ProtectSystem=strict
|
||||
ProtectHome=yes
|
||||
ReadWritePaths=/var/log/bzzz-mcp
|
||||
PrivateTmp=yes
|
||||
|
||||
# Logging
|
||||
StandardOutput=journal
|
||||
StandardError=journal
|
||||
SyslogIdentifier=bzzz-mcp
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
### Service Management
|
||||
|
||||
```bash
|
||||
# Install and enable service
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable bzzz-mcp
|
||||
sudo systemctl start bzzz-mcp
|
||||
|
||||
# Service status and logs
|
||||
sudo systemctl status bzzz-mcp
|
||||
sudo journalctl -u bzzz-mcp -f
|
||||
|
||||
# Service control
|
||||
sudo systemctl stop bzzz-mcp
|
||||
sudo systemctl restart bzzz-mcp
|
||||
sudo systemctl reload bzzz-mcp
|
||||
```
|
||||
|
||||
### Environment File
|
||||
|
||||
```bash
|
||||
# /etc/bzzz-mcp/environment
|
||||
OPENAI_MODEL=gpt-5
|
||||
BZZZ_NODE_URL=http://localhost:8080
|
||||
BZZZ_NETWORK_ID=bzzz-production
|
||||
DAILY_COST_LIMIT=100.0
|
||||
MONTHLY_COST_LIMIT=1000.0
|
||||
LOG_FILE=/var/log/bzzz-mcp/server.log
|
||||
```
|
||||
|
||||
## Monitoring and Health Checks
|
||||
|
||||
### Health Check Script
|
||||
|
||||
```javascript
|
||||
// health-check.js
|
||||
const http = require('http');
|
||||
|
||||
function healthCheck() {
|
||||
return new Promise((resolve, reject) => {
|
||||
const req = http.request({
|
||||
hostname: 'localhost',
|
||||
port: 3000,
|
||||
path: '/health',
|
||||
method: 'GET',
|
||||
timeout: 3000
|
||||
}, (res) => {
|
||||
if (res.statusCode === 200) {
|
||||
resolve('healthy');
|
||||
} else {
|
||||
reject(new Error(`Health check failed: ${res.statusCode}`));
|
||||
}
|
||||
});
|
||||
|
||||
req.on('error', reject);
|
||||
req.on('timeout', () => reject(new Error('Health check timeout')));
|
||||
req.end();
|
||||
});
|
||||
}
|
||||
|
||||
healthCheck()
|
||||
.then(() => process.exit(0))
|
||||
.catch(() => process.exit(1));
|
||||
```
|
||||
|
||||
### Monitoring Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# /usr/local/bin/bzzz-mcp-monitor.sh
|
||||
|
||||
LOG_FILE="/var/log/bzzz-mcp/monitor.log"
|
||||
SERVICE_NAME="bzzz-mcp"
|
||||
|
||||
log() {
|
||||
echo "$(date '+%Y-%m-%d %H:%M:%S') $1" >> $LOG_FILE
|
||||
}
|
||||
|
||||
# Check if service is running
|
||||
if ! systemctl is-active --quiet $SERVICE_NAME; then
|
||||
log "ERROR: Service $SERVICE_NAME is not running"
|
||||
systemctl restart $SERVICE_NAME
|
||||
log "INFO: Attempted to restart $SERVICE_NAME"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Check memory usage
|
||||
MEMORY_USAGE=$(ps -o pid,ppid,cmd,%mem --sort=-%mem -C node | grep bzzz-mcp | awk '{print $4}')
|
||||
if [[ -n "$MEMORY_USAGE" ]] && (( $(echo "$MEMORY_USAGE > 80" | bc -l) )); then
|
||||
log "WARNING: High memory usage: ${MEMORY_USAGE}%"
|
||||
fi
|
||||
|
||||
# Check log file size
|
||||
LOG_SIZE=$(du -m /var/log/bzzz-mcp/server.log 2>/dev/null | cut -f1)
|
||||
if [[ -n "$LOG_SIZE" ]] && (( LOG_SIZE > 100 )); then
|
||||
log "WARNING: Large log file: ${LOG_SIZE}MB"
|
||||
fi
|
||||
|
||||
log "INFO: Health check completed"
|
||||
```
|
||||
|
||||
### Cron Job Setup
|
||||
|
||||
```bash
|
||||
# Add to crontab
|
||||
sudo crontab -e
|
||||
|
||||
# Check every 5 minutes
|
||||
*/5 * * * * /usr/local/bin/bzzz-mcp-monitor.sh
|
||||
```
|
||||
|
||||
## Backup and Recovery
|
||||
|
||||
### Configuration Backup
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# /usr/local/bin/backup-bzzz-mcp.sh
|
||||
|
||||
BACKUP_DIR="/backup/bzzz-mcp"
|
||||
DATE=$(date +%Y%m%d_%H%M%S)
|
||||
|
||||
mkdir -p $BACKUP_DIR
|
||||
|
||||
# Backup configuration
|
||||
tar -czf $BACKUP_DIR/config-$DATE.tar.gz \
|
||||
/etc/bzzz-mcp/ \
|
||||
/opt/bzzz-mcp/secrets/ \
|
||||
/etc/systemd/system/bzzz-mcp.service
|
||||
|
||||
# Backup logs (last 7 days)
|
||||
find /var/log/bzzz-mcp/ -name "*.log" -mtime -7 -exec \
|
||||
tar -czf $BACKUP_DIR/logs-$DATE.tar.gz {} +
|
||||
|
||||
# Cleanup old backups (keep 30 days)
|
||||
find $BACKUP_DIR -name "*.tar.gz" -mtime +30 -delete
|
||||
|
||||
echo "Backup completed: $DATE"
|
||||
```
|
||||
|
||||
### Recovery Procedure
|
||||
|
||||
1. **Stop Service**
|
||||
```bash
|
||||
sudo systemctl stop bzzz-mcp
|
||||
```
|
||||
|
||||
2. **Restore Configuration**
|
||||
```bash
|
||||
cd /backup/bzzz-mcp
|
||||
tar -xzf config-YYYYMMDD_HHMMSS.tar.gz -C /
|
||||
```
|
||||
|
||||
3. **Verify Permissions**
|
||||
```bash
|
||||
sudo chown -R bzzz:bzzz /opt/bzzz-mcp
|
||||
sudo chmod 600 /opt/bzzz-mcp/secrets/*
|
||||
```
|
||||
|
||||
4. **Restart Service**
|
||||
```bash
|
||||
sudo systemctl start bzzz-mcp
|
||||
sudo systemctl status bzzz-mcp
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**1. Service Won't Start**
|
||||
```bash
|
||||
# Check logs
|
||||
sudo journalctl -u bzzz-mcp -n 50
|
||||
|
||||
# Common causes:
|
||||
# - Missing API key file
|
||||
# - Permission issues
|
||||
# - Port conflicts
|
||||
# - Missing dependencies
|
||||
```
|
||||
|
||||
**2. High Memory Usage**
|
||||
```bash
|
||||
# Monitor memory usage
|
||||
ps aux | grep node
|
||||
htop
|
||||
|
||||
# Possible solutions:
|
||||
# - Reduce MAX_AGENTS
|
||||
# - Decrease MAX_ACTIVE_THREADS
|
||||
# - Restart service periodically
|
||||
```
|
||||
|
||||
**3. OpenAI API Errors**
|
||||
```bash
|
||||
# Check API key validity
|
||||
curl -H "Authorization: Bearer $OPENAI_API_KEY" \
|
||||
https://api.openai.com/v1/models
|
||||
|
||||
# Common issues:
|
||||
# - Invalid or expired API key
|
||||
# - Rate limit exceeded
|
||||
# - Insufficient credits
|
||||
```
|
||||
|
||||
**4. BZZZ Connection Issues**
|
||||
```bash
|
||||
# Test BZZZ service connectivity
|
||||
curl http://localhost:8080/api/v1/health
|
||||
|
||||
# Check network configuration
|
||||
netstat -tulpn | grep 8080
|
||||
```
|
||||
|
||||
### Performance Tuning
|
||||
|
||||
**Node.js Optimization:**
|
||||
```bash
|
||||
# Add to service environment
|
||||
NODE_OPTIONS="--max-old-space-size=4096 --optimize-for-size"
|
||||
```
|
||||
|
||||
**System Optimization:**
|
||||
```bash
|
||||
# Increase file descriptor limits
|
||||
echo "bzzz soft nofile 65536" >> /etc/security/limits.conf
|
||||
echo "bzzz hard nofile 65536" >> /etc/security/limits.conf
|
||||
|
||||
# Optimize network settings
|
||||
echo 'net.core.somaxconn = 1024' >> /etc/sysctl.conf
|
||||
sysctl -p
|
||||
```
|
||||
|
||||
### Debug Mode
|
||||
|
||||
Enable debug logging for troubleshooting:
|
||||
|
||||
```bash
|
||||
# Temporary debug mode
|
||||
sudo systemctl edit bzzz-mcp
|
||||
|
||||
# Add:
|
||||
[Service]
|
||||
Environment=LOG_LEVEL=debug
|
||||
|
||||
# Reload and restart
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl restart bzzz-mcp
|
||||
```
|
||||
|
||||
### Log Analysis
|
||||
|
||||
```bash
|
||||
# Real-time log monitoring
|
||||
sudo journalctl -u bzzz-mcp -f
|
||||
|
||||
# Error analysis
|
||||
grep -i error /var/log/bzzz-mcp/server.log | tail -20
|
||||
|
||||
# Performance analysis
|
||||
grep -i "response time" /var/log/bzzz-mcp/server.log | tail -10
|
||||
```
|
||||
|
||||
This completes the comprehensive deployment guide. Follow the appropriate section based on your deployment environment and requirements.
|
||||
Reference in New Issue
Block a user