ArubaOS-CX MCP Server (hpe-cx-mcp)

Сервер Model Context Protocol (MCP), который предоставляет коммутаторы Aruba CX (AOS-CX) MCP-совместимым ИИ-агентам (Claude, VS Code Copilot и др.). Он превращает REST API коммутатора (/rest/v10.x) и SSH CLI в набор безопасных структурированных инструментов для наблюдаемости, устранения неполадок и конфигурации кампусной / ЦОД-фабрики (VLAN, маршрутизация, BGP/OSPF, EVPN-VXLAN, VSX/VSF, портовый доступ / 802.1X, NAE, ARC…).

Сервер работает как Docker-контейнер, общается по MCP через streamable HTTP и поставляется с опциональной именованной аутентификацией по Bearer-токену и JSON-журналированием аудита.

Быстрый старт

cd cx-mcp

# 1) Provide credentials (git-ignored)
cp .env.example .env                 # then edit: set ARUBA_DEFAULT_PASSWORD (and any source tokens)

# 2) Provide the device list (git-ignored)
cp inventory/inventory.example.yaml inventory/inventory.yaml   # then edit: your switches & IPs

# 3) Build and start
docker compose up -d --build

# 4) Watch it come up
docker compose logs -f hpe-cx-mcp    # wait for "✅ hpe-cx-mcp server is up and running"

Конечная точка MCP затем доступна по адресу http://<docker-host>:8002/mcp. Направьте ваш MCP-клиент на неё (см. §9). Полные подробности и заметки по платформам — в §3.

Related MCP server: API-Central

Содержание

1. Что делает этот сервер

2. Доступные инструменты

3. Установка (macOS / Linux / Windows)

4. Тома

5. Переменные окружения

6. Управление инвентарём

7. Безопасность: Bearer-аутентификация и журналирование аудита

8. Управление токенами

9. Подключение MCP-клиента

1. Что делает этот сервер

• Единая точка входа к парку коммутаторов AOS-CX, описанных в инвентаре.

• Чтение (наблюдение): интерфейсы, VLAN, таблицы маршрутизации/ARP/MAC, BGP/OSPF/EVPN, туннели VXLAN, состояние стеков VSX/VSF, состояние оборудования, журналы, 802.1X / портовый доступ, скрипты NAE, распознавание приложений (ARC), полные конфигурации.

• Запись (конфигурация): VLAN-сервисы, loopback, маршрутизируемые порты, VRF, BGP, OSPF, EVPN/VXLAN, аутентификация портов, виртуальный MAC, ARC — каждый в паре с инструментом обратного чтения verify_*.

• Защитные механизмы:

  • Поустройственный access_mode (read-only по умолчанию; запись запрещена, если устройство явно не помечено read-write).

  • Операции, ограниченные площадкой (параметр site) для действия на группу устройств.

  • Обнаружение SSH-команд записи для блокировки изменений конфигурации через сырой CLI на устройствах только для чтения.

• Динамический инвентарь: объединение локального файла с источниками истины NetBox / Nautobot, с опциональным разрешением учётных данных через HashiCorp Vault.

2. Доступные инструменты

Инструменты сгруппированы по назначению. Инструменты чтения требуют доступности устройства; инструменты записи дополнительно требуют, чтобы устройство было read-write.

Инвентарь и сеансы

Сырой доступ (запасные пути)

Система и оборудование

get_system_info, get_hardware_health, get_boot_history, get_transceivers, get_ssh_config, get_logs.

Контейнеры и лицензирование

get_containers (прикладные контейнеры на коммутаторе: статус, образ, лимиты CPU/памяти, сети VRF), get_feature_pack (состояние лицензирования / подписки: режим управления, срок действия, истечение, контроль по функциям).

Облачное управление

get_aruba_central (состояние подключения HPE ANW Central / Aruba Central: подключено, инстанцирование, источник конфигурации, местоположение, VRF/исходный IP, связь с Activate).

Состояние L2 / L3

get_interfaces, get_loopbacks, get_routed_ports, get_vlan_interfaces, get_vlans, get_lldp_neighbors, get_mac_table, get_arp_table, get_routing_table, get_spanning_tree.

Протоколы маршрутизации

get_bgp_neighbors, get_bgp_config, get_bgp_routes, get_ospf_overview, get_ospf_neighbors, get_ospf_interfaces.

EVPN / VXLAN

get_evpn_config, get_evpn_routes, get_evpn_multihoming, get_vxlan_config, get_vxlan_tunnels, get_vxlan_static_peers, get_evpn_vtep_neighbors.

