Skip to main content
Glama

MCP_HCL

A Model Context Protocol server for HCL (H3C Cloud Lab): plan and stage topologies offline, inspect a live lab through its real telnet bridge, and change device configuration only through gated, receipt-backed operations.

CI PyPI npm License: MIT Python 3.11+

Ships a DeepSeek Harness bundle (dsh/) and works with any other MCP client over stdio.


What it does

Area

Tools

Topology planning and staging

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

Offline validation and generation

hcl_validate_plan, hcl_explain_plan, hcl_estimate_plan, hcl_generate_configs, hcl_generate_operations

Live lab read-only inspection

hcl_read_vlans, hcl_read_qos, hcl_inspect_ports, hcl_health_check, hcl_diff, hcl_audit_security, hcl_inspect_project, hcl_capabilities, …

Gated device configuration

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

Full surface: 55 tools / 6 resources, discoverable via tools/list and resources/list. Every tool carries MCP safety annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) so a client can decide what to confirm before calling: 24 read-only, 14 destructive device-mutating, 17 staging/GUI/other.

Related MCP server: Network Sketcher

What it changes in the Harness, and what it does not

  • Changes: one MCP client-connector row in the active DSH profile, which exposes the server's tools as mcp__hcl__<tool>.

  • Does not change: no Harness core file is patched, no module is injected into the Harness process, no lifecycle or install script runs, and no GUI is automated by default.

  • Does not do: create HCL virtual machines, draw cables on the HCL canvas, power devices on, or prove end-to-end connectivity. HCL itself owns VM lifecycle; this server plans, validates, opens and configures.

Requirements

Requirement

Notes

Python

3.11+

MCP client

Any stdio client; DeepSeek Harness 0.1.0-rc.7+ (no upper bound: the bundle composes on the 0.1.0-rc.7 CLI and runs in the 0.2.1-rc.2 desktop app)

Windows

Required for live-lab and GUI tools; offline planning/staging tools also run on Linux/macOS

HCL (H3C Cloud Lab)

Required for native tools; without it the server starts and offline tools still work

Install

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

DeepSeek Harness plugin (adds the hcl MCP server row):

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

Then set the HCL paths in the composed profile patch — see dsh/README.md for the full env table, health check and uninstall steps.

Generic MCP client (claude_desktop_config.json style):

{
  "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"
      }
    }
  }
}

Quick start

# 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"}

Safety and permissions

  • Local only: talks to 127.0.0.1:16600 (HCL backend) and 127.0.0.1:30001-31024 (HCL telnet bridge). No outbound network access.

  • Writes are opt-in: MCP_HCL_ALLOW_LIVE_WRITE defaults to 0; with the default, device-mutating tools return a refusal instead of touching a device.

  • Staged-only deployments: destructive tools refuse the original HCL project and require a stage receipt plus VDI/VM identity binding; every operation writes a receipt under the configured output root.

  • Evidence over claims: read tools report native_readback_verified, and the contract keeps connectivity_verified / guest_boot_verified / full_live_gate_passed false because the server cannot prove those.

  • No secrets: stores no credentials; lab device logins stay inside the emulated network.

Status and evidence

  • Verified on a real Windows HCL install: read-only tools return native_readback_verified: true over the telnet bridge (14 ports, VLAN 1, empty QoS DB, security audit, health and diff), after a restart and a fresh staging round.

  • Boundary documented in 真实 HCL 观测: restart invalidates a staged copy's config-disk UUID, so re-run the restage helper; HCL's GUI cannot be automated from a non-elevated process.

  • Upstream MCP-Packet-Tracer parity is incomplete (12 implemented / 47 planned / 3 unverified). This project does not claim that parity.

Development

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

Module responsibilities and code style: docs/development.md. Contracts and schemas: docs/contract-v2.md, docs/offline-contracts.json. A handful of tests exercise signed PowerShell helpers and need an execution policy that permits them.

Documentation

Document

Purpose

docs/README.md

Documentation index

docs/offline-api.md

Tool groups and call patterns

docs/contract-v2.md

Strict argument/result/recovery contract

docs/deepseek-harness.md

Schema projection and Harness registration

docs/hcl-live-findings.md

Real HCL observations and known issues

docs/live-acceptance.md

Software and native acceptance steps

HANDOFF.md

Current version, verification results, next steps

CHANGELOG.md

Release history

SECURITY.md

Reporting a vulnerability

