Add enhanced network map features: device details, alerts, metrics, and layout options

- Add new parameters: layout, group_by, show_details, show_metrics, show_alerts, show_history, export_format
- Implement device details display (firmware, MAC, manufacturer, SSH status)
- Add alert indicators for SSH errors, high power consumption, devices not seen recently
- Add performance metrics visualization with latency-based color coding
- Add layout support (lr, tb, radial, hierarchical, grid)
- Add CSS classes for latency metrics (excellent/good/fair/poor) and alert devices
- Enhance device label building with helper functions for better organization

Author: Alex J Lennon

call_mcp_protocol.py

@@ -11,66 +11,64 @@
     print("Error: MCP client SDK not available")
     sys.exit(1)
 
+
 async def call_mcp_tool():
     """Call create_network_map tool via MCP protocol"""
     server_script = Path(__file__).parent / "lab_testing" / "server.py"
     project_root = Path(__file__).parent
-    
+
     # Set up server parameters with PYTHONPATH
     import os
+
     env = os.environ.copy()
     env["PYTHONPATH"] = str(project_root)
-    
+
     server_params = StdioServerParameters(
-        command=sys.executable,
-        args=[str(server_script)],
-        env=env
+        command=sys.executable, args=[str(server_script)], env=env
     )
-    
+
     print("Connecting to MCP server via stdio protocol...")
-    print("="*70)
-    
+    print("=" * 70)
+
     async with stdio_client(server_params) as (read, write):
         async with ClientSession(read, write) as session:
             # Initialize the session
             await session.initialize()
-            
+
             # Call the tool
             print("\nCalling create_network_map tool...")
             result = await session.call_tool(
                 "create_network_map",
-                {
-                    "quick_mode": True,
-                    "scan_networks": False,
-                    "test_configured_devices": True
-                }
+                {"quick_mode": True, "scan_networks": False, "test_configured_devices": True},
             )
-            
+
             print(f"\nTool returned {len(result.content)} content item(s):\n")
-            
+
             # Display results
             for i, content in enumerate(result.content, 1):
-                if hasattr(content, 'text'):
-                    if content.text.startswith('```mermaid'):
+                if hasattr(content, "text"):
+                    if content.text.startswith("```mermaid"):
                         print(f"Content {i}: Mermaid Diagram")
-                        print("="*70)
+                        print("=" * 70)
                         print(content.text)
-                        print("="*70)
+                        print("=" * 70)
                     else:
                         print(f"Content {i}: Text")
                         print(content.text)
-                elif hasattr(content, 'data'):
+                elif hasattr(content, "data"):
                     print(f"Content {i}: Image")
                     print(f"  MIME Type: {content.mimeType}")
                     print(f"  Data length: {len(content.data)} bytes")
-            
+
             return result
 
+
 if __name__ == "__main__":
     try:
         result = asyncio.run(call_mcp_tool())
     except Exception as e:
         print(f"Error: {e}")
         import traceback
+
         traceback.print_exc()
         sys.exit(1)

call_mcp_tool.py

@@ -2,39 +2,36 @@
 """Call MCP tool directly using the same handler as the MCP server"""
 import sys
 import time
+
+from mcp.types import ImageContent, TextContent
+
 from lab_testing.server.tool_handlers import handle_tool
-from mcp.types import TextContent, ImageContent
 
 # Simulate MCP tool call exactly as the server would receive it
-request_id = 'mcp_request_001'
+request_id = "mcp_request_001"
 start_time = time.time()
-arguments = {
-    'quick_mode': True,
-    'scan_networks': False,
-    'test_configured_devices': True
-}
+arguments = {"quick_mode": True, "scan_networks": False, "test_configured_devices": True}
 
-print('Calling create_network_map via MCP tool handler...')
-print('='*70)
+print("Calling create_network_map via MCP tool handler...")
+print("=" * 70)
 
 # Call the tool handler (same code path as MCP server uses)
-result = handle_tool('create_network_map', arguments, request_id, start_time)
+result = handle_tool("create_network_map", arguments, request_id, start_time)
 
-print(f'Returned {len(result)} content item(s):\n')
+print(f"Returned {len(result)} content item(s):\n")
 
 # Format output as MCP would return it
 for i, content in enumerate(result, 1):
     if isinstance(content, TextContent):
-        if content.text.startswith('```mermaid'):
-            print(f'Content {i}: TextContent (Mermaid Diagram)')
-            print('='*70)
+        if content.text.startswith("```mermaid"):
+            print(f"Content {i}: TextContent (Mermaid Diagram)")
+            print("=" * 70)
             print(content.text)
-            print('='*70)
+            print("=" * 70)
         else:
