Netbrain MCP

🚀 NetBrain MCP

NetBrain MCP 是一個開源的網絡運維整合平臺，它藉助 Model Context Protocol (MCP) 實現大型語言模型（LLM）與網絡設備的連接。通過標準化協議，AI 助手能夠執行網絡配置、診斷和管理任務，為網絡運維帶來了極大的便利。

🚀 快速開始

🔧 MCP 服務器模式

使用 Python 直接運行

python server.py

使用 MCP 開發工具運行

mcp run server.py

帶調試界面運行 (MCP Inspector)

mcp dev server.py

🚀 生產環境部署

# 安裝依賴
pip install -r requirements.txt

# 啟動服務器
python server.py

✨ 主要特性

🔧 核心功能

• 網絡設備管理：統一管理思科、華為等各種廠商的網絡設備。
• 設備連接：支持通過 SSH 和 Telnet 協議連接到網絡設備。
• 命令執行：可遠程執行網絡命令並獲取結果。
• 憑據管理：安全地管理設備訪問憑據。
• MCP 協議支持：使大型語言模型能夠訪問和控制網絡設備。
• 資源提供功能：通過 URI 將設備、配置等資源提供給 LLM。
• 提示模板系統：提供網絡診斷、配置審查等專用提示模板。

🌐 Web 界面功能

• 專業終端體驗：基於 XTerm.js 的多標籤頁終端，支持命令補全和歷史記錄。
• 網絡拓撲可視化：基於 D3.js 的交互式拓撲圖，支持 CDP/LLDP 自動發現。
• 設備管理界面：擁有直觀的設備添加、編輯和狀態監控界面。
• 會話管理：支持多設備連接會話管理，具備重連和心跳檢測功能。
• 主題系統：具備完整的暗色/明亮主題切換，包括登錄頁面。
• 響應式設計：擁有跨設備兼容的現代化用戶界面。

🚀 高級功能

• 自動拓撲發現：基於 CDP/LLDP 協議自動識別網絡拓撲。
• 智能設備識別：內置廠商 MAC 地址識別功能，可自動推斷設備類型。
• 數據持久化：採用 JSON 文件存儲系統，支持數據備份和恢復。
• 多廠商支持：適配思科、華為、H3C 等主流廠商設備。
• 命令模板庫：預置廠商特定的命令模板和配置片段。
• 網絡掃描：支持網絡範圍掃描和設備自動發現。

📦 安裝指南

生產環境部署

# 安裝依賴
pip install -r requirements.txt

# 啟動服務器
python server.py

💻 使用示例

基礎用法

🌐 Web 界面使用

1. 啟動服務器

python server.py

2. 訪問 Web 界面
   • 打開瀏覽器訪問 http://localhost:8088。
   • 使用登錄頁面進入系統。
3. 使用終端功能
   • 點擊“終端”標籤頁。
   • 添加新設備或選擇現有設備。
   • 建立 SSH/Telnet 連接。
   • 享受專業級終端體驗（命令補全、歷史記錄等）。
4. 查看網絡拓撲
   • 點擊“網絡拓撲”標籤頁。
   • 點擊“發現拓撲”開始自動掃描。
   • 查看可視化的網絡拓撲圖。
   • 雙擊節點可快速連接設備。
5. 管理設備
   • 在“設備”頁面添加、編輯設備信息。
   • 配置設備憑據和連接參數。
   • 監控設備在線狀態。

🔧 MCP 協議使用

可以通過以下步驟測試功能：

1. 運行 MCP 服務器。
2. 使用 MCP Inspector 查看可用工具。
3. 使用 list_devices 工具列出預配置的設備。
4. 使用設備 ID 和憑據 ID 連接設備。
5. 發送命令查看模擬輸出。

📊 資源訪問示例

獲取設備信息：

GET device/1

獲取設備配置：

GET device/1/config

獲取拓撲數據：

GET topology

使用提示模板：

POST render_template
{
  "template_name": "device_diagnosis",
  "context": {
    "device_info": "...",
    "interfaces_info": "..."
  }
}

高級用法

自動拓撲發現

# 通過MCP工具調用
discover_topology({
  "device_ids": "device1,device2"
})

