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-режиме, и решение о вызове принимает клиент.

Related MCP server: whmcs-mcp-server

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

Инструменты, которые дёргают систему, вызываются через 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.

• Документация вендора в репозиторий не входит.

Лицензия

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