┌──────────────┐   MCP (stdio / HTTP)   ┌──────────────┐   SSH / Serial   ┌─────────────┐
│ 智能体/客户端 │ ◀────────────────────▶ │ netdiag-mcp  │ ◀──────────────▶ │ 交换机/服务器 │
└──────────────┘  tools·resources·prompts└──────────────┘  交互式 CLI      └─────────────┘

cd "./MCP-网络检测工具"
pip install -r requirements.txt
# 或安装为命令：pip install -e .

python -m netdiag_mcp --selftest

copy config\devices.example.json config\devices.json   # Windows

{
  "devices": {
    "core-sw1": {
      "transport": "ssh",
      "host": "192.168.1.2",
      "username": "netops",
      "password": "${CORE_SW1_PASSWORD}",
      "vendor": "huawei"
    },
    "console-router": {
      "transport": "serial",
      "serial_port": "COM6",
      "baudrate": 9600,
      "username": "admin",
      "password": "${CONSOLE_R1_PASSWORD}"
    }
  }
}

python -m netdiag_mcp                                   # stdio（给 MCP 客户端调用）
python -m netdiag_mcp --transport streamable-http --port 8931   # 远程共享
python -m netdiag_mcp --list-devices                    # 打印设备清单
python -m netdiag_mcp --list-ports                      # 找 Console 线接在哪个串口

{
  "mcpServers": {
    "netdiag": {
      "command": "python",
      "args": ["-m", "netdiag_mcp"],
      "cwd": "D:/桌面/MCP-网络检测工具",
      "env": {
        "PYTHONPATH": "D:/桌面/MCP-网络检测工具",
        "NETDIAG_MODE": "guarded",
        "NETDIAG_ALLOW_WRITE": "0",
        "CORE_SW1_PASSWORD": "你的口令"
      }
    }
  }
}

python -m netdiag_mcp --transport streamable-http --host 0.0.0.0 --port 8931
# 客户端连接 http://<本机IP>:8931/mcp

list_devices → open_session(device="core-sw1") → health_check(session_id)

open_session(device="core-sw1")
→ get_interfaces()                  # 端口 up/down、错包
→ get_mac_table()                   # 终端挂在哪个口
→ run_ping(target="10.0.0.5")       # 从设备侧确认三层可达
→ get_logs()                        # 对应时间点的 up/down 记录

open_session(transport="serial", serial_port="COM6", baudrate=9600)
send_command("reboot", allow_dangerous=true)
read_output(wait_for="login:|Username:", timeout=180)   # 一次调用等 3 分钟，不轮询
login(username="admin", password="...")

configure_commands(session_id, ["interface Gi0/1", "description uplink"], dry_run=true)
# 人工确认 plan 与拦截项
configure_commands(session_id, [...], dry_run=false)
get_running_config()      # 复核
save_config(confirm=true)

MCP-网络检测工具/
├── netdiag_mcp/
│   ├── __main__.py           # CLI：stdio/http 启动、--selftest、--list-devices/ports
│   ├── server.py             # FastMCP 装配：工具 + 资源 + 提示词 + 服务说明
│   ├── runtime.py            # 单例：设置、设备清单、审计器、会话管理器
│   ├── config.py             # NETDIAG_* 环境变量 + devices.json 加载（含 ${ENV} 展开）
│   ├── models.py             # DeviceEntry / SessionInfo / CommandResult
│   ├── core/
│   │   ├── session.py        # 交互引擎：提示符、翻页、静默判定、登录、会话管理
│   │   ├── cleaning.py       # ANSI/回显/退格/分页符清洗，编码自适应，截断
│   │   ├── safety.py         # 三级命令分级与模式门控
│   │   └── audit.py          # JSONL 审计 + 会话全文 + 脱敏
│   ├── transports/           # ssh.py / serial.py / fake.py(测试) / base.py
│   ├── vendors/              # profiles.py(命令模板) / detect.py(指纹识别)
│   └── tools/                # session/exec/diag/config 四组 MCP 工具
├── config/devices.example.json
├── tests/                    # 67 个单元测试（含假终端端到端）
├── docs/usage.md             # 详细用法与厂商命令映射
├── docs/integration.md       # 第三方智能体接入
└── .env.example

python -m unittest discover -s tests -t . -v     # 全部单元测试
python -m netdiag_mcp --selftest                 # 依赖 + 配置 + 工具 + 测试