中文摘要

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 — see LICENSE.

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

Available Tools

55 tools
hcl_apply_aclB
Destructive

Apply one strict Comware numbered or named ACL after identity, backup and restore preflight.

Changes only requested rules/bindings; readback and unrelated scope checks are mandatory.

Inputs: device (required), topology (required), parameters (required), project_path (required), +1 more.

hcl_apply_interface_tuningB
Destructive

Tune requested interface bandwidth and OSPF fields with scoped readback and saved recovery.

Serial clock and IOS delay mappings remain unavailable; encrypted authentication values are partial. Secrets are omitted from operation receipts and previews.

Inputs: topology (required), parameters (required), project_path (required), dry_run.

hcl_apply_natB
Destructive

Apply static, dynamic or interface/pool PAT intent to one staged router.

Uses recorded ACL/pool identities, bounded backup/readback/persistence and same-VM recovery. Comware outbound semantics and pool ranges do not prove IOS ingress-role/netmask equivalence.

Inputs: topology (required), parameters (required), project_path (required), dry_run.

hcl_apply_netstreamB
Destructive

Apply/remove a scoped NetStream destination with local exporter-name identity.

Named NetFlow monitor/object equivalence and actual collector delivery remain unverified.

Inputs: topology (required), parameters (required), project_path (required), dry_run.

hcl_apply_port_securityB
Destructive

Apply bounded secure-MAC/shutdown intent on one existing access port.

Refuses unproved IOS protect/restrict mappings and unrequested authentication or learned-state conversion.

Inputs: topology (required), parameters (required), project_path (required), dry_run.

hcl_apply_stpC
Destructive

Apply per-VLAN rapid spanning-tree priority and selected edge/guard intent.

Native PVST, root-selection and global BPDU protection are not full IOS equivalence claims.

Inputs: topology (required), parameters (required), project_path (required), dry_run.

hcl_apply_vlanB
Destructive

Apply strict single-device VLAN/port/SVI intent with backup, readback and recovery.

Native trunk membership is replaced with the exact requested allowed VLAN set.

Inputs: device (required), topology (required), parameters (required), project_path (required), +1 more.

hcl_apply_vlan_networkC
Destructive

Apply scoped VLAN/access/trunk/router subinterface changes across staged devices.

All targets and backups precede changes; persistence and recovery stay bound to each VM.

Inputs: topology (required), parameters (required), project_path (required), dry_run.

hcl_audit_securityC
Read-onlyIdempotent

Audit bound running Comware configuration posture without exporting credentials.

Empty device selects staged non-PC bindings, not a complete native canvas inventory. Unsupported Cisco rules and unknown storage algorithms prevent a secure=true verdict.

Inputs: topology (required), project_path (required), device, timeout_seconds.

hcl_backend_capabilitiesA
Read-onlyIdempotent

List the observed backend verbs, their evidence level and gating state.

Read-only and offline: it never opens a socket. The verb list comes from HCL's own logs, not from vendor documentation.

Inputs: no named parameters. Returns: object

hcl_backend_topologyA

Open, inspect or close the backend topology session (state-changing).

The wrapper keys its topology to the connection, so opening keeps one connection alive and reuses it for hcl_device_power. At most one session is held at a time.

action is open, close or status. open needs topology and a working_directory inside a configured project root.

Inputs: action (required), topology, udp_port, project_name, +1 more. Returns: object

hcl_backup_configC

Create and test a native running-config backup for a bound staged device (gated).

Inputs: device (required), topology (required), project_path (required).

hcl_bridge_statusB
Read-onlyIdempotent

Probe the local HCL backend; never infer GUI or CLI control from it.

Inputs: no named parameters. Returns: object

hcl_capabilitiesB
Read-onlyIdempotent

Describe verified capabilities and the activation boundary.

Inputs: no named parameters. Returns: object

hcl_console_execA
Destructive

Send one line to a device console over HCL's telnet bridge (gated).

