# cPanel MCP Server

Serwer MCP (`stdio`) udostępniający agentowi narzędzia do zarządzania zwykłym kontem cPanel przez UAPI oraz serwerem cPanel & WHM przez WHM API 1. Jedna konfiguracja może zawierać wiele hostingów działających w trybie `cpanel`, `whm` albo `both`.

Serwer ma ponad 50 nazwanych operacji dla domen, DNS, poczty, baz MySQL, plików, cron, SSL, PHP, kopii zapasowych, kont hostingowych i usług. Opcjonalne narzędzia ogólne pozwalają wywołać funkcje dodane w nowszych wersjach cPanelu bez aktualizowania serwera MCP.

## Wymagania i instalacja

- Node.js 20 lub nowszy,
- konto cPanel lub użytkownik WHM z tokenem API albo hasłem,
- dostęp sieciowy do portu `2083` (cPanel) lub `2087` (WHM).

```bash
npm install
npm run build
cp .example-connections.json connections.json
chmod 600 connections.json
```

## Konfiguracja MCP

Wspólny plik `connections.json` ma dokładnie trzy poziomy: `serwer → środowisko → logiczna nazwa konta`. Dzięki temu jeden proces MCP może obsługiwać dowolną liczbę cPaneli i serwerów WHM, pogrupowanych np. według firmy i środowiska. Token lub hasło najlepiej wskazywać przez `tokenEnv` albo `passwordEnv`, dzięki czemu sekret nie znajduje się w pliku.

```json
{
  "company": {
    "development": {
      "website": {
        "name": "Website DEV",
        "description": "Development cPanel account",
        "tags": ["website", "dev"],
        "baseUrl": "https://dev-panel.example.com",
        "username": "devuser",
        "passwordEnv": "CPANEL_DEV_PASSWORD",
        "mode": "cpanel"
      }
    },
    "production": {
      "website": {
        "name": "Website PROD",
        "tags": ["website", "prod", "critical"],
        "baseUrl": "https://panel.example.com",
        "username": "produser",
        "tokenEnv": "CPANEL_PROD_TOKEN",
        "mode": "cpanel",
        "cpanelPort": 2083,
        "timeoutMillis": 30000,
        "allowInsecureTls": false
      },
      "server-admin": {
        "name": "Production WHM",
        "baseUrl": "https://whm.example.com",
        "username": "root",
        "tokenEnv": "WHM_PROD_TOKEN",
        "mode": "whm",
        "whmPort": 2087
      }
    }
  }
}
```

Ten sam przykład znajduje się w [`.example-connections.json`](.example-connections.json). Pokazuje konto DEV logowane hasłem i konta produkcyjne logowane tokenami. W wywołaniu narzędzia konto produkcyjne wybiera się przez `server: "company"`, `environment: "production"`, `account: "website"`. Klucz `account` jest logiczną nazwą połączenia, a nie nazwą użytkownika cPanel.

| Opcja | Argument CLI | Zmienna środowiskowa | Domyślna / znaczenie |
|---|---|---|---|
| plik połączeń | `--config PATH` | `CPANEL_MCP_CONFIG` | wymagany |
| tylko odczyt | `--readonly true\|false` | `CPANEL_MCP_READONLY` | `true` |
| ogólne wywołania API | `--allow-raw-api true\|false` | `CPANEL_MCP_ALLOW_RAW_API` | `false` |

Argument CLI ma pierwszeństwo przed odpowiadającą mu zmienną. `mode: "both"` zakłada, że ten sam host, użytkownik i token mogą uwierzytelnić oba interfejsy. Gdy cPanel i WHM używają innych danych logowania, skonfiguruj je jako dwa konta logiczne. Plik `connections.json` znajduje się w `.gitignore` i powinien mieć uprawnienia `600`.

### Opcje konta w konfiguracji JSON

