MCP VPS Initialize

A Model Context Protocol (MCP) server for automated VPS initialization and management. This tool provides SSH-based automation for setting up fresh VPS instances with common services and CI/CD pipelines.

Features

🔐 SSH Authentication: Supports both password and private key authentication
🛠️ VPS Initialization: Automated setup of Node.js, PM2, Rust, Nginx, Redis
🌐 Nginx Configuration: Domain setup with reverse proxy and SSL certificates
🚀 GitHub CI/CD: Automated deploy key generation and workflow creation
📝 Comprehensive Logging: Winston-based structured logging
🔧 TypeScript: Fully typed with strict TypeScript configuration

Installation

# Clone the repository
git clone <repository-url>
cd mcp-vps-initialize

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

Development

# Run in development mode
npm run dev

# Lint code
npm run lint
npm run lint:fix

# Format code
npm run format
npm run format:check

MCP Tools

1. SSH Connect

Connect to a VPS via SSH using password or private key authentication.

Parameters:

host (required): VPS IP address or hostname
username (required): SSH username
port (optional): SSH port (default: 22)
password (optional): SSH password
privateKeyPath (optional): Path to private key file
passphrase (optional): Private key passphrase

Example:

{
  "host": "192.168.1.100",
  "username": "root",
  "password": "your-password"
}

2. VPS Initialize

Initialize a fresh VPS with system updates and optional services.

Parameters:

services (optional): Object specifying which services to install
- nodejs (boolean): Install Node.js LTS
- pm2 (boolean): Install PM2 process manager
- rust (boolean): Install Rust toolchain
- nginx (boolean): Install and configure Nginx
- redis (boolean): Install and configure Redis

Example:

{
  "services": {
    "nodejs": true,
    "pm2": true,
    "nginx": true,
    "redis": false
  }
}

3. Nginx Setup

Configure Nginx with domain, reverse proxy, and SSL certificates.

Parameters:

domain (required): Domain name for the site
port (required): Backend port to proxy requests to
ssl (optional): Enable SSL with Certbot (default: true)

Example:

{
  "domain": "example.com",
  "port": 3000,
  "ssl": true
}

4. GitHub CI/CD Setup

Setup GitHub CI/CD with deploy keys and automated workflows.

Parameters:

repoUrl (required): GitHub repository URL
deployPath (required): Deployment path on the server

Example:

{
  "repoUrl": "https://github.com/username/repo.git",
  "deployPath": "/opt/deployments/myapp"
}

5. Execute Command

Execute arbitrary commands on the connected VPS.

Parameters:

command (required): Command to execute

Example:

{
  "command": "systemctl status nginx"
}

Workflow

Basic VPS Setup

Connect to VPS:

{
  "tool": "ssh_connect",
  "args": {
    "host": "your-vps-ip",
    "username": "root",
    "password": "your-password"
  }
}

Initialize VPS:

{
  "tool": "vps_initialize",
  "args": {
    "services": {
      "nodejs": true,
      "pm2": true,
      "nginx": true
    }
  }
}

Setup Nginx:

{
  "tool": "nginx_setup",
  "args": {
    "domain": "yourdomain.com",
    "port": 3000,
    "ssl": true
  }
}

Setup CI/CD:

{
  "tool": "github_cicd_setup",
  "args": {
    "repoUrl": "https://github.com/username/repo.git",
    "deployPath": "/opt/deployments/myapp"
  }
}

GitHub CI/CD Instructions

After running the github_cicd_setup tool, you'll receive:

Deploy Key: Add to your GitHub repository's Deploy Keys
GitHub Secrets: Add to your repository's Actions secrets
Workflow File: Add to .github/workflows/deploy.yml

The generated workflow will:

Trigger on pushes to main/master branch
Run tests (if available)
Build the application (if build script exists)
Deploy to your VPS automatically

Security Features

Firewall Configuration: Automatic UFW setup with secure defaults
SSL Certificates: Automated Let's Encrypt certificate generation
SSH Key Management: Secure deploy key generation
Process Isolation: Optional deploy user creation

Logging

Logs are written to:

logs/combined.log: All log levels
logs/error.log: Error logs only
Console: Formatted output with colors

Log levels: error, warn, info, debug

Configuration

The server can be configured through environment variables:

LOG_LEVEL: Set logging level (default: 'info')
PORT: Server port (if running standalone)

Troubleshooting

Common Issues

SSH Connection Failed
- Verify IP address and credentials
- Check firewall settings
- Ensure SSH service is running
SSL Certificate Issues
- Verify domain DNS points to server
- Check firewall allows HTTP/HTTPS
- Ensure email is valid for Let's Encrypt
Service Installation Failed
- Check system update status
- Verify internet connectivity
- Review error logs

Debug Mode

Enable debug logging:

LOG_LEVEL=debug npm start

Requirements

Node.js 18+
Fresh Ubuntu/Debian VPS
Domain name (for SSL setup)
GitHub repository (for CI/CD)

