/prowler-mcp

name: prowler-mcp
description: >
  Creates MCP tools for Prowler MCP Server. Covers BaseTool pattern, model design,
  and API client usage.
  Trigger: When working in mcp_server/ on tools (BaseTool), models (MinimalSerializerMixin/from_api_response), or API client patterns.
license: Apache-2.0
metadata:
  author: prowler-cloud
  version: "1.0"
  scope: [root, mcp_server]
  auto_invoke: "Working on MCP server tools"
allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch, WebSearch, Task

Overview

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

| Sub-Server | Prefix | Auth | Purpose | |------------|--------|------|---------| | Prowler | `prowler_*` | Required | Prowler Cloud, Private Cloud & Local Server management tools | | Prowler Hub | `prowler_hub_*` | No | Security checks catalog | | Prowler Docs | `prowler_docs_*` | No | Documentation search |

For complete architecture, patterns, and examples, see [docs/developer-guide/mcp-server.mdx](../../../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](../../docs/developer-guide/mcp-server.mdx)
• **Templates**: See [assets/](assets/) for tool and model templates
• **Testing**: See [prowler-test-mcp](../prowler-test-mcp/SKILL.md) for fixtures and test patterns