MCP聚合网关

# Clone and run complete installation
git clone https://github.com/mohandshamada/MCP-Gateway.git
cd MCP-Gateway
sudo ./scripts/install.sh

# Clone and run setup
git clone https://github.com/mohandshamada/MCP-Gateway.git
cd MCP-Gateway
sudo ./scripts/setup-ubuntu.sh

# Set your domain and email
export DOMAIN="mcp.example.com"
export EMAIL="admin@example.com"

# Run setup scripts in order
sudo ./scripts/setup-ubuntu.sh      # System dependencies
sudo ./scripts/setup-caddy.sh       # Caddy reverse proxy
sudo ./scripts/setup-gateway.sh     # MCP Gateway service

# Clone repository
git clone https://github.com/mohandshamada/MCP-Gateway.git
cd MCP-Gateway/mcp-gateway

# Install dependencies (includes all MCP servers)
npm install

# Setup MCP directories
npm run setup:mcp

# Build
npm run build

# Start
npm start

./scripts/validate-installation.sh

./scripts/health-check.sh

# Check health (all 5 servers should be healthy)
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:3000/admin/health

# Expected: {"status":"healthy","servers":{"total":5,"healthy":5,"unhealthy":0}}

# List all 71 tools
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:3000/admin/tools | jq '.data.total'

# Expected: 71

https://your-domain.com/sse

http://localhost:3000/sse

# Get full configuration with your token embedded
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-domain.com/admin/client-config/claude

# Output (ready to use):
{
  "mcpServers": {
    "mcp-gateway": {
      "url": "https://your-domain.com/sse",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

# Test SSE connection (should stream events)
curl -N \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: text/event-stream" \
  https://your-domain.com/sse

# Check available tools
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-domain.com/admin/tools | jq '.data.total'
# Expected: 71

{
  "mcpServers": {
    "mcp-gateway": {
      "url": "https://mcp.example.com/sse",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer sk-a1b2c3d4e5f6g7h8i9j0..."
      }
    }
  }
}

client-configs/
├── claude-desktop-config.json   # Claude Desktop configuration
├── sse-client-config.json       # Generic SSE client configuration
├── oauth-client-config.json     # OAuth configuration (if enabled)
└── test-connection.sh           # Connection test script

# Full configuration with instructions
curl -H "Authorization: Bearer $TOKEN" https://your-domain.com/admin/client-config

# Download Claude Desktop config file directly
curl -H "Authorization: Bearer $TOKEN" https://your-domain.com/admin/client-config/claude

# Set environment variables
export DOMAIN="mcp.example.com"
export EMAIL="admin@example.com"

# Run setup
sudo ./scripts/setup-caddy.sh

sudo ./scripts/caddy-integration.sh

# Interactive setup (default)
sudo ./scripts/caddy-integration.sh

# Check current status
sudo ./scripts/caddy-integration.sh --check

# Run integration tests
sudo ./scripts/caddy-integration.sh --test

# Fix common issues automatically
sudo ./scripts/caddy-integration.sh --fix

# Non-interactive setup (for automation)
sudo MCP_DOMAIN=mcp.example.com ./scripts/caddy-integration.sh --non-interactive

{
    email admin@example.com
}

your-domain.com {
    header {
        X-Content-Type-Options nosniff
        X-Frame-Options DENY
        X-XSS-Protection "1; mode=block"
        Referrer-Policy strict-origin-when-cross-origin
        -Server
    }

    # SSE endpoint needs special handling for long-lived connections
    handle /sse* {
        reverse_proxy 127.0.0.1:3000 {
            transport http {
                read_timeout 0
                write_timeout 0
            }
            flush_interval -1
        }
    }

    # All other endpoints
    handle {
        reverse_proxy 127.0.0.1:3000
    }

    log {
        output file /var/log/caddy/mcp-gateway.log {
            roll_size 100mb
            roll_keep 5
        }
        format json
    }
}

sudo systemctl enable caddy
sudo systemctl start caddy

{
  "oauthServer": {
    "enabled": true,
    "tokenExpiresIn": 3600,
    "refreshTokenExpiresIn": 86400,
    "clients": [
      {
        "clientId": "mcp-client",
        "clientSecret": "your-secure-secret-here",
        "name": "MCP Gateway Client",
        "scopes": ["mcp:read", "mcp:write", "mcp:admin"],
        "grantTypes": ["client_credentials", "password", "refresh_token"]
      }
    ]
  }
}

# Using client credentials grant
curl -X POST http://localhost:3000/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=mcp-client" \
  -d "client_secret=your-secure-secret-here"

# Response:
{
  "access_token": "abc123def456...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "mcp:read mcp:write mcp:admin"
}

# Get token and save it
TOKEN=$(curl -s -X POST http://localhost:3000/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=mcp-client" \
  -d "client_secret=your-secure-secret-here" | jq -r '.access_token')

# Use token to access SSE endpoint
curl -N -H "Authorization: Bearer $TOKEN" http://localhost:3000/sse

# Or with domain
curl -N -H "Authorization: Bearer $TOKEN" https://mcp.example.com/sse

{
  "mcpServers": {
    "mcp-gateway": {
      "url": "https://mcp.example.com/sse",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer YOUR_OAUTH_TOKEN"
      }
    }
  }
}

curl -X POST http://localhost:3000/oauth/clients \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "my-app",
    "clientSecret": "my-app-secret",
    "name": "My Application",
    "scopes": ["mcp:read", "mcp:write"],
    "grantTypes": ["client_credentials"]
  }'

curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:3000/oauth/info

# Response:
{
  "enabled": true,
  "stats": {
    "clients": 1,
    "activeTokens": 5,
    "refreshTokens": 2
  },
  "clients": [
    {
      "clientId": "mcp-client",
      "name": "MCP Gateway Client",
      "scopes": ["mcp:read", "mcp:write", "mcp:admin"],
      "grantTypes": ["client_credentials", "password", "refresh_token"]
    }
  ]
}

# Start the test OAuth server on port 9000
node scripts/oauth-server.cjs 9000

# Test credentials:
# Client ID: mcp-gateway-client
# Client Secret: mcp-gateway-secret

curl -X POST http://localhost:9000/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=mcp-gateway-client" \
  -d "client_secret=mcp-gateway-secret"

# Response:
# {
#   "access_token": "abc123...",
#   "token_type": "Bearer",
#   "expires_in": 3600,
#   "scope": "mcp:read mcp:write mcp:admin"
# }

# Generate token with your domain (adds to config, prints ready URLs)
./scripts/generate-token.sh mcp.example.com

# Output includes:
# - Generated token
# - Ready-to-use SSE URLs with token
# - Claude Desktop config snippet
# - curl test command

{
  "auth": {
    "enabled": true,
    "tokens": ["your-api-token"],
    "oauth": {
      "enabled": true,
      "clientId": "your-client-id",
      "clientSecret": "your-client-secret",
      "issuer": "https://auth.example.com",
      "authorizationUrl": "https://auth.example.com/authorize",
      "tokenUrl": "https://auth.example.com/token",
      "scopes": ["mcp:read", "mcp:write"]
    }
  }
}

{
  "servers": [
    {
      "id": "remote-oauth-server",
      "transport": "sse",
      "url": "https://api.example.com/mcp/sse",
      "oauth": {
        "clientId": "${API_CLIENT_ID}",
        "clientSecret": "${API_CLIENT_SECRET}",
        "tokenUrl": "https://auth.example.com/oauth/token",
        "grantType": "client_credentials",
        "scopes": ["mcp:read", "mcp:write"],
        "audience": "https://api.example.com",
        "refreshBeforeExpiry": 60
      },
      "enabled": true
    }
  ]
}

export API_CLIENT_ID="your-client-id"
export API_CLIENT_SECRET="your-client-secret"

{
  "oauth": {
    "clientId": "YOUR_AUTH0_CLIENT_ID",
    "clientSecret": "YOUR_AUTH0_CLIENT_SECRET",
    "tokenUrl": "https://YOUR_DOMAIN.auth0.com/oauth/token",
    "audience": "https://your-api.example.com",
    "grantType": "client_credentials"
  }
}

# Install with Docker
docker run -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:latest start-dev

# Access: http://localhost:8080
# Create realm, client, and configure:

{
  "oauth": {
    "clientId": "mcp-gateway",
    "clientSecret": "YOUR_CLIENT_SECRET",
    "tokenUrl": "http://localhost:8080/realms/myrealm/protocol/openid-connect/token",
    "grantType": "client_credentials"
  }
}

{
  "oauth": {
    "clientId": "YOUR_COGNITO_CLIENT_ID",
    "clientSecret": "YOUR_COGNITO_CLIENT_SECRET",
    "tokenUrl": "https://YOUR_POOL.auth.REGION.amazoncognito.com/oauth2/token",
    "grantType": "client_credentials"
  }
}

{
  "domain": {
    "domain": "mcp.example.com",
    "publicUrl": "https://mcp.example.com",
    "ssl": {
      "enabled": true,
      "email": "admin@example.com"
    },
    "proxy": {
      "enabled": true,
      "type": "caddy"
    }
  }
}

┌─────────────────────────────────────────────────────────────────────────────┐
│                              MCP Gateway                                     │
│                                                                              │
│  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐   ┌──────────────┐ │
│  │     Auth     │──▶│    Router    │──▶│   Registry   │──▶│   Adapters   │ │
│  │  Middleware  │   │  (Namespace) │   │ (Health/Pool)│   │ (Stdio/SSE)  │ │
│  └──────────────┘   └──────────────┘   └──────────────┘   └──────────────┘ │
│         │                                                         │          │
│         │              ┌──────────────────────────────────────────┤          │
│         │              │                                          │          │
│         ▼              ▼                                          ▼          │
│  ┌─────────────────────────────────────────────────────────────────────────┐│
│  │                        Production Features                               ││
│  │  • Circuit Breaker    • Retry w/ Backoff    • Request Correlation       ││
│  │  • Rate Limiting      • Health Checks       • Graceful Degradation      ││
│  │  • Config Persistence • Permission Mgmt    • Hot Reload                 ││
│  │  • OAuth Support      • Caddy Integration  • Claude App Ready           ││
│  └─────────────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────────────┘
                            │
          ┌─────────────────┼─────────────────┐
          │                 │                 │
          ▼                 ▼                 ▼
   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
   │   Caddy     │   │  Let's      │   │   Claude    │
   │   Proxy     │   │  Encrypt    │   │   Desktop   │
   │   (SSL)     │   │   (SSL)     │   │   (Client)  │
   └─────────────┘   └─────────────┘   └─────────────┘

curl -H "Authorization: Bearer YOUR_TOKEN" https://your-domain.com/admin/health

{
  "gateway": {
    "host": "0.0.0.0",
    "port": 3000,
    "name": "MCP Gateway",
    "version": "1.0.0"
  },
  "domain": {
    "domain": "mcp.example.com",
    "publicUrl": "https://mcp.example.com",
    "ssl": {
      "enabled": true,
      "email": "admin@example.com"
    },
    "proxy": {
      "enabled": true,
      "type": "caddy"
    }
  },
  "auth": {
    "enabled": true,
    "tokens": ["sk-your-secure-token-here"],
    "oauth": {
      "enabled": false,
      "clientId": null,
      "clientSecret": null
    }
  },
  "servers": [
    {
      "id": "filesystem",
      "transport": "stdio",
      "command": "node",
      "args": ["node_modules/@modelcontextprotocol/server-filesystem/dist/index.js", "/home", "/tmp"],
      "enabled": true,
      "timeout": 60000,
      "maxRetries": 3
    }
  ],
  "settings": {
    "requestTimeout": 120000,
    "enableHealthChecks": true,
    "healthCheckInterval": 30000,
    "enableRateLimiting": true,
    "rateLimit": {
      "windowMs": 60000,
      "maxRequests": 200
    }
  }
}

