# cPanel Workspace Hub

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/)
[![Protocol](https://img.shields.io/badge/Protocol-MCP%20v1.0-purple.svg)](https://modelcontextprotocol.io/)
[![Test Suite](https://img.shields.io/badge/Tests-53%2F53%20Passing-brightgreen.svg)](#testing)
[![Author](https://img.shields.io/badge/Author-qu4nc0d3r-darkblue.svg)](https://github.com/qu4nc0d3r)
[![Live Site](https://img.shields.io/badge/Live%20Site-Online-blue.svg)](https://cpanel-hub.macquan.name.vn/)

Model Context Protocol (MCP) server and automated deployment toolchain for cPanel shared hosting environments. Provides programmatic interfaces for LLM coding agents (Claude Code, Cursor, Claude Desktop, Roo Code/Cline) and terminal CLI workflows to manage subdomains, deploy builds via FTPS, provision MySQL databases, handle snapshot backups, and inspect remote files.

Landing Page: [https://cpanel-hub.macquan.name.vn/](https://cpanel-hub.macquan.name.vn/)

---

## Navigation

- [English Documentation](#english)
  - [Architecture](#architecture)
  - [Core Capabilities](#core-capabilities)
  - [Installation & Setup](#installation--setup)
  - [MCP Client Configuration](#mcp-client-configuration)
  - [CLI Reference](#cli-reference)
  - [MCP Toolset (17 Tools)](#mcp-toolset)
  - [Response Schema Contract](#response-schema-contract)
  - [Testing](#testing)
- [Tài Liệu Tiếng Việt](#tiếng-việt)
  - [Kiến Trúc Hệ Thống](#kiến-trúc-hệ-thống)
  - [Tính Năng Kỹ Thuật](#tính-năng-kỹ-thuật)
  - [Cài Đặt & Cấu Hình](#cài-đặt--cấu-hình)
  - [Cấu Hình MCP Bằng Lệnh](#cấu-hình-mcp-bằng-lệnh)
  - [Lệnh Điều Khiển CLI](#lệnh-điều-khiển-cli)
  - [Bảng Đặc Tả 17 MCP Tools](#bảng-đặc-tả-17-mcp-tools)
  - [Kiểm Thử](#kiểm-thử)
- [License & Credits](#license--credits)

---

<a name="english"></a>
## English

### Architecture

The system consists of three distinct layers:

1. **UAPI & FTP Transport Layer (`scripts/cpanel-api.js`, `scripts/ftp-deploy.js`)**: Encapsulates cPanel Universal API (`DomainInfo::list_domains`, `SubDomain::addsubdomain`, `Mysql::*`) and TLS-secured FTP file operations with directory normalization and resource cleanup guarantees.
2. **Standard CLI Engine (`scripts/cli.js`, `scripts/setup.js`)**: Interactive configuration wizard and deterministic deployment pipeline supporting static asset detection (`dist/`, `build/`).
3. **MCP Stdio Server (`scripts/mcp-server.js`)**: Standard JSON-RPC stdio server exposing 17 structured tools with standardized JSON response envelopes.

### Core Capabilities

- **Subdomain Provisioning**: Calls cPanel UAPI to register `<name>.<domain>`, configure Document Root (`public_html/<name>`), create DNS zone records, and rely on AutoSSL for HTTPS certificate generation.
- **Smart Directory Deployment**: Synchronizes project workspaces to remote Document Roots via FTPS. Automatically detects and prioritizes production bundles (`dist/`, `build/`) or defaults to raw static sources.
- **On-Demand MySQL**: Provisions dedicated databases, generates scoped database users with randomized credentials, and grants `ALL PRIVILEGES` programmatically.
- **Automated Pre-Deploy Snapshots & Rollback**: Downloads current remote Document Root contents to `backups/<subdomain>/` before file upload. Rollback restores previous snapshots in seconds.
- **Direct Remote File Operations**: Remote path traversal, file read, write, upload, and deletion over FTP without requiring cPanel File Manager web access.
- **Strict Response Contract**: All MCP tools emit valid parseable JSON adhering to `{ success, action, message, data, error, timestamp, logs }` with `isError` flags on failure.

### Installation & Setup

#### Prerequisites
- Node.js >= 20.0.0
- Valid cPanel hosting account with API Token access (`Manage API Tokens`) and FTP access.

#### Step 1: Clone and Install
```bash
git clone https://github.com/qu4nc0d3r/cpanel-workspace-hub.git
cd cpanel-workspace-hub
npm install
```

#### Step 2: Configure Environment
Run the interactive setup wizard:
```bash
npm run setup
```
The wizard prompts for credentials, performs live network validation against both cPanel UAPI and FTP endpoints, writes `.env`, and outputs client configuration JSON.

Manual configuration alternative (`.env`):
```env
CPANEL_URL=https://yourdomain.com:2083
CPANEL_USER=your_cpanel_username
CPANEL_API_TOKEN=YOUR_CPANEL_API_TOKEN
CPANEL_MAIN_DOMAIN=yourdomain.com
FTP_HOST=yourdomain.com
FTP_USER=your_cpanel_username
FTP_PASS="your_ftp_password"
FTP_PORT=21
FTP_SECURE=false
```

#### Step 3: Verify Connectivity
```bash
npm run check
```

---

### MCP Client Configuration

#### 1. Claude Code CLI (Single Command)
```bash
claude mcp add cpanel-hub node /absolute/path/to/cpanel-workspace-hub/scripts/mcp-server.js
```

#### 2. Cursor (`.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "cpanel-hub": {
      "command": "node",
      "args": ["/absolute/path/to/cpanel-workspace-hub/scripts/mcp-server.js"]
    }
  }
}
```

#### 3. Claude Desktop (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "cpanel-hub": {
      "command": "node",
      "args": ["/absolute/path/to/cpanel-workspace-hub/scripts/mcp-server.js"]
    }
  }
}
```

#### 4. Inline Environment Injection (Multi-Account Setup)
Clients can inject credentials directly through the configuration without a local `.env`:
```json
{
  "mcpServers": {
    "cpanel-hub": {
      "command": "node",
      "args": ["/absolute/path/to/cpanel-workspace-hub/scripts/mcp-server.js"],
      "env": {
        "CPANEL_URL": "https://yourdomain.com:2083",
        "CPANEL_USER": "username",
        "CPANEL_API_TOKEN": "token",
        "CPANEL_MAIN_DOMAIN": "yourdomain.com",
        "FTP_HOST": "yourdomain.com",
        "FTP_USER": "username",
        "FTP_PASS": "password"
      }
    }
  }
}
```

---

### CLI Reference

| Command | Arguments | Description |
| :--- | :--- | :--- |
| `npm run setup` | None | Interactive configuration wizard with credential verification |
| `npm run check` | None | Test cPanel API and FTP connection health |
| `npm run project:create` | `<project-name>` | Register subdomain, scaffold project directory, and upload template |
| `npm run project:deploy` | `<project-name>` | Create backup snapshot and deploy latest code to remote Document Root |
| `npm run project:rollback` | `<project-name>` | Restore website from latest (or specified) local backup |
| `npm run project:list` | None | Query cPanel for all active subdomains and Document Roots |
| `npm run db:create` | `<project-name>` | Create MySQL database, create user, grant privileges, append `.env` snippet |
| `npm run db:list` | None | Query all MySQL databases and associated users |
| `npm run db:delete` | `<project-name>` | Drop MySQL database and associated project user |
| `npm run mcp` | None | Start Stdio MCP Server |

---

### MCP Toolset

The MCP server exposes 17 tools categorized into 5 operational domains:

#### Authentication & Configuration
- `cpanel_configure`: Update credentials runtime and persist to `.env` after verification.
- `cpanel_check_status`: Execute health check across configuration, cPanel UAPI, and FTP.

#### Subdomain & Project Lifecycle
- `cpanel_create_project`: Provision subdomain on cPanel, scaffold template, and deploy initial build.
- `cpanel_deploy_project`: Sync local workspace (`projects/<name>`) to remote server with automated snapshotting.
- `cpanel_list_projects`: List all active subdomains and mapped Document Roots.
- `cpanel_delete_subdomain`: Delete subdomain mapping via cPanel API 2.

#### Snapshot Backups & Rollback
- `cpanel_backup_project`: Download remote Document Root to timestamped directory under `backups/<subdomain>/`.
- `cpanel_rollback_project`: Restore remote Document Root from specified or latest backup directory.
- `cpanel_list_backups`: Inspect existing snapshots for a given project.

#### Database Management (MySQL)
- `cpanel_create_database`: Provision database, dedicated user, and strong password with `ALL PRIVILEGES`.
- `cpanel_list_databases`: Retrieve all MySQL databases, user associations, and byte sizes.
- `cpanel_delete_database`: Tear down database and dedicated user for a project.

#### Direct Remote File Operations
- `cpanel_list_files`: Read directory contents (name, type, byte size, modify timestamp).
- `cpanel_read_file`: Fetch raw content of remote text files.
- `cpanel_write_file`: Write or overwrite remote file content.
- `cpanel_upload_file`: Transfer local file to remote target path.
- `cpanel_delete_file`: Delete file or recursively remove directory.

---

### Response Schema Contract

Every tool execution emits structured JSON within MCP's `CallToolResult`:

```typescript
interface McpResponse<T = any> {
  success: boolean;       // Operational status
  action: string;        // Tool identifier
  message: string;       // Human-readable summary
  data: T | null;        // Structured payload
  error: string | null;  // Technical error details if success === false
  timestamp: string;     // ISO 8601 execution timestamp
  logs?: string[];       // Step-by-step diagnostic log entries
}
```

Example payload (`cpanel_create_project`):
```json
{
  "success": true,
  "action": "cpanel_create_project",
  "message": "Website project \"shop-mini\" created and deployed successfully",
  "data": {
    "project": "shop-mini",
    "domain": "shop-mini.example.com",
    "url": "https://shop-mini.example.com",
    "remoteDir": "public_html/shop-mini",
    "localDir": "/workspace/projects/shop-mini"
  },
  "error": null,
  "timestamp": "2026-09-07T07:22:54.512Z",
  "logs": [
    "Registered subdomain: shop-mini.example.com",
    "Scaffolded template to local directory",
    "Uploaded assets via FTPS"
  ]
}
```

---

<a name="tiếng-việt"></a>
## Tiếng Việt

### Kiến Trúc Hệ Thống

Hệ thống được thiết kế theo 3 tầng độc lập:

1. **Tầng Giao Tiếp UAPI & FTP (`scripts/cpanel-api.js`, `scripts/ftp-deploy.js`)**: Trừu tượng hóa cPanel Universal API và các luồng truyền nhận file FTPS/TLS với cơ chế chuẩn hóa đường dẫn tuyệt đối và giải phóng tài nguyên tự động.
2. **Tầng Điều Khiển CLI (`scripts/cli.js`, `scripts/setup.js`)**: Điều phối quy trình build/deploy, tự động phát hiện thư mục bundle (`dist/`, `build/`) và cung cấp trình wizard cấu hình trực quan.
3. **Tầng Máy Chủ MCP (`scripts/mcp-server.js`)**: Giao thức chuẩn Model Context Protocol hoạt động qua Stdio JSON-RPC, cung cấp 17 công cụ với schema dữ liệu thống nhất cho AI agent.

### Tính Năng Kỹ Thuật

- **Khởi Tạo Subdomain & AutoSSL**: Gọi cPanel UAPI đăng ký subdomain, liên kết Document Root `public_html/<name>`, sinh bản ghi DNS nội bộ và kích hoạt AutoSSL.
- **Triển Khai Tự Động Hóa**: Đồng bộ mã nguồn lên host qua FTPS. Ưu tiên thư mục build biên dịch (`dist/`, `build/`) hoặc thư mục gốc nếu là mã nguồn tĩnh thuần túy.
- **Quản Trị Cơ Sở Dữ Liệu MySQL**: Tự động tạo cơ sở dữ liệu, khởi tạo user tương ứng, sinh mật khẩu an toàn và cấp quyền `ALL PRIVILEGES`.
- **Sao Lưu Trước Deploy & Rollback**: Tải bản snapshot của Document Root về thư mục `backups/<subdomain>/` trước mỗi lần đẩy code mới. Cho phép khôi phục phiên bản cũ khi xảy ra sự cố.
- **Thao Tác File Trực Tiếp**: Liệt kê thư mục, đọc, ghi, tải lên và xóa file trên máy chủ thông qua kết nối FTP mà không cần đăng nhập cPanel File Manager.
- **Chuẩn Hóa Output JSON Schema**: Toàn bộ công cụ trả về định dạng JSON có cấu trúc `{ success, action, message, data, error, timestamp, logs }`.

### Cài Đặt & Cấu Hình

#### Yêu Cầu Môi Trường
- Node.js >= 20.0.0
- Tài khoản hosting cPanel có hỗ trợ API Token (`Manage API Tokens`) và FTP.

#### Bước 1: Clone và Cài Đặt Dependencies
```bash
git clone https://github.com/qu4nc0d3r/cpanel-workspace-hub.git
cd cpanel-workspace-hub
npm install
```

#### Bước 2: Khởi Chạy Wizard Cấu Hình
```bash
npm run setup
```
Trình wizard sẽ yêu cầu nhập thông số hosting, kiểm tra xác thực trực tiếp qua mạng với cả cPanel UAPI và FTP, lưu cấu hình vào `.env` và in đoạn JSON dành cho MCP Client.

#### Bước 3: Kiểm Tra Trạng Thái Kết Nối
```bash
npm run check
```

---

### Cấu Hình MCP Bằng Lệnh

#### 1. Claude Code CLI (Lệnh Trực Tiếp)
```bash
claude mcp add cpanel-hub node /đường/dẫn/tuyệt/đối/scripts/mcp-server.js
```

#### 2. Cursor (`.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "cpanel-hub": {
      "command": "node",
      "args": ["/đường/dẫn/tuyệt/đối/scripts/mcp-server.js"]
    }
  }
}
```

#### 3. Claude Desktop (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "cpanel-hub": {
      "command": "node",
      "args": ["/đường/dẫn/tuyệt/đối/scripts/mcp-server.js"]
    }
  }
}
```

---

### Lệnh Điều Khiển CLI

| Lệnh | Tham số | Mô tả chức năng |
| :--- | :--- | :--- |
| `npm run setup` | Không | Chạy wizard cấu hình tương tác và kiểm tra xác thực hosting |
| `npm run check` | Không | Kiểm tra trạng thái kết nối cPanel UAPI và FTP |
| `npm run project:create` | `<tên-dự-án>` | Tạo subdomain trên cPanel, tạo thư mục dự án và deploy bản đầu tiên |
| `npm run project:deploy` | `<tên-dự-án>` | Tự động snapshot backup và deploy bản cập nhật mới nhất lên hosting |
| `npm run project:rollback` | `<tên-dự-án>` | Khôi phục website về bản backup đã lưu |
| `npm run project:list` | Không | Lấy danh sách toàn bộ subdomain và Document Root từ cPanel |
| `npm run db:create` | `<tên-dự-án>` | Tạo Database MySQL, tạo User riêng, cấp quyền và sinh cấu hình ENV |
| `npm run db:list` | Không | Liệt kê toàn bộ Database MySQL và danh sách User liên kết |
| `npm run db:delete` | `<tên-dự-án>` | Xóa Database và User MySQL của dự án |
| `npm run mcp` | Không | Khởi động máy chủ Stdio MCP Server |

---

### Bảng Đặc Tả 17 MCP Tools

| Phân nhóm | Tên Tool | Mô tả chức năng |
| :--- | :--- | :--- |
| **Xác thực** | `cpanel_configure` | Cấu hình hoặc cập nhật thông tin hosting trực tiếp qua cửa sổ chat |
| | `cpanel_check_status` | Kiểm tra tính hợp lệ của cấu hình và trạng thái kết nối hệ thống |
| **Dự án & Subdomain** | `cpanel_create_project` | Đăng ký subdomain trên cPanel, khởi tạo template và deploy |
| | `cpanel_deploy_project` | Đồng bộ mã nguồn dự án (hoặc dist/build) lên hosting |
| | `cpanel_list_projects` | Lấy danh sách toàn bộ các subdomain đang chạy trên hosting |
| | `cpanel_delete_subdomain` | Xóa subdomain khỏi cPanel thông qua API 2 |
| **Sao Lưu & Rollback** | `cpanel_backup_project` | Tải bản snapshot thư mục Document Root về thư mục cục bộ `backups/` |
| | `cpanel_rollback_project` | Khôi phục website về bản sao lưu chỉ định hoặc mới nhất |
| | `cpanel_list_backups` | Xem danh sách các bản backup cục bộ của một dự án |
| **Cơ Sở Dữ Liệu** | `cpanel_create_database` | Tạo Database MySQL, tạo user riêng và chuỗi kết nối |
| | `cpanel_list_databases` | Liệt kê toàn bộ cơ sở dữ liệu MySQL và user liên kết |
| | `cpanel_delete_database` | Xóa Database MySQL và user liên kết của dự án |
| **Thao Tác File** | `cpanel_list_files` | Xem danh sách file và thư mục tại một đường dẫn remote |
| | `cpanel_read_file` | Đọc nội dung văn bản của file trên hosting |
| | `cpanel_write_file` | Ghi hoặc cập nhật nội dung file trực tiếp trên hosting |
| | `cpanel_upload_file` | Tải file cục bộ lên đường dẫn đích trên hosting |
| | `cpanel_delete_file` | Xóa file hoặc thư mục trên hosting |

---

<a name="testing"></a>
## Testing / Kiểm Thử

Hệ thống được kiểm thử tự động toàn diện qua `node:test`:
```bash
npm test
```

53/53 tests độc lập đạt kết quả 100% PASS:
- `tests/config.test.js`: Kiểm thử phân tích env, chuẩn hóa định dạng và lưu file an toàn.
- `tests/cpanel-api.test.js`: Mock UAPI & API 2, định danh subdomain, xử lý MySQL limits.
- `tests/ftp-deploy.test.js`: Kiểm thử kết nối FTPS, chuẩn hóa đường dẫn và giải phóng socket trong block finally.
- `tests/cli.test.js`: Kiểm thử router, copy đệ quy an toàn và phát hiện bundle dist/build.
- `tests/db-and-backup.test.js`: Kiểm thử quy trình snapshot backup và rollback.
- `tests/mcp-server.test.js`: Kiểm thử chuẩn hóa phản hồi JSON schema và cờ `isError`.

---

<a name="license--credits"></a>
## License & Credits

- **Author**: [qu4nc0d3r](https://github.com/qu4nc0d3r)
- **Live Landing Page**: [https://cpanel-hub.macquan.name.vn/](https://cpanel-hub.macquan.name.vn/)
- **License**: [MIT](LICENSE)