v6ole/NetBrain_MCP

Fork 0

Files

T

Koreyoshi 3236fa947d Add files via upload

2026-05-22 12:17:24 +08:00

19 KiB

Raw Blame History

NetBrain MCP 系统架构设计

1. 整体架构

NetBrain MCP是一个通过MCP协议连接大型语言模型与网络设备的平台。系统采用模块化设计，基于FastMCP框架实现，主要由以下几个核心部分组成：

                    +------------------+
                    |     客户端       |
                    | (Claude/Cursor)  |
                    +--------+---------+
                             |
                             | MCP 协议 (FastMCP)
                             |
+----------------------------v-----------------------------+
|                       NetBrain MCP                       |
|                     (server.py)                         |
|                                                         |
|  +----------------+   +----------------+   +---------+  |
|  | MCP服务器模块  |<->|  工具管理模块   |<->| 资源模块 |  |
|  | (FastMCP)      |   | (tool_manager) |   |(mcp_res) |  |
|  +----------------+   +----------------+   +---------+  |
|           ^                    ^                ^       |
|           |                    |                |       |
|           v                    v                v       |
|  +----------------+   +----------------+   +---------+  |
|  | 设备管理模块   |<->| 设备连接模块   |<->| 模板系统 |  |
|  |(network_devices)|  |(device_connector)|  |(template)|  |
|  +----------------+   +----------------+   +---------+  |
|           ^                    ^                        |
|           |                    |                        |
|           v                    v                        |
|  +----------------+   +----------------+                |
|  | 拓扑发现模块   |<->| 网络扫描模块   |                |
|  |(topology_disc) |   |(network_scanner)|                |
|  +----------------+   +----------------+                |
+-------------------------------------------------------- +
                             |
                             | Scrapli (SSH/Telnet/混合模式)
                             |
                    +--------v---------+
                    |    网络设备      |
                    | (多厂商支持)     |
                    +------------------+

2. 核心模块说明

2.1 MCP服务器模块 (server.py)

MCP服务器模块是整个系统的核心，基于FastMCP框架实现，负责处理来自大型语言模型（如Claude、GPT等）的请求，并将请求路由到相应的工具或资源处理器。

主要功能：

实现FastMCP协议的服务器端（32个工具，13个资源，13个模板）
处理工具调用和资源请求
管理会话和上下文
提供服务器配置和日志记录

核心组件：

FastMCP服务器实例
工具注册装饰器 @mcp.tool()
资源处理器 @mcp.resource("{uri}")
提示模板处理器 @mcp.prompt("{name}")

实际实现状态： ✅ 已完成，包含所有32个工具实现

2.2 工具管理模块 (tool_manager.py)

工具管理模块负责工具的注册、管理和分类，虽然MCP工具直接通过FastMCP注册，但该模块提供了工具的分类和管理功能。

主要功能：

工具注册和分类管理（6个分类）
工具执行和错误处理
工具元数据管理

核心组件：

ToolManager类：管理所有工具
ToolCategory枚举：工具分类（general, network_device, configuration, topology, diagnostic, security）
ToolInfo数据类：工具元数据

实际实现状态： ✅ 已完成，支持32个MCP工具的分类管理

2.3 资源模块 (mcp_resources.py)

资源模块负责管理和提供各种网络资源，包括设备信息、配置数据、拓扑数据等。

主要功能：

资源注册和管理（13个MCP资源）
资源缓存和刷新（内存+文件双层缓存）
URI模式匹配和参数提取

核心组件：

ResourceManager类：管理资源
ResourceType类：资源类型定义（device, credential, topology, system, config, scan等）
缓存机制：默认5分钟TTL，支持文件持久化

实际实现状态： ✅ 已完成，实现13个MCP资源

2.4 设备管理模块 (network_devices.py)

设备管理模块负责网络设备的生命周期管理，包括设备的添加、查询、更新和删除。

主要功能：

