使用说明
NSM-DEBUG_MCP
Network System Management — Debug MCP Server
A Windows-first MCP server for VS Code that turns serial console interactions into AI-callable tools.
📖 English Guide · 📖 中文教程 · 🐛 Report Bug · 💡 Request Feature
它的作用
连接串行电缆，将服务器指向您的设备，并通过VS Code Copilot Agent与网络设备通信——不需要终端窗口切换。
You (Copilot Chat) → "查看 R1 路由表"
↓
NSM-DEBUG_MCP → serial console → show ip route
↓
Device output → Copilot Chat
特性
| 类别 | 能力 |
|---|---|
| 会话自动化 | 自动登录（用户名/密码/启用），分页禁用 |
| CLI工具 | 20+预定义命令：显示、OSPF、BGP、IS-IS、VLAN、DHCP、IPv6 |
| BootLoader重置 | 路由器、交换机、AC、网关的自动工厂重置 |
| 控制键 | 串行上的原始Ctrl+C/Ctrl+B/Ctrl+Q注入 |
| Win32回退 | CH340通过本机Win32 API的USB串行解决方案 |
| YAML配置文件 | 每个设备一个配置文件——在几秒钟内交换目标 |
5分钟设置（推荐）
此存储库首先是Windows。最快的路径是：
- 克隆仓库。
- 创建本地
.venv在repo根目录中。 - 将软件包安装到其中
.venv. - 打开
NSM-DEBUG_MCPVS Code中的文件夹本身。 - 在要求VS Code启动MCP服务器之前运行自检。
# 1. Clone
git clone https://github.com/QianChang-official/NSM-DEBUG_MCP.git
cd NSM-DEBUG_MCP
# 2. Create and activate a repo-local virtual environment
py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
# 3. Install dependencies
python -m pip install --upgrade pip
pip install -e .
# 4. Copy and edit the example config
Copy-Item .\NSM-DEBUG_MCP.example.yaml .\my_device.yaml
# Edit my_device.yaml: set hostname, credentials, COM port
# 5. Verify the server can load and register tools
python .\tools\selftest_list_tools.py
如果自检打印工具名称，例如 run_cli, show_version，以及 send_control_keys，安装已就绪。
然后：
- 打开
NSM-DEBUG_MCP文件夹直接在VS代码中。 - 跑
Developer: Reload Window一次。 - 在代理模式下打开Copilot聊天。
- 开始
NSM-DEBUG_MCP如果MCP服务器未自动启动，则从MCP服务器列表中删除。
可用的MCP工具
General (click to expand)
| 工具 | 命令 | 描述 |
|---|---|---|
run_cli |
{command} |
执行任何CLI命令 |
show_version |
show version |
设备版本信息 |
show_running_config |
show running-config |
运行配置 |
show_startup_config |
show startup-config |
启动配置 |
show_ip_interface_brief |
show ip interface brief |
接口概述 |
show_ip_route |
show ip route |
IPv4路由表 |
show_vlan |
show vlan |
VLAN配置 |
show_mac_address_table |
show mac-address-table |
MAC地址表 |
show_lldp_neighbors |
show lldp neighbors |
LLDP邻居 |
show_lldp_neighbors_detail |
show lldp neighbors detail |
LLDP邻居详细信息 |
show_ip_dhcp_binding |
show ip dhcp binding |
DHCP租用表 |
show_privilege |
show privilege |
当前特权级别 |
show_flash |
dir flash: |
Flash目录 |
show_interfaces |
show interfaces {interface} |
接口详细信息 |
show_running_include |
show running-config | include {pattern} |
已筛选配置 |
IPv6
| 工具 | 命令 |
|---|---|
show_ipv6_interface_brief |
show ipv6 interface brief |
show_ipv6_route |
show ipv6 route |
Routing Protocols
| 工具 | 命令 |
|---|---|
show_ip_ospf_neighbor |
show ip ospf neighbor |
show_ip_bgp_summary |
show ip bgp summary |
show_isis_neighbors |
show isis neighbors |
show_ip_rip_database |
show ip rip database |
AC / Wireless
| 工具 | 命令 |
|---|---|
show_ap_all |
show ap all |
show_ap_config_summary |
show ap-config summary |
Save & Reset
| 工具 | 命令 |
|---|---|
write_memory |
write memory |
save_config |
save |
Built-in Tools (no YAML config needed)
| 工具 | 说明 |
|---|---|
list_serial_ports |
列出Windows可见的COM端口，而不打开它们 |
connection_status |
显示已编辑机密的服务器、串行和登录会话状态 |
send_control_keys |
发送原始控制键（Ctrl+C、Ctrl+B、Ctrl+Q…） |
auto_factory_reset |
自动BootLoader工厂重置工作流程 |
支持的重置配置文件： router · switch · ws6008 · gateway
独立工具脚本
这 tools/ directory为无头自动化提供了独立的Python脚本（不需要VS代码）：
| 脚本 | 目的 |
|---|---|
selftest_list_tools.py |
加载配置并打印所有已注册的MCP工具名称 |
run_r1_ctrlc_ctrlq_factory_reset.py |
通过日志记录和验证执行完整的路由器出厂重置 |
# Run self-test
python tools/selftest_list_tools.py
# Run automated factory reset (outputs to txt/)
python tools/run_r1_ctrlc_ctrlq_factory_reset.py
自检是将Python/安装问题与串行/YAML问题区分开来的最快方法。先运行它。
配置
一个YAML文件控制着一切。看 NSM-DEBUG_MCP.example.yaml 以获取完整参考。
serial:
port: COM3 # or leave empty for auto-detect
baud_rate: 9600
bytesize: 8
parity: N
stopbits: 1
session:
hostname: R1
username: admin
password: "your_password"
enable_password: "your_enable_password"
commands:
run_cli:
command: "{command}"
need_parse: true
prompts:
- "Execute {command} on the device"
VS代码集成
存储库已包含 .vscode/mcp.json.
重要提示：
- 它假定您创建了
.venv在存储库根目录中。 - 它仅在您打开时自动工作
NSM-DEBUG_MCP文件夹本身作为VS Code工作区。 - 如果您打开父文件夹，VS Code将使用父工作区的
.vscode/mcp.json，而不是这个仓库。
等效MCP配置：
{
"servers": {
"NSM-DEBUG_MCP": {
"type": "stdio",
"command": "${workspaceFolder}\\.venv\\Scripts\\python.exe",
"args": [
"${workspaceFolder}\\src\\nsm_debug_mcp\\server.py",
"${workspaceFolder}\\NSM-DEBUG_MCP.example.yaml"
]
}
}
}
如果要将此服务器集成到现有的多文件夹工作区中，请复制 NSM-DEBUG_MCP 服务器块进入父工作区 .vscode/mcp.json 并调整克隆位置的路径。
故障排除
MCP服务器未出现在VS代码中
- 确认您已打开
NSM-DEBUG_MCP文件夹本身，而不仅仅是其父文件夹。 - 确认
.venv\Scripts\python.exe存在于repo根目录中。 - 跑
python .\tools\selftest_list_tools.py第一。如果失败，请在调试VS Code之前修复Python或包安装。
MCP服务器存在，但无法启动
- 重新运行
Developer: Reload Window创建后.venv以及安装依赖项。 - 检查是否
my_device.yaml或NSM-DEBUG_MCP.example.yaml包含正确的COM端口和提示设置。 - 如果使用CH340串行适配器，请在调试MCP之前验证Windows设备管理器中是否存在COM端口。
从现有PowerShell会话安装失败
- 跑
Set-ExecutionPolicy -Scope Process RemoteSigned如果PowerShell阻止.venv\Scripts\Activate.ps1. - 如果
py -3不可用，请将其替换为可用的Python 3.11+可执行文件。
已验证的环境
| 组件 | 版本 |
|---|---|
| 操作系统 | Windows |
| Python | 3.14 |
| VS代码 | 最新+GitHub Copilot聊天代理模式 |
| 串行适配器 | COM3上的CH340 |
| 目标设备 | 瑞杰RSR20-X、S5310、S5760、WS6008、EG3210 |
| 串行设置 | 9600 8N1 XON/XOFF |
项目结构
NSM-DEBUG_MCP/
├── src/nsm_debug_mcp/ # MCP server implementation
│ ├── __init__.py # Package entry point
│ └── server.py # Core server logic
├── tools/ # Standalone automation scripts
├── markdown/ # Documentation (EN/ZH)
├── .vscode/mcp.json # VS Code MCP launch config
├── NSM-DEBUG_MCP.example.yaml # Unified example configuration
├── pyproject.toml # Python package metadata
└── LICENSE # MIT License
致谢
- 基于 MCP2系列 概念
- GPT辅助重构和真实设备适配
- 在生产实验室环境中对瑞杰网络设备进行了测试
许可证
麻省理工学院 --免费用于个人和商业用途。
If this project helped you, consider giving it a ⭐
