MCP Network Diagnostics

MCP网络诊断

   

AI驱动的网络诊断有两种模式： 操作员模式 （SSH到设备）和 消费者模式 （边缘诊断）。

特性

操作员模式（SSH/Prometheus）

通过连接到路由器和交换机诊断企业网络：

• 设备状态和指标（CPU、内存、接口统计数据）
• 设备之间的路径查找
• 趋势分析与漏洞预测
• 异常检测（z评分、汇率变动、波动性）
• 基于置信度评分的根本原因分析
• 配置更改相关性
• 多供应商支持（思科IOS-XR、IOS-XE、NX-OS）

消费者模式（边缘诊断）

在没有设备访问权限的情况下诊断您的家庭/办公室网络。看 消费者_商品.md 获取完整的消费者指南（工具、基线工作流、用例）。

• Web仪表板 –带有“我的连接”概述、消费者工具、访客会话和每个身份基线的浏览器UI
• 网关健康检查
• DNS解析时间
• 带跳数分析的跟踪路由
• WiFi信号质量（macOS/Linux/Windows）
• 使用异常检测进行基线跟踪（使用仪表板时按身份）
• 提供商上下文（BGP/AS查找、中断相关性）
• 具有意图系统的持续监控代理
• 速度测试集成

快速开始

安装

# Install from source
git clone https://github.com/vedevpatel/mcp-network-diagnostics.git
cd mcp-network-diagnostics
uv sync

快速启动（消费者）

运行仪表板的一个命令，然后在浏览器中打开应用程序-不需要API密钥或登录：

uv run python -m mcp_network.dashboard
# Open http://localhost:8080

将网站用作 客人 （会话由签名的cookie标识；基线和数据按身份进行范围划分）。从概览中，您可以获得实时的“我的连接”视图（网关、DNS、互联网延迟）。自 工具 您可以运行“检查我的连接”、“跟踪路径”、“为什么它很慢？”和基线记录/比较。

要使用Claude（或任何MCP客户端）的相同诊断，请指向 Claude桌面配置 在这个repo上运行 check_my_connection() 或 why_is_it_slow("zoom.us") 通过MCP。

有关完整的消费者指南（所有工具、基线工作流和用例），请参阅 消费者_商品.md.

Web仪表板（消费者用户界面）

运行仪表板以获得基于浏览器的“检查我的连接”体验—不需要MCP或API密钥：

uv run python -m mcp_network.dashboard
# Open http://localhost:8080

• 概述 –“我的连接”实时状态（网关、DNS、延迟）。
• 工具 –配置后，消费者工具（检查我的连接、跟踪路径、为什么速度慢？、记录/比较基线等）以及操作员和代理工具。
• 嘉宾环节 -签名的cookie标识您的会话；基线和数据按身份进行范围划分。标题显示“作为访客使用”（可选“登录”以供将来使用）。
• 费率限制 –每位客人限制（默认60个请求/分钟）。集 CONSUMER_RATE_LIMIT_PER_MINUTE 以覆盖。
• 可选身份验证 –设置 MCP_NETWORK_DASHBOARD_REQUIRE_AUTH=1 需要用于“工具和设置”的API密钥。

使用Docker： docker compose up -d 然后打开http://localhost:8080.

MCP集成（克劳德桌面）

通过编辑将MCP服务器添加到Claude Desktop ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）。

消费者模式（无需设置）

诊断您自己的网络——没有凭据，没有配置文件：

{
  "mcpServers": {
    "network-diagnostics": {
      "command": "/path/to/uv",
      "args": ["--directory", "/path/to/mcp-network-diagnostics", "run", "mcp-network"]
    }
  }
}

操作员模式（模拟-测试/演示）

尝试使用伪10路由器拓扑进行设备诊断：

{
  "mcpServers": {
    "network-diagnostics": {
      "command": "/path/to/uv",
      "args": ["--directory", "/path/to/mcp-network-diagnostics", "run", "mcp-network", "--collector", "simulated"]
    }
  }
}

重新启动克劳德桌面 编辑配置后。

关键MCP工具

仅供操作员使用的工具 （要求 --collector simulated 或SSH/Prometheus）：

操作员模式-模拟（测试）

mcp-network --collector simulated

为演示生成一个假的10路由器拓扑。尝试：

• get_device_status("R1")
• diagnose_latency("R1", "R5")
• predict_trends() -打电话后 refresh_metrics() 5+次

操作员模式-SSH（DevNet沙盒）

export DEVNET_IOSXE_USERNAME=developer
export DEVNET_IOSXE_PASSWORD=C1sco12345
export DEVNET_NXOS_USERNAME=admin
export DEVNET_NXOS_PASSWORD=RG!_Yw200

mcp-network --collector ssh --topology-file iosxe_topology.yaml

克劳德桌面：

