HEROKU_DEPLOYMENT_GUIDE.md•6.44 kB
# 🚀 **HEROKU DEPLOYMENT GUIDE - Charnoks MCP Server**
## **Why Heroku is Perfect for Your MCP Server**
### ✅ **Your Server is Already Production-Ready:**
- Complete Express.js REST API
- WebSocket support for real-time chat
- AI processing with Gemini integration
- Database auto-migration system
- Health checks and monitoring
- Docker containerization ready
- Procfile already configured
### ❌ **n8n/Similar Tools Are NOT Needed:**
- Your MCP server **IS** the workflow engine
- Built-in AI processing and business intelligence
- Direct Supabase database integration
- Real-time WebSocket communication
- Adding another layer would create unnecessary complexity
---
## 🚀 **IMMEDIATE DEPLOYMENT STEPS**
### **Step 1: Prepare for Heroku**
```bash
# 1. Install Heroku CLI
# Download from: https://devcenter.heroku.com/articles/heroku-cli
# 2. Login to Heroku
heroku login
# 3. Create Heroku app
heroku create charnoks-mcp-server
# 4. Add buildpacks (Node.js is auto-detected)
heroku buildpacks:set heroku/nodejs -a charnoks-mcp-server
```
### **Step 2: Configure Environment Variables**
```bash
# Required Variables (replace with your actual values)
heroku config:set NODE_ENV=production -a charnoks-mcp-server
heroku config:set PORT=3002 -a charnoks-mcp-server
# Supabase Configuration
heroku config:set SUPABASE_URL="https://your-project.supabase.co" -a charnoks-mcp-server
heroku config:set SUPABASE_SERVICE_ROLE_KEY="your_service_role_key" -a charnoks-mcp-server
# AI Configuration
heroku config:set GEMINI_API_KEY="your_gemini_api_key" -a charnoks-mcp-server
# Security (generate JWT secret)
heroku config:set JWT_SECRET="$(openssl rand -hex 32)" -a charnoks-mcp-server
heroku config:set MCP_AUTH_TOKEN="$(openssl rand -hex 16)" -a charnoks-mcp-server
# Performance
heroku config:set MAX_REQUESTS_PER_MINUTE=200 -a charnoks-mcp-server
# CORS (add your frontend domain)
heroku config:set ALLOWED_ORIGINS="https://charnoksv3.vercel.app,http://localhost:3000" -a charnoks-mcp-server
```
### **Step 3: Deploy**
```bash
# 1. Add Heroku remote
heroku git:remote -a charnoks-mcp-server
# 2. Deploy
git add .
git commit -m "Deploy MCP server to Heroku"
git push heroku main
# 3. Scale dynos (optional - for production load)
heroku ps:scale web=2 -a charnoks-mcp-server
```
### **Step 4: Verify Deployment**
```bash
# Check health
curl https://charnoks-mcp-server.herokuapp.com/health
# View logs
heroku logs --tail -a charnoks-mcp-server
# Check status
heroku ps -a charnoks-mcp-server
```
---
## 🔧 **HEROKU CONFIGURATION**
### **Your Procfile is Already Perfect:**
```
web: npm start
```
### **Package.json Scripts Ready:**
```json
{
"scripts": {
"build": "tsc",
"start": "node dist/index.js",
"dev": "tsx src/index.ts"
}
}
```
### **Automatic Features:**
- ✅ **Auto-scaling**: Heroku handles traffic spikes
- ✅ **Health monitoring**: Built-in health checks
- ✅ **SSL/HTTPS**: Automatic SSL certificates
- ✅ **Logging**: Centralized log management
- ✅ **Database migration**: Runs automatically on startup
- ✅ **Environment management**: Secure config vars
---
## 🌐 **POST-DEPLOYMENT INTEGRATION**
### **Update Your Charnoksv3 Frontend:**
In your main Charnoksv3 repository, update the MCP client:
```typescript
// services/mcp/mcpClient.ts
export class MCPClient {
private baseUrl: string;
constructor() {
this.baseUrl = process.env.NODE_ENV === 'production'
? 'https://charnoks-mcp-server.herokuapp.com'
: 'http://localhost:3002';
}
async processChickenNote(content: string, userRole: string): Promise<any> {
const response = await fetch(`${this.baseUrl}/api/tools/call`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${process.env.MCP_AUTH_TOKEN}`
},
body: JSON.stringify({
name: 'parse_chicken_note',
arguments: { content, userRole }
})
});
return response.json();
}
}
```
### **WebSocket Integration:**
```javascript
// Real-time chat connection
const ws = new WebSocket('wss://charnoks-mcp-server.herokuapp.com/ws/chat');
ws.onopen = () => {
console.log('Connected to MCP server');
};
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('AI Response:', data);
};
```
---
## 🎯 **PRODUCTION OPTIMIZATIONS**
### **Scale for Production Load:**
```bash
# Scale web dynos
heroku ps:scale web=3 -a charnoks-mcp-server
# Add Redis for caching (if needed)
heroku addons:create heroku-redis:hobby-dev -a charnoks-mcp-server
```
### **Monitoring Setup:**
```bash
# Add logging
heroku addons:create papertrail -a charnoks-mcp-server
# Add performance monitoring
heroku addons:create newrelic -a charnoks-mcp-server
```
### **Database Optimization:**
Your server already includes:
- ✅ Connection pooling
- ✅ Auto-migration on startup
- ✅ Health checks for database connectivity
- ✅ Error handling and retry logic
---
## 📊 **COST COMPARISON**
### **Heroku (Recommended):**
- **Hobby Dyno**: $7/month - Perfect for development/testing
- **Standard Dyno**: $25/month - Production ready with auto-scaling
- **Performance Dyno**: $250/month - High performance for heavy loads
### **Alternative Platforms:**
- **Railway**: Similar to Heroku, $5-20/month
- **Render**: $7-25/month
- **DigitalOcean App Platform**: $5-25/month
### **Why NOT n8n/Similar:**
- Additional $20-50/month cost
- Unnecessary complexity
- Your MCP server already handles workflows
- Performance overhead
- More maintenance required
---
## 🚨 **URGENT NEXT STEPS**
1. **Deploy Immediately**: Your server is production-ready
2. **Test Integration**: Verify your Charnoksv3 app connects properly
3. **Monitor Performance**: Use Heroku metrics
4. **Scale as Needed**: Add more dynos for production load
## 🎉 **Your Architecture Will Be:**
```
Charnoksv3 (Vercel) ←→ MCP Server (Heroku) ←→ Supabase Database
↓ ↓ ↓
UI/Client Logic AI Processing Data Storage
Offline Features Business Logic Real-time Data
User Interface WebSocket Chat Authentication
```
This is a **clean, professional, scalable architecture** that separates concerns properly and leverages each platform's strengths.
**Ready to deploy?** The server is already configured for Heroku - just follow the steps above!