ezezzjzsh/universal-mcp-stable

MCP Runner - Universal MCP Server Orchestrator

The stable, production-ready orchestrator for Model Context Protocol (MCP) servers
Transform any MCP server into a unified SSE gateway with proven reliability across TypeScript, Python, and other implementations.

🚀 Overview

MCP Runner (formerly MCP Gateway Orchestrator) is a minimalist, stateless orchestrator that transforms any MCP server into a production-grade SSE (Server-Sent Events) gateway. Built on John Carmack's engineering principles: every line justified, complexity eliminated, robustness through radical simplicity.

🏆 Key Features

• ✅ Universal Protocol Support - STDIO, SSE, StreamableHTTP → Unified SSE output
• ⚡ Reactive Auto-Healing - Automatic detection and fixing of common deployment issues
• 🛡️ Production Hardened - Node.js 22, Alpine Linux, enterprise-grade supervision
• 🎭 Stateless Architecture - Pure functions, immutable environment, zero configuration drift
• 📊 Battle-Tested - Proven with DataForSEO (52 tools), language servers, and complex integrations

https://img.shields.io/badge/Docker-ezezzjzsh%2Funiversal--mcp--stable-blue?logo=docker](https://hub.docker.com/r/ezezzjzsh/universal-mcp-stable) https://img.shields.io/badge/Node.js-22%20LTS-green?logo=node.js]([***] https://img.shields.io/badge/License-MIT-yellow.svg](https://opensource.org/licenses/MIT)

---

🎯 Quick Start

Using Docker Hub Image (Recommended)

bash
# Deploy DataForSEO MCP Server (52 SEO/SERP tools)
docker run -d -p 8765:8765 \
  -e REPO_URL="https://github.com/dataforseo/mcp-server-typescript" \
  -e PREFLIGHT_COMMANDS="npm install && npm run build" \
  -e MCP_GATEWAY_CONFIG='{"input":{"type":"repo","protocol":"stdio","runCommand":"npx dataforseo-mcp-server"},"output":{"protocol":"sse","port":8765}}' \
  ezezzjzsh/universal-mcp-stable:latest

# Verify deployment
curl http://localhost:8765/sse

Build From Source

bash
# Clone and build
git clone https://github.com/thinkbuddyai/mcp-runner.git
cd mcp-runner
docker build -t mcp-runner:local .

# Run with local image
docker run -d -p 8765:8765 \
  -e REPO_URL="https://github.com/alexwohletz/language-server-mcp" \
  -e PREFLIGHT_COMMANDS="npm install" \
  -e MCP_GATEWAY_CONFIG='{"input":{"type":"repo","protocol":"stdio","runCommand":"npx @languages/language-server-mcp"},"output":{"protocol":"sse","port":8765}}' \
  mcp-runner:local

---

🏗️ Architecture

Universal Pattern: Any Input → SSE Output

mermaid
graph LR
    A[MCP Server] -->|STDIO/SSE/HTTP| B[MCP Runner]
    B --> C[SSE Port 8765]
    
    subgraph "Input Sources"
        D[Git Repository]
        E[Remote URL] 
        F[Local Command]
    end
    
    subgraph "Core Components"
        G[index.ts - Orchestrator]
        H[entrypoint.sh - Supervisor]
        I[known-fixes.ts - Auto-healing]
        J[types.ts - Validation]
    end
    
    D --> A
    E --> A
    F --> A
    
    B -.-> G
    B -.-> H
    B -.-> I
    B -.-> J

Three-Phase Execution

1. 🏗️ Build Phase - Clone repository (if needed), run preflight commands, resolve dependencies
2. 🚀 Runtime Phase - Start background servers (for network protocols), configure environment
3. 🎯 Gateway Phase - Launch supergateway with protocol bridging to SSE

---

🛠️ Configuration

Environment Variables

Configuration Schema

