README.md•5.66 kB
# 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
```bash
# 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
```bash
# 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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"command": "systemctl status nginx"
}
```
## Workflow
### Basic VPS Setup
1. **Connect to VPS:**
```json
{
"tool": "ssh_connect",
"args": {
"host": "your-vps-ip",
"username": "root",
"password": "your-password"
}
}
```
2. **Initialize VPS:**
```json
{
"tool": "vps_initialize",
"args": {
"services": {
"nodejs": true,
"pm2": true,
"nginx": true
}
}
}
```
3. **Setup Nginx:**
```json
{
"tool": "nginx_setup",
"args": {
"domain": "yourdomain.com",
"port": 3000,
"ssl": true
}
}
```
4. **Setup CI/CD:**
```json
{
"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:
1. **Deploy Key**: Add to your GitHub repository's Deploy Keys
2. **GitHub Secrets**: Add to your repository's Actions secrets
3. **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
1. **SSH Connection Failed**
- Verify IP address and credentials
- Check firewall settings
- Ensure SSH service is running
2. **SSL Certificate Issues**
- Verify domain DNS points to server
- Check firewall allows HTTP/HTTPS
- Ensure email is valid for Let's Encrypt
3. **Service Installation Failed**
- Check system update status
- Verify internet connectivity
- Review error logs
### Debug Mode
Enable debug logging:
```bash
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.