fix: AIFW-21695: Missing API coverage in MCP Scan module

[vokit-cisco]

Summary

Adds missing API coverage in MCP Scan module by implementing the MCP Server Stats endpoint.

This change extends the MCP scan client with the ability to retrieve aggregated statistics for MCP servers, including attack techniques, scan coverage metrics, and threat analysis data. The implementation includes comprehensive request/response models and unit test coverage.

Changes

• Added server_stats() method to MCPScanBase for retrieving MCP server statistics.
• Added new response models:
  • GetMCPServerStatsResponse - top-level response for server stats queries.
  • MCPServerStats - aggregated statistics for a single MCP server.
  • AttackTechnique - technique data including severity and context.
  • ScanCoverage - capability scan coverage metrics.
  • ContextObject - context object reference for error/threat association.
  • ContextObjectType enum - types of context objects (MCP_SERVER, MCP_REGISTRY, MCP_SCAN_WORKFLOW).
• Added RegistrationMethod enum for MCP server registration methods (MANUAL, REGISTRY).
• Added mcp_servers_stats() route function for endpoint construction.
• Updated ListMCPServersRequest with new filtering options:
  • scan_date - filter by last scan date.
  • server_types - filter by server type (Remote/Code).
• Added limit field to pagination model for maximum fetch count.
• Updated model exports in __init__.py to include new response models and types.
• Added comprehensive unit tests in test_mcp_scan_base.py:
  • Tests for server_stats() method with various server IDs.
  • Tests for response model parsing and validation.
  • Tests for error handling and edge cases.
• Updated example scripts:
  • manage_mcp_servers.py - integrated stats retrieval.
  • mcp_server_scan.py - showcased new stats functionality.

Test Plan

• Unit tests pass in test_mcp_scan_base.py (404 tests added/updated).
• Unit tests pass in test_mcpscan_routes.py (route coverage verified).
• Response model parsing validated for both camelCase and snake_case fields.
• Example scripts run successfully with new endpoint.
• Backward compatibility maintained for existing endpoints.

Compatibility Notes

• Additive change: New method and models do not impact existing functionality.
• Client code: Can now optionally call server_stats() to retrieve aggregated statistics for MCP servers.
• Integration impact: None - existing integrations continue to work without modification.

Files Modified

• aidefense/mcpscan/__init__.py - Added model exports.
• aidefense/mcpscan/mcp_scan_base.py - Added server_stats() method (38 lines added).
• aidefense/mcpscan/models.py - Added new models and enums (99 lines added).
• aidefense/mcpscan/routes.py - Added mcp_servers_stats() route function.
• aidefense/tests/test_mcp_scan_base.py - Added comprehensive test suite (404 new lines).
• aidefense/tests/test_mcpscan_routes.py - Added route tests.
• examples/mcpscan/manage_mcp_servers.py - Updated with stats retrieval example.
• examples/mcpscan/mcp_server_scan.py - Enhanced with new functionality showcase (39 lines added).

Total: 604 insertions(+), 5 deletions(-)