網絡掃描

# 掃描網絡範圍
scan_network_range({
  "network": "192.168.1.0/24",
  "timeout": 3.0,
  "auto_create_devices": true
})

批量設備配置

# 使用命令模板
send_commands({
  "device_id": "cisco_router_1", 
  "credential_id": "admin_cred",
  "commands": "interface gi0/1;ip address 192.168.10.1 255.255.255.0;no shutdown"
})

📚 詳細文檔

可用工具

NetBrain MCP 提供以下網絡管理工具：

設備管理工具

• list_devices：列出網絡設備，支持按廠商、類型、狀態、標籤過濾。
• add_device：添加新的網絡設備。
• get_device：獲取設備詳細信息。
• update_device：更新設備信息。
• delete_device：刪除設備。

憑據管理工具

• add_credential：添加設備訪問憑據。
• list_credentials：列出所有設備憑據。

設備連接工具

• connect_device：連接到網絡設備。
• disconnect_device：斷開與網絡設備的連接。
• send_command：向網絡設備發送命令。
• send_commands：向網絡設備發送多個命令。
• get_active_connections：獲取當前活動的設備連接。

拓撲發現工具

• discover_topology：基於 CDP/LLDP 協議自動發現網絡拓撲。
• get_topology：獲取已發現的拓撲數據。
• clear_topology：清除拓撲數據。
• get_device_neighbors：獲取設備鄰居信息。
• discover_device_neighbors：發現單個設備的鄰居。
• get_topology_statistics：獲取拓撲統計信息。

網絡掃描工具

• scan_network_range：掃描網絡地址範圍。
• get_scan_results：獲取掃描結果。
• get_scan_statistics：獲取掃描統計信息。
• discover_devices_from_scan_results：從掃描結果中發現設備。
• clear_scan_results：清除掃描結果。
• scan_single_host：掃描單個主機。

資源管理工具

• list_resources：列出可用的 MCP 資源。
• get_resource：獲取指定 URI 的資源。
• clear_resource_cache：清除資源緩存。

模板管理工具

• list_templates：列出可用的提示模板。
• render_template：渲染提示模板。

測試工具

• test_scrapli_connection：測試 Scrapli 連接。
• test_telnet_connection：測試 Telnet 連接。
• send_telnet_command：發送 Telnet 命令。

可用資源

NetBrain MCP 提供以下 MCP 資源：

設備資源

• device/{device_id}：獲取設備詳細信息。
• device/{device_id}/config：獲取設備配置信息。
• device/{device_id}/interfaces：獲取設備接口信息。
• device/{device_id}/routes：獲取設備路由表信息。
• device/{device_id}/neighbors：獲取設備鄰居信息。

拓撲資源

• topology：獲取網絡拓撲數據。
• topology/statistics：獲取拓撲統計信息。

掃描資源

• scan/results：獲取網絡掃描結果。
• scan/statistics：獲取掃描統計信息。
• scan/result/{ip_address}：獲取特定 IP 的掃描結果。

系統資源

• greeting/{name}：獲取個性化問候語。
• system/status：獲取系統狀態信息。
• credentials：獲取所有憑據信息（敏感信息已脫敏）。

提示模板

NetBrain MCP 提供以下提示模板：

• device_diagnosis：設備診斷提示模板。
• config_review：設備配置審查提示模板。
• route_analysis：路由分析提示模板。
• network_diagnosis：網絡診斷提示模板。
• vlan_config：VLAN 配置生成模板。
• network_topology：網絡拓撲分析模板。
• network_security：網絡安全評估模板。

🔧 技術細節

🔧 後端技術棧

• 語言：Python 3.10+
• MCP 框架：FastMCP（基於 mcp Python 包）
• Web 框架：FastAPI + WebSocket
• 設備連接：Scrapli（支持異步/同步混合模式）
• 異步支持：使用 asyncio 實現高效的網絡操作
• 數據存儲：JSON 文件存儲 + 內存緩存
• 模塊化設計：網絡設備管理、連接器、工具管理和資源提供等獨立模塊

🌐 前端技術棧