| Pole | Wymagane | Znaczenie |
|---|---:|---|
| `baseUrl` | tak | adres panelu; port jest zastępowany przez `cpanelPort` lub `whmPort` |
| `username` | tak | użytkownik cPanel albo WHM |
| `tokenEnv` / `token` | alternatywnie | nazwa zmiennej z tokenem albo token wpisany bezpośrednio |
| `passwordEnv` / `password` | alternatywnie | nazwa zmiennej z hasłem albo hasło wpisane bezpośrednio; wymaga HTTPS |
| `mode` | nie | `cpanel`, `whm` lub `both`; domyślnie `cpanel` |
| `cpanelPort` / `whmPort` | nie | domyślnie `2083` / `2087` |
| `timeoutMillis` | nie | limit żądania, domyślnie 30 sekund |
| `allowInsecureTls` | nie | wyłącza weryfikację certyfikatu tylko dla tej instancji; domyślnie `false` |
| `allowedCpanelModules` | nie | allowlista modułów UAPI |
| `allowedWhmFunctions` | nie | allowlista funkcji WHM API 1 |

Każde konto musi mieć dokładnie jedną metodę uwierzytelnienia: `token`, `tokenEnv`, `password` albo `passwordEnv`. Preferowane są warianty `*Env`. Przy haśle serwer wysyła standardowy nagłówek HTTP Basic Authentication do cPanelu lub WHM; połączenie inne niż HTTPS jest odrzucane. `allowInsecureTls: true` nadal szyfruje ruch, ale nie weryfikuje certyfikatu i powinno być jedynie rozwiązaniem awaryjnym.

### Uruchomienie bez klienta MCP

```bash
export CPANEL_DEV_PASSWORD='PASSWORD'
export CPANEL_PROD_TOKEN='TOKEN'
export WHM_PROD_TOKEN='TOKEN'
node dist/index.js --config ./connections.json --readonly true --allow-raw-api false
```

Proces czeka na komunikaty MCP na standardowym wejściu.

### Visual Studio Code (GitHub Copilot)

Dodaj `.vscode/mcp.json` albo użyj polecenia **MCP: Open User Configuration**:

```json
{
  "inputs": [{ "type": "promptString", "id": "cpanel-token", "description": "cPanel API token", "password": true }],
  "servers": {
    "cpanel": {
      "type": "stdio",
      "command": "/usr/bin/node",
      "args": ["/home/USER/src/cpanel-mcp-server/dist/index.js", "--config", "/home/USER/.config/cpanel-mcp/connections.json", "--readonly", "true"],
      "env": { "CPANEL_PROD_TOKEN": "${input:cpanel-token}" }
    }
  }
}
```

### Visual Studio (GitHub Copilot)

Visual Studio odczytuje `%USERPROFILE%\.mcp.json` albo plik `.mcp.json` rozwiązania. Użyj tego samego obiektu serwera co powyżej, zmieniając `command` i ścieżkę skryptu na ścieżki Windows. Nie zapisuj prawdziwego tokenu w repozytorium.

### Codex w Visual Studio Code

Codex CLI i rozszerzenie IDE współdzielą `~/.codex/config.toml`:

```toml
[mcp_servers.cpanel]
command = "/usr/bin/node"
args = ["/home/USER/src/cpanel-mcp-server/dist/index.js", "--config", "/home/USER/.config/cpanel-mcp/connections.json", "--readonly", "true"]
env = { CPANEL_PROD_TOKEN = "TOKEN" }
startup_timeout_sec = 10
tool_timeout_sec = 60
enabled = true
default_tools_approval_mode = "writes"
```

### PhpStorm (JetBrains AI Assistant)

Otwórz **Settings → Tools → AI Assistant → Model Context Protocol (MCP)**, dodaj połączenie STDIO i użyj konfiguracji `mcpServers` analogicznej do przykładu VS Code. Ustaw bezwzględne ścieżki do `dist/index.js` i `connections.json` oraz zmienne z sekretami wskazane przez `tokenEnv` lub `passwordEnv`.

### Codex w PhpStorm

Skonfiguruj serwer w JetBrains AI Assistant, a podczas aktywowania agenta Codex włącz **Pass custom MCP servers**. Alternatywnie uruchom Codex CLI z konfiguracją TOML z poprzedniej sekcji.

### Wygasły lub niezaufany certyfikat TLS

Najbezpieczniej zainstalować prawidłowy certyfikat panelu. Awaryjnie można ustawić `allowInsecureTls: true` tylko dla konkretnej instancji. Nie wyłącza to TLS, ale wyłącza weryfikację tożsamości serwera i ułatwia atak man-in-the-middle.

## Healthcheck

`healthcheck` z `deep=false` sprawdza proces i konfigurację bez połączenia z hostingiem. `deep=true` odpytuje każde połączenie przez UAPI `Variables::get_user_information` lub WHM `version`. Wynik identyfikuje je przez `server`, `environment` i `account`, ale nie zawiera tokenów.