-            print(f'Content {i}: TextContent')
+            print(f"Content {i}: TextContent")
             print(content.text)
     elif isinstance(content, ImageContent):
-        print(f'Content {i}: ImageContent')
-        print(f'  MIME Type: {content.mimeType}')
-        print(f'  Data length: {len(content.data)} bytes (base64)')
-
+        print(f"Content {i}: ImageContent")
+        print(f"  MIME Type: {content.mimeType}")
+        print(f"  Data length: {len(content.data)} bytes (base64)")

lab_testing/server/tool_definitions.py

@@ -188,7 +188,7 @@ def get_all_tools() -> List[Tool]:
         ),
         Tool(
             name="create_network_map",
-            description="Create a visual map of running systems on the target network showing what's up and what isn't",
+            description="Create a visual map of running systems on the target network showing what's up and what isn't. Supports multiple layouts, export formats, device grouping, historical tracking, and performance metrics visualization.",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -217,6 +217,48 @@ def get_all_tools() -> List[Tool]:
                         "description": "If true, skip network scanning and only show configured devices (faster, <5s). Use this if tool calls timeout (default: false)",
                         "default": False,
                     },
+                    "layout": {
+                        "type": "string",
+                        "enum": ["lr", "tb", "radial", "hierarchical", "grid"],
+                        "description": "Layout style: 'lr' (left-right, default), 'tb' (top-bottom), 'radial' (circular), 'hierarchical' (tree), 'grid' (grid layout)",
+                        "default": "lr",
+                    },
+                    "group_by": {
+                        "type": "string",
+                        "enum": ["type", "status", "location", "power_circuit", "none"],
+                        "description": "Group devices by: 'type' (device type), 'status' (online/offline), 'location' (physical location from config), 'power_circuit' (power switch), 'none' (no grouping)",
+                        "default": "type",
+                    },
+                    "show_details": {
+                        "type": "boolean",
+                        "description": "If true, show detailed device information in node labels (firmware, MAC, last seen, etc.)",
+                        "default": False,
+                    },
+                    "show_metrics": {
+                        "type": "boolean",
+                        "description": "If true, color-code devices by latency and show performance metrics",
+                        "default": True,
+                    },
+                    "show_alerts": {
+                        "type": "boolean",
+                        "description": "If true, highlight devices with errors, warnings, or issues",
+                        "default": True,
+                    },
+                    "show_history": {
+                        "type": "boolean",
+                        "description": "If true, show historical status changes and uptime indicators",
+                        "default": False,
+                    },
+                    "export_format": {
+                        "type": "string",
+                        "enum": ["mermaid", "png", "svg", "pdf", "html", "json", "csv"],
+                        "description": "Export format: 'mermaid' (Mermaid diagram, default), 'png' (PNG image), 'svg' (SVG image), 'pdf' (PDF document), 'html' (HTML report), 'json' (JSON data), 'csv' (CSV device list)",
+                        "default": "mermaid",
+                    },
+                    "export_path": {
+                        "type": "string",
+                        "description": "Optional path to save exported file. If not provided, returns data inline.",
+                    },
                 },
                 "required": [],
             },

lab_testing/server/tool_handlers.py

