prowler-mcp
Assists in building Prowler MCP server tools by enforcing BaseTool patterns and model design standards.
Install
mkdir -p .claude/skills/prowler-mcp && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/8017" && unzip -o skill.zip -d .claude/skills/prowler-mcp && rm skill.zipInstalls to .claude/skills/prowler-mcp
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
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.Key capabilities
- →Extend BaseTool for tool implementation
- →Use MinimalSerializerMixin for models
- →Implement from_api_response() factory method
- →Use self.api_client singleton for API calls
- →Apply @mcp.tool() decorator for Hub/Docs tools
How it works
The skill details critical rules for implementing Prowler tools, designing models, and using the API client within the MCP Server.
Inputs & outputs
When to use prowler-mcp
- →Implement new MCP tools in the Prowler server
- →Apply MinimalSerializerMixin to API responses
- →Register new tools using the BaseTool pattern
About this skill
Overview
Stack: Python >= 3.12, FastMCP 3.4.x, httpx, Pydantic, uv (source of truth: mcp_server/pyproject.toml).
prowler_mcp_server/server.py mounts three sub-servers with prefixed namespaces:
| Sub-Server | Prefix | Auth | Source | How tools are defined |
|---|---|---|---|---|
| Prowler App | prowler_* | Required (PROWLER_API_KEY in STDIO, bearer token in HTTP) | prowler_app/ | BaseTool subclasses, auto-loaded |
| Prowler Hub | prowler_hub_* | No | prowler_hub/server.py | @hub_mcp_server.tool(annotations=...) |
| Prowler Docs | prowler_docs_* | No | prowler_documentation/server.py | @docs_mcp_server.tool(annotations=...) |
mcp_server/prowler_mcp_server/
├── server.py # Root server: mounts, SharedFailureMiddleware, /health
├── main.py # CLI: --transport stdio|http --host --port
├── lib/ # errors.py, types.py (NonBlankStr), logger.py, urls.py
├── prowler_app/
│ ├── server.py # FastMCP("prowler-app") + load_all_tools()
│ ├── tools/{feature}.py # BaseTool subclasses (tools/base.py = BaseTool)
│ ├── models/{feature}.py # Pydantic models (models/base.py = MinimalSerializerMixin)
│ └── utils/ # api_client.py, auth.py, tool_loader.py
├── prowler_hub/server.py
└── prowler_documentation/ # server.py, search_engine.py
Critical Rules (Prowler App Tools)
Tool Implementation
- ALWAYS: Put a
BaseToolsubclass inprowler_app/tools/{feature}.py.load_all_tools()imports every module in that package andBaseTool.register_tools()registers every publicasyncmethod (no_prefix) as a tool, exposed asprowler_{method_name}. - NEVER: Register tools manually or import tool modules in
server.py. - ALWAYS: Name methods so the MCP annotations are right.
BaseTool._annotations_for()marksget_*,list_*,search_*as read-only anddelete_*as destructive. Any other name that only reads or that removes/replaces data goes in the class attributeread_only_toolsordestructive_tools(seetools/attack_paths.py,tools/roles.py,tools/muting.py). - ALWAYS: Declare every parameter with
pydantic.Field(default=..., description=...). Required identifiers useNonBlankStrfromprowler_mcp_server.lib.types(rejects""and whitespace, addsminLengthto the schema). - ALWAYS: The method docstring is the tool description the model reads: say what it returns, the default behavior, and which tool to call next.
- A tool class whose
__init__raises is logged and skipped byload_all_tools, so its tools silently vanish. The contract tests intests/test_server.pycatch an empty namespace.
Models
- ALWAYS: Item models extend
MinimalSerializerMixin(dropsNone,"",[],{}frommodel_dump()); override_should_exclude()only when an empty value carries meaning. - ALWAYS: Implement a
from_api_response()classmethod that maps the JSON:API resource to the model. - ALWAYS: Two tiers:
Simplified*for lists,Detailed*(subclass) for one item, plus a*ListResponsebuilt frommeta.pagination(count,pages,page). - NEVER: Return raw API responses. Return
model.model_dump().
API Client
- ALWAYS: Use
self.api_client(theProwlerAPIClientsingleton) with paths relative to/api/v1(e.g."/findings/latest"). - ALWAYS: Pass params through
self.api_client.build_filter_params(): lists become CSV, bools become"true"/"false",Noneis dropped. - ALWAYS: Validate before requesting:
validate_page_size()(1-1000),normalize_date_range()(YYYY-MM-DD, max window). Usepoll_task_until_complete()for endpoints that return a task. - NEVER: Create new httpx clients.
Errors (lib/errors.py)
- ALWAYS: Raise failures; NEVER return an error dict (the client reports it as a success).
- Raise
InvalidArgumentfor a bad argument; letProwlerAPIError/ProwlerAPIUnreachablepropagate.SharedFailureMiddleware(on the root server) turns them into a message the model can act on. - Raise
fastmcp.exceptions.ToolErrorwithout afromclause only for a sentencelib/errors.pycannot know (a resource name, a precondition, the next tool to call). Every server usesmask_error_details=True, so any other exception reaches the model masked.
Hub/Docs Tools
Plain functions decorated on the sub-server; no BaseTool or models. Always set both hints:
@hub_mcp_server.tool(annotations={"readOnlyHint": True, "destructiveHint": False})
async def list_checks(providers: list[str] = Field(default=[], description="...")) -> dict: ...
Quick Reference: New Prowler App Tool
- Models in
prowler_app/models/{feature}.py(see assets/models.py). - Tool class in
prowler_app/tools/{feature}.pyextendingBaseTool(see assets/tool_implementation.py). - Tests in
mcp_server/tests/prowler_app/{models,tools}/test_{feature}.py(seeprowler-test-mcp). - Changelog fragment
mcp_server/changelog.d/<slug>.<type>.md(seeprowler-changelog); never editCHANGELOG.md.
Commands
cd mcp_server
uv run prowler-mcp # STDIO mode
uv run prowler-mcp --transport http --port 8000 # HTTP mode (GET /health)
uv run pytest # Test suite
uv run ruff check . && uv run ruff format --check .
QA Checklist (Prowler App Tools)
- Tool docstrings describe LLM-relevant behavior and the follow-up tool
- Method name prefix (or
read_only_tools/destructive_tools) gives correct annotations - Models use
MinimalSerializerMixinandfrom_api_response() - Params use
Field()with descriptions; required IDs useNonBlankStr - Query params go through
build_filter_params() - Failures are raised, never returned
- No hardcoded secrets
- Tests added under
mcp_server/tests/; changelog fragment added
Resources
- Full Guide: docs/developer-guide/mcp-server.mdx
- Templates: See assets/ for BaseTool, tool and model templates
- Testing: See prowler-test-mcp for fixtures and test patterns
When not to use it
- →When not working on Prowler MCP Server tools
- →When not creating models for Prowler MCP Server
Limitations
- →Specific to Prowler MCP Server development
- →Rules apply primarily to Prowler tools, not Hub/Docs tools
How it compares
This skill provides specific architectural patterns and rules for Prowler MCP tool development, unlike general programming guidance.
Compared to similar skills
prowler-mcp side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| prowler-mcp (this skill) | 0 | 10mo | No flags | Advanced |
| mcp-builder | 136 | 6mo | Review | Advanced |
| copilot-sdk | 7 | 7mo | Review | Intermediate |
| openrouter-function-calling | 5 | 4mo | Review | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by prowler-cloud
View all by prowler-cloud →You might also like
mcp-builder
anthropics
Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).
copilot-sdk
github
Build agentic applications with GitHub Copilot SDK. Use when embedding AI agents in apps, creating custom tools, implementing streaming responses, managing sessions, connecting to MCP servers, or creating custom agents. Triggers on Copilot SDK, GitHub SDK, agentic app, embed Copilot, programmable agent, MCP server, custom agent.
openrouter-function-calling
jeremylongshore
Implement function/tool calling with OpenRouter models. Use when building agents or structured outputs. Trigger with phrases like 'openrouter functions', 'openrouter tools', 'openrouter agent', 'function calling'.
agentica-server
parcadei
Agentica server + Claude proxy setup - architecture, startup sequence, debugging
mcp-developer
Jeffallan
Use when building MCP servers or clients that connect AI systems with external tools and data sources. Invoke for MCP protocol compliance, TypeScript/Python SDKs, resource providers, tool functions.
create-mcp-servers
glittercowboy
Create Model Context Protocol (MCP) servers that expose tools, resources, and prompts to Claude. Use when building custom integrations, APIs, data sources, or any server that Claude should interact with via the MCP protocol. Supports both TypeScript and Python implementations.