feat(mcp_server): add provider management tools

[puchy22]

Context

This PR extends PR #9300's new MCP server architecture with provider management capabilities.

PR #9300 introduced a modular, workflow-based MCP server design optimized for AI agents (Lighthouse AI). This PR builds on that foundation by adding tools for managing cloud provider connections.

Builds on top of PR #9300

Description

Summary

Adds provider management capabilities to the new Prowler App MCP server, enabling AI agents to search, connect, and manage cloud provider integrations.

New Tools (3 total)

1. search_cloud_providers
Search and view configured cloud providers with filtering and pagination.

Features:

• Filter by: provider_id, provider_uid, provider_type, alias, connection status
• Pagination: configurable page size (default 50), page navigation
• Token-optimized responses (empty values excluded)

2. connect_provider
Complete provider onboarding workflow in a single operation.

Features:

• Idempotent: Safe to call multiple times with same parameters
• Workflow steps:
  1. Check if provider exists
  2. Create new or update existing provider
  3. Store credentials securely
  4. Test connection
  5. Return provider details with status
• Task polling: Waits for async connection tests to complete
• Comprehensive error handling: Returns detailed error messages for AI agents

3. delete_provider
Permanently remove a provider from Prowler.

Features:

• Accepts provider_id (Prowler's internal UUID)
• Task polling for async deletion
• Returns confirmation with status and message

New Files

models/providers.py (128 lines)
Pydantic models for provider data:

• SimplifiedProvider: Basic provider info
• DetailedProvider: Extended info with temporal data
• ProvidersListResponse: Paginated list wrapper
• ProviderConnectionStatus: Connection test results

All models include from_api_response() for JSON:API transformation.

tools/providers.py (568 lines)
Provider management tools implementation:

• 3 public tools (search, connect, delete)
• 7 private helper methods for workflow orchestration
• Comprehensive logging and error handling
• Extensive documentation with JSON examples

Architecture

• Auto-discovery: Follows PR feat(mcp_server): implement new Prowler App MCP server design #9300's pattern, tools auto-register at startup
• Shared utilities: Uses api_client.py for consistent HTTP operations
• LLM-optimized: Models use MinimalSerializerMixin to reduce token usage
• Workflow-oriented: Complex operations bundled into single tool calls
• Idempotent: Safe for AI agent retries and error recovery

Token Optimization

• Empty values excluded from responses
• Sparse fieldsets reduce payload size
• Focused data models (simplified vs detailed)
• Estimated 30-40% token reduction vs raw API responses

Steps to review

1. Review provider models - mcp_server/prowler_mcp_server/prowler_app/models/providers.py

   • Verify model structures match API responses
   • Check from_api_response() transformation logic
   • Validate MinimalSerializerMixin usage

2. Review provider tools - mcp_server/prowler_mcp_server/prowler_app/tools/providers.py

   • search_cloud_providers: Test filtering and pagination
   • connect_provider: Test complete workflow for each provider type
     • Verify idempotency (call twice with same params)
     • Check credential validation
     • Test connection test polling
   • delete_provider: Test deletion workflow and polling
   • Review helper methods and error handling

3. Review API client updates - mcp_server/prowler_mcp_server/prowler_app/utils/api_client.py

   • Review new poll_task_until_complete() method
   • Verify task polling logic and error handling

4. Integration testing

   • Verify tools auto-register correctly
   • Test with MCP inspector or AI agent
   • Check error messages are clear and actionable
   • Validate logging output

5. Security review

   • Verify credentials are handled securely
   • Check no sensitive data in logs
   • Validate input sanitization

Checklist

• Are there new checks included in this PR? No
• Review if the code is being covered by tests.
• Review if code is being documented following this specification https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings
• Review if backport is needed. No
• Review if is needed to change the Readme.md No (MCP server component)
• Ensure new entries are added to CHANGELOG.md, if applicable. Yes (will add to mcp_server/CHANGELOG.md if exists)

UI

• N/A (MCP server backend only)

API

• Verify if API specs need to be regenerated. No (uses existing Prowler API)
• Check if version updates are required (e.g., specs, Poetry, etc.). No
• Ensure new entries are added to CHANGELOG.md, if applicable. Yes (if CHANGELOG exists in mcp_server/)

License

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.