Высокая доступность (VSX / VSF)

get_vsx_status, get_vsx_config, get_vsx_sync, get_vsf_status, get_vsf_config, get_maintenance_mode.

NAE (Network Analytics Engine)

get_nae_scripts, get_nae_script, get_nae_agents, get_nae_agent.

Портовый доступ / AAA / 802.1X

get_port_access_clients, get_port_access_client_detail, get_port_access_auth_config, get_port_access_summary, get_port_access_policies, get_port_access_roles, get_port_access_gbps, get_gbp_role_maps, get_port_access_abps, get_radius_servers, get_tacacs_servers, get_aaa_authentication, get_aaa_accounting.

Распознавание и контроль приложений (ARC)

get_app_recognition, get_app_visibility.

Управление конфигурацией

list_configs, get_config, get_full_config, compare_configs, manage_config (сохранение / контрольная точка / откат).

Настройка (запись) + пары проверки

У каждого инструмента configure_* есть парный инструмент обратного чтения verify_*:

Защита от записи: вызов configure_* / create_* / delete_* / manage_config на устройстве read-only отклоняется. Пометьте устройство access_mode: read-write в инвентаре, чтобы разрешить изменения.

Предоставление инструментов: плоский набор (по умолчанию) против устаревших атомарных инструментов

Сервер может предоставлять свои возможности двумя взаимоисключающими способами, выбираемыми флагом CX_FLAT_TOOLSET (см. §5):

Плоский набор (CX_FLAT_TOOLSET=true — по умолчанию). Перечисленные выше ~101 атомарный инструмент свёрнуты в ~23 плоских диспетчера, управляемых аргументом scope (а для записи — ещё и action). Базовый код REST-клиента не меняется — диспетчеры только маршрутизируют к нему, поэтому регрессий в поведении нет. Каждый диспетчер чтения также принимает device: str | list, site или source (внешний запрос к источнику истины) и разворачивает вызов параллельно, возвращая один конверт {scope, results, errors, summary}. Опциональный limit ограничивает длинные поля списков в ответе.

Плюс 7 сохраняемых атомарных инструментов: list_devices, list_sites, get_logs, run_ssh_commands, manage_config, logout, rollback. Диспетчеры записи сохраняют жизненный цикл plan → apply → verify и защиту от записи на уровне устройства. Поля домена передаются в объекте params (ключи описаны в docstring каждого диспетчера).

Устаревшие атомарные инструменты (CX_FLAT_TOOLSET=false). Вместо этого предоставляется полный каталог инструментов, описанный выше, при необходимости формируемый тремя уровнями ниже. Используйте это для мгновенного отката к прежнему поведению.

Прогрессивное раскрытие, функциональные префиксы и безопасность записи (только устаревший режим)

Три необязательных уровня (активны только при CX_FLAT_TOOLSET=false, каждый управляется собственным флагом окружения — см. §5) определяют, как предоставляются устаревшие инструменты:

1. Прогрессивное раскрытие (CX_DEFERRED_TOOLS) — вместо рекламы полного каталога (100+ инструментов) сервер публикует только ~27 Tier-1 инструментов (наиболее часто используемые инструменты чтения/диагностики, запасные выходы, оркестраторы и мета-инструменты). Все остальные инструменты отложены (Tier-2) и доступны по запросу через два мета-инструмента:

Это сохраняет список инструментов агента небольшим и недорогим, оставляя всю поверхность доступной.

2. Функциональные префиксы (CX_TOOL_PREFIXES) — рекламируемые инструменты переименовываются в <domain>__<tool> для группировки по доменам, например routing__get_bgp_neighbors, overlay__configure_evpn, service__create_vlan_service, meta__invoke_tool. Домены: inventory, exec, system, interface, switching, routing, overlay, redundancy, security, app, nae, config, service, meta. invoke_tool принимает как префиксное, так и простое имя.

3. Безопасность записи (CX_WRITE_SAFETY) — рабочий процесс предпросмотра→применения с откатом:

Рабочий процесс: вызовите любой инструмент записи с apply=false (по умолчанию), чтобы получить план и dry_run_token; затем вызовите apply_plan(dry_run_token=…), чтобы применить именно этот план. Идемпотентные слияния configure_* не имеют автоматического обратного действия и сообщаются как unsupported через rollback. Когда CX_REQUIRE_DRY_RUN_TOKEN=true, прямое применение (apply=true) через invoke_tool отклоняется — вызывающие должны пройти через путь предпросмотра→apply_plan.

