HCL 实验台 yzd098776/dsh-HCL-mcp

MCP_HCL

一个面向 HCL（H3C Cloud Lab）的 Model Context Protocol 服务器：离线规划并暂存拓扑，通过真实的 telnet 桥接查看运行中的实验环境，并且只通过带门禁、有回执的操作修改设备配置。

自带 DeepSeek Harness 包（dsh/），也能通过 stdio 与任何其他 MCP 客户端配合使用。

功能

| 领域 | 工具 |
| 拓扑规划与暂存 | hcl_plan_topology、hcl_stage_plan、hcl_stage_copy、hcl_stage_add_device、hcl_stage_link、hcl_move/rename/delete、hcl_export_artifacts、hcl_load_plan、hcl_fix_plan |
| 离线校验与生成 | hcl_validate_plan、hcl_explain_plan、hcl_estimate_plan、hcl_generate_configs、hcl_generate_operations |
| 运行中实验环境只读检查 | hcl_read_vlans、hcl_read_qos、hcl_inspect_ports、hcl_health_check、hcl_diff、hcl_audit_security、hcl_inspect_project、hcl_capabilities、… |
| 带门禁的设备配置 | hcl_apply_vlan、hcl_apply_acl、hcl_apply_nat、hcl_apply_stp、hcl_apply_port_security、hcl_apply_netstream、hcl_apply_interface_tuning、hcl_remove_acl、hcl_remove_nat、hcl_backup_config、hcl_restore_config、hcl_live_deploy、hcl_device_power、hcl_console_exec |

完整接口：55 个工具 / 6 个资源，可通过 tools/list 和 resources/list 发现。每个工具都带 MCP 安全注解（readOnlyHint、destructiveHint、idempotentHint、openWorldHint），客户端据此决定调用前要确认什么：24 个只读，14 个会破坏性修改设备，17 个属于暂存 / GUI / 其他。

在 Harness 里改了什么，没改什么

- 会改：当前 DSH 配置档里的一行 MCP 客户端连接器，它把服务器的工具暴露为 mcp__hcl__<tool>。
- 不会改：不打补丁改任何 Harness 核心文件，不往 Harness 进程注入模块，不运行生命周期或安装脚本，默认也不自动化任何 GUI。
- 不做：不创建 HCL 虚拟机，不在 HCL 画布上连线，不给设备上电，也不证明端到端连通性。VM 生命周期归 HCL 自己管；这个服务器负责规划、校验、打开和配置。

环境要求

| 要求 | 说明 |
| Python | 3.11+ |
| MCP 客户端 | 任何 stdio 客户端；DeepSeek Harness 0.1.0-rc.7+（无上限：该包在 0.1.0-rc.7 命令行上组合，在 0.2.1-rc.2 桌面应用中运行） |
| Windows | live-lab 和 GUI 工具需要它；离线规划/暂存工具也能在 Linux/macOS 上运行 |
| HCL (H3C Cloud Lab) | 原生工具需要它；没有它服务器仍会启动，离线工具照常工作 |

安装

pipx install mcp-hcl # or: uv tool install mcp-hcl

DeepSeek Harness 插件（会添加 hcl MCP 服务器行）：

dsh plugin --profile desktop add dsh-mcp-hcl # from the npm registry
dsh plugin --profile desktop add . # or from this checkout / a release tarball

然后在组合后的配置档补丁里设置 HCL 路径 —— 完整的环境变量表、健康检查和卸载步骤见 dsh/README.md。

通用 MCP 客户端（claude_desktop_config.json 风格）：

{
"mcpServers": {
"hcl": {
"command": "mcp-hcl",
"env": {
"MCP_HCL_INSTALL_ROOT": "E:\\HCL",
"MCP_HCL_PROJECT_ROOTS": "C:\\Users\\me\\HCL\\Projects",
"MCP_HCL_OUTPUT_ROOT": "D:\\mcp-hcl\\staged",
"MCP_HCL_ALLOW_LIVE_WRITE": "0"
}
}
}
}

快速开始