typescript
interface Config {
  input: {
    type: "repo" | "url"
    protocol: "stdio" | "sse" | "streamableHttp"
    runCommand?: string  // For repo inputs
    target?: string      // For URL inputs
    port?: number        // For network protocols
    options?: {          // For URL inputs
      headers?: Record<string, string>
      oauth2Bearer?: string
    }
  }
  output: {
    protocol: "sse"  // Always SSE
    port: number     // Default: 8765
    options?: {
      cors?: boolean | string | string[]
      healthEndpoint?: string | string[]
      baseUrl?: string
      ssePath?: string
      messagePath?: string
    }
  }
}

---

📚 Deployment Patterns

Pattern 1: Repository STDIO (Most Common)

Perfect for CLI-based MCP servers that communicate via standard input/output.

bash
docker run -d -p 8765:8765 \
  -e REPO_URL="https://github.com/username/mcp-server" \
  -e PREFLIGHT_COMMANDS="npm install && npm run build" \
  -e MCP_GATEWAY_CONFIG='{
    "input": {
      "type": "repo",
      "protocol": "stdio",
      "runCommand": "npm start"
    },
    "output": {
      "protocol": "sse",
      "port": 8765
    }
  }' \
  ezezzjzsh/universal-mcp-stable:latest

Pattern 2: Repository Network Server

For MCP servers that run as HTTP/SSE servers themselves.

bash
docker run -d -p 8765:8765 \
  -e REPO_URL="https://github.com/username/sse-server" \
  -e PREFLIGHT_COMMANDS="npm install" \
  -e MCP_GATEWAY_CONFIG='{
    "input": {
      "type": "repo",
      "protocol": "sse",
      "runCommand": "npm start",
      "port": 3001
    },
    "output": {
      "protocol": "sse",
      "port": 8765
    }
  }' \
  ezezzjzsh/universal-mcp-stable:latest

Pattern 3: Remote URL Proxy

Connect to external MCP services.

bash
docker run -d -p 8765:8765 \
  -e MCP_GATEWAY_CONFIG='{
    "input": {
      "type": "url",
      "protocol": "sse",
      "target": "https://api.example.com/mcp",
      "options": {
        "oauth2Bearer": "token",
        "headers": {
          "X-API-Key": "key"
        }
      }
    },
    "output": {
      "protocol": "sse",
      "port": 8765,
      "options": {
        "cors": true,
        "healthEndpoint": ["/health", "/status"]
      }
    }
  }' \
  ezezzjzsh/universal-mcp-stable:latest

---

🔧 Reactive Auto-Healing

MCP Runner includes intelligent auto-healing that detects and fixes common deployment issues automatically:

Auto-Fixed Issues

Manual Interventions Required

Some issues require manual configuration:

• Authentication: API keys, tokens, credentials
• Binary incompatibility: Use bookworm image instead of alpine for glibc requirements
• Repository not found: Use alternative repositories

---

🏭 Production Deployment

Railway Deployment

Deploy to Railway with automatic scaling and monitoring:

yaml
# railway.toml
[build]
builder = "dockerfile"
dockerfilePath = "Dockerfile"

[deploy]
startCommand = "/entrypoint.sh"
healthcheckPath = "/health"
healthcheckTimeout = 10
restartPolicyType = "on-failure"
restartPolicyMaxRetries = 3

[[services]]
name = "mcp-runner"
port = 8765

Docker Compose

yaml
version: '3.8'
services:
  mcp-runner:
    image: ezezzjzsh/universal-mcp-stable:latest
    ports:
      - "8765:8765"
    environment:
      - MCP_GATEWAY_CONFIG=${MCP_CONFIG}
      - REPO_URL=${REPO_URL}
      - PREFLIGHT_COMMANDS=${PREFLIGHT}
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8765/sse"]
      interval: 30s
      timeout: 10s
      retries: 3
    resources:
      limits:
        memory: 1GB
        cpus: '0.5'

