docs: add comprehensive HTTP remote deployment planning documentation
- HTTP_REMOTE_DEPLOYMENT_PLAN.md: High-level architecture and implementation plan - HTTP_IMPLEMENTATION_GUIDE.md: Detailed technical implementation with code examples - HTTP_IMPLEMENTATION_ROADMAP.md: Day-by-day implementation checklist and milestones - HTTP_REMOTE_SUMMARY.md: Executive summary with key findings and recommendations - Updated README.md with references to future HTTP deployment plans Key findings: - Claude Desktop currently only supports stdio transport (local execution) - mcp-remote adapter enables remote server connectivity as a bridge solution - Implementation requires adding StreamableHTTPServerTransport support - Dual-mode operation will maintain backward compatibility 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
czlonkowski
371
HTTP_IMPLEMENTATION_ROADMAP.md
Normal file
371
HTTP_IMPLEMENTATION_ROADMAP.md
Normal file
@@ -0,0 +1,371 @@
|
||||
# HTTP Implementation Roadmap
|
||||
|
||||
## Quick Reference Architecture
|
||||
|
||||
```
|
||||
┌─────────────────┐ ┌──────────────┐ ┌─────────────────┐
|
||||
│ Claude Desktop │ stdio │ mcp-remote │ HTTP │ n8n-MCP HTTP │
|
||||
│ ├────────>│ adapter ├────────>│ Server │
|
||||
└─────────────────┘ └──────────────┘ └─────────────────┘
|
||||
│ │
|
||||
│ Auth Token │
|
||||
└──────────────────────────┘
|
||||
```
|
||||
|
||||
## Implementation Checklist
|
||||
|
||||
### Prerequisites
|
||||
- [ ] Understand StreamableHTTPServerTransport API
|
||||
- [ ] Review mcp-remote documentation
|
||||
- [ ] Set up test environment with Express.js
|
||||
- [ ] Plan session management strategy
|
||||
|
||||
### Phase 1: Core HTTP Server (Days 1-3)
|
||||
|
||||
#### Day 1: Basic HTTP Server
|
||||
- [ ] Install dependencies: `express`, `cors`, `helmet`, `compression`
|
||||
- [ ] Create `src/mcp/transports/http-transport.ts`
|
||||
- [ ] Implement basic Express server structure
|
||||
- [ ] Add health check endpoint `/health`
|
||||
- [ ] Add MCP endpoint `/mcp` (placeholder)
|
||||
|
||||
#### Day 2: MCP Integration
|
||||
- [ ] Import StreamableHTTPServerTransport
|
||||
- [ ] Implement session management (in-memory)
|
||||
- [ ] Connect transport to MCP server
|
||||
- [ ] Handle JSON-RPC requests
|
||||
- [ ] Test with simple curl commands
|
||||
|
||||
#### Day 3: Authentication & Security
|
||||
- [ ] Implement Bearer token authentication
|
||||
- [ ] Add rate limiting
|
||||
- [ ] Configure CORS properly
|
||||
- [ ] Add request logging
|
||||
- [ ] Basic error handling
|
||||
|
||||
### Phase 2: Server Modifications (Days 4-6)
|
||||
|
||||
#### Day 4: Refactor Server Class
|
||||
- [ ] Modify `N8NDocumentationMCPServer` to accept any transport
|
||||
- [ ] Add `connect(transport)` method
|
||||
- [ ] Update `run()` method for backward compatibility
|
||||
- [ ] Test stdio mode still works
|
||||
|
||||
#### Day 5: Configuration System
|
||||
- [ ] Create configuration interface
|
||||
- [ ] Add environment variable support
|
||||
- [ ] Implement CLI argument parsing
|
||||
- [ ] Create `.env.example` file
|
||||
- [ ] Document all configuration options
|
||||
|
||||
#### Day 6: Unified Entry Point
|
||||
- [ ] Create `index-universal.ts`
|
||||
- [ ] Implement mode detection (stdio vs http)
|
||||
- [ ] Handle graceful shutdown
|
||||
- [ ] Test both modes work correctly
|
||||
|
||||
### Phase 3: Production Readiness (Days 7-9)
|
||||
|
||||
#### Day 7: Docker & Deployment
|
||||
- [ ] Create `Dockerfile.http`
|
||||
- [ ] Add health checks to Docker
|
||||
- [ ] Create `docker-compose.yml`
|
||||
- [ ] Write deployment script
|
||||
- [ ] Test container locally
|
||||
|
||||
#### Day 8: Monitoring & Logging
|
||||
- [ ] Enhance logging with correlation IDs
|
||||
- [ ] Add metrics collection
|
||||
- [ ] Implement `/metrics` endpoint
|
||||
- [ ] Add session analytics
|
||||
- [ ] Create monitoring dashboard
|
||||
|
||||
#### Day 9: Documentation
|
||||
- [ ] Write user setup guide
|
||||
- [ ] Create troubleshooting guide
|
||||
- [ ] Document API endpoints
|
||||
- [ ] Add architecture diagrams
|
||||
- [ ] Create video tutorial
|
||||
|
||||
### Phase 4: Testing & Launch (Days 10-14)
|
||||
|
||||
#### Day 10: Testing Suite
|
||||
- [ ] Unit tests for HTTP transport
|
||||
- [ ] Integration tests for full flow
|
||||
- [ ] Load testing with Apache Bench
|
||||
- [ ] Security testing (auth, injection)
|
||||
- [ ] Cross-platform client testing
|
||||
|
||||
#### Day 11: Beta Deployment
|
||||
- [ ] Deploy to test server
|
||||
- [ ] Configure nginx + SSL
|
||||
- [ ] Test with mcp-remote
|
||||
- [ ] Monitor performance
|
||||
- [ ] Gather initial feedback
|
||||
|
||||
#### Day 12: Performance Optimization
|
||||
- [ ] Implement response caching
|
||||
- [ ] Optimize database queries
|
||||
- [ ] Add connection pooling
|
||||
- [ ] Profile memory usage
|
||||
- [ ] Fine-tune nginx config
|
||||
|
||||
#### Day 13: Security Hardening
|
||||
- [ ] Security audit
|
||||
- [ ] Implement CSP headers
|
||||
- [ ] Add request validation
|
||||
- [ ] Set up fail2ban
|
||||
- [ ] Configure firewall rules
|
||||
|
||||
#### Day 14: Production Launch
|
||||
- [ ] Final deployment
|
||||
- [ ] Update documentation
|
||||
- [ ] Announce to community
|
||||
- [ ] Monitor closely
|
||||
- [ ] Respond to feedback
|
||||
|
||||
## Code Templates
|
||||
|
||||
### 1. Minimal Express Server Test
|
||||
```typescript
|
||||
// test-server.ts - Quick test to verify concept
|
||||
import express from 'express';
|
||||
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
|
||||
|
||||
const app = express();
|
||||
app.use(express.json());
|
||||
|
||||
const transport = new StreamableHTTPServerTransport();
|
||||
|
||||
app.post('/mcp', async (req, res) => {
|
||||
await transport.handleRequest(req, res);
|
||||
});
|
||||
|
||||
app.listen(3000, () => {
|
||||
console.log('Test server running on http://localhost:3000');
|
||||
});
|
||||
```
|
||||
|
||||
### 2. Environment Variables
|
||||
```bash
|
||||
# .env
|
||||
MCP_MODE=http
|
||||
MCP_PORT=3000
|
||||
MCP_HOST=0.0.0.0
|
||||
MCP_AUTH_TOKEN=development-token-change-in-production
|
||||
MCP_SESSION_TIMEOUT=1800000
|
||||
MCP_MAX_SESSIONS=50
|
||||
MCP_CORS_ORIGINS=http://localhost:3000,https://claude.ai
|
||||
NODE_ENV=development
|
||||
LOG_LEVEL=debug
|
||||
```
|
||||
|
||||
### 3. Test Script
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# test-http.sh - Test HTTP endpoint
|
||||
|
||||
TOKEN="development-token-change-in-production"
|
||||
URL="http://localhost:3000/mcp"
|
||||
|
||||
# Test health check
|
||||
curl -s http://localhost:3000/health | jq .
|
||||
|
||||
# Test MCP endpoint
|
||||
curl -s -X POST $URL \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-d '{
|
||||
"jsonrpc": "2.0",
|
||||
"method": "tools/list",
|
||||
"id": 1
|
||||
}' | jq .
|
||||
```
|
||||
|
||||
### 4. nginx Configuration
|
||||
```nginx
|
||||
# /etc/nginx/sites-available/n8n-mcp
|
||||
server {
|
||||
listen 80;
|
||||
server_name mcp.yourdomain.com;
|
||||
return 301 https://$server_name$request_uri;
|
||||
}
|
||||
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
server_name mcp.yourdomain.com;
|
||||
|
||||
ssl_certificate /etc/letsencrypt/live/mcp.yourdomain.com/fullchain.pem;
|
||||
ssl_certificate_key /etc/letsencrypt/live/mcp.yourdomain.com/privkey.pem;
|
||||
|
||||
# Security headers
|
||||
add_header X-Frame-Options "SAMEORIGIN" always;
|
||||
add_header X-Content-Type-Options "nosniff" always;
|
||||
add_header X-XSS-Protection "1; mode=block" always;
|
||||
|
||||
location / {
|
||||
proxy_pass http://localhost:3000;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection 'upgrade';
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_cache_bypass $http_upgrade;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Claude Desktop Config
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"n8n-docs-remote": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"mcp-remote@latest",
|
||||
"connect",
|
||||
"https://mcp.yourdomain.com/mcp"
|
||||
],
|
||||
"env": {
|
||||
"MCP_AUTH_TOKEN": "your-secure-token"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Testing Scenarios
|
||||
|
||||
### Scenario 1: Basic Connectivity
|
||||
1. Start HTTP server locally
|
||||
2. Use curl to test endpoints
|
||||
3. Verify authentication works
|
||||
4. Check session creation
|
||||
|
||||
### Scenario 2: mcp-remote Integration
|
||||
1. Install mcp-remote globally
|
||||
2. Configure with local server
|
||||
3. Test all MCP tools work
|
||||
4. Verify session persistence
|
||||
|
||||
### Scenario 3: Load Testing
|
||||
```bash
|
||||
# Test 100 concurrent users
|
||||
ab -n 1000 -c 100 \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-p request.json \
|
||||
http://localhost:3000/mcp
|
||||
```
|
||||
|
||||
### Scenario 4: Security Testing
|
||||
1. Test without auth token (should fail)
|
||||
2. Test with invalid token (should fail)
|
||||
3. Test SQL injection attempts
|
||||
4. Test large payload handling
|
||||
5. Test rate limiting
|
||||
|
||||
## Deployment Commands
|
||||
|
||||
### Local Development
|
||||
```bash
|
||||
# Start in development mode
|
||||
npm run dev:http
|
||||
|
||||
# Watch logs
|
||||
tail -f logs/mcp-http.log
|
||||
```
|
||||
|
||||
### Production Deployment
|
||||
```bash
|
||||
# Build and deploy
|
||||
npm run build
|
||||
docker build -f Dockerfile.http -t n8n-mcp-http .
|
||||
docker run -d --name n8n-mcp-http \
|
||||
-p 3000:3000 \
|
||||
--env-file .env.production \
|
||||
--restart unless-stopped \
|
||||
n8n-mcp-http
|
||||
|
||||
# Check status
|
||||
docker logs n8n-mcp-http
|
||||
curl https://mcp.yourdomain.com/health
|
||||
```
|
||||
|
||||
## Monitoring Checklist
|
||||
|
||||
### Application Metrics
|
||||
- [ ] Request rate
|
||||
- [ ] Response times
|
||||
- [ ] Error rates
|
||||
- [ ] Active sessions
|
||||
- [ ] Memory usage
|
||||
- [ ] CPU usage
|
||||
|
||||
### Business Metrics
|
||||
- [ ] Unique users
|
||||
- [ ] Most used tools
|
||||
- [ ] Peak usage times
|
||||
- [ ] Geographic distribution
|
||||
|
||||
### Alerts to Configure
|
||||
- [ ] Server down
|
||||
- [ ] High error rate (> 5%)
|
||||
- [ ] Slow response times (> 1s)
|
||||
- [ ] Memory usage > 80%
|
||||
- [ ] Disk space < 20%
|
||||
- [ ] SSL certificate expiring
|
||||
|
||||
## Rollback Plan
|
||||
|
||||
If issues arise:
|
||||
|
||||
1. **Immediate**: Switch DNS back to maintenance page
|
||||
2. **Quick Fix**: Rollback Docker container to previous version
|
||||
3. **Investigate**: Check logs and metrics
|
||||
4. **Fix Forward**: Deploy hotfix if simple
|
||||
5. **Full Rollback**: Restore previous version if complex
|
||||
|
||||
## Success Criteria
|
||||
|
||||
### Week 1
|
||||
- [ ] HTTP server running locally
|
||||
- [ ] All MCP tools working via HTTP
|
||||
- [ ] Basic authentication working
|
||||
- [ ] Session management functional
|
||||
|
||||
### Week 2
|
||||
- [ ] Deployed to test environment
|
||||
- [ ] SSL/HTTPS working
|
||||
- [ ] mcp-remote integration tested
|
||||
- [ ] Documentation complete
|
||||
|
||||
### Week 3
|
||||
- [ ] Beta users testing
|
||||
- [ ] Performance acceptable
|
||||
- [ ] No security issues found
|
||||
- [ ] Monitoring in place
|
||||
|
||||
### Week 4
|
||||
- [ ] Production deployment
|
||||
- [ ] Public announcement
|
||||
- [ ] User adoption beginning
|
||||
- [ ] Positive feedback
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
After successful launch, consider:
|
||||
|
||||
1. **WebSocket Support** - Real-time bidirectional communication
|
||||
2. **OAuth2/SSO** - Enterprise authentication
|
||||
3. **Multi-tenancy** - Separate instances per organization
|
||||
4. **Usage Analytics** - Detailed usage tracking
|
||||
5. **API Keys** - Per-user authentication
|
||||
6. **Webhooks** - Event notifications
|
||||
7. **Clustering** - Horizontal scaling
|
||||
8. **GraphQL API** - Alternative query interface
|
||||
|
||||
This roadmap provides a clear, actionable path to implementing HTTP support in n8n-MCP. Each phase builds on the previous one, ensuring a stable and well-tested deployment.
|
||||
Reference in New Issue
Block a user