cpanel-workspace-hub

# cPanel Workspace Hub

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/

Navigation

• English Documentation

  • Architecture

  • Core Capabilities

  • Installation & Setup

  • MCP Client Configuration

  • CLI Reference

  • MCP Toolset (17 Tools)

  • Response Schema Contract

  • Testing

• Tài Liệu Tiếng Việt

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

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

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

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

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

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

  • Kiểm Thử

• License & Credits

Related MCP server: cPanel MCP Server

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

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:

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):

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

npm run check

MCP Client Configuration

1. Claude Code CLI (Single Command)

claude mcp add cpanel-hub node /absolute/path/to/cpanel-workspace-hub/scripts/mcp-server.js

2. Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "cpanel-hub": {
      "command": "node",
      "args": ["/absolute/path/to/cpanel-workspace-hub/scripts/mcp-server.js"]
    }
  }
}

3. Claude Desktop (claude_desktop_config.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:

{
  "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

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:

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):

{
  "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"
  ]
}

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

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

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

npm run check

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

1. Claude Code CLI (Lệnh Trực Tiếp)

claude mcp add cpanel-hub node /đường/dẫn/tuyệt/đối/scripts/mcp-server.js

2. Cursor (.cursor/mcp.json)

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

3. Claude Desktop (claude_desktop_config.json)

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

Lệnh Điều Khiển CLI

Bảng Đặc Tả 17 MCP Tools

Testing / Kiểm Thử

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

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.

License & Credits

• Author: qu4nc0d3r

• Live Landing Page: https://cpanel-hub.macquan.name.vn/

• License: MIT