mcp-hcl 0.5.0__tar.gz

mcp_hcl-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MCP_HCL contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_hcl-0.5.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: mcp-hcl
+Version: 0.5.0
+Summary: Agent-neutral MCP server for strict offline HCL planning, artifacts and gated control
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/yzd098776/dsh-HCL-mcp
+Project-URL: Documentation, https://github.com/yzd098776/dsh-HCL-mcp/blob/main/docs/README.md
+Project-URL: Repository, https://github.com/yzd098776/dsh-HCL-mcp
+Project-URL: Changelog, https://github.com/yzd098776/dsh-HCL-mcp/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/yzd098776/dsh-HCL-mcp/issues
+Project-URL: Security, https://github.com/yzd098776/dsh-HCL-mcp/security/policy
+Keywords: mcp,model-context-protocol,hcl,h3c,network-automation,netops,comware,deepseek-harness
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Telecommunications Industry
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<2,>=1.28
+Requires-Dist: pydantic<3,>=2.11
+Requires-Dist: packaging<27,>=24
+Provides-Extra: dev
+Requires-Dist: ruff==0.17.0; extra == "dev"
+Requires-Dist: jsonschema<5,>=4.26; extra == "dev"
+Dynamic: license-file
+
+# 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](https://github.com/yzd098776/dsh-HCL-mcp/actions/workflows/software-ci.yml/badge.svg)](https://github.com/yzd098776/dsh-HCL-mcp/actions/workflows/software-ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](pyproject.toml)
+
+Ships a DeepSeek Harness bundle ([`dsh/`](dsh/README.md)) 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.
+
+## 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+ for the bundled plugin |
+| 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
+
+```powershell
+pipx install mcp-hcl                 # or: uv tool install mcp-hcl
+```
+
+DeepSeek Harness plugin (adds the `hcl` MCP server row):
+
+```powershell
+dsh plugin --profile desktop add .\dsh   # from this checkout, or from a release tarball
+```
+
+Then set the HCL paths in the composed profile patch — see
+[`dsh/README.md`](dsh/README.md) for the full env table, health check and
+uninstall steps.
+
+Generic MCP client (`claude_desktop_config.json` style):
+
+```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"
+      }
+    }
+  }
+}
+```
+
+## Quick start
+
+```text
+# 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 观测](docs/hcl-live-findings.md): 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
+
+```powershell
+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](docs/development.md).
+Contracts and schemas: [docs/contract-v2.md](docs/contract-v2.md),
+[docs/offline-contracts.json](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](docs/README.md) | Documentation index |
+| [docs/offline-api.md](docs/offline-api.md) | Tool groups and call patterns |
+| [docs/contract-v2.md](docs/contract-v2.md) | Strict argument/result/recovery contract |
+| [docs/deepseek-harness.md](docs/deepseek-harness.md) | Schema projection and Harness registration |
+| [docs/hcl-live-findings.md](docs/hcl-live-findings.md) | Real HCL observations and known issues |
+| [docs/live-acceptance.md](docs/live-acceptance.md) | Software and native acceptance steps |
+| [HANDOFF.md](HANDOFF.md) | Current version, verification results, next steps |
+| [CHANGELOG.md](CHANGELOG.md) | Release history |
+| [SECURITY.md](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`，并在
+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](docs/hcl-live-findings.md)。
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+本仓库是基于 [cheese-sansan/MCP_HCL](https://github.com/cheese-sansan/MCP_HCL)（MIT）
+面向 DeepSeek Harness 插件市场的适配版本：新增插件包、工具安全注解与发布面文档，
+未改变服务的功能边界与验收口径。

mcp_hcl-0.5.0/README.md

@@ -0,0 +1,168 @@
+# 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](https://github.com/yzd098776/dsh-HCL-mcp/actions/workflows/software-ci.yml/badge.svg)](https://github.com/yzd098776/dsh-HCL-mcp/actions/workflows/software-ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](pyproject.toml)
+
+Ships a DeepSeek Harness bundle ([`dsh/`](dsh/README.md)) 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.
+
+## 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+ for the bundled plugin |
+| 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
+
+```powershell
+pipx install mcp-hcl                 # or: uv tool install mcp-hcl
+```
+
+DeepSeek Harness plugin (adds the `hcl` MCP server row):
+
+```powershell
+dsh plugin --profile desktop add .\dsh   # from this checkout, or from a release tarball
+```
+
+Then set the HCL paths in the composed profile patch — see
+[`dsh/README.md`](dsh/README.md) for the full env table, health check and
+uninstall steps.
+
+Generic MCP client (`claude_desktop_config.json` style):
+
+```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"
+      }
+    }
+  }
+}
+```
+
+## Quick start
+
+```text
+# 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 观测](docs/hcl-live-findings.md): 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
+
+```powershell
+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](docs/development.md).
+Contracts and schemas: [docs/contract-v2.md](docs/contract-v2.md),
+[docs/offline-contracts.json](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](docs/README.md) | Documentation index |
+| [docs/offline-api.md](docs/offline-api.md) | Tool groups and call patterns |
+| [docs/contract-v2.md](docs/contract-v2.md) | Strict argument/result/recovery contract |
+| [docs/deepseek-harness.md](docs/deepseek-harness.md) | Schema projection and Harness registration |
+| [docs/hcl-live-findings.md](docs/hcl-live-findings.md) | Real HCL observations and known issues |
+| [docs/live-acceptance.md](docs/live-acceptance.md) | Software and native acceptance steps |
+| [HANDOFF.md](HANDOFF.md) | Current version, verification results, next steps |
+| [CHANGELOG.md](CHANGELOG.md) | Release history |
+| [SECURITY.md](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`，并在
+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](docs/hcl-live-findings.md)。
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+本仓库是基于 [cheese-sansan/MCP_HCL](https://github.com/cheese-sansan/MCP_HCL)（MIT）
+面向 DeepSeek Harness 插件市场的适配版本：新增插件包、工具安全注解与发布面文档，
+未改变服务的功能边界与验收口径。

mcp_hcl-0.5.0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mcp-hcl"
+version = "0.5.0"
+description = "Agent-neutral MCP server for strict offline HCL planning, artifacts and gated control"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+dependencies = ["mcp>=1.28,<2", "pydantic>=2.11,<3", "packaging>=24,<27"]
+keywords = [
+    "mcp",
+    "model-context-protocol",
+    "hcl",
+    "h3c",
+    "network-automation",
+    "netops",
+    "comware",
+    "deepseek-harness",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Telecommunications Industry",
+    "Intended Audience :: Developers",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: System :: Networking",
+]
+
+[project.urls]
+Homepage = "https://github.com/yzd098776/dsh-HCL-mcp"
+Documentation = "https://github.com/yzd098776/dsh-HCL-mcp/blob/main/docs/README.md"
+Repository = "https://github.com/yzd098776/dsh-HCL-mcp"
+Changelog = "https://github.com/yzd098776/dsh-HCL-mcp/blob/main/CHANGELOG.md"
+Issues = "https://github.com/yzd098776/dsh-HCL-mcp/issues"
+Security = "https://github.com/yzd098776/dsh-HCL-mcp/security/policy"
+
+[project.scripts]
+mcp-hcl = "mcp_hcl.server:main"
+mcp-hcl-lab = "mcp_hcl.lab_bundle:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+mcp_hcl = ["data/*.json", "data/*.ps1"]
+
+[project.optional-dependencies]
+dev = ["ruff==0.17.0", "jsonschema>=4.26,<5"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+extend-exclude = ["docs/history", "work", "build", "dist"]
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F811", "F821", "F822", "F823", "I"]
+
+[tool.ruff.lint.per-file-ignores]
+# These entry points bind the tested package before importing it.
+"scripts/run_software_verification.py" = ["E402"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "lf"

mcp_hcl-0.5.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mcp_hcl-0.5.0/src/mcp_hcl/__init__.py

@@ -0,0 +1,3 @@
+"""HCL MCP tools backed by observed HCL project behavior."""
+
+__version__ = "0.5.0"