# Configuration file path
CONFIG_PATH=/path/to/gateway.json

# Authentication tokens (comma-separated)
MCP_GATEWAY_TOKENS=token1,token2,token3

# Single token
MCP_GATEWAY_TOKEN=your-token

# Node environment
NODE_ENV=production

# Domain (for non-interactive setup)
MCP_DOMAIN=mcp.example.com
MCP_SSL_EMAIL=admin@example.com

# OAuth (for non-interactive setup)
MCP_OAUTH_ENABLED=true
MCP_OAUTH_CLIENT_ID=your-client-id
MCP_OAUTH_CLIENT_SECRET=your-client-secret
MCP_OAUTH_ISSUER=https://auth.example.com

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "filesystem__read_file",
    "arguments": {
      "path": "/home/user/document.txt"
    }
  }
}

States: CLOSED → OPEN → HALF_OPEN → CLOSED

- Failure threshold: 5 consecutive failures
- Recovery timeout: 30 seconds
- Success threshold: 2 successes to close

curl -H "Authorization: Bearer $TOKEN" https://your-domain.com/admin/servers/filesystem | jq '.data.circuitBreaker'

Retry 1: 1000ms + jitter
Retry 2: 2000ms + jitter
Retry 3: 4000ms + jitter
Max delay: 30000ms

# Request
curl -H "Authorization: Bearer $TOKEN" https://your-domain.com/admin/health

# Response includes x-request-id header
# Logs include requestId for correlation

# Register server (automatically saved to gateway.json)
curl -X POST https://your-domain.com/admin/servers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "new-server", "transport": "stdio", "command": "node", "args": ["server.js"]}'

# Server will persist across restarts

# Run health check (reads token from config automatically)
./scripts/health-check.sh

# With custom domain
./scripts/health-check.sh mcp.example.com

# Quick health check
curl -H "Authorization: Bearer $TOKEN" https://your-domain.com/admin/health

# Detailed metrics
curl -H "Authorization: Bearer $TOKEN" https://your-domain.com/admin/metrics

# 1. System dependencies (Node.js, Chrome, etc.)
sudo ./scripts/setup-ubuntu.sh

# 2. Caddy reverse proxy (SSL, domain configuration)
export DOMAIN="mcp.example.com"
export EMAIL="admin@example.com"
sudo ./scripts/setup-caddy.sh

# 3. MCP Gateway service (systemd, config validation)
sudo ./scripts/setup-gateway.sh

# MCP Gateway
sudo systemctl start mcp-gateway
sudo systemctl stop mcp-gateway
sudo systemctl restart mcp-gateway
sudo systemctl status mcp-gateway
sudo journalctl -u mcp-gateway -f

# Caddy
sudo systemctl start caddy
sudo systemctl stop caddy
sudo systemctl restart caddy
sudo systemctl status caddy
sudo journalctl -u caddy -f

# Run health check
./scripts/health-check.sh

# Or manually
curl -H "Authorization: Bearer $TOKEN" https://your-domain.com/admin/health

# Check permission status
curl -H "Authorization: Bearer $TOKEN" https://your-domain.com/admin/permissions

# Create directory with secure permissions (755)
curl -X POST https://your-domain.com/admin/permissions/mkdir \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path": "/opt/data/uploads"}'

# Set permissions
curl -X POST https://your-domain.com/admin/permissions/set \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path": "/opt/data", "mode": 511, "recursive": true}'