{
  "mcpServers": {
    "network-diagnostics": {
      "command": "/path/to/uv",
      "args": [
        "--directory", "/path/to/mcp-network-diagnostics",
        "run", "mcp-network",
        "--collector", "ssh",
        "--topology-file", "/path/to/iosxe_topology.yaml"
      ],
      "env": {
        "DEVNET_IOSXE_USERNAME": "developer",
        "DEVNET_IOSXE_PASSWORD": "C1sco12345",
        "DEVNET_NXOS_USERNAME": "admin",
        "DEVNET_NXOS_PASSWORD": "RG!_Yw200"
      }
    }
  }
}

操作员模式-普罗米修斯

docker run -d -p 9090:9090 prom/prometheus
docker run -d -p 9100:9100 prom/node-exporter

mcp-network --collector prometheus \
  --prometheus-url http://localhost:9090 \
  --topology-file network_topology.yaml

消费者模式工具

持续监控代理

用自然语言设置网络目标，让代理监视违规行为：

# Start monitoring
set_intent("Zoom calls should never lag")
set_intent("Alert me if gaming latency exceeds 50ms")
set_intent("My connection should stay close to baseline")

# Check status
agent_status()
list_intents()

# View incidents
get_incidents()

# Stop when done
stop_agent()

代理人：

• 每60秒监测一次（可配置）
• 解析自然语言目标→ 结构化意图
• 自动诊断违规行为
• 自动跟踪基线
• 警报冷却防止垃圾邮件

操作员模式工具

建筑

┌─────────────────────────────────────────────────────────┐
│                   MCP Server (stdio)                     │
├─────────────────────────────────────────────────────────┤
│                   Intelligence Layer                     │
│  • Path finding   • Trend analysis  • Anomaly detection │
│  • Root cause     • Intent parsing  • Context enrichment│
├─────────────────────────────────────────────────────────┤
│                    Data Collection                       │
├──────────────────┬──────────────────────────────────────┤
│  Operator Mode   │         Consumer Mode                │
│  • SSH           │  • EdgeCollector (ping/trace/DNS)    │
│  • Prometheus    │  • BaselineStorage (ring buffers)    │
│  • Simulated     │  • NetworkAgent (continuous)         │
└──────────────────┴──────────────────────────────────────┘

拓扑文件格式

所有运算符模式收集器都使用YAML拓扑文件：

devices:
  - id: my-router          # Unique ID for tool calls
    type: router            # router or switch
    device_type: iosxe      # iosxr, iosxe, nxos (SSH only)
    host: 192.168.1.1
    username: ${MY_USER}    # ${VAR} = env variable
    password: ${MY_PASS}
    port: 22
    interfaces:
      - name: GigabitEthernet0/0/0
        prometheus_name: GigE0_0_0  # Prometheus only

links:
  - src_device: my-router
    src_interface: GigabitEthernet0/0/0
    dst_device: other-router
    dst_interface: GigabitEthernet1
    default_latency_ms: 2.0

thresholds:  # Optional, overrides defaults
  cpu: 80.0
  memory: 85.0
  utilization: 80.0
  errors: 100
  anomaly:
    z_score_threshold: 2.0
    rate_shift_threshold: 3.0

环境变量替换： ${VAR_NAME} 被替换为 $VAR_NAME 在启动时。

.local.yaml 惯例： 文件匹配 *_topology.local.yaml 没有资格获得证书。

运输

MCP服务器支持两种传输方式：

stdio运输

Claude Desktop的默认设置。MCP客户端将服务器作为子进程生成，并通过stdin/stdout进行通信。

# Run directly (for testing)
mcp-network --collector simulated

# Claude Desktop config points to the command

HTTP传输

用于远程访问或当多个客户端需要连接到同一服务器时。

mcp-network --transport streamable-http --port 8000 --path /mcp
# Endpoint: http://localhost:8000/mcp

客户端通过HTTP POST连接到 /mcp 使用MCP JSON-RPC协议的端点。

HTTP MCP部署

对于生产HTTP MCP部署：

基本用法

# Start HTTP MCP server (no auth)
uv run mcp-network --transport streamable-http --port 8000 --path /mcp

# With authentication required
uv run mcp-network --transport streamable-http --port 8000 --require-auth

身份验证和API密钥

当 --require-auth 设置，客户端必须提供API密钥：

curl -X POST http://localhost:8000/mcp \
  -H "Authorization: Bearer mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

通过以下方式创建API密钥：

• 这 create_api_key MCP工具（超级用户角色）
• 仪表板设置页面（使用API密钥文件时）
• 直接在 ~/.mcp_network/api_keys.json

角色: consumer （仅限边缘工具）→ operator （+设备访问）→ admin （+代理控制）→ superuser （完全访问）。看 安全.md 了解详情。

速率限制

• 按密钥限制：基于角色（消费者：60/min，操作员：120/min，管理员：300/min）
• 全球限额：总共1000个要求/分钟（用覆盖 MCP_NETWORK_GLOBAL_RPM 任何人）
• 超出限制返回HTTP 429 Retry-After 头球

Docker部署

# Build and run
docker compose up -d

# Access dashboard at http://localhost:8080

对于反向代理后面的HTTP MCP：