3. Установка (macOS / Linux / Windows)

Предварительные требования

• Docker и Docker Compose v2 (docker compose …).

  • macOS / Windows: Docker Desktop.

  • Linux: Docker Engine + плагин Compose.

• Сетевая доступность от хоста Docker до управляющих IP-адресов коммутаторов (HTTPS/443 для REST, TCP/22 для SSH).

• Доступ REST должен быть настроен на целевых устройствах и в правильном VRF: в режиме Read-Write для доступа на чтение и запись, и в режиме Read-only для доступа только на чтение.

• Доступ SSH также должен быть настроен на целевых устройствах для инструментов, которые его требуют.

Настройка (первый запуск)

Секреты и параметры развёртывания находятся вне docker-compose.yml, в файлах, которые игнорируются git, чтобы они никогда не были закоммичены. Поставляются два шаблона — скопируйте каждый и заполните его:

cd cx-mcp

# 1) Credentials & external source tokens  →  .env  (git-ignored)
cp .env.example .env
#    then edit .env and set at least ARUBA_DEFAULT_PASSWORD

# 2) Device inventory  →  inventory/inventory.yaml  (git-ignored)
cp inventory/inventory.example.yaml inventory/inventory.yaml
#    then edit it: list your switches, their IPs and per-device access_mode

.env внедряется в контейнер через env_file: в docker-compose.yml. Минимальное содержимое (полный список см. в .env.example):

ARUBA_DEFAULT_USERNAME=admin
ARUBA_DEFAULT_PASSWORD=your-switch-password
ARUBA_API_VERSION=latest
# Optional external sources of truth (leave empty if unused):
NETBOX_URL=
NETBOX_TOKEN=
INFRAHUB_URL=
INFRAHUB_TOKEN=

Никогда не коммитьте .env или inventory/inventory.yaml — они содержат реальные учётные данные и IP-адреса устройств. Только шаблоны *.example отслеживаются git.

Сборка и запуск (все платформы)

cd cx-mcp
docker compose up -d --build

Сервер прослушивает http://<host>:8002/mcp (порт хоста 8002 → контейнер 8000, см. docker-compose.yml). Образ собирается как hpe-cx-mcp:latest и запускается как контейнер hpe-cx-mcp.

Проверьте, что он работает:

docker compose logs -f hpe-cx-mcp
# look for, in order:
#   "Uvicorn running on http://0.0.0.0:8000"
#   "✅ hpe-cx-mcp server is up and running on http://0.0.0.0:8000 — if your agent
#    already has an open MCP connection, reset it (MCP: Disconnect → Connect) …"

Строка ✅ … server is up and running выводится, когда слушатель готов. Если запуск завершается сбоем, сервер регистрирует ❌ hpe-cx-mcp server failed to start с полной трассировкой (затем завершается с ненулевым кодом).

Примечание: каждый docker compose up -d --build пересобирает образ и перезапускает сервер, что делает недействительной любую существующую MCP-сессию. После пересборки переподключите клиент (MCP: Disconnect → Connect), чтобы получить актуальные инструменты.

Примечания по платформам

Linux

• Смонтированные папки принадлежат вашему пользователю хоста. Контейнер работает как uid 1000; если ваш пользователь хоста не uid 1000, сделайте записываемые папки читаемыми/записываемыми для uid 1000:

  mkdir -p logs secrets
  sudo chown -R 1000:1000 logs secrets
  chmod 700 secrets

• Чтобы получить доступ к коммутаторам в локальной L2-сети хоста, вы можете раскомментировать network_mode: host в docker-compose.yml (только Linux).

macOS (Docker Desktop)

• Общий доступ к файлам обрабатывается виртуальной машиной; bind-mounts работают из коробки, а переназначение uid автоматическое — в большинстве случаев ручной chown не требуется.

• network_mode: host не поддерживается так же, как на Linux; сохраняйте сопоставление ports: по умолчанию (8002:8000).

Windows (Docker Desktop + WSL2)

• Выполняйте команды из оболочки WSL2 или PowerShell. Настоятельно рекомендуется хранить проект внутри файловой системы WSL2 (например, \\wsl$\… / ~/cx-mcp) для корректных прав на файлы и производительности.

• Используйте прямые слэши в путях томов в docker-compose.yml (./inventory:/app/inventory:ro).

• network_mode: host недоступен; сохраняйте сопоставление ports:.

4. Тома

