# 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`), чтобы клиент понимал,
что можно звать свободно, а что нет.

## Установка

```bash
pip install -r requirements.txt
```

```bash
copy .env.example .env
```

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

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

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

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

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

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

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

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

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

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

## Запуск

MCP-сервер:

```bash
python server.py
```

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

```bash
python web_ui.py
```

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

```bash
python vizual.py
```

## Ограничения

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

## Лицензия

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