TP-Link Easy Smart Switch MCP

MCP-сервер на TypeScript + Bun для коммутаторов TP-Link и Mercury Easy Smart. Он работает через веб-интерфейс коммутатора и не зависит от SNMP.

Цель по умолчанию: http://192.168.3.10

Установка в качестве плагина Codex

Сначала установите Bun, затем добавьте независимый маркетплейс network-tools и этот плагин:

codex plugin marketplace add qwe7002-ai/net-tool-plugins --ref main
codex plugin add tplink-easy-smart-switch-mcp@net-tool-plugins

После установки запустите новую задачу Codex, чтобы инструменты MCP и навык управления коммутаторами были загружены.

Related MCP server: mcp-omada

Протестированные модели

Текущая реализация протестирована на следующих снимках веб-интерфейса и вызовах статуса только для чтения:

• TP-Link TL-SE2106 по адресу 192.168.3.10, прошивка 1.8.1 Build 20251128 Rel.57341

• Mercury SE106 Pro по адресу 192.168.3.11, прошивка 1.0.0 Build 20240812 Rel.65021

Другие коммутаторы TP-Link или Mercury Easy Smart могут работать, если они используют те же страницы веб-интерфейса и CGI-эндпоинты, но они ещё не проверены.

Подтверждённые особенности устройств

• Интерфейс управления доступен по HTTP 80

• Форма входа отправляется на POST /logon.cgi

• Поля входа: username и зашифрованный password

• Страница входа загружает /cryp_new.js

• Известные переменные веб-интерфейса включают g_product, g_year и encryptType

• Некоторые прошивки предоставляют токен запроса в виде простого числового присваивания, например g_tid=1320064778;, а не строки в кавычках. Другие страницы могут только ссылаться на top.g_tid, поэтому парсеры должны различать присваивания и ссылки.

Инструменты

Инструменты только для чтения:

• get_switch_status: Вернуть сводку статуса коммутатора

• get_port_status: Вернуть статус портов

• get_vlan_status: Вернуть статус VLAN портов, 802.1Q VLAN, PVID и MTU VLAN

• get_trunk_status: Вернуть статус агрегации портов/LAG

• search_mac_address: Запросить mac_address_search.cgi по одному MAC-адресу и вернуть изученный порт/VLAN, если коммутатор содержит запись

• analyze_topology: Проанализировать два или более каскадно подключённых коммутатора и сообщить порт межкоммутаторного канала, связь вышестоящего/нижестоящего и соотношение VLAN через этот канал

Анализ топологии работает так: выполняется вход в каждый коммутатор и запрос к поиску MAC через CGI по управляющему MAC-адресу соседнего коммутатора. Если коммутатор сообщает MAC-адрес соседа на порту, этот порт используется как подтверждение межкоммутаторного канала. Когда поиск MAC не может подтвердить канал, обнаружение переключается на активные пары портов SFP/10G как на предположение с низкой уверенностью, отдавая предпочтение пересечению VLAN и используя живой трафик как решающий фактор. У этих коммутаторов Easy Smart нет LLDP, поэтому доступным сигналом является такая внутриполосная корреляция.

Инструменты настройки CGI:

• configure_mtu_vlan: Сгенерировать или отправить mtuVlanSet.cgi из VlanMtuRpm.htm

• configure_port_vlan: Сгенерировать или отправить pvlanSet.cgi из VlanPortBasicRpm.htm

• configure_8021q_vlan: Сгенерировать или отправить qvlanSet.cgi из Vlan8021QRpm.htm

• configure_vlan_pvid: Сгенерировать или отправить vlanPvidSet.cgi из Vlan8021QPvidRpm.htm

• configure_trunk_group: Сгенерировать или отправить port_trunk_set.cgi / port_trunk_display.cgi из PortTrunkRpm.htm

• save_configuration: Сгенерировать или отправить POST savingconfig.cgi из SavingConfigRpm.htm

Инструменты настройки по умолчанию используют apply: false, что возвращает предварительный просмотр запроса в режиме dry-run и ничего не отправляет. Реальная запись требует выполнения всех следующих условий:

• apply: true

• confirm: "APPLY"