License

MIT License - see LICENSE file for details.

MCP VPS Initialize

Features

🔐 SSH Authentication: Supports both password and private key authentication
🛠️ VPS Initialization: Automated setup of Node.js, PM2, Rust, Nginx, Redis
🌐 Nginx Configuration: Domain setup with reverse proxy and SSL certificates
🚀 GitHub CI/CD: Automated deploy key generation and workflow creation
📝 Comprehensive Logging: Winston-based structured logging
🔧 TypeScript: Fully typed with strict TypeScript configuration

Installation

# Clone the repository
git clone <repository-url>
cd mcp-vps-initialize

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

Development

# Run in development mode
npm run dev

# Lint code
npm run lint
npm run lint:fix

# Format code
npm run format
npm run format:check

MCP Tools

1. SSH Connect

Connect to a VPS via SSH using password or private key authentication.

Parameters:

host (required): VPS IP address or hostname
username (required): SSH username
port (optional): SSH port (default: 22)
password (optional): SSH password
privateKeyPath (optional): Path to private key file
passphrase (optional): Private key passphrase

Example:

{
  "host": "192.168.1.100",
  "username": "root",
  "password": "your-password"
}

2. VPS Initialize

Initialize a fresh VPS with system updates and optional services.

Parameters:

services (optional): Object specifying which services to install
- nodejs (boolean): Install Node.js LTS
- pm2 (boolean): Install PM2 process manager
- rust (boolean): Install Rust toolchain
- nginx (boolean): Install and configure Nginx
- redis (boolean): Install and configure Redis

Example:

{
  "services": {
    "nodejs": true,
    "pm2": true,
    "nginx": true,
    "redis": false
  }
}

3. Nginx Setup

Configure Nginx with domain, reverse proxy, and SSL certificates.

Parameters:

domain (required): Domain name for the site
port (required): Backend port to proxy requests to
ssl (optional): Enable SSL with Certbot (default: true)

Example:

{
  "domain": "example.com",
  "port": 3000,
  "ssl": true
}

4. GitHub CI/CD Setup

Setup GitHub CI/CD with deploy keys and automated workflows.

Parameters:

repoUrl (required): GitHub repository URL
deployPath (required): Deployment path on the server

Example:

{
  "repoUrl": "https://github.com/username/repo.git",
  "deployPath": "/opt/deployments/myapp"
}

5. Execute Command

Execute arbitrary commands on the connected VPS.

Parameters:

command (required): Command to execute

Example:

{
  "command": "systemctl status nginx"
}

Workflow

Basic VPS Setup

Connect to VPS:

{
  "tool": "ssh_connect",
  "args": {
    "host": "your-vps-ip",
    "username": "root",
    "password": "your-password"
  }
}

Initialize VPS:

{
  "tool": "vps_initialize",
  "args": {
    "services": {
      "nodejs": true,
      "pm2": true,
      "nginx": true
    }
  }
}

Setup Nginx:

{
  "tool": "nginx_setup",
  "args": {
    "domain": "yourdomain.com",
    "port": 3000,
    "ssl": true
  }
}

Setup CI/CD:

{
  "tool": "github_cicd_setup",
  "args": {
    "repoUrl": "https://github.com/username/repo.git",
    "deployPath": "/opt/deployments/myapp"
  }
}

GitHub CI/CD Instructions

After running the github_cicd_setup tool, you'll receive:

Deploy Key: Add to your GitHub repository's Deploy Keys
GitHub Secrets: Add to your repository's Actions secrets
Workflow File: Add to .github/workflows/deploy.yml

The generated workflow will:

Trigger on pushes to main/master branch
Run tests (if available)
Build the application (if build script exists)
Deploy to your VPS automatically

Security Features

Firewall Configuration: Automatic UFW setup with secure defaults
SSL Certificates: Automated Let's Encrypt certificate generation
SSH Key Management: Secure deploy key generation
Process Isolation: Optional deploy user creation

Logging

Logs are written to:

logs/combined.log: All log levels
logs/error.log: Error logs only
Console: Formatted output with colors

Log levels: error, warn, info, debug

Configuration

The server can be configured through environment variables:

LOG_LEVEL: Set logging level (default: 'info')
PORT: Server port (if running standalone)

Troubleshooting

Common Issues

SSH Connection Failed
- Verify IP address and credentials
- Check firewall settings
- Ensure SSH service is running
SSL Certificate Issues
- Verify domain DNS points to server
- Check firewall allows HTTP/HTTPS
- Ensure email is valid for Let's Encrypt
Service Installation Failed
- Check system update status
- Verify internet connectivity
- Review error logs

Debug Mode

Enable debug logging:

LOG_LEVEL=debug npm start

Requirements

Node.js 18+
Fresh Ubuntu/Debian VPS
Domain name (for SSL setup)
GitHub repository (for CI/CD)

License

MIT License - see LICENSE file for details.