Supply either pipe (\\.\pipe\<topology>-device<N> or telnet://127.0.0.1:<30001..31024>) or topology plus device; the default endpoint for a topology is the telnet bridge HCL publishes for that device. Output that arrived before the command is drained and reported as discarded_stale_bytes so stale console text cannot be mistaken for this request's answer.

Inputs: command (required), pipe, device, expect, +1 more. Returns: object

hcl_device_powerA
Destructive

Power one device on through the observed backend verb (gated).

Requires an open session from hcl_backend_topology: the wrapper keys the topology to the connection, so a one-shot request is answered with errorCode=228. Only power-on was observed - no stop verb exists in the logs, so on=False is reported as unsupported rather than guessed.

Inputs: device (required), on. Returns: object

hcl_diffD
Read-onlyIdempotent

Compare planned addresses with freshly bound guest observations.

Missing/extra live devices and a positive in_sync remain unknown until an authoritative native topology inventory is available.

Inputs: plan (required), topology (required), project_path (required), timeout_seconds.

hcl_estimate_planD
Read-onlyIdempotent

Use the same planner to count devices, links, addresses and services.

Inputs: request (required).

hcl_explain_planC
Read-onlyIdempotent

Explain a valid saved plan and its evidence boundaries without an LLM.

Inputs: plan (required).

hcl_export_artifactsB

Atomically export an offline plan/config/operation bundle under the output root.

Inputs: plan (required), artifact_name (required), idempotency_key.

hcl_fix_planC
Read-onlyIdempotent

Return a repaired copy; preserve manually supplied addresses and services.

Inputs: plan (required).

hcl_full_buildB

Plan and compile an isolated HCL project, optionally open it in an existing GUI.

activate defaults false. No VM power or CLI deployment occurs. Offline builds support durable idempotency; live activation is never replayed.

Inputs: request (required), port_map (required), stage_name (required), project_path (required), +3 more.

hcl_generate_configsB
Read-onlyIdempotent

Generate documented Comware templates for ten typed services, offline only.

Inputs: plan (required).

hcl_generate_operationsC
Read-onlyIdempotent

Generate a declarative HCL operation manifest; executable=false until live adapters are accepted.

Inputs: plan (required), include_configs.

hcl_get_device_detailsC
Read-onlyIdempotent

Read one installed model's default interfaces; never claim guest CLI verification.

Inputs: model (required). Returns: object

hcl_health_checkC
Read-onlyIdempotent

Read interface anomalies and repeated addresses from staged running guests.

Carrier state does not prove cabling; healthy remains unknown.

Inputs: topology (required), project_path (required), include_ipv6, timeout_seconds.

hcl_inspect_portsB
Read-onlyIdempotent

Read bound running-device interface state; empty device inspects all staged devices.

Link/cable inventory remains unverified, so only_linked=true is rejected.

Inputs: topology (required), project_path (required), device, only_linked.

hcl_inspect_projectB
Read-onlyIdempotent

Read devices and links from one saved HCL project without changing it.

Inputs: project_path (required). Returns: object

hcl_list_devicesB
Read-onlyIdempotent

List installed HCL model defaults, with file evidence and firmware boundaries.

Inputs: no named parameters. Returns: object

hcl_list_modulesD
Read-onlyIdempotent

Read the documented native NIC mode and fixed profiles; model compatibility is unverified.

Inputs: model.

hcl_list_projectsA
Read-onlyIdempotent

List HCL projects immediately under configured project roots.

Inputs: no named parameters. Returns: object

hcl_list_templatesC
Read-onlyIdempotent

List deterministic HCL-native graph templates.

Inputs: no named parameters.

hcl_live_deployC
Destructive

Back up all staged devices before deployment; restore modified devices on failure (gated).

Inputs: topology (required), project_path (required), devices.

hcl_load_planB
Read-onlyIdempotent

Hash-check and reload an exported plan; never open the HCL GUI.

Inputs: artifact_directory (required).

hcl_open_projectB

Open a staged .net in an existing SimwareClient (write-gated); no guest boot or CLI deployment.

Inputs: hcl_pid (required), project_path (required).

hcl_parity_reportB
Read-onlyIdempotent

Read the pinned mapping and API differences against current MCP discovery.

Inputs: no named parameters. Returns: object

hcl_plan_topologyC
Read-onlyIdempotent

Build a deterministic plan from a strict TopologyRequest; never deploy.

Inputs: request (required).

hcl_read_qosB
Read-onlyIdempotent

Read native user-defined traffic classes, behaviors and policies from one bound device.

Inputs: device (required), topology (required), project_path (required).

hcl_read_vlansB
Read-onlyIdempotent

Read detailed native VLAN state from one bound staged device; no default or capacity guesses.

Inputs: device (required), topology (required), project_path (required).

hcl_remove_aclA
Destructive

Remove one exact numbered/named ACL and optional IPv4 binding with backup, scope and startup readback.

Named types may be resolved from the actual config; unrelated definitions and bindings remain protected.

Inputs: device (required), topology (required), parameters (required), project_path (required), +1 more.

hcl_remove_natB
Destructive

Remove exact NAT mappings, binding and optional unshared ACL/pool resources.

Reused operation keys return recorded receipts without replaying device commands.

Inputs: topology (required), parameters (required), project_path (required), dry_run.

hcl_restore_configB
Destructive

Restore a tested native backup and compare the complete running configuration (gated).

Inputs: topology (required), backup_id (required), project_path (required).

hcl_save_projectC

Verify the active staged project identity, save it and parse the saved files (write-gated).

Inputs: hcl_pid (required), project_path (required).

hcl_stage_add_deviceC

Copy a project, add a device cloned from a known model, and optionally link it.

Inputs: x (required), y (required), new_name (required), stage_name (required), +6 more. Returns: object

hcl_stage_add_noteD

Append a bounded note in the observed .net representation to a copy.

Inputs: x (required), y (required), text (required), stage_name (required), +2 more.

hcl_stage_clear_annotationsB

Remove observed NOTE blocks only; preserve unknown drawing/Non-vBox data.

Inputs: stage_name (required), project_path (required), idempotency_key.

hcl_stage_copyB

Create an isolated HCL project for safe live-gate verification.

Inputs: stage_name (required), project_path (required), idempotency_key. Returns: object

hcl_stage_delete_deviceC

Remove one saved device and reciprocal links from a separate project copy.

Inputs: device (required), stage_name (required), project_path (required), idempotency_key.

hcl_stage_move_deviceB

Move one saved device in an isolated project copy; no live canvas mutation.

Inputs: x (required), y (required), device (required), stage_name (required), +2 more.

hcl_stage_planB

Compile a validated plan into a separate .net project using real source models.

Replaces source devices/notes in the copy. Every linked CLI port needs an explicit model-to-scene map. Command transcripts stay outside startup configs. No GUI open, VM creation, power, CLI deployment or connectivity is claimed by a staged result.

Inputs: plan (required), port_map (required), stage_name (required), project_path (required), +1 more.

hcl_stage_rename_deviceB

Rename one device and both ends of its saved links in a new project copy.

Inputs: device (required), new_name (required), stage_name (required), project_path (required), +1 more.

hcl_validate_planB
Read-onlyIdempotent

Validate intent and, by default, require a connected declared wired topology.

Use Comware interface names, not .net scene port keys. Validation does not prove firmware support, deployment or actual network connectivity. configuration checks individual intents without requiring one wired component.

Inputs: plan (required), validation_level. Returns: object

hcl_verify_connectivityC

Parse bounded actual ping statistics from a bound staged console; never infer success from exit status.

Inputs: device (required), topology (required), destination (required), project_path (required), +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.6/5.0

    Scored across 55 tools

    Disambiguation3/5

    Many tools target distinct phases, but several clusters overlap: hcl_capabilities/hcl_backend_capabilities/hcl_parity_report/hcl_bridge_status; hcl_stage_copy/hcl_full_build/hcl_stage_plan; hcl_plan_topology/hcl_estimate_plan; and hcl_apply_vlan/hcl_apply_vlan_network. hcl_stage_add_device can also link, overlapping with hcl_stage_link. Descriptions help, but the set is large enough that an agent could easily misselect.

    Naming Consistency4/5

    All tool names use a consistent hcl_ prefix and snake_case, with most following a verb_noun pattern such as hcl_list_devices, hcl_stage_add_device, and hcl_apply_vlan. Minor deviations like hcl_capabilities, hcl_full_build, hcl_device_power, and hcl_console_exec are still readable and do not seriously break the pattern.

    Tool Count1/5

    With 55 tools, the surface is far beyond a well-scoped 3-15 range and even beyond the 25+ threshold for 'too many'. The many specialized, gated, and stage-specific operations make the server unwieldy for an agent to navigate reliably.

    Completeness4/5

    The tool set broadly covers planning, validation, staging CRUD, project lifecycle, config generation/export/load, backup/restore/deploy, live readback, audit, and many apply/remove operations. Some gaps remain, such as project deletion and complete live link inventory, and power-off is unsupported, but the core lifecycle is well represented.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to interact with local H3C Cloud Lab network simulation environments, allowing discovery of projects, devices, and links, as well as execution of Comware CLI commands.
      1
      Apache 2.0