Ensp

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。