forge-tools-lexicomai

MCP-сервер для обслуживания продуктов Lexicom AI на серверах компании. Даёт AI-ассистенту (агенту) инструменты: посмотреть статус продукта, его конфигурацию и лицензию, логи, здоровье, диагностику и список доступных версий в репозитории. Позволяет администратору быстро разбираться с развёрнутыми сервисами и сокращать рутину.

Что такое MCP-сервер коротко. MCP — стандартный протокол подключения AI-ассистентов к инструментам. Этот сервер — небольшая отдельная программа: она читает запросы от ассистента, выполняет действия (по SSH на боевые машины) и возвращает результат. Ассистент вызывает его инструменты по имени — например «покажи статус продукта ups».

---

Что умеет (текущая версия)

Инструмент	Что делает
products_list	Сводка по всем машинам: продукт → машина, состояние, порт, лицензия, версия
service_status	Краткий статус конкретного продукта (unit, порт, состояние, лицензия)
repo_catalog	Список доступных версий продукта в репозитории (ветки release/beta)
base_status	Полнота базовой среды /opt/pve на машине
service_config_get	Top-level ключи config.json продукта (+ наличие примера схемы)
license_get	Содержимое license.json (service, срок, ключ)
license_verify	Проверка лицензии: поля + живой ответ /license/check продукта
service_logs	Хвост журнала продукта (опц. фильтр)
service_health	Живой статус + /openapi.json (жив/версия) + /license/check
service_diagnose	Чек-лист: юнит, порт, лицензия, база /opt/pve
errors_search	Поиск ошибок в журнале продукта за окно времени

Изменения (только при read_only=false + allow_mutate + одобрение)

Инструмент	Что делает
service_install	Установка продукта (асинхронно, возвращает id); по умолчанию последняя версия
service_update	Обновление до последней версии в ветке (backup инсталлятором)
service_uninstall	Удаление продукта
base_ensure	Создание минимальной базы /opt/pve (идемпотентно)
service_config_set	Изменение ключей config.json (точечный путь) + рестарт
license_apply	Запись license.json + проверка через /license/check
service_restart	Перезапуск службы продукта
service_install_status	Прогресс установки по id

Установка идёт асинхронно (возвращает id, прогресс — service_install_status), чтобы не блокировать агента. Для GPU-продуктов (crs, spr) автоматически подхватывается ускоритель (cu13) через nvidia-smi.

Поддерживаемые продукты

acs, ams, cls, crs, llm, qas, res, sbs, see, ses, ses-sip, smc, spr, tts, ups, vds

Не поддерживаются: vllm (open-source), spr5 (легаси), ses-sip-gateway-api (вспомогательные).

Как сервер узнаёт о продуктах

Ничего не «зашито» в код. Все данные берутся из живой системы:

• порт, движок (uvicorn/gunicorn/python/bwrap) и venv — из действующего systemd-юнита (ExecStart) продукта;
• живость и версия — по GET /openapi.json (продукты на FastAPI его отдают);
• лицензия — из license.json + живой проверки GET /license/check;
• версии в репозитории — по web-API SFTPGo (каталог /repos/<продукт>/<ветка>).

Поэтому добавлять/обновлять продукты можно без правки кода — только в конфиге указать, какие продукты на какой машине.

Сборка

go build -o forge-tools-lexicomai .
./forge-tools-lexicomai --health   # → ok (проверка, что сервер живой)
go test -race ./...

Зависимости минимальны: общая библиотека forge-toolkit + официальный Go-SDK MCP. Собранный бинарь forge-tools-lexicomai в репозиторий не коммитится (в .gitignore).

Подключение сервера

Сервер запускается как stdio-процесс (читает/пишет MCP-протокол через стандартные ввод/вывод). В конфиге MCP-хоста указывается команда запуска и флаг -config:

{ "command": "/opt/lexicomai/forge-tools-lexicomai",
  "args": ["-config", "/etc/lexicomai/lexicomai.json"] }

То же самое подходит для любого MCP-клиента.

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

Файл lexicomai.json. Реальные адреса, ключи и пароли в репозиторий не попадают — подставляются переменными окружения ${VAR} (или берутся из локального файла, который не коммитится).

{
  "targets": [
    {
      "alias": "prod",
      "ssh": { "host": "${LEXICOMAI_HOST}", "user": "${LEXICOMAI_USER}",
               "key": "${LEXICOMAI_SSH_KEY}", "port": 22 },
      "products": ["ups", "spr", "cls"],
      "allow_mutate": false
    }
  ],
  "default": "prod",
  "read_only": true,
  "timeout_seconds": 15,
  "max_output_bytes": 4194304,
  "repo": { "base": "https://cloud.connect2ai.net",
            "user": "${SFTPGO_USER}", "pass": "${SFTPGO_PASS}" }
}

Поле	Смысл
targets[]	Управляемые машины: alias (имя), ssh (host/user/key/port), products (что на ней живёт), allow_mutate (разрешены ли изменения)
default	Машина по умолчанию
read_only	Полный запрет мутаций (по умолчанию true)
timeout_seconds	Таймаут одного SSH-вызова/пробы
max_output_bytes	Ограничение размера результата
repo	Доступ к репозиторию дистрибутивов (web-клиент SFTPGo)

Требования: у машины должен быть SSH-доступ по ключу (пользователь с sudo -n); products[] объявляет продукты на машине.

Безопасность

• По умолчанию — только чтение; мутации включаются явно (read_only=false
  • allow_mutate на конкретной машине) и дополнительно требуют одобрения.
• Никаких адресов/подсетей/ключей в коде — всё из конфига/окружения.
• Команды на машине выполняются через sudo -n; пользовательский ввод экранируется; ключ лицензии в выводе маскируется.
• Инструменты ограничены по времени (таймаут) и размеру результата.

Проверено

• go build, go vet, go test -race — зелёные; gofmt — чисто.
• Ручная проверка MCP (T1): initialize → сервер отвечает именем lexicomai, tools/list возвращает инструменты с корректными обязательными параметрами.

Статус

• M1 (готово): каркас + read-only инструменты.
• M3–M5 (готово): установка/обновление/удаление, изменение конфигурации, применение лицензий, база /opt/pve, управление службой — для всех поддерживаемых продуктов. Написано по архитектуре остальных MCP-серверов компании. Live-проверка на боевых машинах — только на стейджинге.