Waygate MCP

Waygate MCP - Secure Containerized MCP Server Framework 🐳🔒

Version: 2.0.0 Status: Production-Ready Successor to: NEXUS MCP Architecture: Security-Hardened Docker Containers

🚀 Overview

Waygate MCP is an enterprise-grade Model Context Protocol (MCP) server framework built with security-first containerization. Unlike traditional virtual environment deployments, Waygate uses Docker containers for superior isolation, security, and reproducibility.

🔐 Why Containers > Virtual Environments

Security Aspect	Virtual Environment	Container	Advantage
Process Isolation	❌ Shared with host	✅ Isolated namespace	Prevents interference
Network Isolation	❌ Uses host network	✅ Private network	Controls traffic
File System	❌ Full host access	✅ Isolated filesystem	Limits breach impact
Resource Limits	❌ No limits	✅ cgroups limits	Prevents DoS
Privilege Escalation	⚠️ Easier	✅ Non-root user	Reduced attack surface

✨ Key Features

Security-Hardened Containers: Non-root execution, read-only filesystem, dropped capabilities
Production-Ready: Built with FastAPI for high performance
Diagnostic Excellence: Comprehensive troubleshooting tools and playbooks
Plugin Architecture: Extensible through modular plugins
Enterprise Features: SSL/TLS, rate limiting, monitoring built-in
One-Line Setup: Automated secure deployment with quickstart.sh

🚀 Quick Start (One Command!)

# Secure automated setup
curl -sSL https://raw.githubusercontent.com/jeremylongshore/waygate-mcp/main/quickstart.sh | bash

Or clone and run locally:

git clone https://github.com/jeremylongshore/waygate-mcp.git
cd waygate-mcp
chmod +x quickstart.sh
./quickstart.sh

📋 Manual Installation

Prerequisites

Docker 20.10+
Docker Compose 2.0+
Git
2GB+ disk space

Step-by-Step Setup

# 1. Clone the repository
git clone https://github.com/jeremylongshore/waygate-mcp.git
cd waygate-mcp

# 2. Generate secure configuration
export WAYGATE_SECRET_KEY=$(openssl rand -base64 32)
export WAYGATE_API_KEY=$(uuidgen)

# 3. Create environment file
cat > .env << EOF
WAYGATE_ENV=production
WAYGATE_SECRET_KEY=${WAYGATE_SECRET_KEY}
WAYGATE_API_KEY=${WAYGATE_API_KEY}
EOF

# 4. Build and start containers
docker-compose build --pull --no-cache
docker-compose up -d

# 5. Verify health
curl http://localhost:8000/health

Access Points

API: http://localhost:8000
Health Check: http://localhost:8000/health
Metrics: http://localhost:8000/metrics
Documentation: http://localhost:8000/docs (development mode)

📁 Project Structure

waygate-mcp/
├── ai-dev-tasks/         # AI development documentation
│   ├── PRDs/            # Product requirements
│   ├── ADRs/            # Architecture decisions
│   ├── tasks/           # Task breakdowns
│   └── specifications/  # Technical specs
├── src/                 # Source code
├── tests/               # Test suites
├── docs/                # Documentation
├── scripts/             # Utility scripts
└── configs/             # Configuration files

🐳 Development Mode

# Run in development mode with hot reload
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up

# Access container shell for debugging
docker-compose exec waygate /bin/bash

# View logs
docker-compose logs -f waygate

🔧 Configuration

Configuration via environment variables in .env file:

# Environment
WAYGATE_ENV=production          # production/development
WAYGATE_LOG_LEVEL=INFO          # DEBUG/INFO/WARNING/ERROR

# Security (CHANGE THESE!)
WAYGATE_SECRET_KEY=<generated>  # Generate with: openssl rand -base64 32
WAYGATE_API_KEY=<generated>     # Generate with: uuidgen

# Network
WAYGATE_CORS_ORIGINS=["https://yourdomain.com"]
WAYGATE_RATE_LIMIT=100          # Requests per minute

# Resources
WAYGATE_MAX_REQUEST_SIZE=10485760  # 10MB

🛡️ Security Features

Container Security

✅ Non-root user: Runs as UID 1000 (waygate user)
✅ Read-only filesystem: Writable volumes only where needed
✅ Dropped capabilities: All capabilities dropped except NET_BIND_SERVICE
✅ No new privileges: Prevents privilege escalation
✅ Resource limits: CPU (2 cores) and Memory (1GB) limits
✅ Network isolation: Custom Docker network with defined subnet
✅ Secrets management: Environment-based with .env file

Application Security

✅ API key authentication: Required for API access
✅ Rate limiting: Configurable per-endpoint limits
✅ CORS protection: Configurable allowed origins
✅ Input validation: Pydantic models for all inputs
✅ SSL/TLS ready: Nginx configuration included

📊 API Endpoints

Endpoint	Method	Description
`/`	GET	Service information
`/health`	GET	Health check
`/ready`	GET	Readiness check
`/metrics`	GET	Prometheus metrics
`/mcp/execute`	POST	Execute MCP command
`/mcp/status`	GET	MCP engine status
`/plugins`	GET	List plugins
`/diagnostics/connection`	GET	Connection diagnostics
`/diagnostics/performance`	GET	Performance diagnostics

🔍 Diagnostics

Run diagnostics to troubleshoot issues:

# Check server status
curl http://localhost:8000/health

# Run connection diagnostics
curl http://localhost:8000/diagnostics/connection

# Check performance metrics
curl http://localhost:8000/diagnostics/performance

🚦 Development

Running Tests

pytest tests/ -v --cov=src

Code Quality

# Format code
black src/ tests/

# Lint
flake8 src/ tests/

# Type checking
mypy src/

📝 Documentation

PRD: ai-dev-tasks/PRDs/00-prd-waygate-mcp-framework.md
Architecture: ai-dev-tasks/ADRs/ADR-001-core-architecture.md
Tech Spec: ai-dev-tasks/specifications/tech-spec-waygate-mcp.md
Tasks: ai-dev-tasks/tasks/00-tasks-waygate-mcp-implementation.md

🔄 Migration from NEXUS MCP

NEXUS MCP has been archived at /home/jeremy/projects/archived/NEXUS_MCP.

To migrate:

Export NEXUS configuration
Transform to Waygate format
Deploy Waygate instance
Verify functionality

🤝 Contributing

Create feature branch
Make changes
Run tests
Submit PR

📄 License

Open Source - MIT License

🆘 Support

For issues or questions, check the documentation in ai-dev-tasks/ or create an issue.

Built with AI Assistance - Developed with Claude (Anthropic) Maintained by: Jeremy Longshore Last Updated: 2025-01-14