Add filtering, sorting, limiting, and force refresh to list_devices tool

- Add force_refresh parameter to bypass cache and rescan all devices
- Add ssh_status_filter to filter by SSH status (ok, error, refused, timeout, unknown)
- Add power_state_filter to filter Tasmota devices by power state (on, off)
- Add sort_by parameter (ip, friendly_name, status, last_seen) with sort_order (asc/desc)
- Add limit parameter to cap number of results
- Update tool definition, handler, and documentation
- Add helper function _get_ssh_status() for consistent SSH status determination

Author: Alex J Lennon

=3.5.0

@@ -146,18 +146,18 @@ Data flow: AI → MCP Server → Tools → Lab Framework → Hardware
 
 ## Tools
 
-- **Device**: `list_devices` (with filtering, summary stats, power state), `test_device`, `ssh_to_device`, `verify_device_identity`, `verify_device_by_ip`, `update_device_ip`, `update_device_friendly_name`
+- **Device**: `list_devices` (with filtering, sorting, limiting, summary stats, power state) - Shows device inventory with Power Switch column: Tasmota devices display their own power state (🟢 ON/🔴 OFF), other devices show which power switch controls them. Supports filtering by type, status, SSH status, power state, and search. Supports sorting by IP, friendly_name, status, or last_seen. Supports limiting results. Use force_refresh to bypass cache. `test_device`, `ssh_to_device`, `verify_device_identity`, `verify_device_by_ip`, `update_device_ip`, `update_device_friendly_name`
 - **VPN**: `vpn_status`, `connect_vpn`, `disconnect_vpn`
 - **Power**: `start_power_monitoring` (DMM or Tasmota), `get_power_logs`, `analyze_power_logs`, `monitor_low_power`, `compare_power_profiles` - Power monitoring via DMM (SCPI) or Tasmota energy monitoring
-- **Tasmota**: `tasmota_control`, `list_tasmota_devices`, `power_cycle_device` - Power cycle devices via Tasmota switches. Tasmota devices show power state (ON/OFF) and consumption (Watts) in device list
+- **Tasmota**: `tasmota_control`, `list_tasmota_devices`, `power_cycle_device` - Power cycle devices via Tasmota switches. Tasmota devices show power state (🟢 ON/🔴 OFF) in the Power Switch column and consumption (Watts) in the Type column of the device list
 - **Test Equipment**: `list_test_equipment`, `query_test_equipment` - Auto-detect and query test equipment (DMM, oscilloscopes) via SCPI protocol
 - **OTA/Containers**: `check_ota_status`, `trigger_ota_update`, `list_containers`, `deploy_container`, `get_system_status`, `get_firmware_version`, `get_foundries_registration_status`, `get_secure_boot_status`, `get_device_identity`
 - **Process Management**: `kill_stale_processes` - Kill duplicate processes that might interfere
 - **Remote Access**: `create_ssh_tunnel`, `list_ssh_tunnels`, `close_ssh_tunnel`, `access_serial_port`, `list_serial_devices` - SSH tunnels and serial port access
 - **Change Tracking**: `get_change_history`, `revert_changes` - Track and revert changes for security/debugging
 - **Batch/Regression**: `batch_operation`, `regression_test`, `get_device_groups`
 - **Network Mapping**: `create_network_map` - Visual map of network with device type, uptime, friendly names, power switches
-- **Device Verification**: `verify_device_identity`, `verify_device_by_ip`, `update_device_ip` - Verify device identity in DHCP environments. Device list shows SSH status, last seen timestamps, and power switch relationships
+- **Device Verification**: `verify_device_identity`, `verify_device_by_ip`, `update_device_ip` - Verify device identity in DHCP environments. Device list shows SSH status, last seen timestamps, and power switch information (Tasmota devices show their own state, other devices show controlling switch)
 - **Help**: `help` - Get usage documentation and examples
 
 ## Resources

README.md

@@ -7,7 +7,7 @@
 
 import os
 from pathlib import Path
-from typing import Optional
+from typing import List, Optional
 
 # Default paths - can be overridden via environment variables
 DEFAULT_LAB_TESTING_ROOT = Path("/data_drive/esl/ai-lab-testing")
@@ -106,24 +106,25 @@ def get_logs_dir() -> Path:
 def get_target_network() -> str:
     """
     Get the target network for lab testing operations.
-    
+
     Priority:
     1. TARGET_NETWORK environment variable
     2. Value from lab_devices.json config file (if exists)
     3. Default: 192.168.2.0/24
-    
+
     Returns:
         Network CIDR string (e.g., "192.168.2.0/24")
     """
     # Check environment variable first
     env_network = os.getenv("TARGET_NETWORK")
     if env_network:
         return env_network
-    
+
     # Check config file
     try:
         if LAB_DEVICES_JSON.exists():
             import json
+
             with open(LAB_DEVICES_JSON) as f:
                 config = json.load(f)
                 infrastructure = config.get("lab_infrastructure", {})
