MCP_HCL

一个与 Agent 客户端无关的 H3C Cloud Lab (HCL) MCP Server。当前版本针对 Windows HCL 5.10.3 已实测的工程文件载入路径：读取现有 .net 工程，在独立副本中阶段性加入设备或链路，然后由使用者在 HCL 中打开该副本。代码采用 MIT 许可证；仓库不包含 HCL 程序、镜像、用户工程或设备配置。

当前能力与边界

status: staged 表示新工程文件已生成，不表示当前 HCL 画布已改变。调用方必须打开结果中的 project_file，再观察 HCL 画布与运行日志。当前不提供自动打开工程、设备启动、Console CLI、连通性测试或直接控制当前画布的工具。

工具只接受配置的项目根目录内的工程。新设备使用工程中已有设备作为型号模板；端口名称会检查格式和占用情况，但尚未核对该 HCL 型号是否实际提供指定端口。HCL 载入工程是最后的兼容性校验。阶段名只允许 1–20 位 ASCII 字母、数字和下划线，生成目录不得已存在。

Related MCP server: Vivado Agent MCP

安装与启动

需要 Windows、Python 3.11+ 及合法安装的 HCL。以下命令在 PowerShell 中从本仓库执行，把依赖安装到本项目的 .venv：

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .

本机开发环境没有 py 命令时，可用已有 Python 的绝对路径代替第一行。项目依赖固定在 MCP Python SDK 1.x；2.x 的高层 Server 导入路径不同。

配置项目根目录与阶段输出目录，然后启动 stdio Server：

$env:MCP_HCL_PROJECT_ROOTS = 'C:\Users\YOUR_NAME\HCL\Projects'
$env:MCP_HCL_OUTPUT_ROOT = 'E:\YOUR_WORKSPACE\MCP_HCL\work\staged'
.\.venv\Scripts\python.exe -m mcp_hcl.server

MCP_HCL_PROJECT_ROOTS 可用分号隔开多个绝对目录。若未设置，默认读取当前用户的 HCL\Projects；MCP_HCL_OUTPUT_ROOT 默认是启动时工作目录下的 work\staged。将同一命令和环境变量配置到任意支持 stdio MCP 的客户端即可，不需要特定 Agent 的推理代码。

使用顺序

1. 用 hcl_list_projects 或 hcl_inspect_project 确认源工程及其设备名、已有端口。

2. 用 hcl_stage_add_device 或 hcl_stage_link 生成阶段工程。要在同一批次继续修改，把上次返回的 project_directory 作为下次的 project_path，并使用新的 stage_name。

3. 在 HCL 中打开最终返回的 .net 文件，确认画布设备与链路；设备未启动时不能把拓扑加载成功解释为网络连通。

阶段工程放在 work/ 下并被 Git 忽略。源工程文件从不原地修改。生成前检查设备 ID、名称和端口占用；输出目录使用临时目录组装后再命名为最终阶段目录。不要把 work/ 内的 HCL 工程、VDI/VMDK 或配置文件加入开源仓库。

验证

.\.venv\Scripts\python.exe -m unittest discover -s tests -v

实测基线（2026-09-29，HCL 5.10.3）：通过真实 MCP stdio 客户端调用 hcl_stage_add_device，从 6 台设备、5 条链路的工程生成包含第 7 台路由器 MCP_R8 和第 6 条链路的阶段工程。HCL 重新打开该工程后，日志记录 MCP_R8 的 NETFile::create_node、新链路的 NETFile::add_connection；仿真后端双向 create_udp 都返回成功，VirtualBox 的第 7 台虚拟机配置盘指向阶段工程，状态为关机。原工程文件未改变。

后端内部接口单独创建设备并不会自动更新当前画布，因此本版本不把后端调用包装成“实时 GUI 创建”。上述验收证明拓扑加载，不证明设备启动、Comware 配置或网络连通性。