Metadata-Version: 2.1
Name: ensp-nexus
Version: 0.2.3
Summary: A safe, user-friendly MCP and web control plane for Huawei eNSP
Author: NetOpt
License: BSL-1.1
Requires-Python: >=3.11
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Networking
Requires-Dist: cryptography>=43.0
Requires-Dist: fastapi>=0.115
Requires-Dist: mcp[cli]>=1.26,<2
Requires-Dist: pydantic>=2.10
Requires-Dist: python-multipart>=0.0.18
Requires-Dist: uvicorn[standard]>=0.34
Project-URL: Homepage, https://github.com/quwentao2005/ensp-nexus
Description-Content-Type: text/markdown

<!--
mcp-name: io.github.quwentao2005/ensp-nexus
-->

# eNSP Nexus

eNSP Nexus 是一个面向 AI 时代网络工程师培养的 Huawei eNSP 实验控制平面。
它把 eNSP 模拟器、Web 终端与 MCP（Model Context Protocol）工具统一在一个
工作区中，让人工智能助手能够直接参与网络实验的配置、验证与排障流程，
让学习者把精力集中在协议理解与架构思考，而不是重复的命令录入。

## 设计理念

- **AI 协同学习**：通过 MCP 协议向 AI 助手暴露结构化的拓扑、配置与会话状态，
  使其能够辅助配置下发、错误诊断和实验复盘。
- **安全优先**：内置危险命令拦截、操作审计、配置快照与防抖刷新机制，
  避免误操作破坏实验环境。
- **原生级终端体验**：基于 WebSocket 透明转发的字符级 Web 终端，键入体验
  对标专业终端工具（Tab 补全、密码不回显、分页交互等）。

## 主要功能

- 导入 eNSP 实验文件夹，自动解析拓扑与设备 Console 端口
- 多设备共享会话的 Web 原生终端
- 配置快照管理（imported / live / stale 三态）
- MCP 工具集：设备发现、配置采集、命令执行、排障辅助
- 危险命令拦截与操作审计日志

## 部署方法

### 环境要求

- Python 3.11 或更高版本
- Node.js 22 或更高版本（启动 Web 控制台所需）
- Windows 操作系统（需运行 eNSP 模拟器）
- 已安装并运行 Huawei eNSP

### 安装

```bash
pip install ensp-nexus
```

### 作为 MCP Server 接入 AI 助手

在支持 MCP 的客户端（如 Claude Desktop、Cursor 等）配置文件中添加：

```json
{
  "mcpServers": {
    "ensp-nexus": {
      "command": "ensp-nexus-mcp"
    }
  }
}
```

### 启动 Web 控制台

Web 控制台通过 MCP 自动启动，**无需手动运行任何命令**。

接入 AI 助手后，直接在对话中调用 `nexus_start_web_console` 工具即可：
它会自动拉起本地 API（默认 http://127.0.0.1:8000）和 Web 前端
（http://localhost:3000），并在首次启动时打开浏览器。

### 健康检查

```bash
ensp-nexus-doctor
```

## 使用说明

### 推荐工作流

1. 在 AI 助手中调用 `nexus_start_web_console` 启动 Web 控制台（或手动运行 `ensp-nexus-api`）
2. 调用 `nexus_import_lab_folder` 导入包含 `.topo` 文件和配置目录的完整实验
3. 系统自动按 Console 端口精确探测并按 UUID 关联配置文件
4. 可选：调用 `nexus_add_credential` 加密保存设备登录凭据
5. 调用 `nexus_connect` 建立 Console 会话
6. 调用 `nexus_run_command` 执行配置命令；空回车或翻页用 `nexus_terminal_input`
7. 调用 `nexus_session_timeline` 按时间查看用户与 AI 的配置顺序
8. 排障时先调用 `nexus_prepare_troubleshooting` 读取缓存证据，再按需进入实时深度模式

### MCP 工具列表

eNSP Nexus 通过 MCP 暴露 31 个工具，按功能分为 6 组：

#### 工作区与状态

| 工具 | 说明 |
|------|------|
| `nexus_start_web_console` | **幂等启动 API 与 Web 控制台**，可自动打开浏览器；无需指定项目路径 |
| `nexus_quick_start` | 获取最短、最安全的使用流程和推荐下一步 |
| `nexus_system_status` | 检查服务、设备库、会话和拓扑状态，不连接或修改设备 |
| `nexus_audit_log` | 查看最近审计记录；敏感字段在写入前已脱敏 |