offline: turn a declarative request into a real, staged HCL project
hcl_estimate_plan {template: "router_on_a_stick", routers: 1, pcs_per_lan: 3}
hcl_stage_plan {project_path: "C:\\Users\\me\\HCL\\Projects\\lab",
stage_name: "demo", request: {...}, port_map: {...}}

live: read the running lab through the telnet bridge
hcl_read_vlans {project_path: "...\\work\\staged\\demo\\lab", topology: "topo1",
device: "MSR36-20_1"}

安全与权限

- 仅限本地：只与 127.0.0.1:16600（HCL 后端）和 127.0.0.1:30001-31024（HCL telnet 桥）通信。不访问外网。
- 写入需显式开启：MCP_HCL_ALLOW_LIVE_WRITE 默认为 0；保持默认时，会改动设备的工具直接返回拒绝，不会碰设备。
- 只允许暂存部署：破坏性工具拒绝操作原始 HCL 项目，要求提供暂存回执，并绑定 VDI/VM 身份；每次操作都会在配置的输出根目录下写一份回执。
- 证据优先于声明：读取类工具会报告 native_readback_verified，而契约中 connectivity_verified / guest_boot_verified / full_live_gate_passed 保持 false，因为服务器无法证明这些。
- 不存密钥：不保存任何凭据；实验设备的登录信息始终留在模拟网络内部。

状态与证据

- 已在真实 Windows HCL 安装上验证：只读工具通过 telnet 桥返回 native_readback_verified: true（14 个端口、VLAN 1、空 QoS 库、安全审计、健康检查和 diff），验证前重启过一次，并重新做了一轮暂存。
- 边界记录在 真实 HCL 观测：重启会让暂存副本的配置盘 UUID 失效，所以要重跑 restage 辅助脚本；HCL 的 GUI 无法从非提权进程自动化操作。
- 与上游 MCP-Packet-Tracer 的对齐尚未完成（已实现 12 / 47 planned / 3 项未验证）。本项目不声称已达成对等。

开发

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e '.[dev]'
.\.venv\Scripts\python.exe scripts\check_all.py # ruff + full software verification

模块职责与代码风格见 docs/development.md。
契约与 schema 见 docs/contract-v2.md、 docs/offline-contracts.json。
少数测试会调用带签名的 PowerShell 辅助脚本，需要放开执行策略才能跑。

文档

| 文档 | 用途 |
| docs/README.md | 文档索引 |
| docs/offline-api.md | 工具分组与调用方式 |
| docs/contract-v2.md | 严格的参数/结果/恢复契约 |
| docs/deepseek-harness.md | Schema 投影与 Harness 注册 |
| docs/hcl-live-findings.md | 真实 HCL 观察记录与已知问题 |
| docs/live-acceptance.md | 软件验收与原生验收步骤 |
| HANDOFF.md | 当前版本、验证结果、下一步 |
| CHANGELOG.md | 发布历史 |
| SECURITY.md | 上报漏洞 |

中文摘要

MCP_HCL 把 HCL（H3C Cloud Lab）的规划、staging、只读回读与受控配置封装成 MCP 工具，既可接入任意 MCP 客户端，也自带 DeepSeek Harness 插件包（dsh/）。

安装：pipx install mcp-hcl，再 dsh plugin --profile desktop add dsh-mcp-hcl（或仓库根 add .），并在 profile 的 patch 里填好 MCP_HCL_INSTALL_ROOT / MCP_HCL_PROJECT_ROOTS / MCP_HCL_OUTPUT_ROOT。写设备默认关闭（MCP_HCL_ALLOW_LIVE_WRITE=0），只读与离线工具可直接使用。边界：本服务不创建虚拟机、不代替 HCL 画布，也不声称已证明业务连通性；真实设备结论见 docs/hcl-live-findings.md。

License

MIT — 见 LICENSE。

本仓库基于 cheese-sansan/MCP_HCL（MIT）面向 DeepSeek Harness 插件市场的适配版本：新增插件包、工具安全注解与发布面文档，未改变服务的功能边界与验收口径。