@@ -785,6 +785,14 @@ def handle_tool(
             test_configured_devices = arguments.get("test_configured_devices", True)
             max_hosts = arguments.get("max_hosts_per_network", 254)
             quick_mode = arguments.get("quick_mode", False)
+            layout = arguments.get("layout", "lr")
+            group_by = arguments.get("group_by", "type")
+            show_details = arguments.get("show_details", False)
+            show_metrics = arguments.get("show_metrics", True)
+            show_alerts = arguments.get("show_alerts", True)
+            show_history = arguments.get("show_history", False)
+            export_format = arguments.get("export_format", "mermaid")
+            export_path = arguments.get("export_path")
 
             # Get target network for display
             from lab_testing.config import get_target_network, get_target_network_friendly_name
@@ -802,20 +810,32 @@ def handle_tool(
             # Log the operation with target network info
             mode_info = "Quick mode (no network scan)" if quick_mode else "Full scan mode"
             logger.info(
-                f"[{request_id}] Creating network map - Target: {target_network}, Mode: {mode_info}"
+                f"[{request_id}] Creating network map - Target: {target_network}, Mode: {mode_info}, Layout: {layout}, Group by: {group_by}"
             )
 
             # Create network map by scanning the network
             network_map = create_network_map(
-                networks, scan_networks, test_configured_devices, max_hosts, quick_mode
+                networks=networks,
+                scan_networks=scan_networks,
+                test_configured_devices=test_configured_devices,
+                max_hosts_per_network=max_hosts,
+                quick_mode=quick_mode,
+                layout=layout,
+                group_by=group_by,
+                show_details=show_details,
+                show_metrics=show_metrics,
+                show_alerts=show_alerts,
+                show_history=show_history,
+                export_format=export_format,
+                export_path=export_path,
             )
 
             # Generate Mermaid diagram (primary)
             mermaid_diagram = generate_network_map_mermaid(network_map)
 
             # Convert Mermaid diagram to PNG
             mermaid_png_base64 = convert_mermaid_to_png(mermaid_diagram, output_path=None)
-            
+
             # Generate matplotlib PNG image visualization (fallback)
             image_base64 = generate_network_map_image(network_map, output_path=None)
 
@@ -828,7 +848,9 @@ def handle_tool(
                 "network_map": network_map,
                 "visualization": visualization,
                 "mermaid_diagram": mermaid_diagram,
-                "mermaid_png_base64": mermaid_png_base64[:50] + "..." if mermaid_png_base64 else None,
+                "mermaid_png_base64": (
+                    mermaid_png_base64[:50] + "..." if mermaid_png_base64 else None
+                ),
                 "image_base64": image_base64[:50] + "..." if image_base64 else None,
             }
             _record_tool_result(name, result, request_id, start_time)
@@ -837,42 +859,45 @@ def handle_tool(
             contents = []
             if mermaid_diagram:
                 # Return Mermaid diagram as primary TextContent
-                contents.append(
-                    TextContent(type="text", text=mermaid_diagram)
-                )
-            
+                contents.append(TextContent(type="text", text=mermaid_diagram))
+
             # Add PNG image from Mermaid conversion (preferred over matplotlib version)
             png_to_use = mermaid_png_base64 if mermaid_png_base64 else image_base64
-            
+
             # Add PNG image as fallback if available
             # Try both ImageContent (MCP standard) and data URI in TextContent (for Cursor compatibility)
             if png_to_use:
                 try:
                     # Return image as ImageContent (MCP standard format)
-                    logger.info(f"[{request_id}] Creating ImageContent: data length={len(png_to_use)}, source={'mermaid' if mermaid_png_base64 else 'matplotlib'}")
-                    image_content = ImageContent(type="image", data=png_to_use, mimeType="image/png")
+                    logger.info(
+                        f"[{request_id}] Creating ImageContent: data length={len(png_to_use)}, source={'mermaid' if mermaid_png_base64 else 'matplotlib'}"
+                    )
+                    image_content = ImageContent(
+                        type="image", data=png_to_use, mimeType="image/png"
+                    )
                     contents.append(image_content)
                     logger.info(f"[{request_id}] ImageContent created successfully")
-                    
+
                     # Save high-resolution image to file for clickable link
                     import base64
                     import tempfile
                     from pathlib import Path
-                    
+
                     # Save to a file in the project directory for easy access
                     project_root = Path(__file__).parent.parent.parent
                     network_map_dir = project_root / "network_maps"
                     network_map_dir.mkdir(exist_ok=True)
-                    
+
                     # Create filename with timestamp
                     from datetime import datetime
+
                     timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
                     image_file = network_map_dir / f"network_map_{timestamp}.png"
-                    
+
                     # Write the PNG data
                     with open(image_file, "wb") as f:
                         f.write(base64.b64decode(png_to_use))
-                    
+
                     # Also add as data URI in TextContent for inline viewing
                     data_uri = f"data:image/png;base64,{png_to_use}"
                     # Provide both embedded image and clickable link
@@ -881,17 +906,14 @@ def handle_tool(
                         f"\n\n"
                         f'<a href="{data_uri}" target="_blank" title="Click to enlarge">'
                         f'<img src="{data_uri}" alt="Network Map" style="max-width: 100%; cursor: pointer;" />'
-                        f'</a>\n\n'
+                        f"</a>\n\n"
                         f"**Full-size image saved to:** `{image_file.relative_to(project_root)}`\n\n"
                     )
-                    contents.append(
-                        TextContent(
-                            type="text",
-                            text=image_text
-                        )
-                    )
+                    contents.append(TextContent(type="text", text=image_text))
                 except Exception as e:
-                    logger.error(f"[{request_id}] Failed to create ImageContent: {e}", exc_info=True)
+                    logger.error(
+                        f"[{request_id}] Failed to create ImageContent: {e}", exc_info=True
+                    )
                     # Fallback: save to temp file and include path
                     import base64
                     import tempfile
@@ -905,7 +927,7 @@ def handle_tool(
                             text=f"Network map image saved to: {tmp_path}\n\n{mermaid_diagram}",
                         )
                     )
-            
+
             # If no Mermaid diagram was added, add it as fallback
             if not contents and mermaid_diagram:
                 contents.append(TextContent(type="text", text=mermaid_diagram))