zyxel-mcp

MCP-сервер, который позволяет AI-клиентам безопасно читать и настраивать коммутаторы серии Zyxel GS1900 с интеллектуальным управлением.

У GS1900 нет REST API или SSH — только веб-интерфейс с большим количеством JavaScript. Этот сервер реконструирует этот интерфейс в 26 типизированных MCP-инструментов, обёрнутых в защитные механизмы, которые позволяют безопасно направлять LLM на производственное сетевое оборудование.

Проверено на GS1900-24E, прошивка V2.40(AAHK.1).

Почему нужны защитные механизмы

LLM, перенастраивающий коммутатор, может легко отрезать собственный путь управления — одна неверная PVID на аплинк-порту, и устройство становится доступным только при физическом подключении к нему. Поэтому этот сервер отказывает на уровне HTTP в любой операции, которая может разорвать связь.

Жёсткие блокировки (без переопределения):

• изменения IP-адреса управления / DNS / шлюза / management-VLAN

• учётные записи пользователей и методы аутентификации

• отключение служб управления HTTP/HTTPS или TELNET/SSH

• восстановление конфигурации, сброс к заводским настройкам, загрузка прошивки

• удаление VLAN 1 или любого VLAN, в котором ещё есть порты-участники

• отключение порта, у которого в данный момент поднят линк

• любая запись на порт, указанный в ZYXEL_PROTECTED_PORTS (аплинки, транки AP)

Дополнительная безопасность:

• Dry-run по умолчанию — каждый инструмент записи принимает dry_run (по умолчанию true) и возвращает разницу между текущим и целевым состоянием, не касаясь коммутатора

• Автоматическое резервное копирование — текущая конфигурация экспортируется перед любой записью

• Журнал аудита — append-only JSONL каждой операции чтения и записи

• Сохранение при записи — успешные записи сохраняются из running в startup

Related MCP server: zyxel-mcp-server

Установка

Требуется Python 3.10+.

git clone git@github.com:hugil/zyxel-mcp.git
cd zyxel-mcp
cp .env.example .env      # then edit .env
uv run mcp-zyxel

Зарегистрируйте в MCP-клиенте через stdio, например, в .vscode/mcp.json:

{
  "servers": {
    "zyxel": {
      "command": "uv",
      "args": ["--directory", "/path/to/zyxel-mcp", "run", "mcp-zyxel"],
      "env": {
        "ZYXEL_HOST": "192.168.1.1",
        "ZYXEL_USER": "admin",
        "ZYXEL_PASSWORD": "...",
        "ZYXEL_PROTECTED_PORTS": "1,4"
      }
    }
  }
}

Конфигурация

Вся конфигурация основана на переменных окружения; см. .env.example.

Снимки, резервные копии и журналы аудита — это операторские данные, не часть этого инструмента. ZYXEL_SYNC_DIR не имеет значения по умолчанию, поэтому они никогда не попадают в это дерево исходников — укажите его вне репозитория.

Инструменты (26)

Чтение — get_system_info, get_port_status, get_port_counters, list_vlans, get_vlan_membership, get_mac_table, get_pvids, get_stp_config, get_lag_config, get_loopguard_config, get_lldp_config, get_port_security_config, get_syslog_config, get_mirror_config, get_running_config_text

Запись (dry-run по умолчанию, авто-бэкап, авто-сохранение) — set_port_vlan_membership, set_pvid, set_port_config, set_system_info, create_vlan, delete_vlan

Обслуживание — backup_config, save_running_to_startup, reboot(ack='REBOOT')

Снимок / синхронизация — sync_snapshot, sync_to_github

Снимки конфигурации

sync_snapshot записывает детерминированное, готовое к восстановлению описание коммутатора в ZYXEL_SYNC_DIR; sync_to_github также коммитит и отправляет его в ZYXEL_SYNC_REMOTE.

$ZYXEL_SYNC_DIR/
  README.md              generated topology: VLAN table, port map,
                         membership matrix, MAC/device inventory
  running-config.cfg     full CLI config, secrets redacted
  annotations.json       hand-edited MAC -> hostname/role/notes,
                         never overwritten by a snapshot
  system.json  vlans.json  ports.json  membership.json
  mac-table.json  inventory.json  lldp-neighbors.json
  running-config.raw.cfg unscrubbed, git-ignored — never committed

Снимки идемпотентны: изменчивые данные (аптайм, настенные часы, загрузка CPU/памяти, порядок MAC-таблицы) удаляются или сортируются, поэтому коммит появляется только при реальном изменении конфигурации.

Перед коммитом редактируются: хэши паролей администратора, community-строки SNMP, ключи RADIUS/TACACS. Серийный номер и диапазон MAC сохраняются для целей RMA.

Сгенерированный README спроектирован так, что если коммутатор выйдет из строя, кто-то сможет купить ту же модель и восстановить сеть только из закоммиченных файлов.

Как это работает

Веб-интерфейс GS1900 полностью управляется через /cgi-bin/dispatcher.cgi:

1. Вход — пароль запутывается JavaScript-кодом страницы входа в строку из 320 символов (символы размещаются в обратном порядке на каждом 7-м индексе, цифры длины на фиксированных смещениях 123 и 289, остальное случайно). Это переписано в encode_password().

2. Сессия — опрашивайте login_chk=1 до получения OK, затем извлекайте токен XSSID из загрузочной страницы cmd=1. Он должен отправляться и как cookie, и как скрытое поле формы при каждой записи. На пользователя существует только одна веб-сессия, поэтому клиент очищает устаревшие сессии перед аутентификацией.

3. Страницы — каждая функция имеет целочисленный идентификатор cmd, например, 799 статус порта, 1283 список VLAN (ajax), 1290/1291/1292 список/редактирование/применение PVID, 1293/1294 просмотр/применение членства в VLAN, 2049 MAC-таблица, 5899 сохранение running→startup.

4. Записи членства должны повторять текущий выбор каждой строки плюс скрытые поля vlanMode_N, иначе неотправленные строки молча сбрасываются.

contrib/ содержит небольшие автономные скрипты, использовавшиеся при реверс-инжиниринге GUI; это справочный материал, не часть сервера.

Структура

src/mcp_zyxel/
  server.py        MCP tool + resource definitions
  zyxel_client.py  auth, session, XSSID handling, locked-cmd enforcement
  zyxel_ops.py     typed reads/writes per feature page
  safety.py        connectivity lock-outs, protected ports, audit, backups
  sync.py          snapshot, scrubbing, topology README, git push
contrib/           standalone probing scripts (reference)
probe.py           dump dispatcher pages and their form fields

Отказ от ответственности

Не связан с Zyxel. Управление недокументированным веб-GUI по своей сути хрупко — проверяйте поведение на своей версии прошивки и держите dry-run по умолчанию включённым, пока не доверяете ему.

Лицензия

MIT