• 終端模擬：XTerm.js - 專業級終端體驗
• 數據可視化：D3.js - 網絡拓撲可視化
• 即時通信：WebSocket - 雙向即時通信
• 界面框架：現代 Web 技術 + CSS3 動畫
• 主題系統：CSS 變量 + JavaScript 主題管理
• 響應式設計：Flexbox + Grid 佈局

系統組件

🔧 核心組件

• 工具管理器 (tool_manager.py)：管理工具的註冊、分類和調用。
• 設備管理器 (network_devices.py)：管理網絡設備信息和憑據。
• 連接管理器 (device_connector.py)：處理與網絡設備的連接和命令執行。
• 資源管理器 (mcp_resources.py)：管理 MCP 資源和提示模板。
• MCP 服務器 (server.py)：提供 MCP 接口，集成其他組件。
• 模板系統 (template_system.py)：提供 AI 提示模板管理和渲染。

🌐 Web 界面組件

• Web 服務器 (web/app.py)：FastAPI Web 服務器，提供 RESTful API 和 WebSocket 支持。
• WebSocket 終端 (web/static/js/terminal.js)：即時終端通信和 XTerm.js 集成。
• 拓撲可視化 (web/static/js/topology.js)：D3.js 網絡拓撲渲染引擎。
• 主題管理 (web/static/js/theme.js)：全局主題切換和持久化。
• 設備管理界面 (web/templates/)：HTML 模板和用戶界面。

🚀 擴展組件

• 拓撲發現引擎 (topology_discovery_improved.py)：CDP/LLDP 協議拓撲發現。
• 網絡掃描器 (network_scanner.py)：網絡範圍掃描和廠商 MAC 地址識別。
• 設備提示模板 (device_prompts.py)：設備特定的 AI 提示模板。
• 數據存儲層 (data/)：JSON 文件存儲和數據持久化。
• 命令模板庫 (templates/)：廠商特定的命令模板和配置片段。

項目亮點

🎯 已完成的核心功能

✅ 完整的 MCP 協議實現：基於 FastMCP 的標準化 AI - 設備通信協議。 ✅ 專業級終端體驗：基於 XTerm.js，支持命令補全、歷史記錄、真實提示符。 ✅ 網絡拓撲可視化：基於 D3.js 的交互式拓撲圖，支持 CDP/LLDP 自動發現。 ✅ 多廠商設備支持：思科、華為、H3C 等主流廠商統一接入。 ✅ 現代化 Web 界面：響應式設計，暗色/明亮主題，跨設備兼容。 ✅ 數據持久化存儲：JSON 文件存儲，自動備份恢復。 ✅ 智能設備識別：內置廠商 MAC 地址庫，自動設備類型推斷。 ✅ 網絡掃描功能：支持大規模網絡發現和設備自動識別。

🚀 技術特色

• 高度模塊化架構：基於抽象工廠和策略模式的可擴展設計。
• 異步性能優化：全異步架構帶來高併發處理能力。
• AI 驅動操作：MCP 協議實現 AI 與網絡設備的無縫集成。
• 專業工程實踐：完整的錯誤處理、日誌記錄、配置管理。
• 混合連接模式：Scrapli 異步/同步智能適配，確保最佳兼容性。

🔮 未來擴展方向

雖然項目核心功能已完成，未來可考慮以下增強：

• 企業級功能：用戶權限管理、審計日誌、合規報告。
• 監控告警：網絡性能監控、故障自動診斷、預測性維護。
• 協議擴展：SNMP、NETCONF、RESTCONF 等更多網絡協議。
• 虛擬化集成：eNSP、GNS3、EVE - NG 等網絡模擬器支持。
• AI 能力增強：網絡故障智能分析、配置優化建議。

項目團隊

• 技術負責人：Koreyoshi - MCP 協議實現、系統架構設計。
• 功能開發：Koreyoshi - 設備管理、數據存儲、拓撲發現。
• 前端開發：Koreyoshi - Web 界面、終端功能、可視化設計。

📄 許可證

文檔中未提及相關內容，故跳過該章節。

貢獻

歡迎通過 Pull Requests 或 Issues 提交您的建議和改進。