• Успешный вход

• Пройдена проверка правил веб-интерфейса

• Читаемый token/top.g_tid

Установка

bun install

Запуск во время разработки

bun run src/index.ts

Сборка бинарного файла

Windows:

bun run build:win

Текущая платформа:

bun run build

Результат сборки записывается в dist/.

Если MCP-клиент во время initialize всё ещё сообщает о старой версии сервера, его command, вероятно, указывает на старый исполняемый файл. Обновите его на dist/tplink-easy-smart-switch-mcp.exe и перезапустите клиент.

Отладка MCP

Список инструментов MCP:

bun run debug

Вызовите инструмент статуса коммутатора:

bun run debug -- --tool get_switch_status --host 192.168.3.10 --username admin --password your-password
bun run debug -- --tool get_switch_status --host 192.168.3.11

Вызовите инструмент статуса портов:

bun run debug -- --tool get_port_status --host 192.168.3.10 --username admin --password your-password

Предварительно просмотрите запросы настройки без их отправки:

bun run debug -- --tool configure_mtu_vlan --params '{ "enabled": true }'
bun run debug -- --tool configure_port_vlan --params '{ "mode": "set", "vid": 1, "ports": "1,2" }'
bun run debug -- --tool configure_8021q_vlan --params '{ "mode": "set", "vid": 20, "name": "main", "untaggedPorts": "3", "taggedPorts": "5,6" }'
bun run debug -- --tool configure_vlan_pvid --params '{ "pvid": 20, "ports": "3" }'
bun run debug -- --tool configure_trunk_group --params '{ "mode": "set", "group": 1, "ports": "1,2" }'
bun run debug -- --tool save_configuration --params '{}'

Примеры страниц

Снимки только для чтения для разработки хранятся в:

• examples/tplink-192.168.3.10: коммутатор TP-Link Easy Smart по адресу 192.168.3.10

• examples/mercury-192.168.3.11: Mercury SE106 Pro по адресу 192.168.3.11

Они включают страницы VLAN, агрегации каналов, резервного копирования/восстановления конфигурации, сохранения конфигурации, а также pvlan.js, qvlan.js и menuList.js. Эти образцы не содержат значений SessionID или паролей.

Вы также можете отправлять необработанные JSON-RPC-запросы:

bun run debug -- --raw '{ "jsonrpc": "2.0", "id": 99, "method": "tools/list", "params": {} }'

Пример MCP-клиента

{
  "mcpServers": {
    "tplink-easy-smart-switch": {
      "command": "C:\\path\\to\\tplink-easy-smart-switch-mcp.exe",
      "env": {
        "TPLINK_HOST": "192.168.3.10",
        "TPLINK_USERNAME": "admin",
        "TPLINK_PASSWORD": "your-password"
      }
    }
  }
}

Примечания

Содержимое страниц разбирается DOM-парсером и нормализуется в сводки заголовка, формы, фрейма, ссылок, таблиц и текста. Данные о статусе в основном извлекаются из JavaScript-переменных на страницах, таких как MainRpm.htm, VlanPortBasicRpm.htm, Vlan8021QRpm.htm, Vlan8021QPvidRpm.htm, VlanMtuRpm.htm и PortTrunkRpm.htm.

В протестированных прошивках TP-Link TL-SE2106 и Mercury SE106 Pro страница MacSearchRpm.htm представляет собой форму поиска, а не полную выгрузку таблицы коммутации. Поэтому поддерживаемая функция MAC — это search_mac_address, которая следует логике страницы и вызывает mac_address_search.cgi с параметрами txt_macAddress_search, txt_vid_search и token.

Извлечение токена поддерживает взятый в кавычки g_tid, обычный числовой g_tid и скрытые поля token. Скрипт захвата скрывает как взятые в кавычки, так и обычные присваивания g_tid перед сохранением примеров для разработки.

Вызовы CGI настройки используют явный поток подтверждения. Разработка и отладка по умолчанию работают в режиме dry-run. save_configuration также является действием записи; оно следует логике страницы SavingConfigRpm.htm и использует POST savingconfig.cgi, но не отправляет запрос, если явно не подтверждено.