设备信息管理（支持多厂商：cisco, huawei, h3c, juniper等）
设备凭据管理（SSH/Telnet/SNMP等协议）
设备状态监控
JSON文件持久化存储

核心组件：

DeviceManager类：设备管理器
NetworkDevice类：设备数据模型（包含platform字段支持Scrapli）
DeviceCredential类：设备凭据模型
枚举类：DeviceType, DeviceVendor, DeviceStatus, ConnectionProtocol

实际实现状态： ✅ 已完成，支持完整的设备生命周期管理

2.5 设备连接模块 (device_connector.py)

设备连接模块负责与网络设备建立连接并执行命令，基于Scrapli库实现混合异步/同步模式。

主要功能：

设备连接管理（基于Scrapli混合模式）
命令执行和结果处理
连接池管理和自动重连
多协议支持（SSH/Telnet）

核心组件：

ConnectionManager类：连接管理器
ScrapliConnector类：主要连接器实现（支持异步/同步混合）
DeviceConnector抽象类：连接器接口
CommandResult类：命令执行结果

技术特色：

混合异步/同步模式：智能检测连接对象类型，自动选择异步或同步调用方式
平台自适应：根据设备厂商自动选择合适的Scrapli驱动
自动重连机制：连接断开时自动重连并重试命令

实际实现状态： ✅ 已完成，支持思科、华为等多厂商设备

2.6 模板系统 (template_system.py + device_prompts.py)

模板系统负责管理和渲染各种提示和命令模板，提高系统的灵活性和扩展性。

主要功能：

提示模板管理（13个专业模板）
模板渲染和上下文处理
消息模型支持（System, User, Assistant）
资源集成渲染

核心组件：

TemplateManager类：高级提示模板管理器
Message模型：结构化消息格式
模板函数：支持字符串和消息列表两种返回格式
资源集成函数：render_template_with_resources

模板分布：

template_system.py：8个通用模板
device_prompts.py：5个设备专用模板

实际实现状态： ✅ 已完成，实现13个专业网络运维模板

2.7 拓扑发现模块 (topology_discovery_improved.py)

拓扑发现模块负责自动发现和维护网络拓扑，基于CDP/LLDP协议实现。

主要功能：

基于CDP/LLDP的拓扑发现
多厂商设备邻居发现适配
拓扑数据模型维护
智能拓扑构建算法

核心组件：

ImprovedTopologyDiscovery类：改进的拓扑发现引擎
NetworkTopology类：拓扑数据模型
厂商适配方法：discover_cisco_neighbors, discover_huawei_neighbors等

实际实现状态： ✅ 已完成，支持自动拓扑发现

2.8 网络扫描模块 (network_scanner.py)

网络扫描模块负责网络范围扫描和设备识别功能。

主要功能：

网络范围扫描（ping检测、端口扫描）
厂商MAC地址识别
SNMP设备发现
扫描结果分析和设备推荐

核心组件：

ImprovedNetworkScanner类：网络扫描引擎
并发扫描机制：支持可配置的并发数
厂商识别：内置厂商MAC地址数据库

实际实现状态： ✅ 已完成，支持智能网络扫描

3. 数据模型

3.1 实际数据存储架构

系统采用JSON文件存储架构，具体结构如下：

NetBrainMCP/
├── data/                    # 主数据存储目录
│   ├── devices.json         # 设备信息（NetworkDevice对象序列化）
│   └── credentials.json     # 凭据信息（DeviceCredential对象序列化，包含敏感信息）
├── resource_cache/          # 资源缓存目录
│   └── *.json              # 缓存文件（按URI哈希命名）
├── templates/              # 模板缓存目录
│   └── *.json              # 模板元数据文件
└── logs/                   # 日志文件目录
    ├── netbrain_mcp.log    # 主日志
    ├── device_connector.log # 连接日志
    └── audit.log           # 审计日志

3.2 核心数据实体关系

