WEDOS WAPI MCP server
by hrnicek
README.md
# WEDOS WAPI MCP server
[MCP](https://modelcontextprotocol.io) server pro [WEDOS WAPI](https://kb.wedos.com/wapi.html). Umožňuje AI asistentům (Claude Desktop, Claude Code, Codex, ChatGPT…) spravovat domény, DNS záznamy a kredit u WEDOS – i napříč více účty.
> Neoficiální projekt, není spojen se společností WEDOS Internet, a.s.
## Co umí
- **Domény** – výpis, detail, kontrola dostupnosti, registrace, prodloužení, transfer, změna nameserverů, odeslání auth-info
- **DNS** – výpis zón a záznamů, přidání / úprava / smazání záznamu, commit zóny, přidání a smazání zóny
- **Kontakty a NSSET** – detail, kontrola dostupnosti handle
- **Účet** – stav kreditu, historie, POLL fronta notifikací
- **Více účtů** – jedna instance serveru, účet se volí parametrem `account`
- **Ochrany** – testovací režim, režim jen pro čtení (globálně i per účet), MCP anotace pro destruktivní akce
- **Fallback** – `wapi_call` zavolá libovolný WAPI příkaz, který nemá vlastní tool
- **Transport** – stdio (lokálně) i Streamable HTTP (vzdáleně, např. pro ChatGPT)
## Požadavky
- Node.js 18+
- Účet u WEDOS s aktivovaným WAPI
## 1. Nastavení WAPI ve WEDOS
V [klientské administraci WEDOS](https://client.wedos.com) → **Můj účet → Nastavení WAPI**:
1. Zaškrtni **Aktivovat WAPI**.
2. Do **Povolené IP adresy** zadej veřejnou IP stroje, ze kterého server poběží (zjistíš přes `curl -4 ifconfig.me`). Více IP odděl mezerou, IPv6 je podporováno.
3. **Způsob notifikací**: nech **POLL fronta**.
4. **Preferovaný protokol**: **JSON**.
5. V sekci **Nastavení hesla** nastav WAPI heslo (je jiné než heslo k účtu).
> Máš-li dynamickou IP (domácí připojení), whitelist po její změně přestane fungovat. Pro trvalý provoz je lepší server se statickou IP.
## 2. Instalace
```bash
git clone https://github.com/hrnicek/wedos-wapi-mcp.git
cd wedos-wapi-mcp
npm install # zároveň spustí build do dist/
```
## 3. Konfigurace
### Jeden účet
Stačí proměnné prostředí:
| Proměnná | Povinná | Popis |
|---|---|---|
| `WEDOS_LOGIN` | ano | Login (e-mail) do WEDOS |
| `WEDOS_WAPI_PASSWORD` | ano | WAPI heslo |
| `WEDOS_TEST_MODE` | ne | `1` = požadavky se posílají s `test: 1`, nic se reálně neprovede |
| `WEDOS_READ_ONLY` | ne | `1` = registrují se jen čtecí tooly |
| `WEDOS_WAPI_URL` | ne | výchozí `https://api.wedos.com/wapi/json` |
| `WEDOS_TIMEOUT_MS` | ne | výchozí `30000` |
### Více účtů
Zkopíruj `accounts.example.json` na `accounts.json` (je v `.gitignore`) a uprav:
```json
{
"default": "hlavni",
"accounts": {
"hlavni": { "label": "Hlavní účet", "login": "ucet@example.cz", "passwordEnv": "WEDOS_PW_HLAVNI" },
"klient": { "label": "Klient s.r.o.", "login": "admin@klient.cz", "passwordEnv": "WEDOS_PW_KLIENT", "readOnly": true }
}
}
```
| Klíč | Popis |
|---|---|
| `default` | účet použitý, když tool nedostane `account` |
| `login` | login do WEDOS |
| `passwordEnv` | název env proměnné s heslem (doporučeno – heslo pak není v souboru) |
| `password` | alternativně heslo přímo v souboru |
| `readOnly` | zápisové tooly pro tento účet vrátí chybu |
| `test` | testovací režim jen pro tento účet |
Server pak spustíš s `WEDOS_ACCOUNTS_FILE=/cesta/k/accounts.json` a hesly v příslušných proměnných. Globální `WEDOS_TEST_MODE` a `WEDOS_READ_ONLY` platí pro všechny účty.
> Povolenou IP je nutné nastavit u **každého** WEDOS účtu zvlášť.
## 4. Připojení do klienta
V příkladech nahraď `/cesta/k/wedos-wapi-mcp` skutečnou cestou.
### Claude Desktop
Settings → Developer → Edit Config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"wedos": {
"command": "node",
"args": ["/cesta/k/wedos-wapi-mcp/dist/index.js"],
"env": {
"WEDOS_ACCOUNTS_FILE": "/cesta/k/wedos-wapi-mcp/accounts.json",
"WEDOS_PW_HLAVNI": "heslo",
"WEDOS_PW_KLIENT": "heslo"
}
}
}
}
```
Poté Claude Desktop úplně ukonči (Cmd+Q) a spusť znovu.
### Claude Code
```bash
claude mcp add wedos -s user \
-e WEDOS_LOGIN=ucet@example.cz \
-e WEDOS_WAPI_PASSWORD='heslo' \
-- node /cesta/k/wedos-wapi-mcp/dist/index.js
```
### Codex
`~/.codex/config.toml`:
```toml
[mcp_servers.wedos]
command = "node"
args = ["/cesta/k/wedos-wapi-mcp/dist/index.js"]
[mcp_servers.wedos.env]
WEDOS_ACCOUNTS_FILE = "/cesta/k/wedos-wapi-mcp/accounts.json"
WEDOS_PW_HLAVNI = "heslo"
WEDOS_PW_KLIENT = "heslo"
```
### ChatGPT (vzdálený server přes HTTP)
ChatGPT neumí spouštět lokální procesy, potřebuje veřejnou HTTPS URL. Server spusť v HTTP režimu na serveru se statickou IP:
```bash
MCP_TRANSPORT=http PORT=3000 HOST=127.0.0.1 \
MCP_PATH_SECRET=$(openssl rand -hex 24) \
WEDOS_ACCOUNTS_FILE=/cesta/k/accounts.json WEDOS_PW_HLAVNI=heslo \
node dist/index.js
```
- Endpoint: `POST /mcp/<MCP_PATH_SECRET>` (Streamable HTTP, stateless), healthcheck `GET /health`.
- Před server dej reverzní proxy s HTTPS (Nginx, Caddy…) a proces spouštěj jako službu (systemd, supervisor, PM2).
- V ChatGPT: Settings → Connectors → Developer mode → Create → URL `https://tvoje-domena.cz/mcp/<secret>`, autentizace „No authentication“.
> **Bezpečnost:** jedinou ochranou je tajný řetězec v URL. Kdo ho zná, má plný přístup k účtům včetně registrace domén za kredit. Vypni access log pro tuto cestu, používej `readOnly` všude, kde nepotřebuješ zápis, a secret pravidelně měň.
## 5. Použití
Ověření spojení:
> pingni wedos
Příklady promptů:
- „Jaké mám WEDOS účty?“
- „Vypiš domény, které expirují do konce roku.“
- „Přidej A záznam `test.example.cz` → `1.2.3.4` s TTL 300.“
- „Smaž TXT záznam pro `_acme-challenge` na example.cz na účtu klient.“
- „Kolik mám kreditu?“
Bez uvedení účtu se použije výchozí. Každá odpověď obsahuje pole `account`, takže je vidět, nad kterým účtem akce proběhla.
## Přehled toolů
| Tool | Typ | WAPI příkaz |
|---|---|---|
| `accounts_list` | čtení | – |
| `wapi_ping` | čtení | `ping` |
| `credit_info` | čtení | `credit-info` |
| `account_list` | čtení | `account-list` |
| `poll_req` / `poll_ack` | čtení / zápis | `poll-req` / `poll-ack` |
| `domains_list` | čtení | `domains-list` |
| `domain_info` | čtení | `domain-info` |
| `domain_check` | čtení | `domain-check` |
| `domain_transfer_check` | čtení | `domain-transfer-check` |
| `domain_create` | zápis, **účtuje kredit** | `domain-create` |
| `domain_renew` | zápis, **účtuje kredit** | `domain-renew` |
| `domain_transfer` | zápis, **účtuje kredit** | `domain-transfer` |
| `domain_update_ns` | destruktivní | `domain-update-ns` |
| `domain_send_auth_info` | zápis | `domain-send-auth-info` |
| `contact_info` / `contact_check` | čtení | `contact-info` / `contact-check` |
| `nsset_info` | čtení | `nsset-info` |
| `dns_domains_list` | čtení | `dns-domains-list` |
| `dns_domain_info` | čtení | `dns-domain-info` |
| `dns_rows_list` | čtení | `dns-rows-list` |
| `dns_row_detail` | čtení | `dns-row-detail` |
| `dns_domain_add` | zápis | `dns-domain-add` |
| `dns_domain_delete` | destruktivní | `dns-domain-delete` |
| `dns_row_add` | zápis | `dns-row-add` |
| `dns_row_update` | destruktivní | `dns-row-update` |
| `dns_row_delete` | destruktivní | `dns-row-delete` |
| `dns_domain_commit` | zápis | `dns-domain-commit` |
| `wapi_call` | destruktivní | libovolný |
DNS zápisové tooly po změně automaticky volají `dns-domain-commit`; vypneš parametrem `commit: false` (např. při dávce více změn).
## Jak to funguje
- Požadavek jde jako `POST` na `https://api.wedos.com/wapi/json` s polem `request` obsahujícím JSON.
- Autentizace: `auth = sha1(login + sha1(wapi_heslo) + HH)`, kde `HH` je aktuální hodina v časové zóně `Europe/Prague`.
- Kódy `1000` = OK, `1001` = přijato asynchronně (výsledek přijde do POLL fronty), `>= 2000` = chyba – tool vrátí `isError` i s plnou odpovědí.
## Řešení problémů
| Problém | Příčina / řešení |
|---|---|
| Chyba autentizace | IP není ve whitelistu, špatné WAPI heslo, nebo požadavek padl přesně na přelom hodiny – zopakuj |
| `fetch failed` / timeout | Síťová chyba nebo blokace IP po překročení rate limitu – počkej a zkus znovu |
| `Account "x" is read-only` | Účet má v `accounts.json` `readOnly: true` |
| Klient tooly nevidí | Zkontroluj cestu k `dist/index.js`, spusť `npm run build`, restartuj klienta |
| Nesedí parametry příkazu | Ověř v [dokumentaci WAPI](https://kb.wedos.com/wapi.html) a případně použij `wapi_call` |
## Vývoj
```bash
npm run dev # tsc --watch
npm run build
```
Struktura:
- `src/wapi.ts` – HTTP klient pro WAPI (autentizace, chyby, timeout)
- `src/accounts.ts` – načítání účtů z env / `accounts.json`
- `src/index.ts` – registrace MCP toolů, stdio a HTTP transport
## Licence
MIT
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues