@genxis/whmrockstar/README.md

🎸 GenXis WHMRockStar - AI-powered multi-server WHM/cPanel management via Model Context Protocol (MCP). Enhanced with proper MCP stdio protocol support and multi-server management.

# 🎸 GenXis WHMRockStar v2.1

[![npm version](https://badge.fury.io/js/@genxis%2Fwhmrockstar.svg)](https://badge.fury.io/js/@genxis%2Fwhmrockstar)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D16.0.0-brightgreen)](https://nodejs.org/)

**AI-powered multi-server WHM/cPanel management via Model Context Protocol (MCP)**

Transform your dedicated LAMP server management with AI assistance. Now with SSH integration for full root access, automated key deployment, and complete system control.

## 🚀 What's New in v2.1

### v2.1.0 - SSH Integration & Root Access
- 🚀 **SSH Integration**: Full root-level SSH access via automated key deployment
- 🔐 **Automated SSH Setup**: Uses WHM API to install SSH keys - no manual configuration
- 💻 **System Management**: Execute any command, restart services, check system health
- 🔧 **Direct File Access**: Edit system files including /etc/, /var/log/, Apache configs
- 📊 **System Monitoring**: Check disk space, memory usage, service status

### v2.0.0 - MCP Protocol & Multi-Server
- ✅ **Proper MCP Protocol**: Full stdio-based MCP implementation for seamless integration
- ✅ **Multi-Server Support**: Manage multiple WHM servers from a single interface
- ✅ **Enhanced Server Context**: Clear server identification in all operations
- ✅ **Improved Error Handling**: Better error messages and debugging
- ✅ **Backward Compatibility**: Legacy configurations automatically migrated

## 🚀 Quick Start

### One-Line Installation

```bash
npx @genxis/whmrockstar setup
```

That's it! The setup wizard will guide you through configuration and automatically integrate with your IDE.

### Manual Installation

```bash
npm install -g @genxis/whmrockstar
genxis-whm setup
```

## 📋 Prerequisites

- **Dedicated Server(s)** with LAMP stack
- **WHM/cPanel** with root access
- **Node.js** 16.0.0 or higher
- **WHM API Token(s)** (generated in WHM)

## ⚠️ Security Notice

- **NEVER commit API tokens to version control**
- **Rotate API tokens regularly** for security
- **Use environment variables or secure config files** for production
- API tokens are stored locally in `~/.genxis-whmrockstar/servers.json`

## 🔧 Multi-Server Configuration

### Adding Your First Server

```bash
genxis-whm setup
```

### Adding Additional Servers

```bash
genxis-whm add-server
```

### Managing Servers

```bash
# List all configured servers
genxis-whm list-servers

# Test all server connections
genxis-whm test-all

# Test specific server
genxis-whm test server1

# Show server configuration
genxis-whm config server1

# Remove a server
genxis-whm remove-server server1
```

## 🎯 Features

- 🔑 **Secure WHM API Integration** - Full WHM/cPanel management via API
- 🌐 **Multi-Server Support** - Manage multiple WHM servers from one MCP instance
- 📁 **File Management** - CRUD operations on server files via cPanel API
- 🔐 **Secure Token Management** - Support for daily API token rotation
- 📊 **Account Management** - Create, list, suspend, unsuspend, and terminate accounts
- 📈 **Resource Monitoring** - Check disk usage, bandwidth, and account limits
- 🛠️ **Configuration Checks** - Find and fix .htaccess and PHP configuration issues
- ⚡ **DNS Management** - Add, modify, and remove DNS zones and records
- 📦 **Package Management** - Create and manage hosting packages
- 🔄 **Backup Operations** - Create and restore account backups
- 🎯 **Interactive CLI** - Easy setup and server management commands
- 📝 **Audit Logging** - Track all operations for security and debugging
- 🚀 **SSH Integration** - Full root-level SSH access via automated key deployment
- 💻 **System Management** - Restart services, check system health, execute commands
- 🔧 **Direct File Access** - Edit system files including /etc/, /var/log/ via SSH

### Core WHM/cPanel Operations

- **Account Management**: Create, list, suspend, unsuspend, terminate cPanel accounts
- **Domain Management**: Add, remove, list domains and subdomains
- **Server Monitoring**: Real-time server status, load, memory, and service monitoring
- **Service Control**: Restart Apache, MySQL, Nginx, and other services
- **Update Management**: Check for and install server updates

### AI Integration

- **Natural Language Commands**: "List accounts on server1" or "Create account on production server"
- **Intelligent Server Selection**: AI understands server context and suggests appropriate servers
- **Enhanced Error Handling**: Clear error messages with server context
- **Batch Operations**: Process multiple accounts across multiple servers

### IDE Integration

- **VS Code**: Full integration via MCP protocol (Roo-Cline, Claude)
- **Windsurf**: Native support with real-time updates
- **Claude Desktop**: Direct AI assistance for server management
- **JetBrains**: Plugin-ready architecture

## 📖 Usage Examples

### Basic Commands

```javascript
// After setup, use natural language in your AI assistant:

"List all servers"
"List all cPanel accounts on server1"
"Create a new account for johndoe.com on production server"
"Check server load on all servers"
"Restart Apache service on server2"
"Suspend account 'spammer' on server1 for abuse"
```

### Multi-Server Operations

```javascript
// Server-specific operations
"Show me all accounts on my production server"
"What's the status of my development server?"
"Create a test account on staging server"

// Cross-server operations
"Compare account counts across all servers"
"Show server load for all configured servers"
```

### Programmatic Usage

```javascript
const WHMRockStarMCPServer = require('@genxis/whmrockstar');

// The MCP server automatically handles multi-server configurations
const server = new WHMRockStarMCPServer();
await server.start();

// All operations include server context in responses
```

## 🛠️ Available Tools

### Server Management
- `whm_list_servers` - List all configured WHM servers

### SSH Operations (v2.1+)
- `ssh_setup` - Install SSH keys via WHM API (one-time setup)
- `ssh_command` - Execute any shell command as root
- `ssh_file_read` - Read any system file
- `ssh_file_write` - Write to any system file
- `ssh_service` - Manage systemd services (restart/stop/start/status)
- `ssh_system_check` - Check disk, memory, Apache config, error logs

### Account Management
- `whm_list_accounts` - List all WHM accounts (with server context)
- `whm_create_account` - Create new cPanel account
- `whm_account_summary` - Get detailed account information
- `whm_suspend_account` - Suspend account with reason
- `whm_unsuspend_account` - Reactivate suspended account
- `whm_terminate_account` - Permanently remove account (with confirmation)

### Server Monitoring
- `whm_server_status` - Get server status and statistics
- `whm_server_load` - Monitor server load averages
- `whm_service_status` - Check status of all services
- `whm_restart_service` - Restart specific services

### Domain Management
- `whm_list_domains` - List domains for account

All tools support optional `serverId` parameter. If only one server is configured, it's used automatically.

## 🔒 Security

### Best Practices

- **API Token Security**: Tokens are stored locally and never transmitted to third parties
- **HTTPS Only**: All WHM communications use HTTPS
- **Local Processing**: All operations run locally on your machine
- **No Data Collection**: GenXis doesn't collect or store your server data
- **Server Isolation**: Each server configuration is isolated and secure

### Multi-Server Token Management

```bash
# Test connections for all servers
genxis-whm test-all

# View server configurations (tokens are masked)
genxis-whm config

# Update specific server
genxis-whm remove-server old-server
genxis-whm add-server  # Add updated configuration
```

## 📁 File Structure

```
~/.genxis-whmrockstar/
├── servers.json          # Multi-server configuration (v2.0)
├── config.json           # Legacy single server config (auto-migrated)
└── logs/                 # Operation logs
    └── whm-operations.log
```

### Multi-Server Configuration Format

```json
{
  "version": "2.0",
  "servers": {
    "production": {
      "name": "Production Server",
      "server": "192.168.1.100",
      "apiToken": "your-token",
      "port": "2087",
      "username": "root",
      "enabled": true
    },
    "staging": {
      "name": "Staging Server", 
      "server": "192.168.1.101",
      "apiToken": "your-token",
      "port": "2087",
      "username": "root",
      "enabled": true
    }
  }
}
```

## 🔧 Advanced Configuration

### MCP Settings (Auto-Generated)

```json
{
  "mcpServers": {
    "genxis-whm": {
      "command": "node",
      "args": ["path/to/mcp-server.js"],
      "disabled": false,
      "alwaysAllow": [],
      "disabledTools": []
    }
  }
}
```

### Environment Variables (Legacy Support)

```bash
# Single server via environment (auto-migrated to multi-server config)
export WHM_SERVER="your-server-ip"
export WHM_API_TOKEN="your-api-token"
export WHM_PORT="2087"
export WHM_SERVER_ID="env-server"
export WHM_SERVER_NAME="Environment Server"
```

## 🚨 Troubleshooting

### Common Issues

**No Servers Configured**
```bash
# Add your first server
genxis-whm setup

# Or add additional servers
genxis-whm add-server
```

**Connection Failed**
```bash
# Test specific server
genxis-whm test server1

# Test all servers
genxis-whm test-all

# Check server configuration
genxis-whm config server1
```

**MCP Not Working in IDE**
```bash
# Regenerate MCP configuration
genxis-whm setup --force

# Check MCP server status
genxis-whm start
```

**Server Context Issues**
```bash
# List available servers
genxis-whm list-servers

# Ensure server IDs are unique and descriptive
genxis-whm config
```

### Debug Mode

```bash
# Enable verbose logging
export LOG_LEVEL=debug
genxis-whm start

# View logs
genxis-whm logs

# Test with detailed output
genxis-whm test-all
```

## 🆙 Migration from v1.0

v2.0 automatically migrates v1.0 configurations:

1. **Legacy config.json** → Migrated to multi-server format
2. **Environment variables** → Added as server configuration
3. **MCP settings** → Updated to use new stdio protocol

No manual migration required!

## 📚 API Reference

### Tool Parameters

All tools support these common parameters:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `serverId` | string | No* | Server ID (auto-selected if only one server) |

*Required only when multiple servers are configured

### Server Context in Responses

All tool responses include server context:

```json
{
  "server": {
    "id": "production",
    "name": "Production Server",
    "address": "192.168.1.100"
  },
  "operation": "list_accounts",
  "result": "<omitted for brevity>",
  "timestamp": "2025-01-01T00:00:00.000Z"
}
```

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Setup

```bash
git clone https://github.com/genxis/genxis-whmrockstar.git
cd genxis-whmrockstar
npm install

# Test the MCP server
npm run start

# Test CLI commands
npm run setup
```

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🆘 Support

- **Documentation**: [https://docs.genxis.com/whmrockstar](https://docs.genxis.com/whmrockstar)
- **Issues**: [GitHub Issues](https://github.com/genxis/genxis-whmrockstar/issues)
- **Email**: support@genxis.com
- **Community**: [Discord](https://discord.gg/genxis)

## 🏷️ Version History

### v2.0.0 (Current)
- ✅ **BREAKING**: Proper MCP stdio protocol implementation
- ✅ **NEW**: Multi-server support with server context
- ✅ **NEW**: Enhanced CLI with server management commands
- ✅ **NEW**: Automatic migration from v1.0 configurations
- ✅ **NEW**: Improved error handling and debugging
- ✅ **NEW**: Server-aware tool responses
- ✅ **IMPROVED**: Better IDE integration compatibility

### v1.0.0 (Legacy)
- ✅ Initial release
- ✅ Basic WHM/cPanel integration
- ✅ HTTP/SSE-based MCP protocol
- ✅ Single server support
- ✅ Basic IDE integration

---

**Made with ❤️ by [GenXis](https://genxis.com)**

*Transform your multi-server management with AI-powered automation*


## 🔒 Security and Reliability (v2.1 updates)

From this release:

- TLS verification is ON by default. If you use a self-signed certificate during migration/testing, you can explicitly opt out per server by setting `verifyTLS: false` in `%USERPROFILE%\.genxis-whmrockstar\servers.json`. Prefer installing a valid cert or providing a custom CA instead of disabling verification.
- Optional custom CA: Provide a path to a CA PEM via `caPath` in the server config to keep verification enabled while trusting your own CA.
- Built-in retries: Transient network errors and 5xx/429 responses are retried with exponential backoff (defaults: 3 retries, starting at ~300ms). You can tune with `retries` and `retryDelayMs` per server.
- Audit logging: MCP tool calls write a redacted JSONL entry to `%USERPROFILE%\.genxis-whmrockstar\audit.log` including tool name, serverId, outcome, and a digest of params (no raw secrets).

### Example servers.json

```json
{
  "servers": {
    "prod-1": {
      "server": "your-whm-server.com",
      "port": "2087",
      "username": "root",
      "apiToken": "<ROOT_SCOPED_WHM_API_TOKEN>",
      "name": "WHM Prod 1",
      "timeout": 45000,
      "verifyTLS": true,
      "caPath": "C:\\Users\\Administrator\\Desktop\\certs\\my-ca.pem",
      "retries": 3,
      "retryDelayMs": 300
    }
  }
}
```

Notes:
- Keep `servers.json` permission-restricted to your Windows user (NTFS ACLs).
- Rotate tokens periodically. Avoid committing tokens to version control.
- If you must disable TLS verification (not recommended), set `verifyTLS: false` only temporarily.

### Audited tools
- whm_list_servers
- whm_list_accounts
- whm_restart_service
- whm_call_api (covers full-access operations)

You can open `%USERPROFILE%\.genxis-whmrockstar\audit.log` to review actions by timestamp.