NetworkDevice (network_devices.py)
├── id: str (UUID)
├── name: str
├── ip_address: str
├── device_type: DeviceType (enum)
├── vendor: DeviceVendor (enum)
├── platform: str (Scrapli平台类型)
├── model: str
├── os_version: str
├── status: DeviceStatus (enum)
├── credential_id: str (关联DeviceCredential)
├── tags: List[str]
└── custom_attributes: Dict[str, Any]

DeviceCredential (network_devices.py)
├── id: str (UUID)
├── name: str
├── username: str
├── password: str (明文存储，生产环境应加密)
├── protocol: ConnectionProtocol (enum)
├── port: int
├── enable_password: str
└── ssh_key_file: str

ConnectionManager (device_connector.py)
├── active_connections: Dict[str, DeviceConnector]
└── ScrapliConnector instances

4. 接口设计

4.1 实际MCP工具接口

系统通过FastMCP协议提供以下32个工具：

设备管理工具 (6个)

@mcp.tool()
async def list_devices(vendor, device_type, status, tag) -> List[Dict[str, Any]]

@mcp.tool()
async def add_device(name, ip_address, device_type, vendor, platform, ...) -> Dict[str, Any]

@mcp.tool()
async def get_device(device_id) -> Optional[Dict[str, Any]]

@mcp.tool()
async def update_device(device_id, **kwargs) -> Optional[Dict[str, Any]]

@mcp.tool()
async def delete_device(device_id) -> bool

连接管理工具 (5个)

@mcp.tool()
async def connect_device(device_id, credential_id) -> Dict[str, Any]

@mcp.tool()
async def disconnect_device(device_id, credential_id) -> Dict[str, Any]

@mcp.tool()
async def send_command(device_id, credential_id, command, timeout) -> Dict[str, Any]

@mcp.tool()
async def send_commands(device_id, credential_id, commands, timeout) -> List[Dict[str, Any]]

@mcp.tool()
async def get_active_connections() -> List[Dict[str, Any]]

拓扑发现工具 (6个)

@mcp.tool()
async def discover_topology(device_ids) -> Dict[str, Any]

@mcp.tool()
async def get_topology() -> Dict[str, Any]

@mcp.tool()
async def clear_topology() -> Dict[str, Any]

@mcp.tool()
async def get_device_neighbors(device_id) -> Dict[str, Any]

@mcp.tool()
async def discover_device_neighbors(device_id) -> Dict[str, Any]

@mcp.tool()
async def get_topology_statistics() -> Dict[str, Any]

网络扫描工具 (6个)

@mcp.tool()
async def scan_network_range(network, timeout, max_concurrent, ...) -> Dict[str, Any]

@mcp.tool()
async def get_scan_results(ip_address, alive_only) -> Dict[str, Any]

@mcp.tool()
async def get_scan_statistics() -> Dict[str, Any]

@mcp.tool()
async def discover_devices_from_scan_results(...) -> Dict[str, Any]

@mcp.tool()
async def clear_scan_results() -> Dict[str, Any]

@mcp.tool()
async def scan_single_host(ip_address, timeout, ...) -> Dict[str, Any]

其他工具 (9个)

凭据管理：2个
资源管理：3个
模板管理：2个
测试工具：2个

4.2 实际MCP资源接口

系统提供以下13个MCP资源：

# 设备相关资源 (5个)
@resource_manager.register_resource("device/{device_id}", ResourceType.DEVICE)
@resource_manager.register_resource("device/{device_id}/config", ResourceType.CONFIG)
@resource_manager.register_resource("device/{device_id}/interfaces", ResourceType.DEVICE)
@resource_manager.register_resource("device/{device_id}/routes", ResourceType.DEVICE)
@resource_manager.register_resource("device/{device_id}/neighbors", ResourceType.TOPOLOGY)

# 系统资源 (4个)
@resource_manager.register_resource("greeting/{name}", ResourceType.SYSTEM)
@resource_manager.register_resource("credentials", ResourceType.CREDENTIAL)
@resource_manager.register_resource("system/status", ResourceType.SYSTEM)
@resource_manager.register_resource("topology", ResourceType.TOPOLOGY)

