eNSP MCP

Tests License: MIT

给华为 eNSP 用的一站式 MCP：搭拓扑和配设备在同一个工具集里完成。

An unofficial MCP server for building Huawei eNSP topologies and configuring lab devices through their console ports.

当前版本 1.2.0，共 16 个 MCP 工具。本版增加 eNSP/VirtualBox/镜像启动前诊断、原生分区背景框和文字避让，并把防火墙默认选择改为 USG5500。详见更新记录与开发及验收说明。

拓扑侧全是离线的文件操作，不用开 eNSP；设备侧走 eNSP 的 console 端口，要求 eNSP 已启动、目标设备已开机。

能干什么

按型号加设备、按接口名连线，接口序号和 .topo 的 XML 细节都不用管
自动分层布局，自动分配 console 端口，自动生成 MAC 和 AP 序列号
用 eNSP 原生背景矩形和文字创建分区，自动给标题、设备名和分区留出间距
交给 eNSP 之前检查拓扑结构，以及 VirtualBox、Hyper-V/VBS、模板机和镜像
可选渲染 PNG 辅助预览；拓扑创建和验收不依赖预览图
导出 Mermaid / draw.io / CSV，直接拿去写文档
telnet 进设备批量下发配置、读回实配做对比、跑 ping 和各种 display

安装

基本环境：Python 3.10 或更高版本。实际运行 eNSP 和连接设备需要 Windows 与已安装的 eNSP；使用 AR、WLAN、NE/CE 或 USG6000V 时，还需要与 eNSP 版本匹配的 VirtualBox、模板机或设备镜像。仓库不提供这些厂商软件。

git clone https://github.com/Heaxu/ensp-mcp.git
cd ensp-mcp
python -m pip install -e .

也可以从 GitHub Releases 下载 wheel 后安装：

python -m pip install .\ensp_mcp-1.2.0-py3-none-any.whl

在 MCP 客户端配置文件中注册：

{
  "mcpServers": {
    "ensp-mcp": {
      "command": "ensp-mcp"
    }
  }
}

也可以用 Python 解释器启动，便于切换虚拟环境：python -m ensp_mcp.server。开发更新后要在客户端重启 MCP 服务，已运行的进程不会自动加载新源码。

环境自检：python -m ensp_mcp.doctor。给定拓扑并把运行前置条件作为退出状态： python -m ensp_mcp.doctor --topo lab.topo --strict-runtime。运行测试： python -B -m unittest discover -s tests -t . -v。

典型流程

environment_check    先检查 eNSP、VirtualBox、模板机和镜像
list_models          看型号、接口和选择建议；普通防火墙默认 USG5500
topo_create          建一个空拓扑
topo_add_devices     批量加设备
topo_connect         批量连线
topo_layout          自动摆开；需要时生成分区背景和标题
topo_validate        检查
topo_render          （可选）出辅助预览图
  ↓ 在 eNSP 里打开，全选启动设备
device_push_config   灌配置
device_probe         ping 一下验证

工具

设备库

工具	干什么
`list_models`	列出 43 种型号、接口、默认选择和启动风险。给 `topo_path` 还能核对内置表和实际 eNSP 版本有没有出入

没有明确型号要求时，categoryDefaults 中的防火墙默认值是 USG5500。显式传入 USG6000V 仍会严格按该型号创建，同时返回外部镜像和启动风险提示，不会静默换成端口结构不同的型号。

拓扑

工具	干什么
`topo_create`	新建空 `.topo`
`topo_inspect`	读出设备、链路、每台设备的空闲接口和 console 端口
`topo_add_devices`	批量加设备，支持 `count` 批量克隆和终端 IP 预设
`topo_connect`	批量连线，接口可写名字也可省略让它自动挑空闲口
`topo_remove`	删设备或断连线
`topo_layout`	`layered` / `tree` / `grid` / `ring` 四种普通布局，也可按 `zones` 生成原生分区背景和标题
`topo_validate`	重名、接口越界、一口多连、console 冲突、孤立设备、图标/文字/分区碰撞和条件型号风险
`topo_render`	可选的 Pillow PNG 辅助示意图
`topo_export`	导出 Mermaid / draw.io / CSV

分区示例：

{
  "path": "D:/lab/campus.topo",
  "zones": [
    {"title": "总部核心区", "devices": ["Core1", "Core2", "FW1"], "color": "#E8F1FF"},
    {"title": "办公区", "devices": ["Access1", "PC1", "PC2"], "color": "#EAF8EE"}
  ]
}

分区布局使用 eNSP 原生 shape/txttip 字段，按设备名宽度计算单元格，并给背景框、标题栏和相邻分区预留固定间距。未列出的设备默认进入“未分区”。 eNSP 的标注没有稳定 ID，因此拓扑已有手工图形或文字时默认拒绝覆盖；确实要全部重建时显式传 replace_annotations=true。普通布局遇到已有标注也默认拒绝移动设备，避免背景框留在旧坐标。

启动环境

工具	干什么
`environment_check`	只读检查 eNSP、VirtualBox 版本和硬件虚拟化、Hyper-V/VBS 冲突、Host-Only 网卡、AR/WLAN 基机、SVRP 与 USG6000V 镜像

