home / skills / prowler-cloud / prowler / prowler-mcp

prowler-mcp skill

safe

This skill helps you implement Prowler MCP App tools by guiding BaseTool usage, MinimalSerializerMixin models, and API client patterns across the server.

npx playbooks add skill prowler-cloud/prowler --skill prowler-mcp

Review the files below or copy the command above to add this skill to your agents.

Files (4)

SKILL.md

2.5 KB

---
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 App | `prowler_app_*` | Required | Cloud 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 App 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 App 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 App)

- [ ] Tool docstrings describe LLM-relevant behavior
- [ ] Models use `MinimalSerializerMixin`
- [ ] API responses transformed to simplified models
- [ ] Error handling returns `{"error": str, "status": "failed"}`
- [ ] Parameters use `Field()` with descriptions
- [ ] No hardcoded secrets

---

## Resources

- **Full Guide**: [docs/developer-guide/mcp-server.mdx](../../../docs/developer-guide/mcp-server.mdx)
- **Templates**: See [assets/](assets/) for tool and model templates

Overview

This skill documents how to create and maintain MCP tools for the Prowler MCP Server. It focuses on the Prowler App pattern: extending BaseTool, designing two-tier models with MinimalSerializerMixin, and using the shared API client. It highlights naming, registration, and QA expectations so new tools are consistent and safe.

How this skill works

When working in mcp_server/, the skill inspects tool classes in prowler_app/tools/, model definitions in prowler_app/models/, and API client usage across the app. It enforces that Prowler App tools extend BaseTool (auto-registered), responses use MinimalSerializerMixin and from_api_response(), and that the singleton self.api_client and build_filter_params() are used for requests. For Hub/Docs tools it expects use of the @mcp.tool() decorator without BaseTool or models.

When to use it

Adding a new cloud management tool under prowler_app/tools/
Creating list/detail models for API responses in prowler_app/models/
Refactoring raw API calls to the shared self.api_client singleton
Validating tool docstrings, parameter Field() descriptions, and error shapes
Implementing features that require auto-registration via tool_loader.py

Best practices

Always extend BaseTool for Prowler App tools; do not manually register classes
Model responses with MinimalSerializerMixin and implement from_api_response() factories
Use two-tier models: simplified models for lists and detailed models for single-item endpoints
Use self.api_client and build_filter_params() for every API call; never create new httpx clients
Return structured errors: {"error": str, "status": "failed"} and avoid leaking secrets
Keep tool public methods limited to intended surface; only public methods become tools

Example use cases

Create a new AWS IAM management tool class extending BaseTool that lists users with a Minimal list model
Add a detailed EC2 instance model with from_api_response() and a simplified list model for overview endpoints
Replace direct httpx usage with self.api_client and use build_filter_params() for query handling
Implement a Prowler Hub search tool using @mcp.tool() with no BaseTool or models
Run the QA checklist before merge: docstrings, Field() descriptions, model mixin, and error shape

FAQ

Do Hub and Docs tools use BaseTool and models?

No. Hub and Docs tools should use the @mcp.tool() decorator directly and do not require BaseTool subclasses or model mixins.

What must models include for Prowler App responses?

Models must use MinimalSerializerMixin, provide a from_api_response() factory, and follow the two-tier pattern: simplified models for lists and detailed models for single items.