# 拓扑资源 (1个)
@resource_manager.register_resource("topology/statistics", ResourceType.TOPOLOGY)

# 扫描资源 (3个)
@resource_manager.register_resource("scan/results", ResourceType.SCAN)
@resource_manager.register_resource("scan/statistics", ResourceType.SCAN)
@resource_manager.register_resource("scan/result/{ip_address}", ResourceType.SCAN)

5. 安全设计

5.1 当前安全实现状态

已实现的安全措施：

日志记录：完整的操作日志和审计跟踪
凭据存储：JSON文件存储（明文，需要加密改进）
连接安全：基于SSH/Telnet的设备连接
输入验证：工具参数验证和类型检查

待实现的安全措施：

凭据加密：计划实现AES-256加密存储
访问控制：计划实现基于角色的权限管理
传输加密：计划支持HTTPS/WSS
API认证：计划实现API密钥认证

5.2 数据安全

当前数据保护措施：

敏感数据标识：明确识别设备凭据等敏感信息
日志脱敏：避免在日志中记录明文密码
文件权限：建议设置适当的文件系统权限

6. 扩展性设计

6.1 模块化架构

系统采用高度模块化的设计：

独立模块：每个模块都有明确的职责和接口
装饰器模式：工具、资源、模板均通过装饰器注册
抽象接口：DeviceConnector抽象基类支持多种连接器实现
工厂模式：ConnectorFactory根据设备类型创建合适的连接器

6.2 多厂商支持

已支持的厂商：

Cisco：IOS, IOS-XE, NX-OS
Huawei：VRP系统
H3C：Comware系统
Juniper：JUNOS系统
Arista：EOS系统

扩展机制：

Scrapli平台适配：通过platform字段指定驱动类型
命令模板适配：针对不同厂商的命令差异进行适配
邻居发现适配：为不同厂商实现专用的邻居发现方法

6.3 协议支持

当前支持的协议：

SSH：主要连接协议，支持密钥和密码认证
Telnet：备用连接协议
SNMP：计划支持
NETCONF：计划支持

7. 部署架构

7.1 单机部署（当前实现）

适用于小型网络环境和开发测试：

+-----------------+
| NetBrain MCP    |
| Python应用      |
| FastMCP服务器   |
| JSON文件存储    |
+-----------------+
        |
        | Scrapli
        |
+-------v-------+
| 网络设备     |
| (多厂商)     |
+--------------+

部署要求：

Python 3.10+
依赖包：scrapli, mcp, fastapi等
网络访问：能够SSH/Telnet到目标设备

7.2 容器化部署（计划）

支持Docker容器化部署：

+------------------+
| Docker容器       |
| ├── NetBrain MCP |
| ├── Python环境   |
| └── 数据卷       |
+------------------+

7.3 分布式部署（未来规划）

适用于大型网络环境：

+-------------+    +-------------+    +-------------+
| MCP API服务 |--->| 设备管理服务 |--->| 数据库服务  |
+-------------+    +-------------+    +-------------+
       ^                  ^
       |                  |
       v                  v
+-------------+    +-------------+
| 拓扑服务    |<-->| 扫描服务    |
+-------------+    +-------------+

8. 技术栈

8.1 实际技术栈

核心框架：

MCP框架：FastMCP（基于mcp Python包）
异步框架：asyncio
设备连接：Scrapli（支持异步/同步混合模式）

编程语言：

Python：3.10+
类型提示：完整的类型注解支持

数据存储：

文件存储：JSON格式
缓存：内存缓存 + 文件缓存
数据持久化：自动加载和保存机制

网络协议：

SSH：asyncssh（异步）/ paramiko（同步）
Telnet：telnetlib3
其他：计划支持SNMP、NETCONF

日志系统：

日志框架：Python logging
格式化：JsonFormatter支持UTF-8
文件管理：日志轮转和归档

8.2 依赖包版本

根据requirements.txt：