传入 path 后查看 readyForTopology 和每个 modelChecks[].blockers；还没建图时也可传 models=["AR2220", "USG5500"] 预检计划型号。CLI 对应参数可重复写，例如 python -m ensp_mcp.doctor --model AR2220 --model USG5500 --strict-runtime。该检查不会启动虚拟机，不会关闭 Windows 功能，也不会注册或修改镜像。

eNSP 1.3.00.200T 优先使用经验证的 VirtualBox 5.2.x。VirtualBox 驱动处于 Running 并不能证明设备可启动：如果 Hyper-V/VBS 占用 AMD-V/VT-x，老版本 VirtualBox 仍会报 raw-mode 错误。诊断会把这种情况单独报为 VBOX_HYPERV_CONFLICT。

USG6000V 是条件使用型号，通常要另行安装并注册 vfw_usg.vdi；只有实验明确要求该型号或其独有能力时再选。一般防火墙实验优先 USG5500，它使用 eNSP 自带的本地模拟器和固件。NE40E、CE6800、CE12800 还依赖已注册的 SVRP 镜像。

设备配置

target 既接受设备名（如 Core1，需要配 topo_path），也接受 console 端口号（如 2002）。

工具	干什么
`device_exec`	执行任意命令并返回回显
`device_push_config`	灌整份配置，可以来自文本或 `.cfg` 文件
`device_fetch_config`	读回运行配置，可存盘，可和基线逐行对比
`device_probe`	ping / tracert / 接口状态 / ARP / MAC / 路由 / VLAN / OSPF
`device_sessions`	查看和关闭保持中的 console 连接

四个操作设备的工具都支持 username、password、new_password。无需认证时省略；仅密码的 console 可只给 password；new_password 仅在设备要求首次设置或修改密码时使用，不会主动触发改密。

执行结果。 检查返回的 ok、逐条 results 和 saveStatus。 device_exec / device_push_config 默认 stop_on_error=true，遇错停止；出错后不自动保存，也不自动回滚已生效的配置。超时或断线会关闭连接并报告明确错误，不会自动重放命令。saveStatus.status=saved 才表示识别到保存成功。

整份配置。 device_push_config 支持以 # 分段的运行配置，每个分段回到系统视图后再执行。device_fetch_config 的差异包含 unifiedDiff，保留上下文、行顺序及重复项。

探测结果。 ping 结果中的 parsed.reachable 才表示是否连通；null 表示回显不足，不能判断。其他 display 查询目前返回原始回显。

几个说明

接口命名。 交换机从 1 开始（GigabitEthernet0/0/1），路由器和 AP 从 0 开始（GigabitEthernet0/0/0）。写 GE0/0/1、Gi0/0/1、 GigabitEthernet0/0/1 都认，也可以直接写扁平序号。

console 端口。 eNSP 把有 console 的设备映射到本机 2000 起的 TCP 端口。 PC、Server、STA、Cloud、HUB 这些没有 console，只能在 eNSP 界面里双击配置。

Cloud。 它的接口是在 eNSP 界面里手工添加并绑定真实网卡的，.topo 里接口数写作 0。连线时按序号给（0、1、2……），校验会提醒你去界面里补配置。

设备开关机。 eNSP 启动部分设备时会动态克隆 VirtualBox 模板机，实例名不固定。MCP 先做只读预检，最终启动仍在 eNSP 界面完成；预检通过也不等同于镜像已经完成真实启动验收。

文件格式。 eNSP 写出的 .topo 声明 encoding="UNICODE" 但实际是 UTF-8、CRLF 换行。本工具按同样的形态写回，读的时候两种编码都认。

编辑已有拓扑时保留标注、扩展属性和实际板卡 XML，使用原子写入；若文件在读取后被其他程序修改，会拒绝覆盖并要求重新读取。避免同时在 eNSP 和 MCP 中保存同一文件。读取兼容 UTF-8、UTF-16 以及官方中文样例使用的 CP936/ GB18030。接口与线型校验不替代真实设备的启动和连通性验收。

topo_render 是 Pillow 生成的示意图，并非从 eNSP 导出的截图；它不验证真实界面、镜像或启动状态。Mermaid/draw.io/CSV 导出主要表达设备和链路，不保证原生分区标注的视觉等价。

小规模端到端验收

python examples/e2e_lab.py create --directory ./work/e2e-lab
# 在 eNSP 中打开生成的 acceptance.topo 并启动两台交换机
python examples/e2e_lab.py run --directory ./work/e2e-lab --apply
# 手动重启两台设备后，只读复验保存和连通性
python examples/e2e_lab.py run --directory ./work/e2e-lab

脚本会保留实际 MCP 结果和读回配置。自动测试的 Telnet 服务是协议测试桩，不能替代真实 eNSP 设备测试，也不表示 43 种型号均已完成联调。

开源许可与声明

本项目代码采用 MIT License。项目是社区维护的非官方工具，与华为及 eNSP 官方没有隶属或授权关系。Huawei、eNSP 及相关产品名称归各自权利人所有。

仓库不包含 eNSP、VirtualBox、USG6000V/SVRP 镜像或其他厂商软件。请从合法来源自行取得所需软件和镜像，并遵守相应许可。问题和改进建议可提交到 GitHub Issues。