Add files via upload

2025-05-30 21:59:39 +08:00
parent d7b1778a85
commit 3236fa947d
88 changed files with 30606 additions and 0 deletions
@@ -0,0 +1,729 @@
+# NetBrain MCP 项目教程
+
+本教程详细介绍如何使用NetBrain MCP项目，包括MCP协议的基本概念、实际实现方式和高级使用技巧。
+
+## 1. MCP协议概述
+
+### 1.1 什么是MCP？
+
+MCP（Model Context Protocol）是一个开放标准，用于连接LLM（大型语言模型）应用程序与外部数据源和工具。可以将MCP视为"AI领域的USB-C"——一种通用连接器，使AI模型能够与外部工具或数据源建立安全的双向连接。
+
+### 1.2 NetBrain MCP的实现特点
+
+NetBrain MCP基于**FastMCP框架**实现，具有以下特点：
+
+- **32个MCP工具**：涵盖设备管理、连接控制、拓扑发现、网络扫描等
+- **13个MCP资源**：提供设备、配置、拓扑、扫描等数据资源
+- **13个提示模板**：专业的网络运维AI提示模板
+- **混合异步/同步模式**：智能适配不同类型的设备连接
+- **多厂商支持**：思科、华为、H3C、Juniper等主流设备
+
+## 2. MCP核心概念
+
+### 2.1 工具（Tools）
+
+工具是模型控制的函数，允许LLM执行动作和产生副作用。
+
+#### 2.1.1 NetBrain MCP工具分类
+
+**设备管理工具（6个）**
+```python
+@mcp.tool()
+async def list_devices(vendor: str = None, device_type: str = None, status: str = None, tag: str = None) -> List[Dict[str, Any]]:
+    """列出网络设备，支持过滤条件"""
+
+@mcp.tool()  
+async def add_device(name: str, ip_address: str, device_type: str, vendor: str, platform: str = None, ...) -> Dict[str, Any]:
+    """添加新的网络设备"""
+
+@mcp.tool()
+async def get_device(device_id: str) -> Optional[Dict[str, Any]]:
+    """获取设备详细信息"""
+
+@mcp.tool()
+async def update_device(device_id: str, **kwargs) -> Optional[Dict[str, Any]]:
+    """更新设备信息"""
+
+@mcp.tool()
+async def delete_device(device_id: str) -> bool:
+    """删除设备"""
+```
+
+**连接管理工具（5个）**
+```python
+@mcp.tool()
+async def connect_device(device_id: str, credential_id: str) -> Dict[str, Any]:
+    """连接到网络设备"""
+
+@mcp.tool()
+async def disconnect_device(device_id: str, credential_id: str) -> Dict[str, Any]:
+    """断开设备连接"""
+
+@mcp.tool()
+async def send_command(device_id: str, credential_id: str, command: str, timeout: int = 30) -> Dict[str, Any]:
+    """发送单个命令到设备"""
+
+@mcp.tool()
+async def send_commands(device_id: str, credential_id: str, commands: List[str], timeout: int = 30) -> List[Dict[str, Any]]:
+    """发送多个命令到设备"""
+
+@mcp.tool()
+async def get_active_connections() -> List[Dict[str, Any]]:
+    """获取当前活动的设备连接"""
+```
+
+**拓扑发现工具（6个）**
+```python
+@mcp.tool()
+async def discover_topology(device_ids: List[str]) -> 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: str) -> Dict[str, Any]:
+    """获取设备的邻居信息"""
+
+@mcp.tool()
+async def discover_device_neighbors(device_id: str) -> Dict[str, Any]:
+    """发现设备邻居"""
+
+@mcp.tool()
+async def get_topology_statistics() -> Dict[str, Any]:
+    """获取拓扑统计信息"""
+```
+
+#### 2.1.2 工具实现方式
+
+NetBrain MCP使用FastMCP的装饰器方式注册工具：
+
+```python
+# 在server.py中的实际实现
+from mcp.server.fastmcp import FastMCP
+from network_devices import device_manager
+from device_connector import connection_manager
+
+# 创建FastMCP服务器实例
+mcp = FastMCP("NetBrain MCP")
+
+@mcp.tool()
+async def add_device(
+    name: str,
+    ip_address: str, 
+    device_type: str,
+    vendor: str,
+    platform: str = None,
+    model: str = None,
+    os_version: str = None,
+    location: str = None,
+    description: str = None
+) -> Dict[str, Any]:
+    """添加新的网络设备到系统中"""
+    try:
+        # 创建设备对象
+        device = NetworkDevice(
+            name=name,
+            ip_address=ip_address,
+            device_type=DeviceType(device_type),
+            vendor=DeviceVendor(vendor),
+            platform=platform or "",
+            model=model or "",
+            os_version=os_version or "",
+            location=location or "",
+            description=description or ""
+        )
+        
+        # 添加设备
+        device_id = device_manager.add_device(device)
+        
+        return {
+            "success": True,
+            "device_id": device_id,
+            "message": f"设备 {name} 添加成功"
+        }
+        
+            except Exception as e:
+        logger.error(f"添加设备失败: {str(e)}")
+        return {
+            "success": False,
+            "error": str(e)
+        }
+```
+
+### 2.2 资源（Resources）
+
+资源是应用程序控制的数据对象，通过URI标识，用于为LLM提供上下文信息。
+
+#### 2.2.1 NetBrain MCP资源列表
+
+系统实现了13个MCP资源：
+
+**设备相关资源（5个）**
+```python
+@resource_manager.register_resource("device/{device_id}", ResourceType.DEVICE)
+async def get_device_resource(device_id: str) -> Dict[str, Any]:
+    """获取设备基本信息"""
+
+@resource_manager.register_resource("device/{device_id}/config", ResourceType.CONFIG)
+async def get_device_config_resource(device_id: str) -> Dict[str, Any]:
+    """获取设备配置信息"""
+
+@resource_manager.register_resource("device/{device_id}/interfaces", ResourceType.DEVICE)
+async def get_device_interfaces_resource(device_id: str) -> Dict[str, Any]:
+    """获取设备接口信息"""
+
+@resource_manager.register_resource("device/{device_id}/routes", ResourceType.DEVICE)
+async def get_device_routes_resource(device_id: str) -> Dict[str, Any]:
+    """获取设备路由信息"""
+
+@resource_manager.register_resource("device/{device_id}/neighbors", ResourceType.TOPOLOGY)
+async def get_device_neighbors_resource(device_id: str) -> Dict[str, Any]:
+    """获取设备邻居信息"""
+```
+
+**系统资源（4个）**
+```python
+@resource_manager.register_resource("greeting/{name}", ResourceType.SYSTEM)
+async def get_greeting_resource(name: str) -> Dict[str, Any]:
+    """问候信息资源（示例）"""
+
+@resource_manager.register_resource("credentials", ResourceType.CREDENTIAL)
+async def get_credentials_resource() -> Dict[str, Any]:
+    """获取凭据列表"""
+
+@resource_manager.register_resource("system/status", ResourceType.SYSTEM)
+async def get_system_status_resource() -> Dict[str, Any]:
+    """获取系统状态"""
+
+@resource_manager.register_resource("topology", ResourceType.TOPOLOGY)
+async def get_topology_resource() -> Dict[str, Any]:
+    """获取网络拓扑"""
+```
+
+#### 2.2.2 资源实现方式
+
+```python
+# 在server.py中的实际资源处理器
+@mcp.resource("{uri}")
+async def mcp_resource_handler(uri: str) -> Any:
+    """
+    MCP资源处理器，处理所有资源请求
+    
+    Args:
+        uri: 资源URI
+        
+    Returns:
+        资源内容
+    """
+    try:
+        result = await resource_manager.get_resource(uri)
+        return result
+    except Exception as e:
+        logger.error(f"获取资源失败: {uri}, 错误: {str(e)}")
+        return {"error": f"获取资源失败: {str(e)}"}
+```
+
+### 2.3 提示模板（Prompts）
+
+提示模板是用户控制的交互模板，帮助构造有效的LLM提示。
+
+#### 2.3.1 NetBrain MCP提示模板
+
+系统实现了13个专业网络运维提示模板：
+
+**template_system.py中的模板（8个）**
+```python
+@template_manager.register_template(
+    name="device_diagnosis",
+    description="网络设备诊断模板"
+)
+def device_diagnosis_template(device_info: Dict[str, Any], interfaces_info: str = None, logs: str = None) -> List[Message]:
+    """网络设备诊断提示模板，用于分析设备状态和接口信息"""
+    system_prompt = f"""你是一位专业的网络工程师，负责诊断{device_info.get('vendor', '未知厂商')}的{device_info.get('device_type', '网络设备')}。
+请根据提供的设备信息、接口状态和日志，进行专业分析并提供诊断报告。"""
+    
+    return [
+        SystemMessage(system_prompt),
+        UserMessage(f"请诊断设备：{device_info}")
+    ]
+
+@template_manager.register_template(
+    name="config_review", 
+    description="网络设备配置审查模板"
+)
+def config_review_template(device_info: Dict[str, Any], config_content: str, focus_area: str = None) -> List[Message]:
+    """网络配置审查提示模板，用于审查设备配置并提供改进建议"""
+    # 实现...
+```
+
+**device_prompts.py中的模板（5个）**
+```python
+@template_manager.register_template(
+    name="cisco_device_analysis",
+    description="思科设备专业分析模板"
+)
+def cisco_device_analysis_template(device_info: Dict[str, Any], command_outputs: Dict[str, str]) -> List[Message]:
+    """思科设备专业分析模板"""
+    # 实现...
+
+@template_manager.register_template(
+    name="huawei_device_analysis", 
+    description="华为设备专业分析模板"
+)
+def huawei_device_analysis_template(device_info: Dict[str, Any], command_outputs: Dict[str, str]) -> List[Message]:
+    """华为设备专业分析模板"""
+    # 实现...
+```
+
+#### 2.3.2 模板实现方式
+
+```python
+# 在server.py中的模板处理器
+@mcp.prompt("{name}")
+async def mcp_prompt_handler(name: str, arguments: dict = None) -> str:
+    """
+    MCP提示模板处理器
+    
+    Args:
+        name: 模板名称
+        arguments: 模板参数
+        
+    Returns:
+        渲染后的提示内容
+    """
+    try:
+        result = template_manager.render_template(name, arguments or {})
+        if isinstance(result, list):
+            # 如果返回消息列表，转换为字符串
+            return "\n".join([msg.content for msg in result])
+        return result or ""
+    except Exception as e:
+        logger.error(f"渲染模板失败: {name}, 错误: {str(e)}")
+        return f"模板渲染失败: {str(e)}"
+```
+
+## 3. 实际使用示例
+
+### 3.1 基本设备管理
+
+#### 3.1.1 添加设备凭据
+
+```
+# 在Claude或其他MCP客户端中输入：
+请帮我添加一个思科设备的SSH凭据，用户名是admin，密码是cisco123，端口是22
+```
+
+AI将自动调用`add_credential`工具：
+```python
+# 实际调用的工具
+await add_credential(
+    name="思科SSH凭据",
+    username="admin", 
+    password="cisco123",
+    protocol="ssh",
+    port=22
+)
+```
+
+#### 3.1.2 添加网络设备
+
+```
+请添加一台思科路由器，名称是Router-01，IP地址是192.168.1.1，型号是ISR4321，使用刚才添加的凭据
+```
+
+AI将调用`add_device`工具：
+```python
+await add_device(
+    name="Router-01",
+    ip_address="192.168.1.1",
+    device_type="router",
+    vendor="cisco", 
+    platform="cisco_iosxe",
+    model="ISR4321"
+)
+```
+
+### 3.2 设备连接和命令执行
+
+#### 3.2.1 连接设备
+
+```
+请连接到Router-01设备
+```
+
+AI将调用连接工具：
+```python
+await connect_device(
+    device_id="router-01-uuid",
+    credential_id="credential-uuid"
+)
+```
+
+#### 3.2.2 执行命令
+
+```
+在Router-01上执行 show version 命令
+```
+
+AI将调用命令执行工具：
+```python
+await send_command(
+    device_id="router-01-uuid",
+    credential_id="credential-uuid", 
+    command="show version",
+    timeout=30
+)
+```
+
+### 3.3 拓扑发现
+
+```
+请发现Router-01的网络拓扑
+```
+
+AI将调用拓扑发现工具：
+```python
+await discover_topology(
+    device_ids=["router-01-uuid"]
+)
+```
+
+### 3.4 使用提示模板
+
+```
+使用设备诊断模板分析Router-01的状态
+```
+
+AI将：
+1. 获取设备信息资源
+2. 获取设备接口信息 
+3. 使用device_diagnosis模板进行分析
+
+## 4. 高级功能
+
+### 4.1 批量操作
+
+#### 4.1.1 批量命令执行
+
+```
+在Router-01上依次执行以下命令：
+1. show running-config
+2. show ip route
+3. show interface status
+```
+
+AI将调用`send_commands`工具：
+```python
+await send_commands(
+    device_id="router-01-uuid",
+    credential_id="credential-uuid",
+    commands=[
+        "show running-config",
+        "show ip route", 
+        "show interface status"
+    ]
+)
+```
+
+#### 4.1.2 网络扫描
+
+```
+请扫描192.168.1.0/24网段，发现网络设备
+```
+
+AI将调用网络扫描工具：
+```python
+await scan_network_range(
+    network="192.168.1.0/24",
+    timeout=5,
+    max_concurrent=50,
+    ports=[22, 23, 80, 443, 161]
+)
+```
+
+### 4.2 资源访问
+
+#### 4.2.1 获取设备配置
+
+```
+请获取Router-01的配置信息
+```
+
+AI将访问配置资源：
+```
+资源URI: device/router-01-uuid/config
+```
+
+#### 4.2.2 获取拓扑信息
+
+```
+显示当前网络拓扑的统计信息
+```
+
+AI将访问拓扑资源：
+```
+资源URI: topology/statistics
+```
+
+### 4.3 智能诊断
+
+#### 4.3.1 使用诊断模板
+
+```
+使用华为设备分析模板检查Switch-01的状态
+```
+
+AI将：
+1. 识别设备是华为设备
+2. 获取设备相关信息和命令输出
+3. 使用`huawei_device_analysis`模板
+4. 提供专业的分析报告
+
+#### 4.3.2 配置审查
+
+```
+使用配置审查模板检查Router-01的安全配置
+```
+
+AI将使用`config_review`模板，重点关注安全配置。
+
+## 5. 系统集成
+
+### 5.1 连接到Claude Desktop
+
+#### 5.1.1 配置文件
+
+编辑Claude Desktop配置文件：
+
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+   ```json
+   {
+   "mcpServers": {
+    "netbrain-mcp": {
+       "command": "python",
+      "args": ["/path/to/NetBrainMCP/server.py"],
+      "env": {
+        "LOG_LEVEL": "INFO"
+      }
+     }
+   }
+   }
+   ```
+
+#### 5.1.2 验证连接
+
+重启Claude Desktop后，在对话中输入：
+```
+请列出所有可用的网络设备
+```
+
+如果看到工具图标并得到设备列表响应，说明连接成功。
+
+### 5.2 连接到Cursor IDE
+
+#### 5.2.1 启动SSE模式
+
+```bash
+cd /path/to/NetBrainMCP
+python server.py --mode sse --port 8000
+```
+
+#### 5.2.2 配置Cursor
+
+1. 打开Cursor → 设置 → 功能 → MCP服务器
+2. 添加新服务器：
+   - **名称**: netbrain-mcp
+   - **类型**: sse  
+   - **URL**: http://localhost:8000/sse
+
+### 5.3 Web界面使用
+
+#### 5.3.1 启动Web服务器
+
+```bash
+python server.py --web --port 8080
+```
+
+#### 5.3.2 访问Web界面
+
+在浏览器中访问：http://localhost:8080
+
+Web界面提供：
+- 设备管理页面
+- 多标签页终端
+- 交互式拓扑图
+
+## 6. 故障排除
+
+### 6.1 常见问题
+
+#### 6.1.1 MCP服务器无法启动
+
+**问题症状**：
+```
+ModuleNotFoundError: No module named 'mcp'
+```
+
+**解决方案**：
+```bash
+pip install -r requirements.txt
+```
+
+#### 6.1.2 设备连接失败
+
+**问题症状**：
+```
+{"success": false, "error": "连接超时"}
+```
+
+**解决方案**：
+1. 检查网络连通性：`ping 192.168.1.1`
+2. 验证SSH/Telnet服务：`telnet 192.168.1.1 22`
+3. 确认凭据正确性
+4. 检查防火墙设置
+
+#### 6.1.3 Claude Desktop连接问题
+
+**问题症状**：Claude Desktop不显示工具图标
+
+**解决方案**：
+1. 检查配置文件路径和格式
+2. 验证Python路径和脚本路径
+3. 查看Claude Desktop日志
+4. 重启Claude Desktop
+
+### 6.2 调试技巧
+
+#### 6.2.1 启用详细日志
+
+```bash
+export LOG_LEVEL=DEBUG
+python server.py
+```
+
+#### 6.2.2 测试工具连接
+
+```python
+# 测试Scrapli连接
+python -c "
+import asyncio
+from server import test_scrapli_connection
+result = asyncio.run(test_scrapli_connection(
+    host='192.168.1.1',
+    username='admin',
+    password='cisco123',
+    platform='cisco_iosxe'
+))
+print(result)
+"
+```
+
+## 7. 扩展开发
+
+### 7.1 添加自定义工具
+
+```python
+@mcp.tool()
+async def custom_network_tool(param1: str, param2: int) -> Dict[str, Any]:
+    """自定义网络工具"""
+    try:
+        # 实现自定义逻辑
+        result = perform_custom_operation(param1, param2)
+        return {"success": True, "result": result}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+```
+
+### 7.2 添加自定义资源
+
+```python
+@resource_manager.register_resource("custom/{id}", ResourceType.CUSTOM)
+async def get_custom_resource(id: str) -> Dict[str, Any]:
+    """自定义资源处理器"""
+    # 实现自定义资源获取逻辑
+    return {"data": f"自定义数据 for {id}"}
+```
+
+### 7.3 添加自定义模板
+
+```python
+@template_manager.register_template(
+    name="custom_analysis",
+    description="自定义分析模板"
+)
+def custom_analysis_template(data: Dict[str, Any]) -> str:
+    """自定义分析模板"""
+    return f"基于数据 {data} 进行自定义分析..."
+```
+
+## 8. 最佳实践
+
+### 8.1 设备管理最佳实践
+
+1. **统一命名规范**：使用一致的设备命名格式
+2. **合理分组标签**：按功能、位置、环境分组
+3. **定期更新信息**：保持设备信息的准确性
+4. **备份配置数据**：定期备份重要配置
+
+### 8.2 使用技巧
+
+1. **充分利用模板**：使用专业模板获得更好的分析结果
+2. **批量操作**：对多个设备执行相同操作时使用批量工具
+3. **资源组合**：结合多个资源获得全面的设备视图
+4. **缓存机制**：利用系统缓存提高查询效率
+
+### 8.3 安全建议
+
+1. **凭据管理**：使用强密码和定期轮换
+2. **网络隔离**：在安全的网络环境中部署
+3. **访问控制**：限制MCP服务器的访问权限
+4. **日志监控**：定期检查操作日志
+
+## 9. 性能优化
+
+### 9.1 连接优化
+
+```python
+# 调整连接池设置
+MAX_CONNECTIONS = 10
+CONNECTION_TIMEOUT = 30
+COMMAND_TIMEOUT = 60
+```
+
+### 9.2 缓存优化
+
+```python
+# 调整缓存策略
+RESOURCE_CACHE_TTL = 300  # 5分钟
+CONFIG_CACHE_TTL = 600    # 10分钟
+TOPOLOGY_CACHE_TTL = 900  # 15分钟
+```
+
+### 9.3 并发控制
+
+```python
+# 网络扫描并发控制
+DEFAULT_MAX_CONCURRENT = 50
+SCAN_TIMEOUT = 5
+```
+
+## 10. 总结
+
+NetBrain MCP项目提供了一个完整的网络运维AI集成平台，通过MCP协议实现：
+
+- **32个专业工具**：涵盖网络设备管理的各个方面
+- **13个数据资源**：提供丰富的网络设备和拓扑信息
+- **13个提示模板**：专业的网络运维AI指导
+- **多厂商支持**：思科、华为等主流设备厂商
+- **灵活部署**：支持Claude Desktop、Cursor IDE和Web界面
+
+通过本教程，您应该能够熟练使用NetBrain MCP系统进行AI驱动的网络运维工作。系统的模块化设计和丰富的扩展机制，也为进一步的定制和开发提供了良好的基础。