admin/homelab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial homelab GitOps repository setup

Browse Source 
This commit establishes the foundation for the homelab GitOps repository:

- Created layered architecture (infrastructure/platform/apps)
- Added MCP servers umbrella chart with SOPS-encrypted secrets
- Configured Flux Kustomizations for infrastructure and platform layers
- Set up SOPS + Age for secrets management
- Added .gitignore and documentation

MCP servers include:
- Gateway with auth (API keys in encrypted secrets)
- n8n MCP (workflow automation)
- Playwright MCP (browser automation)
- Kubernetes MCP (kubectl operations)
- GitHub MCP (repository management)
- Gitea MCP (self-hosted git)
- SQLite MCP (database operations)
- Filesystem MCP (file operations)
- Fetch MCP (HTTP requests)
- Memory MCP (shared memory/state)

All secrets are encrypted with SOPS using Age encryption.
This commit is contained in:
CaffeineTux
2025-11-16 02:28:44 -05:00
commit 9fc30a3573
15 changed files with 1448 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

394
platform/mcp-servers/README.md Normal file
View File

@@ -0,0 +1,394 @@
# MCP Umbrella Helm Chart
Complete deployment solution for the MCP (Model Context Protocol) server ecosystem. This umbrella chart deploys all MCP servers with a central gateway for unified access.
## Architecture
```
┌─────────────────────────────────────────────────────────────────┐
│ MCP Gateway │
│ (LoadBalancer Service) │
│ http://<LoadBalancer-IP>:3000 │
│ │
│ Routes requests to individual MCP servers: │
│ POST /mcp/n8n-mcp → n8n-mcp:3001 │
│ POST /mcp/playwright-mcp → playwright-mcp:3002 │
│ POST /mcp/kubernetes-mcp → kubernetes-mcp:3003 │
│ POST /mcp/github-mcp → github-mcp:3004 │
│ ... (all 13 MCP servers) │
└─────────────────────────────────────────────────────────────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ n8n-MCP │ │Playwright│ │Kubernetes│ │ GitHub │
│ :3001 │ │ MCP │ │ MCP │ │ MCP │
│ │ │ :3002 │ │ :3003 │ │ :3004 │
└──────────┘ └──────────┘ └──────────┘ └──────────┘
... (9 more servers)
┌──────────────────────────────────────────────────────┐
│ Memory MCP (Central State) │
│ :3013 → Redis/PostgreSQL │
│ Provides shared state for all MCP servers │
└──────────────────────────────────────────────────────┘
```
## Features
- **13 MCP Servers** available for automation
- **Central Gateway** with API key authentication
- **LoadBalancer** access to entire MCP ecosystem
- **Memory-MCP** as central coordinator for shared state
- **Selective Deployment** - enable only the servers you need
- **Production-Ready** with RBAC, security contexts, and health checks
- **Auto-Scaling** for gateway and resource-intensive servers
## Quick Start
### 1. Prerequisites
```bash
# Ensure you're in the right directory
cd /data/data/com.termux/files/home/git/mcp-servers/mcp-umbrella
# Build chart dependencies
helm dependency build
```
### 2. Generate API Keys
```bash
# Generate secure API keys for the gateway
echo "n8n API key: $(openssl rand -hex 32)"
echo "admin API key: $(openssl rand -hex 32)"
```
### 3. Configure Required Secrets
Create a `custom-values.yaml` file:
```yaml
mcp-gateway:
gateway:
auth:
apiKeys:
- name: "n8n"
key: "YOUR_N8N_API_KEY_HERE"
- name: "admin"
key: "YOUR_ADMIN_API_KEY_HERE"
n8n-mcp:
n8nMCP:
n8n:
apiKey: "YOUR_N8N_INSTANCE_API_KEY"
github-mcp:
github:
token: "YOUR_GITHUB_TOKEN"
owner: "your-github-username"
```
### 4. Deploy
```bash
# Create the mcp namespace
kubectl create namespace mcp
# Install the umbrella chart
helm install mcp-ecosystem . \
--namespace mcp \
-f custom-values.yaml
```
### 5. Verify Deployment
```bash
# Check all pods
kubectl get pods -n mcp
# Get gateway LoadBalancer IP
kubectl get svc -n mcp mcp-ecosystem-mcp-gateway
# Test health endpoint
GATEWAY_IP=$(kubectl get svc -n mcp mcp-ecosystem-mcp-gateway -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
curl http://$GATEWAY_IP:3000/health
```
## MCP Servers Included
| Server | Port | Status | Description |
|--------|------|--------|-------------|
| **mcp-gateway** | 3000 | Always Enabled | Central routing gateway |
| **n8n-mcp** | 3001 | Enabled | n8n workflow automation |
| **playwright-mcp** | 3002 | Enabled | Browser automation |
| **kubernetes-mcp** | 3003 | Enabled | Kubectl operations |
| **github-mcp** | 3004 | Enabled | GitHub API operations |
| **postgresql-mcp** | 3005 | Disabled* | PostgreSQL operations |
| **sqlite-mcp** | 3006 | Enabled | SQLite operations |
| **prometheus-mcp** | 3007 | Disabled* | Metrics queries |
| **slack-mcp** | 3008 | Disabled* | Slack operations |
| **s3-mcp** | 3009 | Disabled* | S3/MinIO operations |
| **filesystem-mcp** | 3010 | Enabled | File operations |
| **puppeteer-mcp** | 3011 | Disabled* | Chrome automation |
| **fetch-mcp** | 3012 | Enabled | HTTP requests |
| **memory-mcp** | 3013 | Enabled | Central state coordinator |
*\*Requires additional configuration - see [Configuration](#configuration) section*
## Configuration
### Enabling/Disabling Servers
In your `custom-values.yaml`:
```yaml
# Enable a disabled server
prometheus-mcp:
enabled: true
prometheus:
url: "http://your-prometheus-server"
# Disable an enabled server
playwright-mcp:
enabled: false
```
### Configuring the Gateway
```yaml
mcp-gateway:
service:
type: LoadBalancer
loadBalancerIP: "192.168.1.100" # Optional static IP
ingress:
enabled: true # Enable Ingress (currently disabled)
hosts:
- host: mcp.caffeinetux.com
paths:
- path: /
pathType: Prefix
autoscaling:
enabled: true
minReplicas: 1
maxReplicas: 5
```
### Configuring Memory-MCP Backend
Choose Redis or PostgreSQL:
```yaml
memory-mcp:
storage:
backend: "redis" # or "postgres"
redis:
host: "redis.default.svc.cluster.local"
port: 6379
password: "your-redis-password"
```
## Usage Examples
### From n8n Workflow
Use the HTTP Request node:
```javascript
// n8n HTTP Request Node
Method: POST
URL: http://mcp-ecosystem-mcp-gateway.mcp.svc.cluster.local:3000/mcp/playwright-mcp
Authentication: Header Auth
Header Name: Authorization
Header Value: Bearer YOUR_N8N_API_KEY
Body:
{
"jsonrpc": "2.0",
"method": "navigate",
"params": {
"url": "https://example.com"
},
"id": 1
}
```
### From External Client
```bash
# Get list of available servers
curl -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
http://<LoadBalancer-IP>:3000/servers
# Make MCP request to Kubernetes-MCP
curl -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "get_pods",
"params": {"namespace": "default"},
"id": 1
}' \
http://<LoadBalancer-IP>:3000/mcp/kubernetes-mcp
```
### Store Shared State in Memory-MCP
```bash
# Store a value
curl -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "memory_store",
"params": {
"namespace": "workflow",
"key": "user_session",
"value": {"user_id": 123, "state": "active"},
"ttl": 3600
},
"id": 1
}' \
http://<LoadBalancer-IP>:3000/mcp/memory-mcp
# Retrieve the value
curl -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "memory_retrieve",
"params": {
"namespace": "workflow",
"key": "user_session"
},
"id": 2
}' \
http://<LoadBalancer-IP>:3000/mcp/memory-mcp
```
## Upgrading
```bash
# Update dependencies
helm dependency update
# Upgrade the deployment
helm upgrade mcp-ecosystem . \
--namespace mcp \
-f custom-values.yaml
```
## Uninstalling
```bash
# Remove the deployment
helm uninstall mcp-ecosystem --namespace mcp
# Optionally delete the namespace
kubectl delete namespace mcp
```
## Troubleshooting
### Gateway not accessible
```bash
# Check gateway pod logs
kubectl logs -n mcp -l app.kubernetes.io/name=mcp-gateway
# Check service
kubectl describe svc -n mcp mcp-ecosystem-mcp-gateway
```
### MCP server not responding
```bash
# Check specific server logs
kubectl logs -n mcp -l app.kubernetes.io/name=playwright-mcp
# Check if server is registered in gateway
curl -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
http://<LoadBalancer-IP>:3000/servers
```
### Authentication errors
```bash
# Verify API keys are set
kubectl get secret -n mcp mcp-ecosystem-mcp-gateway-auth -o yaml
# Test without auth (should fail with 401)
curl http://<LoadBalancer-IP>:3000/servers
```
## Resource Requirements
### Minimal Setup (5 servers)
- **CPU**: ~2 cores total
- **Memory**: ~3Gi total
- **Storage**: ~15Gi (PVCs for SQLite, Filesystem, Playwright)
### Full Setup (all 13 servers)
- **CPU**: ~6 cores total
- **Memory**: ~10Gi total
- **Storage**: ~50Gi (with all persistence enabled)
### Per-Server Resources
| Server | CPU Request | CPU Limit | RAM Request | RAM Limit |
|--------|-------------|-----------|-------------|-----------|
| Gateway | 100m | 500m | 128Mi | 512Mi |
| n8n-MCP | 50m | 200m | 128Mi | 256Mi |
| Playwright | 200m | 1000m | 512Mi | 2Gi |
| Kubernetes | 100m | 100m | 128Mi | 128Mi |
| Memory-MCP | 100m | 200m | 256Mi | 512Mi |
| Others | 50-100m | 100-200m | 64-128Mi | 128-256Mi |
## Security
- **API Key Authentication** on gateway
- **RBAC** for Kubernetes-MCP cluster access
- **Secrets** for all credentials (GitHub tokens, database passwords, etc.)
- **Non-root users** in all containers
- **Read-only root filesystem** where possible
- **Network policies** (add custom NetworkPolicy resources as needed)
## Advanced Configuration
### Custom n8n Node
See [n8n-mcp-node/README.md](../n8n-mcp-node/README.md) for installing a custom n8n node that simplifies MCP gateway access.
### Monitoring
```yaml
# Enable Prometheus monitoring
prometheus-mcp:
enabled: true
prometheus:
url: "http://prometheus-server.prometheus.svc.cluster.local"
```
### High Availability
```yaml
mcp-gateway:
replicaCount: 3
autoscaling:
enabled: true
minReplicas: 3
maxReplicas: 10
```
## Support
For issues or questions:
- Check the individual MCP server READMEs in `../*/README.md`
- Review logs: `kubectl logs -n mcp <pod-name>`
- GitHub Issues: https://github.com/modelcontextprotocol/servers
## License
See individual MCP server repositories for their respective licenses.