MCP-GATEWAY/
├── config/
│   ├── gateway.json          # Main configuration
│   └── gateway.example.json  # Example configuration
├── client-configs/           # Generated client configurations
│   ├── claude-desktop-config.json
│   ├── sse-client-config.json
│   └── test-connection.sh
├── dist/                     # Compiled JavaScript
├── docs/                     # Documentation
├── logs/                     # Application logs
├── mcp-data/                 # MCP tool data (755 permissions)
│   ├── data/
│   ├── cache/
│   ├── downloads/
│   ├── screenshots/
│   ├── uploads/
│   └── workspace/
├── node_modules/             # Includes all MCP servers
├── scripts/
│   ├── setup-ubuntu.sh       # System dependencies setup
│   ├── setup-caddy.sh        # Caddy reverse proxy setup
│   ├── setup-gateway.sh      # MCP Gateway service setup
│   ├── health-check.sh       # Health check script (reads token from config)
│   ├── generate-token.sh     # Generate auth tokens with ready-to-use URLs
│   ├── oauth-server.cjs      # Test OAuth authorization server
│   ├── Caddyfile.template    # Caddy configuration template
│   └── caddy-integration.sh  # Advanced Caddy integration with OAuth
├── src/                      # TypeScript source
├── tests/                    # Test files
├── DEPLOYMENT.md             # Quick deployment guide
└── README.md                 # This file

# Install dependencies
npm install

# Development mode with hot reload
npm run dev

# Type checking
npm run typecheck

# Linting
npm run lint
npm run lint:fix

# Run tests
npm test
npm run test:watch
npm run test:coverage

# Build for production
npm run build

# Run comprehensive validation
./scripts/validate-installation.sh

# Quick health check
./scripts/health-check.sh

# Pre-deployment check
./scripts/pre-deploy-check.sh

# Check Caddy logs
sudo journalctl -u caddy -f

# Validate Caddyfile
caddy validate --config /etc/caddy/Caddyfile

# Force certificate renewal
caddy reload --config /etc/caddy/Caddyfile

# Check individual server status
curl -H "Authorization: Bearer $TOKEN" https://your-domain.com/admin/servers/filesystem

# Check circuit breaker state
jq '.data.circuitBreaker' # Look for "open" state

# Restart server
curl -X POST -H "Authorization: Bearer $TOKEN" https://your-domain.com/admin/servers/filesystem/restart

# Check if running as root
curl -H "Authorization: Bearer $TOKEN" https://your-domain.com/admin/permissions

# If not root, restart with sudo
sudo systemctl restart mcp-gateway

# Install Chrome manually
wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo gpg --dearmor -o /usr/share/keyrings/google-chrome.gpg
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/google-chrome.gpg] http://dl.google.com/linux/chrome/deb/ stable main" | sudo tee /etc/apt/sources.list.d/google-chrome.list
sudo apt-get update && sudo apt-get install -y google-chrome-stable

# Check Chrome installation
google-chrome --version

# Check config file permissions
ls -la config/gateway.json

# Should be writable
chmod 666 config/gateway.json

# The setup script will detect this and create a start script
./scripts/setup-ubuntu.sh

# Then start manually using one of these methods:
./start-gateway.sh                                    # Helper script created by setup
node dist/index.js                                    # Direct execution
screen -dmS mcp-gateway bash -c 'npm start'           # Screen session
nohup node dist/index.js > logs/mcp-gateway.log 2>&1 &  # Background with nohup

openssl rand -hex 32
# Use as: sk-<generated-hex>

# Set required environment variables
export DOMAIN=mcp.example.com
export EMAIL=admin@example.com

# Run setup scripts
sudo ./scripts/setup-ubuntu.sh
sudo ./scripts/setup-caddy.sh
sudo ./scripts/setup-gateway.sh

# Verify deployment
./scripts/health-check.sh

export MCP_DOMAIN=mcp.example.com
export MCP_SSL_EMAIL=admin@example.com
export MCP_API_TOKEN=sk-$(openssl rand -hex 32)
export MCP_OAUTH_ENABLED=false

sudo -E ./scripts/caddy-integration.sh --non-interactive