topaz-network-assistant

MCP-сервер для работы с коммутаторами «Топаз»: поиск по документации плюс инструменты сетевой диагностики и генерации конфигураций. Плюс отдельный веб-интерфейс, если MCP-клиента под рукой нет.

Задача была простая по формулировке и муторная по сути. Документация к коммутаторам — большой PDF, где нужная команда есть, но найти её быстро нельзя: поиск по словам не работает, когда не помнишь точного написания, а помнишь только «надо повесить порт в другой VLAN». Инженер каждый раз листает руководство заново.

Сервер даёт языковой модели два умения сразу: искать по этой документации и тут же щупать сеть — пинговать, смотреть таблицы, считать подсети, собирать конфиг. Дипломная работа, доведённая до рабочего состояния.

Два способа запуска

Как MCP-сервер (server.py) — 19 инструментов для любого MCP-клиента, например Claude Desktop. Основной сценарий: модель сама решает, что вызвать.

Как веб-приложение (web_ui.py) — FastAPI на localhost:8080: чат по документации, диагностика и инвентарь в браузере, без MCP-клиента.

Важно не путать: в вебе чат — это обычная RAG-цепочка (найти 5 фрагментов по смыслу → положить в промт → ответить). Она не вызывает инструменты сама. Tool calling есть только в MCP-режиме, и решение о вызове принимает клиент.

Инструменты MCP-сервера

Группа	Инструменты
Документация	topaz_search_docs, topaz_get_chunks
Диагностика	topaz_ping, topaz_batch_ping, topaz_traceroute, topaz_dns_lookup, topaz_check_port, topaz_scan_ports, topaz_whois
Состояние узла	topaz_system_info, topaz_network_interfaces, topaz_routing_table, topaz_arp_table
Расчёты	topaz_subnet_calc
Конфигурации	topaz_generate_vlan_config, topaz_generate_base_config
Инвентарь	topaz_inventory_add, topaz_inventory_list, topaz_inventory_remove

Инструменты, которые дёргают систему, вызываются через subprocess.run() со списком аргументов — shell=True не используется нигде. Хосты и параметры проходят валидацию pydantic до вызова. Каждый инструмент помечен MCP-аннотациями (readOnlyHint, destructiveHint), чтобы клиент понимал, что можно звать свободно, а что нет.

Установка

pip install -r requirements.txt

copy .env.example .env

Заполните EMBED_API_KEY и CHAT_API_KEY. Эмбеддинги и чат-модель могут жить у разных провайдеров — ключи и base_url раздельные.

Проверить настройку:

python -c "import config; print(config.check() or 'всё в порядке')"

Сборка базы знаний

Векторной базы в репозитории нет: она производная от документации вендора, и распространять её вместе с кодом неправильно. Соберите свою из PDF, который у вас есть.

python ingest/extract_commands.py "путь/к/документации.pdf" -o topaz_commands.json

python ingest/clean_commands.py topaz_commands.json -o topaz_clean.json

python ingest/build_index.py topaz_clean.json -d topaz_vector_db

Эмбеддинги для базы считает локальная модель paraphrase-multilingual-MiniLM-L12-v2 — многоязычная взята намеренно, англоязычные на русских технических текстах ищут заметно хуже. За сборку базы провайдеру платить не нужно.

Промежуточный шаг с «починкой» JSON выглядит костылём и им является: извлечение из PDF даёт местами битую структуру, и чинить её оказалось дешевле, чем вылизывать парсер.

Запуск

MCP-сервер:

python server.py

Веб-интерфейс на http://localhost:8080:

python web_ui.py

Посмотреть, как разложилась база (t-SNE в 3D, открывается в браузере):

python vizual.py

Ограничения

• Веб-интерфейс не имеет аутентификации. Он рассчитан на 127.0.0.1, и в .env.example захардкожен именно этот хост. Выставлять его наружу нельзя: инструменты диагностики запускают системные команды.
• Оценочный набор в репозиторий не входит: замер делался в рамках дипломной работы на 1000 подготовленных запросов — ответ модели вводился в реальный коммутатор и проверялся на работоспособность, доля успешных — 95%. Сами запросы и протокол замера остались в тексте ВКР, автоматического харнесса в коде нет.
• Тестов нет. CI нет.
• Генераторы конфигов дают заготовку под синтаксис «Топаз», а не готовый к заливке конфиг. Проверяйте глазами перед применением.
• server.py и web_ui.py — по 1200 строк каждый и заметно дублируют друг друга: инструменты в них реализованы дважды. Просится общий модуль, руки не дошли.
• Часть инструментов зависит от системных утилит (ping, tracert/traceroute, arp) и от платформы. Проверялось на Windows.
• Документация вендора в репозиторий не входит.

Лицензия

Лицензия не выбрана — по умолчанию все права сохранены за автором. Учтите, что документация коммутаторов принадлежит производителю: код публиковать можно, извлечённые из руководства данные — вопрос отдельный.