@@ -134,27 +135,28 @@ def get_target_network() -> str:
     except Exception:
         # If config read fails, fall back to default
         pass
-    
+
     # Default target network
     return DEFAULT_TARGET_NETWORK
 
 
-def get_lab_networks() -> list[str]:
+def get_lab_networks() -> List[str]:
     """
     Get list of lab networks for scanning.
-    
+
     Priority:
     1. Networks from lab_devices.json config file
     2. TARGET_NETWORK environment variable (as single-item list)
     3. Default: [target_network]
-    
+
     Returns:
         List of network CIDR strings
     """
     # Check config file first
     try:
         if LAB_DEVICES_JSON.exists():
             import json
+
             with open(LAB_DEVICES_JSON) as f:
                 config = json.load(f)
                 infrastructure = config.get("lab_infrastructure", {})
@@ -164,7 +166,7 @@ def get_lab_networks() -> list[str]:
                     return lab_networks
     except Exception:
         pass
-    
+
     # Fall back to target network
     return [get_target_network()]
 

lab_testing/config.py

@@ -26,7 +26,7 @@ def get_help_content() -> Dict[str, Any]:
         },
         "tools": {
             "device_management": {
-                "list_devices": "List all devices with status, IPs, types, firmware, SSH status, last seen, and power switches. Returns brief summary (always visible) then full table. Supports filtering by device_type_filter, status_filter, search_query. Includes summary statistics (counts by type/status/SSH status). Shows Tasmota power state/consumption and test equipment detection.",
+                "list_devices": "List all devices with status, IPs, types, firmware, SSH status, last seen, and power switches. Returns brief summary (always visible) then full table. Supports filtering by device_type_filter, status_filter, ssh_status_filter, power_state_filter, search_query. Supports sorting (sort_by: ip/friendly_name/status/last_seen, sort_order: asc/desc) and limiting results (limit). Includes summary statistics (counts by type/status/SSH status). Shows Tasmota power state/consumption and test equipment detection. Power Switch column: For Tasmota devices, shows their own power state (🟢 ON/🔴 OFF); for other devices, shows which power switch controls them (if configured). Use force_refresh=true to bypass cache and rescan all devices.",
                 "test_device": "Test connectivity to a device (ping and SSH check). Best practice: Use before running operations on devices. In DHCP environments, use verify_device_identity to ensure correct device.",
                 "ssh_to_device": "Execute SSH command on a device (requires device_id, command, optional username). Best practice: Test device connectivity first with test_device.",
                 "verify_device_identity": "Verify device identity at given IP matches expected device (important for DHCP). Updates IP in config if verified and changed.",
@@ -92,8 +92,13 @@ def get_help_content() -> Dict[str, Any]:
                 "1. Use 'vpn_status' to check VPN connection",
                 "2. Use 'list_devices' to see available devices (shows brief summary first, then full table)",
                 "3. Filter devices: 'list_devices(device_type_filter=\"tasmota_device\")' or 'list_devices(status_filter=\"online\")'",
-                "4. Search devices: 'list_devices(search_query=\"192.168.2.18\")'",
-                "5. Use 'test_device' to verify connectivity",
+                "4. Filter by SSH status: 'list_devices(ssh_status_filter=\"error\")' to find devices with SSH issues",
+                "5. Filter Tasmota by power: 'list_devices(power_state_filter=\"on\")' to find powered-on Tasmota devices",
+                "6. Search devices: 'list_devices(search_query=\"192.168.2.18\")'",
+                "7. Sort results: 'list_devices(sort_by=\"ip\", sort_order=\"asc\")' or 'list_devices(sort_by=\"last_seen\", sort_order=\"desc\")'",
+                "8. Limit results: 'list_devices(limit=10)' to show only first 10 devices",
+                "9. Force refresh: 'list_devices(force_refresh=true)' to bypass cache and rescan",
+                "10. Use 'test_device' to verify connectivity",
             ],
             "device_discovery": [
                 "1. Devices are automatically discovered via network scanning",
@@ -156,11 +161,14 @@ def get_help_content() -> Dict[str, Any]:
             "For low power: set appropriate threshold_mw, monitor for sufficient duration",
             "For regression: organize devices by tags/groups, use batch operations",
             "Tag devices in config for easy rack management and grouping",
-            "Use list_devices filters to quickly find specific devices (type, status, search)",
+            "Use list_devices filters to quickly find specific devices (type, status, SSH status, power state, search)",
+            "Use list_devices sorting (sort_by, sort_order) to organize results by IP, name, status, or last seen",
+            "Use list_devices limit parameter to cap results for large networks",
+            "Use list_devices force_refresh=true to bypass cache when you need fresh data",
             "Device list shows brief summary first - always visible without expanding",
             "In DHCP environments: verify device identity before operations, use update_device_ip if IP changed",
             "Device discovery is optimized with parallel SSH identification and caching",
-            "Tasmota devices show power state and consumption in device list",
+            "Tasmota devices show power state (🟢 ON/🔴 OFF) in the Power Switch column and consumption (Watts) in the Type column of the device list",
             "Test equipment (DMM) can be queried with SCPI commands via query_test_equipment",
         ],
         "foundries_io_integration": {

lab_testing/resources/help.py

@@ -62,6 +62,7 @@
 # Development mode: Set up auto-reload
 try:
     from lab_testing.server.dev_reload import setup_auto_reload
+
     setup_auto_reload()
 except ImportError:
     pass  # dev_reload module not available
@@ -89,7 +90,9 @@ async def handle_list_tools() -> List[Tool]:
 
 
 @server.call_tool()
-async def handle_call_tool(name: str, arguments: Dict[str, Any]) -> List[Union[TextContent, ImageContent]]:
+async def handle_call_tool(
+    name: str, arguments: Dict[str, Any]
+) -> List[Union[TextContent, ImageContent]]:
     """Handle tool execution requests"""
     request_id = str(uuid.uuid4())[:8]
     start_time = time.time()

lab_testing/server.py

@@ -38,38 +38,38 @@ def _should_reload_module(module_name: str) -> bool:
     module_file = _get_module_file(module_name)
     if not module_file or not module_file.exists():
         return False
-    
+
     current_mtime = module_file.stat().st_mtime
     cached_mtime = _module_mtimes.get(module_name)
-    
+
     if cached_mtime is None or current_mtime > cached_mtime:
         _module_mtimes[module_name] = current_mtime
         return cached_mtime is not None  # Only reload if we've seen it before
-    
+
     return False
 
 
 def reload_if_changed(module_name: str) -> bool:
     """
     Reload a module if its file has changed.
-    
+
     Args:
         module_name: Full module name (e.g., 'lab_testing.server.tool_handlers')
-    
+
     Returns:
         True if module was reloaded, False otherwise
     """
     if not _should_reload_module(module_name):
         return False
-    
+
     try:
         if module_name in sys.modules:
             importlib.reload(sys.modules[module_name])
             return True
     except Exception as e:
         # Log but don't fail - reload errors shouldn't crash the server
         print(f"Warning: Failed to reload {module_name}: {e}", file=sys.stderr)
-    
+
     return False
 
 
@@ -92,12 +92,12 @@ def reload_lab_testing_modules():
         "lab_testing.resources.health",
         "lab_testing.config",
     ]
-    
+
     reloaded = []
     for module_name in modules_to_check:
         if reload_if_changed(module_name):
             reloaded.append(module_name)
-    
+
     return reloaded
 
 
@@ -110,16 +110,8 @@ def setup_auto_reload():
     """Set up auto-reload for development mode"""
     if not is_dev_mode():
         return
-    
+
     # Initialize mtimes for all modules
     reload_lab_testing_modules()
-    
-    print("Development mode enabled: Auto-reload active", file=sys.stderr)
-
-
-
-
-
-
-
 
+    print("Development mode enabled: Auto-reload active", file=sys.stderr)

lab_testing/server/dev_reload.py

@@ -19,7 +19,8 @@ def get_all_tools() -> List[Tool]:
             name="list_devices",
             description=(
                 "List all devices on the target network with their status, firmware, and relationships. "
-                "Supports filtering by type, status, and search queries. Includes summary statistics."
+                "Supports filtering by type, status, SSH status, power state, and search queries. "
+                "Includes summary statistics. Supports sorting and limiting results."
             ),
             inputSchema={
                 "type": "object",
@@ -41,6 +42,34 @@ def get_all_tools() -> List[Tool]:
                         "description": "Include summary statistics (counts by type/status) in response (default: true)",
                         "default": True,
                     },
+                    "force_refresh": {
+                        "type": "boolean",
+                        "description": "Bypass cache and rescan all devices (default: false)",
+                        "default": False,
+                    },
+                    "ssh_status_filter": {
+                        "type": "string",
+                        "description": "Filter by SSH status (e.g., 'ok', 'error', 'refused', 'timeout', 'unknown')",
+                    },
+                    "power_state_filter": {
+                        "type": "string",
+                        "description": "Filter Tasmota devices by power state (e.g., 'on', 'off')",
+                    },
+                    "sort_by": {
+                        "type": "string",
+                        "description": "Sort results by field: 'ip', 'friendly_name', 'status', 'last_seen' (default: type then friendly_name)",
+                    },
+                    "sort_order": {
+                        "type": "string",
+                        "description": "Sort order: 'asc' or 'desc' (default: 'asc')",
+                        "enum": ["asc", "desc"],
+                        "default": "asc",
+                    },
+                    "limit": {
+                        "type": "integer",
+                        "description": "Maximum number of devices to return (default: no limit)",
+                        "minimum": 1,
+                    },
                 },
                 "required": [],
             },