Три папки хоста монтируются в контейнер:

volumes:
  - ./inventory:/app/inventory:ro
  - ./logs:/app/logs
  - ./secrets:/app/secrets

Код приложения встроен в образ — монтируются только эти папки данных. После изменения любого *.py пересоберите с помощью docker compose up -d --build (простой перезапуск недостаточен).

Владение (Linux): logs/ и secrets/ должны быть доступны для записи контейнерному uid 1000. secrets/ должен быть 0700, а его файл .tokens записывается сервером с правами 0600.

5. Переменные окружения

Секреты и значения, зависящие от развёртывания (учётные данные, токены внешних источников), предоставляются через игнорируемый git .env файл, который docker-compose.yml загружает через env_file: (скопируйте .env.example в .env, см. §3). Несекретные операционные флаги (MCP_*, CX_*, INVENTORY_FILE) задаются непосредственно в docker-compose.yml в разделе environment:. Логические значения принимают true/1/yes/on.

Транспорт

Учётные данные устройства и API (задаются в .env; можно переопределить для каждого устройства в инвентаре)

Инвентарь и внешние источники

Bearer-аутентификация (необязательно, по умолчанию выключена)

Журналирование аудита (необязательно, по умолчанию выключено)

Прогрессивное раскрытие, префиксы и безопасность записи (необязательно)

6. Управление инвентарём

Файл инвентаря (inventory/inventory.yaml) объявляет устройства и способы доступа к ним. Он исключён из git (в нём реальные IP и учётные данные); создайте его один раз из прилагаемого шаблона:

cp inventory/inventory.example.yaml inventory/inventory.yaml

Значения в файле переопределяют переменные окружения. Поддерживаемые форматы: YAML, JSON, TOML.

Минимальный пример

defaults:
  username: admin
  password: "secret"
  api_version: latest        # auto-detect the newest REST version
  verify_ssl: false
  timeout: 30
  access_mode: read-only     # writes denied unless overridden per device

devices:
  Spine1:
    host: 192.0.2.21
    description: "Core switch"
    tags: [core, spine]
    site: campus-principal
    access_mode: read-write   # allow configuration changes on this device
  Access-01:
    host: 192.0.2.23
    site: campus-principal

Параметры для каждого устройства

host (обязательно), username, password, api_version, verify_ssl, timeout, tags, description, site, ssh_port, ssh_username, ssh_password, access_mode (read-only | read-write), vault (true для получения учётных данных из Vault).

Сайты

Понятие site необязательно и позволяет инструментам нацеливаться на группу устройств (list_devices(site=…), run_on_site(site, …)). Используйте либо поле site: для каждого устройства, либо блок верхнего уровня sites:, группирующий устройства.

Варианты источников инвентаря

Есть несколько способов определить, откуда берётся список устройств:

1. Только локально (по умолчанию) — устройства из файла:

   source: local        # may be omitted

2. Единый внешний источник — загрузка из источника правды:

   source: netbox
   sources:
     netbox:
       type: netbox            # netbox | nautobot | infrahub
       url: https://netbox.example.com
       token: "<api-token>"    # or via NETBOX_TOKEN env var
       verify_ssl: false

3. Объединённые источники с приоритетом — устройство, присутствующее в нескольких источниках, берётся из источника с более высоким приоритетом:

   source: [local, netbox]
   source_priority: [local, netbox]   # local wins over netbox

Приоритет получения учётных данных (сначала самый высокий):

1. Учётные данные, заданные для конкретного устройства в его записи.

2. HashiCorp Vault (когда vault включён глобально или для устройства).

3. Переменные окружения / значения по умолчанию в инвентаре.

После редактирования инвентаря примените изменения без пересборки с помощью инструмента refresh_inventory или перезапустите контейнер.

Проверка при запуске (fail-fast)

Файл инвентаря проверяется при запуске. Если его не удаётся разобрать (синтаксическая ошибка YAML/JSON/TOML) или он нарушает ожидаемую схему (например, неправильно отступленный ключ source:, или source имеет нестроковое/несписочное значение), сервер регистрирует конкретную ошибку на английском и отказывается запускаться, а не работает молча с пустым или частичным инвентарём:

❌ Inventory file '/app/inventory/inventory.yaml' failed validation — the server will NOT start.
   YAML syntax error: expected '<document start>', but found '<block mapping start>'
     in "<unicode string>", line 22, column 1
   Fix the inventory file, then restart the container.

