prowler-cloud/prowler/prowler-mcp

Overview

The Prowler MCP Server uses three sub-servers with prefixed namespacing:

For complete architecture, patterns, and examples, see docs/developer-guide/mcp-server.mdx.

Critical Rules (Prowler Tools Only)

Tool Implementation

• ALWAYS: Extend BaseTool (auto-registered via tool_loader.py, only public methods from the class are exposed as a tool)
• NEVER: Manually register BaseTool subclasses
• NEVER: Import tools directly in server.py

Models

• ALWAYS: Use MinimalSerializerMixin for responses
• ALWAYS: Implement from_api_response() factory method
• ALWAYS: Use two-tier models (Simplified for lists, Detailed for single items)
• NEVER: Return raw API responses

API Client

• ALWAYS: Use self.api_client singleton
• ALWAYS: Use build_filter_params() for query parameters
• NEVER: Create new httpx clients

Hub/Docs Tools

Use @mcp.tool() decorator directly—no BaseTool or models required.

Quick Reference: New Prowler Tool

1. Create tool class in prowler_app/tools/ extending BaseTool
2. Create models in prowler_app/models/ using MinimalSerializerMixin
3. Tools auto-register via tool_loader.py

QA Checklist (Prowler Tools)

• [ ] Tool docstrings describe LLM-relevant behavior
• [ ] Models use MinimalSerializerMixin
• [ ] API responses transformed to simplified models
• [ ] Failures are raised, never returned. A returned error dict is reported

as a success. Raise InvalidArgument for a bad argument, let ProwlerAPIError/ProwlerAPIUnreachable propagate, and raise ToolError without a `from` clause only for a sentence lib/errors.py cannot know (a resource name, a precondition, the next tool to call)

• [ ] Parameters use Field() with descriptions
• [ ] No hardcoded secrets
• [ ] Tests added under mcp_server/tests/

Resources

• Full Guide: docs/developer-guide/mcp-server.mdx
• Templates: See assets/ for tool and model templates
• Testing: See prowler-test-mcp for fixtures and test patterns