Kubernetes

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-runner
spec:
  replicas: 3
  selector:
    matchLabels:
      app: mcp-runner
  template:
    spec:
      containers:
      - name: mcp-runner
        image: ezezzjzsh/universal-mcp-stable:latest
        ports:
        - containerPort: 8765
        env:
        - name: MCP_GATEWAY_CONFIG
          valueFrom:
            configMapKeyRef:
              name: mcp-config
              key: config.json
        resources:
          requests:
            memory: "512Mi"
            cpu: "250m"
          limits:
            memory: "1Gi"
            cpu: "500m"

---

🧪 Local Development

Prerequisites

• Docker 20.10+
• Node.js 22+ (for local testing)
• Git

Development Setup

bash
# Clone repository
git clone https://github.com/thinkbuddyai/mcp-runner.git
cd mcp-runner

# Install dependencies
npm install

# Run tests
npm test
npm run typecheck

# Build TypeScript
npm run build

# Test locally
MCP_GATEWAY_CONFIG='{"input":{"type":"repo","protocol":"stdio","runCommand":"echo test"},"output":{"protocol":"sse","port":8765}}' \
  node dist/index.js

Helper Script

Use the deployment helper for quick testing:

bash
# Create deployment config
cat > test-config.json << 'EOF'
{
  "name": "test-mcp",
  "port": 8765,
  "repo": {
    "url": "https://github.com/dataforseo/mcp-server-typescript",
    "preflight": "npm install && npm run build"
  },
  "config": {
    "input": {
      "type": "repo",
      "protocol": "stdio",
      "runCommand": "npx dataforseo-mcp-server"
    },
    "output": {
      "protocol": "sse",
      "port": 8765
    }
  }
}
EOF

# Deploy
./deploy.sh test-config.json

---

🚨 Troubleshooting

Container Won't Start

bash
# Check logs
docker logs <container-name>

# Verify configuration
echo $MCP_GATEWAY_CONFIG | jq .

# Test configuration locally
node dist/index.js

Port Already in Use

bash
# Find process using port
lsof -i :8765
netstat -tulpn | grep 8765

# Kill process
kill -9 <PID>

Authentication Errors

bash
# For Azure DevOps
-e AZURE_DEVOPS_ORG_URL="https://dev.azure.com/org" \
-e AZURE_DEVOPS_PAT="your_token"

# For DataForSEO
-e DATAFORSEO_LOGIN="your_login" \
-e DATAFORSEO_PASSWORD="your_password"

# For API services
-e API_KEY="your_key" \
-e API_SECRET="your_secret"

Build Failures

bash
# Increase timeout
-e PREFLIGHT_COMMANDS="npm install --timeout=600000"

# Use legacy peer deps
-e PREFLIGHT_COMMANDS="npm install --legacy-peer-deps"

# Skip optional dependencies
-e PREFLIGHT_COMMANDS="npm install --no-optional"

---

📈 Performance

Resource Usage

• Docker Image: ~150MB (Alpine Linux + Node.js 22)
• Memory: ~50MB baseline + server requirements
• CPU: Minimal (process supervision only)
• Startup Time: <2s for STDIO, <20s for network protocols

Benchmarks

bash
# Load testing
ab -n 1000 -c 10 http://localhost:8765/sse

# Memory monitoring
docker stats <container-name>

# Response time
time curl -s http://localhost:8765/sse | head -1

---

📚 Tested MCP Servers

Production Ready

Authentication Required

---

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing)
3. Make your changes
4. Run tests (npm test)
5. Commit (git commit -m 'Add amazing feature')
6. Push (git push origin feature/amazing)
7. Open a Pull Request

Code Style

• TypeScript with strict mode
• ESLint for linting
• Prettier for formatting
• Conventional commits

---

📖 Documentation

• CLAUDE.md - Technical deep-dive and architecture details
• API Documentation - Configuration and API reference
• Deployment Guide - Production deployment patterns
• Security Guide - Security best practices

---

🙏 Acknowledgments

• https://modelcontextprotocol.io team for the MCP specification
• Supermachine AI for the supergateway tool
• The MCP community for testing and feedback

---

📄 License

MIT License - see LICENSE for details.

---