内容
# HCL-Lab MCP 服务器
[](LICENSE)
[](https://www.python.org/)
[](https://modelcontextprotocol.io/)
**h3c-hcl-mcp** 是一个开源的 MCP（模型上下文协议）服务器，允许 AI 代理（如 Claude Desktop、Claude Code、Cursor、ChatGPT MCP 客户端、Cline、Roo Code 等 MCP 兼容客户端）与本地 [H3C Cloud Lab (HCL)](https://www.h3c.com/cn/Products_And_Solution/Cloud_Computing/HCL/) 网络仿真环境进行交互。
> ⚠️ **重要提示**：本项目是一个社区互操作性工具。它 **不** 受 H3C 赞助、背书或支持。您必须合法安装 HCL；本仓库不包含、分发或下载任何 HCL 可执行文件、镜像或文档。
## 功能介绍
- **发现** 本地机器上的 HCL 项目、设备和链接
- **连接** 到正在运行的 H3C/Comware 设备，通过 HCL 环回 Telnet 控制台或 SSH
- **执行** 受控的 Comware CLI 命令（`display`、诊断）
- **检索** 设备信息、接口、配置和拓扑数据
- **分析** 实验室拓扑并协助网络实验
- （未来）**配置** 变更，计划 → 差异 → 批准 → 应用工作流
## 快速入门
### 前提条件
- 安装了 [H3C Cloud Lab 5.10.x](https://www.h3c.com/cn/Products_And_Solution/Cloud_Computing/HCL/) 的 Windows 系统
- Python 3.12+
- [uv](https://docs.astral.sh/uv/)（推荐）或 pip
### 安装
```bash
# 通过 uvx（推荐 — 无需显式安装）
uvx h3c-hcl-mcp
# 或通过 pip
pip install h3c-hcl-mcp
h3c-hcl-mcp
```
### MCP 客户端配置
**Claude Desktop**（`claude_desktop_config.json`）：
```json
{
"mcpServers": {
"h3c-hcl": {
"command": "uvx",
"args": [
"--from", "h3c-hcl-mcp==0.1.0",
"h3c-hcl-mcp",
"--config", "C:\\Users\\YOUR_NAME\\.config\\h3c-hcl-mcp\\config.yaml"
]
}
}
}
```
**Cursor**（`.cursor/mcp.json`）：
```json
{
"mcpServers": {
"h3c-hcl": {
"command": "uvx",
"args": [
"--from", "h3c-hcl-mcp==0.1.0",
"h3c-hcl-mcp",
"--config", "C:\\Users\\YOUR_NAME\\.config\\h3c-hcl-mcp\\config.yaml"
]
}
}
}
```
## 当前状态
| 版本 | 阶段 | 描述 |
|---|---|---|
| `v0.0.1` | 引导 | 仓库治理、软件包骨架、CI、ADR |
| `v0.1.0` | 计划 | 只读 MVP — HCL 项目发现、控制台 Telnet、设备信息 |
| `v1.0.0` | 目标 | 稳定 API、全面测试覆盖、多客户端验证 |
**当前版本：v0.0.1（预 alpha）** — 开发刚刚开始。有关完整架构，请参见 [docs/design.md](docs/design.md)。
## 架构
```
任何 MCP 客户端（Claude、Cursor、ChatGPT 等）
│
MCP 协议（stdio / 流式 HTTP）
│
HCL-Lab MCP 服务器
│
┌────┴────┐
│ │
HCL 层 Comware 层
│ │
拓扑 CLI 通过
发现 Telnet/SSH
```
代码库遵循 **六边形架构**，具有严格的依赖方向：
```text
mcp → application → ports ← adapters/infrastructure
domain
```
有关模块边界、端口接口和工具模式，请参见 [docs/design.md](docs/design.md)。
## MCP 工具（v0.1）
| 工具 | 状态 | 描述 |
|---|---|---|
| `server_health` | ✅ 已准备 | 服务器版本、配置状态、健康检查 |
| `hcl_list_projects` | ✅ 已准备 | 列出本地 HCL 项目 |
| `hcl_get_topology` | ✅ 已准备 | 设备、接口、链接 |
| `hcl_get_runtime` | ✅ 已准备 | HCL 进程状态、设备运行时、控制台可用性 |
| `h3c_list_devices` | ✅ 已准备 | 具有传输能力的设备 |
| `h3c_get_facts` | ✅ 已准备 | sysname、Comware 版本、正常运行时间、型号 |
| `h3c_run_display` | ✅ 已准备 | 执行白名单 `display` 命令 |
| `h3c_get_config` | ✅ 已准备 | 运行/启动/快照配置（已编辑） |
| `h3c_get_interfaces` | 接口状态、速度、描述、地址 |
| `h3c_ping` | 网络可达性测试 |
| `h3c_trace_route` | 路径跟踪 |
| `h3c_diff_config` | 配置差异，无需写入设备 |
## 安全
- **默认：只读**。写入操作需要明确选择、计划批准和审计。
- 所有设备输出都被视为 **不受信任的数据**。
- 密码永远不会被记录或明文存储。
- 命令通过白名单验证 — 无 shell 注入，无 `eval`。
- 仅连接到 `127.0.0.1` 以获取 HCL 控制台；无 LAN 扫描。
有关完整安全模型，请参见 [SECURITY.md](SECURITY.md)。
## 开发
```bash
# 克隆
git clone https://github.com/FlySun1116/HCL-Lab_mcp.git
cd HCL-Lab_mcp
# 创建虚拟环境并安装开发依赖项
uv sync --extra dev
# lint 和类型检查
uv run ruff check .
uv run ruff format --check .
uv run mypy src/
# 运行测试
uv run pytest
# 构建
uv build
# 运行 MCP 检查器
npx @modelcontextprotocol/inspector uv run h3c-hcl-mcp
```
有关指南，请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
Apache-2.0。有关详细信息，请参见 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。
## 免责声明
本项目是一个社区互操作性项目。H3C、HCL、Comware 和相关商标归其各自所有者所有。用户必须遵守 HCL 的许可条款并合法安装 HCL。本仓库不包含、重新分发或反向工程任何 HCL 专有软件。
