ArubaOS-CX MCP 服务器（hpe-cx-mcp）

一个模型上下文协议（MCP）服务器，将 Aruba CX（AOS-CX） 交换机开放给支持 MCP 的 AI 代理（Claude、VS Code Copilot 等）。它将交换机 REST API（/rest/v10.x）和 SSH CLI 转化为一组经过精心设计的、安全且结构化的工具，用于园区/数据中心网络的可观测性、故障排查和配置管理（VLAN、路由、BGP/OSPF、EVPN-VXLAN、VSX/VSF、端口接入/802.1X、NAE、ARC……）。

该服务器以 Docker 容器方式运行，通过 streamable HTTP 提供 MCP 服务，并附带可选的命名 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 服务、环回接口、路由端口、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（网络分析引擎）

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_* 回读工具：

写入保护：对 read-only 设备调用 configure_* / create_* / delete_* / manage_config 将被拒绝。在清单中将设备标记为 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） —— 带回滚的 preview→apply 工作流：

工作流：以 apply=false（默认）调用任意写工具，获得一个计划 以及 dry_run_token；然后调用 apply_plan(dry_run_token=…) 来应用该确切计划。幂等的 configure_* 合并没有自动逆操作，会被 rollback 报告为 unsupported。当 CX_REQUIRE_DRY_RUN_TOKEN=true 时，通过 invoke_tool 直接应用（apply=true）会被拒绝——调用方必须走 preview→apply_plan 路径。

3. 安装（macOS / Linux / Windows）

前提条件

• Docker 和 Docker Compose v2（docker compose …）。

  • macOS / Windows：Docker Desktop。

  • Linux：Docker Engine + Compose 插件。

• 从 Docker 主机到交换机管理 IP 的网络可达性（REST 使用 HTTPS/443，SSH 使用 TCP/22）。

• 必须在目标设备上并在正确的 VRF 中配置 REST 访问：读写访问需要 Read-Write 模式，只读访问需要 Read-only 模式。

• 对于需要 SSH 的工具，还必须在目标设备上配置 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 通过 docker-compose.yml 中的 env_file: 注入容器。最小内容（完整列表见 .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，随后输出完整 traceback（然后以非零状态退出）。

注意： 每次执行 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 网络上的交换机，你可以在 docker-compose.yml 中取消注释 network_mode: host（仅限 Linux）。

macOS（Docker Desktop）

• 文件共享由 VM 处理；绑定挂载开箱即用，uid 重映射自动完成——大多数情况下无需手动 chown。

• network_mode: host 不支持与 Linux 相同的方式；请保留默认的 ports: 映射（8002:8000）。

Windows（Docker Desktop + WSL2）

• 从 WSL2 shell 或 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 工具应用更改，或重启容器。

启动校验（快速失败）

清单文件在启动时进行校验。如果无法解析（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 拒绝（故障关闭），因此服务不可达。创建第一个令牌（见 §8）并重启容器以解锁——令牌存储在启动时加载一次。

• 审计（CX_AUDIT_ENABLED=true）：每次工具调用在 logs/audit.jsonl 中输出一行 JSON，包括 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_ 为前缀。为每个客户端/代理使用一个独立的令牌，以便在审计日志中获得按操作者（actor）的归因。

第一个令牌： 启用认证后，服务器以 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" }
    }
  }
}