Контейнер завершается с ненулевым кодом возврата (видно в docker logs / docker compose ps). Исправьте указанную строку и перезапустите. Примечания:

• Отсутствующий файл инвентаря — это только предупреждение (его можно смонтировать позже) — сервер всё равно запускается.

• Недоступность внешних источников (NetBox / Nautobot / Infrahub) не является фатальной: разобранный локальный инвентарь остаётся пригодным, а динамическое объединение деградирует корректно.

• Инструмент времени выполнения refresh_inventory применяет ту же проверку, но никогда не приводит к сбою работающего сервера: при плохом файле он возвращает ошибку и сохраняет ранее загруженный инвентарь.

7. Безопасность: Bearer-аутентификация и журналирование аудита

Обе функции по умолчанию выключены и полностью обратно совместимы.

• Аутентификация (CX_AUTH_ENABLED=true): каждый запрос к /mcp должен содержать Authorization: Bearer <token>. Отсутствующие/недействительные токены получают HTTP 401. Имя токена становится actor, записываемым в журнал аудита, так что вы всегда знаете, кто что сделал. Если аутентификация включена, но токена ещё нет, сервер всё равно запускается, но в режиме LOCKED: каждый MCP-запрос отклоняется с HTTP 503 (fail-closed), так что сервисы недоступны. Создайте первый токен (см. §8) и перезапустите контейнер, чтобы разблокировать — хранилище токенов загружается один раз при запуске.

• Аудит (CX_AUDIT_ENABLED=true): одна JSON-строка на каждый вызов инструмента в logs/audit.jsonl, включая actor, src_ip, tool, category (чтение/запись), целевое device, отредактированные arguments, outcome, HTTP status_code и duration_ms. Секреты (пароли/токены) маскируются.

Включите оба:

# docker-compose.yml
CX_AUTH_ENABLED:  "true"
CX_AUDIT_ENABLED: "true"

docker compose up -d --build

8. Управление токенами

Токены хранятся в secrets/.tokens (права 0600). Управляйте ими внутри работающего контейнера с помощью встроенного CLI:

# Create a named token (prints the secret once — save it)
docker compose exec hpe-cx-mcp python cx_token_manager.py generate --name vscode-dev

# List tokens (names, descriptions, created — secret truncated)
docker compose exec hpe-cx-mcp python cx_token_manager.py list

# Show one token
docker compose exec hpe-cx-mcp python cx_token_manager.py show --name vscode-dev

# Revoke a token
docker compose exec hpe-cx-mcp python cx_token_manager.py revoke --name vscode-dev

Сгенерированные токены имеют префикс cx_. Используйте отдельный токен для каждого клиента/агента, чтобы получать атрибуцию по исполнителю в журнале аудита.

Первый токен: когда аутентификация включена, сервер запускается в режиме LOCKED (HTTP 503 на каждый запрос), пока не появится токен. После создания первого токена примените его без перезапуска с помощью горячей перезагрузки (см. ниже):

docker compose exec hpe-cx-mcp python cx_reload.py

(также подойдёт docker compose restart hpe-cx-mcp).

Горячая перезагрузка (без пересборки / без перезапуска)

Файлы токенов и инвентаря загружаются в память при запуске. После изменения secrets/.tokens (через указанный выше CLI) или inventory/inventory.yaml примените изменения к работающему серверу, отправив ему сигнал перезагрузки:

docker compose exec hpe-cx-mcp python cx_reload.py

Это перезагружает и токены, и инвентарь на месте — добавление/отзыв токена или добавление/обновление устройства вступает в силу со следующего запроса. Команда только отправляет сигнал; результат (количество, ошибки) записывается в журналы:

docker compose logs --tail=20 hpe-cx-mcp

Перезагрузка выполняется вручную и явно — автоматического отслеживания файлов нет.

Если клиенты подключаются через общее реле, все вызовы отображаются под одним токеном реле; для атрибуции по агенту подключайтесь напрямую к hpe-cx-mcp с отдельными токенами.

9. Подключение MCP-клиента

Укажите вашему MCP-клиенту конечную точку streamable-HTTP:

URL:  http://<docker-host>:8002/mcp

Когда аутентификация включена, добавьте заголовок:

Authorization: Bearer cx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Пример (стиль VS Code mcp.json):

{
  "servers": {
    "hpe-cx-mcp": {
      "type": "http",
      "url": "http://localhost:8002/mcp",
      "headers": { "Authorization": "Bearer cx_xxxxxxxxxxxxxxxxxxxx" }
    }
  }
}