# docker-compose.override.yml
services:
  mcp-http:
    build: .
    command: ["uv", "run", "mcp-network", "--transport", "streamable-http", "--port", "8000", "--require-auth"]
    ports:
      - "8000:8000"
    environment:
      - MCP_NETWORK_SESSION_SECRET=${SESSION_SECRET}
    volumes:
      - ./api_keys.json:/root/.mcp_network/api_keys.json:ro

将nginx或Caddy放在前面进行TLS终止：

# nginx.conf snippet
location /mcp {
    proxy_pass http://mcp-http:8000/mcp;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

安全注意事项

部署HTTP MCP时：

• 始终使用TLS 生产中（终止于反向代理）
• 设置强会话秘密: export MCP_NETWORK_SESSION_SECRET=$(openssl rand -hex 32)
• 配置CORS: MCP_NETWORK_CORS_ORIGINS=https://your-app.com （仅默认为同一来源）
• SSRF保护：消费者工具验证目的地以防止内部网络扫描
• 命令注入：SSH收集器验证命令是否为只读(show, display等等）
• 速率限制：默认启用；通过环境变量进行调优

看 安全.md 完整的威胁模型和安全架构。

发展

# Install with dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest tests/

# Type checking
mypy src/

# Linting
ruff check src/

快速烟雾测试

仪表板运行时(uv run python -m mcp_network.dashboard):

# Test all dashboard endpoints, rate limiting, session handling
./test_dashboard_curl.sh

# Test with lower rate limit for faster rate-limit verification
CONSUMER_RATE_LIMIT_PER_MINUTE=10 ./test_dashboard_curl.sh

开发人员资源

• docs/MCP_QUICKSTART.md --连接Claude Desktop的5分钟指南
• examples/mcp_client_example.py --程序化MCP客户端使用
• examples/http_mcp.example.sh -HTTP MCP API的卷曲示例

测试覆盖率

• 359测试 涵盖所有收集器、工具和分析
• 算法的单元测试（趋势、异常、寻路）
• MCP工具的集成测试
• 跨平台边缘收集器测试（macOS/Linux/Windows）

局限性

• 只读 -无设备配置更改
• 静态拓扑 -在YAML中定义设备/链接（无自动发现）
• DevNet凭据 -定期旋转；如果SSH失败，请从developer.cisco.com刷新
• 消费者模式限制 -在某些平台上，Traceroute需要root/admin权限
• 代理持久性 -在MCP服务器进程内运行；服务器重新启动时停止

项目结构

src/mcp_network/
├── dashboard/           # Web UI (consumer + operator views)
│   ├── app.py           # FastAPI app, session middleware
│   ├── session.py       # Guest session (signed cookie)
│   ├── consumer_limits.py  # Per-identity rate limits
│   ├── routes/          # Overview, tools, devices, incidents, etc.
│   └── templates/       # Jinja2 HTML
├── collectors/          # Data collection backends
│   ├── simulated.py     # Fake topology for testing
│   ├── ssh.py           # Cisco SSH collector
│   ├── prometheus.py    # Prometheus metrics
│   └── edge.py          # Consumer mode diagnostics
├── graph/               # Path finding & analysis
├── trends/              # Time-series analysis
│   ├── analyzer.py      # Breach prediction
│   └── anomaly.py       # Statistical detection
├── context/             # External enrichment
│   ├── bgp.py           # AS lookup via Team Cymru
│   └── outages.py       # Provider status
├── agent/               # Continuous monitoring
│   ├── core.py          # NetworkAgent loop
│   └── intents.py       # Natural language parsing
├── baseline/            # Consumer baseline tracking
└── tools/               # MCP tool implementations

例子

消费者模式工作流程

1. Check connection health
   → check_my_connection()

2. Diagnose a slow service
   → why_is_it_slow("netflix.com")

3. Investigate routing
   → trace_path("8.8.8.8")
   (Shows AS numbers, provider info, latency per hop)

4. Establish baseline
   → record_baseline()
   (Run check_my_connection() 5+ times over days)

5. Detect anomalies
   → compare_to_baseline()
   (Shows if current latency is 2x+ worse)

6. Continuous monitoring
   → set_intent("Zoom should stay under 100ms")
   → agent_status()  # Check every minute

操作员模式工作流

1. View topology
   → list_devices()

2. Check device health
   → get_device_status("R1")

3. Find path
   → find_path("R1", "R5")

4. Diagnose latency
   → diagnose_latency("R1", "R5")
   (AI analyzes hop-by-hop, identifies bottlenecks)

5. Track trends (simulated only)
   → refresh_metrics() x5
   → predict_trends()
   (Shows if CPU will breach in 12 minutes)

6. Detect anomalies
   → refresh_metrics() x10
   → detect_anomalies()
   (Z-score spikes, rate shifts, volatility changes)

7. Root cause
   → analyze_root_cause("R2", "cpu")
   (Correlates with config changes, health events)

学分

内置：

• MCP-SDK -模型上下文协议
• Netmiko -多供应商SSH
• 文本FSM -Cisco输出解析