#### 设备与凭据管理

| 工具 | 说明 |
|------|------|
| `nexus_scan_ensp` | 并发扫描已授权网段中的 eNSP Console 端口（默认本机 2000-2099） |
| `nexus_register_device` | 保存一台 eNSP 设备；相同 host 和 port 会更新现有记录 |
| `nexus_list_devices` | 列出已保存的设备，不包含任何密码 |
| `nexus_add_credential` | 将登录凭据加密保存在本机；返回结果不含密码 |
| `nexus_list_credentials` | 列出凭据标签和用户名；密码只显示是否已设置 |

#### 会话与命令执行

| 工具 | 说明 |
|------|------|
| `nexus_connect` | 通过共享 API 连接设备；Web、终端和 AI 复用同一条会话 |
| `nexus_list_sessions` | 列出 Console 会话、连接时长与最后活动时间 |
| `nexus_disconnect` | 安全断开一个 Console 会话 |
| `nexus_run_command` | 共享会话命令入口；命令直接执行并记录风险分类与时间线 |
| `nexus_run_readonly` | 执行 display/show/ping 等只读命令；检测到配置命令时自动拒绝 |
| `nexus_terminal_input` | 向共享终端原样输入；空回车或翻页空格均可发送 |
| `nexus_session_timeline` | 按时间顺序读取会话的连接、输入、命令和刷新记录 |

#### 实验与拓扑

| 工具 | 说明 |
|------|------|
| `nexus_import_lab_folder` | 导入完整 eNSP 实验目录：解析 .topo、按 UUID 匹配配置、探测 Console 端口 |
| `nexus_latest_lab` | 获取最新实验、拓扑设备、配置匹配、Console 端口和快照新鲜度 |
| `nexus_import_topology` | 解析并保存 eNSP XML/JSON/简化文本拓扑内容 |
| `nexus_topology_report` | 读取最新拓扑，支持 summary / full / markdown / mermaid 格式 |
| `nexus_get_device_config` | 按拓扑 UUID 或设备名读取配置文本；source 为 best / imported / live |
| `nexus_search_configs` | 跨最新实验的设备配置全文搜索，返回命中行 |
| `nexus_network_config_analysis` | 汇总拓扑结构、接口、VLAN、路由协议与配置新鲜度 |

#### 配置刷新

| 工具 | 说明 |
|------|------|
| `nexus_refresh_live_config` | 用隔离的临时连接抓取当前配置；保存后立即断开 |
| `nexus_refresh_lab_configs` | 为外部终端产生的变更并发刷新配置 |
| `nexus_reload_lab_source` | 从导入时记录的原始路径重新解析整个拓扑与配置文件夹 |

#### 排障辅助

| 工具 | 说明 |
|------|------|
| `nexus_prepare_troubleshooting` | 缓存优先准备排障上下文；动态分类并返回证据、发现和回答结构 |
| `nexus_list_troubleshooting_categories` | 列出排障问题分类、匹配关键词和回答结构 |
| `nexus_upsert_troubleshooting_category` | 新增或更新动态排障分类及其专属回答结构 |
| `nexus_delete_troubleshooting_category` | 删除不再适用的排障分类 |
| `nexus_save_troubleshooting_experience` | 生成自包含排障经验 HTML，含拓扑、推理、验证和抓包记录 |

### MCP 资源与提示

除工具外，eNSP Nexus 还暴露以下资源供 AI 助手读取：

- `nexus://topology/latest` — 最新拓扑的 Markdown 报告
- `nexus://lab/latest` — 最新实验的清单与配置覆盖
- `nexus://configs/{topology_device_id}` — 单台设备的完整配置快照
- `nexus://system/safety` — 终端操作约定（脱敏、审计、扫描范围等）

内置提示模板：

- `diagnose_ensp_device(device_name, symptom)` — 生成缓存优先、按分类回答的设备诊断流程

### 安全约定

- 所有服务默认绑定 `127.0.0.1`，不对外暴露
- 密码只在本机加密保存，任何 MCP 输出都不会返回明文
- 端口扫描默认限制在回环和 RFC1918 私网
- 所有连接、扫描、命令操作均写入审计记录
- 命令直接发送到设备，风险分类仅用于标记和审计，不阻塞输入

## License

Business Source License 1.1（个人与教育用途免费，2029-01-01 起转为 Apache 2.0）。

## 相关链接

- 主页：https://github.com/quwentao2005/ensp-nexus
- MCP Registry：https://registry.modelcontextprotocol.io
