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

More agent context in prowler-cloud/prowler

43 other files this repository gives its agents.