npm package: @purplesquirrel/mcp-hub
Description: Unified MCP server hub - runs all MCP servers from a single container
Author: Purple Squirrel Media
Latest version: 1.0.0

# MCP Hub

**All MCP Servers in One Container**

Run 9 MCP servers from a single Docker container with a REST API orchestrator.

---

## Container Size Comparison

| Variant | Base | Runtime | Compressed | Uncompressed |
|---------|------|---------|------------|--------------|
| **Standard** | node:20-slim | Node + pip | ~250 MB | ~675 MB |
| **Optimized** | bun:1.1-slim | Bun + uv | ~150 MB | ~400 MB |
| **Minimal** | bun:1.1-alpine | Bun + uv | **~100 MB** | **~280 MB** |

### Why Bun + uv?

| Tool | vs Traditional | Benefit |
|------|----------------|---------|
| **Bun** | 3x faster than Node | Smaller binary, native TS, faster startup |
| **uv** | 10-100x faster than pip | Rust-based, parallel installs, smaller cache |

---

## Servers Included

| Server | Runtime | Tools | Description |
|--------|---------|-------|-------------|
| `guardrails` | Bun | 15 | AI security layer - input/output filtering |
| `ibmz` | Bun | 13 | IBM Z mainframe - Key Protect HSM + z/OS |
| `watsonx` | Bun | 4 | IBM watsonx.ai - Granite, Llama, Mistral |
| `ibmcloud` | Bun | 80 | IBM Cloud CLI - full service coverage |
| `mega` | Bun | 18 | MEGA cloud storage operations |
| `oracle` | Bun | 21 | Oracle Cloud Infrastructure |
| `volcengine` | Bun | 4 | ByteDance Doubao LLM models |
| `sentinel` | Bun | 20 | Enterprise AI safety platform |
| `davinci` | Python | 30 | DaVinci Resolve video automation |

**Total: 9 servers, 205 MCP tools**

---

## Quick Start

### Build Options

```bash
cd /Volumes/Virtual\ Server/projects

# Standard (Node.js + pip) - most compatible
docker build -t mcp-hub -f mcp-hub/Dockerfile .

# Optimized (Bun + uv) - recommended
docker build -t mcp-hub -f mcp-hub/Dockerfile.optimized .

# Minimal (Alpine + Bun + uv) - smallest
docker build -t mcp-hub:minimal -f mcp-hub/Dockerfile.minimal .
```

### Run

```bash
docker run -d \
  --name mcp-hub \
  -p 3000:3000 \
  -e IBM_CLOUD_API_KEY=xxx \
  -e WATSONX_API_KEY=xxx \
  mcp-hub
```

### Docker Compose

```bash
cd mcp-hub
cp .env.example .env
# Edit .env with your credentials
docker-compose up -d
```

---

## API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/health` | Health check |
| GET | `/servers` | List all servers with status |
| POST | `/servers/:id/start` | Start a specific server |
| POST | `/servers/:id/stop` | Stop a specific server |
| GET | `/servers/:id/logs` | Get server logs |
| POST | `/start-all` | Start all servers |
| POST | `/stop-all` | Stop all servers |

### Example Usage

```bash
# Health check
curl http://localhost:3000/health

# List servers
curl http://localhost:3000/servers | jq

# Start all servers
curl -X POST http://localhost:3000/start-all

# Start specific server
curl -X POST http://localhost:3000/servers/watsonx/start

# Get logs (last 50 lines)
curl "http://localhost:3000/servers/watsonx/logs?limit=50"
```

---

## Environment Variables

### IBM Cloud Services
```bash
IBM_CLOUD_API_KEY=        # Required for ibmz, ibmcloud
KEY_PROTECT_INSTANCE_ID=  # Required for ibmz
WATSONX_API_KEY=          # Required for watsonx
WATSONX_PROJECT_ID=       # Required for watsonx
```

### Oracle Cloud
```bash
# Mount ~/.oci directory as volume
-v ~/.oci:/root/.oci:ro
```

### ByteDance Volcengine
```bash
VOLCENGINE_ACCESS_KEY=
VOLCENGINE_SECRET_KEY=
VOLCENGINE_ENDPOINT_ID=
```

---

## Claude Code Integration

### Option 1: Direct exec (recommended)

Add to `~/.mcp.json`:

```json
{
  "mcpServers": {
    "guardrails": {
      "command": "docker",
      "args": ["exec", "-i", "mcp-hub", "bun", "run", "/app/servers/guardrails/index.js"]
    },
    "watsonx": {
      "command": "docker",
      "args": ["exec", "-i", "mcp-hub", "bun", "run", "/app/servers/watsonx/index.js"]
    },
    "oracle": {
      "command": "docker",
      "args": ["exec", "-i", "mcp-hub", "bun", "run", "/app/servers/oracle/index.js"]
    },
    "davinci": {
      "command": "docker",
      "args": ["exec", "-i", "mcp-hub", "/app/venv/bin/python", "-m", "davinci_resolve_mcp"]
    }
  }
}
```

### Option 2: All servers via orchestrator

```json
{
  "mcpServers": {
    "mcp-hub": {
      "command": "docker",
      "args": ["exec", "-i", "mcp-hub", "bun", "run", "orchestrator.js"],
      "env": {
        "MCP_MODE": "stdio"
      }
    }
  }
}
```

---

## Dockerfiles

| File | Size | Use Case |
|------|------|----------|
| `Dockerfile` | ~675 MB | Maximum compatibility (Node.js) |
| `Dockerfile.optimized` | ~400 MB | Recommended (Bun + uv) |
| `Dockerfile.minimal` | ~280 MB | Smallest (Alpine + Bun + uv) |

---

## Push to Registry

```bash
# GitHub Container Registry
docker tag mcp-hub ghcr.io/purplesquirrelmedia/mcp-hub:latest
docker push ghcr.io/purplesquirrelmedia/mcp-hub:latest

# Docker Hub
docker tag mcp-hub purplesquirrel/mcp-hub:latest
docker push purplesquirrel/mcp-hub:latest
```

---

## Performance

| Metric | Node.js | Bun |
|--------|---------|-----|
| Cold start | ~800ms | ~200ms |
| Install time | ~45s | ~8s |
| Memory/server | ~50 MB | ~30 MB |
| All 9 servers | ~450 MB RAM | ~270 MB RAM |

---

## License

MIT - Purple Squirrel Media