scrapli>=2025.1.30      # 网络设备连接
mcp                     # MCP协议支持
fastapi                 # Web框架（Web界面）
asyncio                 # 异步支持
jinja2                  # 模板引擎
pydantic               # 数据验证
websockets             # WebSocket支持

9. 性能特征

9.1 并发性能

异步架构优势：

全异步设计，支持高并发操作
混合异步/同步模式，兼容不同类型的连接器
连接池管理，减少连接开销

性能指标：

并发连接：支持多设备同时连接
命令执行：支持批量命令并发执行
资源缓存：5分钟默认TTL，减少重复获取

9.2 内存管理

缓存策略：

资源缓存：内存 + 文件双层缓存
连接缓存：活动连接池管理
模板缓存：编译后的模板缓存

内存优化：

按需加载：资源和连接按需创建
自动清理：过期缓存自动清理
连接管理：空闲连接自动断开

10. 开发路线图

10.1 已完成阶段 ✅

阶段一：MCP协议实现与基础框架

FastMCP服务器架构
32个MCP工具实现
13个MCP资源实现
基础架构设计

阶段二：网络设备管理

基于Scrapli的设备连接引擎
多厂商设备支持
设备认证管理系统
JSON文件数据存储

阶段三：配置管理与MCP增强

13个提示模板系统
资源缓存机制
拓扑发现功能
网络扫描功能

阶段四：测试与文档

系统功能测试
技术文档编写
用户操作指南

10.2 当前系统状态

项目状态：✅ 已完成所有计划功能

核心功能完成度：

MCP协议实现：100%
设备管理功能：100%
连接管理功能：100%
拓扑发现功能：100%
网络扫描功能：100%
模板系统：100%
资源系统：100%

生产就绪状态：

功能完整性：✅ 完成
稳定性测试：✅ 完成
文档完善：✅ 完成
部署准备：✅ 完成

10.3 未来增强方向

安全增强：

凭据加密存储
基于角色的访问控制
API认证机制
审计日志增强

性能优化：

数据库支持（SQLite/PostgreSQL）
分布式架构支持
缓存优化策略
连接池调优

功能扩展：

Web管理界面增强
更多厂商设备支持
高级网络分析功能
监控告警系统

集成能力：

第三方API集成
企业身份认证集成
监控系统集成
配置管理平台集成

NetBrain MCP系统已成功完成所有预定目标，具备生产环境部署条件。系统架构设计合理，技术栈成熟稳定，功能完整丰富，为AI驱动的网络运维提供了强大的基础平台。

19 KiB Raw Blame History Unescape Escape

NetBrain MCP 系统架构设计

1. 整体架构

2. 核心模块说明

2.1 MCP服务器模块 (server.py)

2.2 工具管理模块 (tool_manager.py)

2.3 资源模块 (mcp_resources.py)

2.4 设备管理模块 (network_devices.py)

2.5 设备连接模块 (device_connector.py)

2.6 模板系统 (template_system.py + device_prompts.py)

2.7 拓扑发现模块 (topology_discovery_improved.py)

2.8 网络扫描模块 (network_scanner.py)

3. 数据模型

3.1 实际数据存储架构

3.2 核心数据实体关系

4. 接口设计

4.1 实际MCP工具接口

设备管理工具 (6个)

连接管理工具 (5个)

拓扑发现工具 (6个)

网络扫描工具 (6个)

其他工具 (9个)

4.2 实际MCP资源接口

5. 安全设计

5.1 当前安全实现状态

5.2 数据安全

6. 扩展性设计

6.1 模块化架构

6.2 多厂商支持

6.3 协议支持

7. 部署架构

7.1 单机部署（当前实现）

7.2 容器化部署（计划）

7.3 分布式部署（未来规划）

8. 技术栈

8.1 实际技术栈

8.2 依赖包版本

9. 性能特征

9.1 并发性能

9.2 内存管理

10. 开发路线图

10.1 已完成阶段 ✅

10.2 当前系统状态

10.3 未来增强方向

19 KiB

Raw Blame History