## Narzędzia

Każde narzędzie wskazuje połączenie przez `server`, `environment` i `account` oraz przyjmuje obiekt `parameters` zgodny z parametrami odpowiedniej funkcji cPanel. `list_connections` pokazuje wszystkie trzy poziomy i metadane bez sekretów. Zwracany jest JSON znormalizowany z typowych kopert UAPI/WHM.

### cPanel UAPI

- konto, domeny i statystyki: `cpanel_get_account_information`, `cpanel_list_domains`, `cpanel_get_domain_data`, `cpanel_get_resource_usage`,
- DNS: listowanie, dodawanie, edycja i usuwanie rekordów,
- poczta: konta, hasła, limity, forwardery i autorespondery,
- MySQL: bazy, użytkownicy i uprawnienia,
- pliki: listowanie, odczyt, zapis, tworzenie katalogów i usuwanie,
- cron, certyfikaty SSL, wersje PHP oraz pełny backup konta.

### WHM API 1

- wersja serwera, lista i podsumowanie kont,
- tworzenie, modyfikacja, zawieszanie, odwieszanie i usuwanie kont,
- pakiety hostingowe,
- strefy DNS i rekordy,
- SSL vhosty oraz instalacja certyfikatów,
- status i restart usług, wykorzystanie dysku oraz tymczasowe sesje użytkowników.

Pełną listę nazwanych narzędzi zawiera [`src/catalog.ts`](src/catalog.ts). Ich `parameters` pozostają elastyczne, ponieważ dostępność i argumenty funkcji zależą od wersji cPanelu, profilu serwera i uprawnień tokenu.

### Funkcje spoza katalogu

`cpanel_uapi_call` i `whm_api_call` są dostępne dopiero po ustawieniu `CPANEL_MCP_ALLOW_RAW_API=true`. Wymagają jawnego `mutation: true|false`; mutacje nadal respektują tryb `READONLY`. Allowlisty instancji obowiązują również te narzędzia.

## READONLY i bezpieczeństwo

Serwer domyślnie uruchamia się z `READONLY=true`. Nazwane mutacje oraz ogólne wywołania zadeklarowane jako mutacje są wtedy blokowane przed wysłaniem żądania.

- preferuj tokeny o najmniejszych niezbędnych uprawnieniach; jeśli panel nie udostępnia tokenów, przechowuj hasło przez `passwordEnv`,
- osobno konfiguruj cPanel i WHM, jeśli mają różne dane logowania,
- stosuj `allowedCpanelModules` i `allowedWhmFunctions` w środowiskach produkcyjnych,
- pozostaw ogólne API wyłączone, jeśli nazwane narzędzia wystarczają,
- wymagaj potwierdzenia klienta MCP dla narzędzi usuwających konta, pliki, DNS i bazy,
- nie zapisuj hasła cPanel/WHM, haseł skrzynek, baz ani kluczy prywatnych w repozytorium lub parametrach narzędzi.

Uwaga: cPanel nie udostępnia metadanych określających, czy dowolna funkcja API modyfikuje stan. W ogólnych narzędziach prawidłowa wartość `mutation` jest odpowiedzialnością wywołującego; allowlisty zapewniają dodatkową granicę bezpieczeństwa.

## Wartości ograniczone parametrów

Nazwy modułów, funkcji i parametrów API są walidowane. Ścieżka oraz host żądania są konstruowane wyłącznie z konfiguracji, więc parametry narzędzia nie mogą przekierować żądania na inny serwer. Timeout ma maksymalnie 300 sekund. Tokeny nie są zwracane przez `list_connections`, błędy ani healthcheck.

## Testy

```bash
npm run check
```

Testy jednostkowe nie wymagają prawdziwego serwera cPanel. Sprawdzają adresy UAPI/WHM, schemat autoryzacji, dane formularzy, tryby API, allowlisty, ochronę sekretów, domyślne ustawienia i pokrycie katalogu operacji.

Test integracyjny z hostingiem należy rozpocząć od `--readonly true`, `healthcheck(deep=true)` i narzędzi listujących. Konkretne funkcje mogą być niedostępne zależnie od licencji, wersji, profilu WHM i uprawnień konta.