后端网络运维数据可视化【免费下载链接】NetAlertXCentralized network visibility and continuous asset discovery. Monitor devices, detect change, and stay aware across distributed networks.项目地址https://gitcode.com/gh_mirrors/ne/NetAlertX点击查看免费下载NetAlertX 的MCPModel Context ProtocolServer Bridge将网络监控能力以标准化的「MCP 工具Tools」形式暴露给 AI 助手并通过 Server-Sent Events 实现实时通信。本文基于 docs/API_MCP.md 并对照仓库源码 server/api_server/mcp_endpoint.py、server/api_server/api_server_start.py 与测试用例 test/api_endpoints/test_mcp_tools_endpoints.py完整讲解 MCP 接入的架构原理、认证方式、端点、工具清单、调用示例、AI 客户端集成与错误处理读完即可让 Claude Desktop 或自定义 MCP 客户端直接操作 NetAlertX 的设备和网络数据。一、MCP Server Bridge 能做什么MCP Server Bridge 把 NetAlertX 的 REST API 能力包装成 AI 助手可调用的MCP Tools典型能力包括搜索、查询设备信息按 MAC、名称、IP、厂商触发网络扫描如 ARP 扫描获取网络拓扑与事件告警通过 Wake-on-LAN 唤醒设备获取已存储的开放端口信息为设备设置别名所有 MCP 端点与标准 REST 端点功能一致但针对 AI 助手集成做了协议级优化。MCP 桥接层自动处理请求/响应序列化AI 客户端无需感知底层 HTTP 细节。从源码看MCP 桥的实现位于 mcp_endpoint.py遵循JSON-RPC 2.0 over HTTP SSE的 MCP 标准协议支持协议版本2024-11-05见 mcp_endpoint.py 第 52 行并声明了tools、resources、prompts三类标准能力。二、架构与连接流程2.1 三层组件架构MCP Bridge 由三部分组成源码注释见 mcp_endpoint.py 第 16-22 行层组件说明AI 客户端Claude Desktop / 自定义 MCP 客户端通过 SSE Bearer 认证连接MCP 服务器:20212/mcp/sse、/mcp/messages、/mcp/sse/openapi.json会话管理与 JSON-RPC 处理API 服务器:20211内部回环/devices/*、/nettools/*、/events/*实际业务逻辑注意端口说明文档与架构图中的:20212为GRAPHQL_PORT即 API 服务器端口也是 MCP 端点所在端口20211为前端 WebUI 端口。实际以你的GRAPHQL_PORT设置值为准默认 20212相关排查可参考 docs/DEBUG_API_SERVER.md。2.2 MCP 连接与工具调用时序一次典型的 AI 助手工具调用过程如下AI 助手通过 SSE 连接/mcp/sse建立持久会话会话建立后AI 发送tools/list请求MCP 服务器内部请求/mcp/sse/openapi.json由 openapi_spec() 路由处理获取可用工具规格MCP 将 OpenAPI 规格转换为 MCP 工具定义返回给 AIAI 发送tools/call例如search_devicesMCP 服务器通过内部回环 HTTP 调用API 端点POST /devices/search见 _execute_tool()回环地址为http://localhost:{GRAPHQL_PORT}API 查询 SQLite 数据库返回 JSONMCP 服务器将结果包装为 MCP 工具结果格式返回给 AI。2.3 内部实现要点会话管理每次 SSE GET 连接会创建session_idUUID消息通过有界队列默认上限 1000可由设置MCP_QUEUE_MAXSIZE调整传递空闲会话超过 300 秒SESSION_TIMEOUT会被后台清理线程回收SSE 每 20 秒SSE_KEEPALIVE_INTERVAL发送 keep-alive 注释保持连接mcp_endpoint.py 第 57-60 行。工具动态映射工具并非硬编码而是由 OpenAPI 注册表动态生成。map_openapi_to_mcp_tools()会把 OpenAPI operation 转换为 MCP 工具的inputSchema自动从请求体与路径/查询参数推导参数与必填项mcp_endpoint.py 第 307 行。工具按operationId去重优先选择/mcp/路由与 POST 方法保证同名工具只出现一次。OpenAPI 规格生成规格由 spec_generator.py 基于注册表与 Flask 路由内省生成含 Pydantic 模型到 JSON Schema 的自动转换并强制operationId全局唯一registry.py。Pydantic 校验工具调用前会对参数做 Pydantic 模型校验request_model校验失败返回结构化错误mcp_endpoint.py 第 710-727 行。三、认证机制MCP 端点与 REST 端点共用Bearer Token 认证使用Settings → Core → General中的API_TOKENAuthorization: Bearer API_TOKEN认证校验逻辑见 check_auth()Fail closed若API_TOKEN未配置或过短少于 2 字符直接拒绝访问并记录严重日志两种传递方式优先解析Authorization头中的Bearertoken同时支持查询字符串?token...主要为 SSE 等流式端点设计。源码明确警告查询字符串 token 可能暴露在访问日志、浏览器历史、Referer 头与代理日志中应优先使用 Authorization 头疑似泄露时及时轮换 token恒定时间比较使用secrets.compare_digest()做 token 比较防止时序攻击测试模式环境变量MCP_TEST_MODE1可在无 token 时绕过认证但严禁在生产环境启用。未授权请求返回 HTTP 403{ success: false, message: ERROR: Not authorized, error: Forbidden }四、连接端点与 OpenAPI 规格4.1 主连接端点/mcp/sseGET/POST/mcp/sseAI 客户端的主连接端点通过 Server-Sent Events 建立持久连接api_server_start.py 第 194 行。GET创建会话并建立 SSE 流首个事件为endpoint事件携带消息投递地址/mcp/messages?session_ididmcp_endpoint.py 第 1061 行POST无状态地直接处理 JSON-RPC 请求并返回响应OPTIONSCORS 预检。浏览器端连接示例const eventSource new EventSource(/mcp/sse, { headers: { Authorization: Bearer API_TOKEN } }); eventSource.onmessage function(event) { const response JSON.parse(event.data); console.log(MCP Response:, response); };4.2 消息端点/mcp/messagesPOST/mcp/messages?session_idid向指定会话提交 JSON-RPC 消息处理结果会入队并由 SSE 流推送回客户端mcp_endpoint.py 第 1088 行。缺少session_id返回 400会话不存在或过期返回 404队列已满返回 503。4.3 OpenAPI 规格端点GET/mcp/sse/openapi.json另有等价入口/openapi.json返回全部 MCP 工具的 OpenAPI 3.1 规格描述每个工具的参数与 schema。{ openapi: 3.0.0, info: { title: NetAlertX Tools, version: 1.1.0 }, servers: [{url: /}], paths: { /devices/by-status: { post: {operationId: list_devices} }, /device/{mac}: { post: {operationId: get_device_info} }, /devices/search: { post: {operationId: search_devices} } } }从源码看规格缓存于_openapi_spec_cache并会识别反向代理头X-Forwarded-Prefix以正确生成servers前缀mcp_endpoint.py 第 240-300 行。此外还有GET /docs提供 Swagger UI 便于人工浏览工具定义。五、可用 MCP 工具清单以下工具清单与 OpenAPI 规格中的operationId一一对应路由定义见 api_server_start.py5.1 设备管理工具工具端点说明list_devices/devices/by-status按在线状态列出设备status支持connected、down、favorites、new、archived、all、my、offline见 api_server_start.py 第 849-852 行get_device_info/device/{mac}获取指定 MAC 设备的详细信息MAC 需符合00:11:22:33:44:55格式正则search_devices/devices/search按 MAC、名称或 IP 搜索设备用于为其他工具定位 MAC 地址get_latest_device/devices/latest获取最近一次发现的设备set_device_alias/device/{mac}/set-alias设置设备友好名称实质为更新devName列5.2 网络工具工具端点说明trigger_scan/nettools/trigger-scan触发网络发现扫描type需匹配已加载插件名如ARPSCAN默认值ARPSCAN校验见 api_server_start.py 第 1195-1197 行run_nmap_scan/nettools/nmap对目标执行 NMAP 扫描以识别开放端口scan为目标 IP/网段mode为扫描模式get_open_ports/device/open_ports获取已存储的 NMAP 开放端口为空时需先调用run_nmap_scanwol_wake_device/nettools/wakeonlan通过 Wake-on-LAN 唤醒设备支持仅传 IP 时自动解析 MACget_network_topology/devices/network/topology获取网络拓扑地图5.3 事件与监控工具工具端点说明get_recent_alerts/events/recent获取最近 24 小时默认可通过hours参数调整的事件get_last_events/events/last获取最近 10 条事件六、工具调用实战示例MCP 工具调用采用 JSON-RPC 2.0 格式method为tools/callparams.name为工具名params.arguments为参数对象。6.1 搜索设备search_devices工具调用{ jsonrpc: 2.0, id: 1, method: tools/call, params: { name: search_devices, arguments: { query: 192.168.1 } } }响应{ jsonrpc: 2.0, id: 1, result: { content: [ { type: text, text: {\n \success\: true,\n \devices\: [\n {\n \devName\: \Router\,\n \devMac\: \AA:BB:CC:DD:EE:FF\,\n \devLastIP\: \192.168.1.1\\n }\n ]\n} } ], isError: false } }底层实现上search_devices对应POST /devices/searchapi_server_start.py 第 898 行当query是合法 MAC 时直接按 MAC 查详情否则走DeviceInstance.search()模糊匹配结果为空时返回 404。6.2 触发网络扫描trigger_scan工具调用{ jsonrpc: 2.0, id: 2, method: tools/call, params: { name: trigger_scan, arguments: { type: ARPSCAN } } }响应{ jsonrpc: 2.0, id: 2, result: { content: [ { type: text, text: {\n \success\: true,\n \message\: \Scan triggered for type: ARPSCAN\\n} } ], isError: false } }注意type必须在LOADED_PLUGINS设置中存在否则返回 400 及可用的扫描类型列表触发实际通过向执行队列写入run|scan_type事件完成api_server_start.py 第 1199-1203 行。6.3 Wake-on-LAN 唤醒设备wol_wake_device工具调用{ jsonrpc: 2.0, id: 3, method: tools/call, params: { name: wol_wake_device, arguments: { devMac: AA:BB:CC:DD:EE:FF } } }底层wake_on_lan端点支持mac/devMac或devLastIP/ip两种传参若只给 IP会先按 IP 解析 MACapi_server_start.py 第 1025-1058 行。七、与 AI 助手集成7.1 Claude Desktop 集成在 Claude Desktop 的mcp.json配置中注册 NetAlertX MCP 服务器{ mcp: { servers: { netalertx: { command: node, args: [/path/to/mcp-client.js], env: { NETALERTX_URL: http://your-server:GRAPHQL_PORT, NETALERTX_TOKEN: your-api-token } } } } }其中NETALERTX_URL的端口应使用 NetAlertX 的GRAPHQL_PORT设置值默认20212NETALERTX_TOKEN对应API_TOKEN。7.2 通用 MCP 客户端Python 示例以下示例使用 Python MCP SDK通过stdio_client以curl子进程方式连接 MCP 端点import asyncio import json from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def main(): # Connect to NetAlertX MCP server server_params StdioServerParameters( commandcurl, args[ -N, -H, Authorization: Bearer API_TOKEN, http://your-server:GRAPHQL_PORT/mcp/sse ] ) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: # Initialize connection await session.initialize() # List available tools tools await session.list_tools() print(fAvailable tools: {[t.name for t in tools.tools]}) # Call a tool result await session.call_tool(search_devices, {query: router}) print(fSearch result: {result}) if __name__ __main__: asyncio.run(main())7.3 扩展能力Resources 与 Prompts除工具外MCP 服务器还提供两类标准能力源码见 mcp_endpoint.py 第 797-1001 行Resources只读资源netalertx://api/openapi.json完整 OpenAPI 规格以及日志文件app.log、stderr.log、app_front.log、app.php_errors.log及plugins/*.log仅当NETALERTX_LOG配置存在时列出。日志读取做了路径穿越防护并只保留文件末尾 500 行。Prompts预置提示词内置analyze_network_health网络健康分析、investigate_device设备调查参数device_identifier、troubleshoot_connectivity连通性排查参数target_ip三个编排型提示词AI 可直接使用它们组合调用多个工具完成复杂任务。八、错误处理与排障8.1 工具级错误结构MCP 工具调用失败时返回isError: true的结构化结果{ jsonrpc: 2.0, id: 1, result: { content: [ { type: text, text: Error calling tool: Device not found } ], isError: true } }底层实现中_execute_tool()将 HTTP 状态码 ≥ 400 的响应标记为isError并保留完整 JSON 或纯文本内容mcp_endpoint.py 第 745-765 行Pydantic 校验失败会返回Validation error及字段级details内部回环超时60 秒返回Request timed out。8.2 常见错误类型401/403— 认证失败token 缺失、错误或未配置400— 参数无效或缺少必填字段含 JSON-RPC 层错误-32602 Invalid params404— 资源不存在设备、扫描结果等对应工具未找到时返回-32601 Method not found500— 服务器内部错误含 JSON-RPC 层-32603503— 消息队列已满会话被丢弃8.3 调试建议用tools/list确认工具确实暴露且未被禁用工具可被按operationId禁用设置MCP_DISABLED_TOOLS逗号分隔默认禁用dbquery_read,dbquery_write两个直接 SQL 工具spec_generator.py 第 85-114 行调用被禁用的工具会直接返回Error: Tool xxx is disabled访问GET /openapi.json或/docsSwagger UI核对每个工具的入参 schema仓库提供完整的 MCP 端点测试test/api_endpoints/test_mcp_tools_endpoints.py、test/api_endpoints/test_mcp_openapi_spec.py、test/api_endpoints/test_mcp_disabled_tools.py可作为行为参考。九、注意事项小结MCP 端点与 REST 端点共用同一API_TOKEN认证所有工具返回 JSON且包装在 MCP 协议格式中SSE 维持持久连接以支持实时更新会话空闲超 5 分钟会被自动清理工具参数与其对应的 REST 端点参数一致参数命名可参考对应端点错误响应同时包含 HTTP 状态码与描述性消息MCP 桥接层自动完成请求/响应序列化客户端无需关心内部回环调用细节。相关文档API 总览 — 核心 REST API 文档设备 API — 单台设备管理设备集合 API — 批量设备操作网络工具 API — Wake-on-LAN、扫描与网络工具事件 API — 事件日志与监控调试 API 服务器 — GRAPHQL_PORT 与 API_TOKEN 配置排查赞分享后端网络运维数据可视化【免费下载链接】NetAlertXCentralized network visibility and continuous asset discovery. Monitor devices, detect change, and stay aware across distributed networks.项目地址https://gitcode.com/gh_mirrors/ne/NetAlertX点击查看免费下载相关推荐Arthas MCP Server 完全接入指南通过 MCP 协议让 AI 助手直接执行 Java 诊断命令Arthas MCP Server 完全接入指南通过 MCP 协议让 AI 助手直接执行 Java 诊断命令 Arthas MCP Server 是 Arth开发工具可观测性调试器性能剖析IDA Pro MCP借助 MCP 协议将 IDA Pro 接入大语言模型的逆向工程助手IDA Pro MCP借助 MCP 协议将 IDA Pro 接入大语言模型的逆向工程助手 IDA Pro MCP 是一个运行在 IDA Pro 之上的 Mod逆向工程MCP 服务AI 应用OmX Hermes MCP Bridge面向协调器的受控任务调度与状态/产物读取桥接协议OmX Hermes MCP Bridge面向协调器的受控任务调度与状态/产物读取桥接协议 OmXOh My codeX为 Hermes 风格的协调器提供人工智能AI AgentAgent 编排Agent 工作流CLI开发工具AI 技能上一篇前端开发认证考试imagesLoaded相关知识点解析下一篇Submitty核心功能解析作业提交、自动评分与TA人工grading全流程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
