brunopark-mcp

AI-orchestrated security testing via 6 Python tools, exposed as MCP (Model Context Protocol) tools.

Lean alternative to HexStrike AI — same architecture (MCP + Decision Engine + Visual Engine), but built around 6 high-quality Python tools instead of 150+ external CLI dependencies.

What is this?

brunopark-mcp is a Model Context Protocol server that exposes Bruno's 6 security tools as tools callable by any MCP-compatible AI agent (Claude Desktop, Hermes, Cursor, VS Code Copilot, etc).

It also includes a Decision Engine that auto-selects which tools to run based on the target type and the user's stated objective (recon, vuln_hunt, comprehensive, etc).

The 6 tools

Plus meta-tools:

• smart_security_scan(target, objective) — auto-picks tools and chains them

• analyze_target(target) — classify target type and recommend tools

• create_attack_plan(target, objective) — return ordered list (dry run, no execution)

• list_tools() — list all available tools

Architecture

LLM Agent (Claude/Hermes/GPT)
    → MCP protocol
    → brunopark-mcp server (FastMCP)
    → 6 Python tools as @mcp.tool() decorators
    → Structured JSON results back to LLM

Inspired by HexStrike AI v6.0 architecture, but:

• 6 tools instead of 150

• 1 file (server.py) instead of 17k-line monolith

• No external CLI dependencies (nmap, sqlmap, etc)

• Heuristic Decision Engine (no LLM cost per call)

Installation

# 1. Install brunopark-mcp core
pip install -e .

# 2. Install all 6 tools (optional — they degrade gracefully if missing)
pip install recon-tool port-scanner sub-hunter front-end-scanner api-pathfinder nemesis-scanner

# Or install one by one
pip install recon-tool

If a tool is not installed, the corresponding MCP tool returns a structured error with installation instructions.

Configuration

Claude Desktop

Edit ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "brunopark-mcp": {
      "command": "python3",
      "args": ["-m", "brunopark_mcp"],
      "timeout": 300
    }
  }
}

Cursor

Same config in Cursor's MCP settings.

Hermes

Add to ~/.hermes/config.yaml:

mcp_servers:
  - name: brunopark-mcp
    command: python3
    args: ["-m", "brunopark_mcp"]
    tools: [terminal, file, web]

Usage example

Ask the LLM:

"Do a comprehensive security scan of example.com"

The LLM will call:

smart_security_scan(target="https://example.com", objective="comprehensive")

The Decision Engine will:

1. Classify the target as domain (or web_application if you pass a URL)

2. Rank tools by effectiveness

3. Execute: hunt_subdomains → scan_ports → recon_target → scan_frontend → fuzz_api → orchestrate_nemesis

4. Aggregate findings into a severity-scored report

Decision Engine

Pre-built matrix that maps target type → tool ranking. No LLM cost per call.

TOOL_EFFECTIVENESS = {
    "web_application": {
        "scan_frontend": 0.95,
        "fuzz_api": 0.90,
        "scan_ports": 0.85,
        "recon_target": 0.80,
        "hunt_subdomains": 0.50,
        "orchestrate_nemesis": 0.85,
    },
    "network_host": {
        "scan_ports": 0.95,
        "recon_target": 0.85,
        "orchestrate_nemesis": 0.90,
    },
    "domain": {
        "hunt_subdomains": 0.95,
        "orchestrate_nemesis": 0.92,
        "recon_target": 0.70,
    },
    "api_endpoint": {
        "fuzz_api": 0.95,
        "scan_frontend": 0.80,
    },
}

Objectives

Safety

This is a security testing framework. Each of the 6 underlying tools has its own ethical disclaimer. Default behavior is non-destructive (read-only scanning). Destructive options (like Ghost Mode bypass in fuzz_api) are opt-in.

Use only on targets you own or have explicit written authorization to test.

Development

pip install -e ".[dev]"
pytest
ruff check src tests
mypy src

Comparison to HexStrike AI

License

MIT

Author

Bruno Rodrigo