homelab/platform/mcp-servers/README.md

# 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.