# brunopark-mcp

[![CI](https://github.com/brunopark852/brunopark-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/brunopark852/brunopark-mcp/actions/workflows/ci.yml)
[![Latest Release](https://img.shields.io/github/v/release/brunopark852/brunopark-mcp?color=blue&label=release)](https://github.com/brunopark852/brunopark-mcp/releases/latest)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)](https://www.python.org)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-compatible-purple)](https://modelcontextprotocol.io)
[![Tests](https://img.shields.io/badge/tests-55%20passing-brightgreen)](tests/)
[![LOC](https://img.shields.io/badge/loc-1.9k-orange)](src/brunopark_mcp/)
[![Repo Size](https://img.shields.io/github/repo-size/brunopark852/brunopark-mcp)](https://github.com/brunopark852/brunopark-mcp)

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

Lean alternative to [HexStrike AI](https://github.com/0x4m4/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](https://modelcontextprotocol.io) 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

| MCP Tool | Wraps | Purpose |
|----------|-------|---------|
| `recon_target` | [recon-tool](https://github.com/brunopark852/recon-tool) | Banner grabbing + CVE lookup |
| `scan_ports` | [port-scanner](https://github.com/brunopark852/port-scanner) | Async port scan + banner grabbing |
| `hunt_subdomains` | [sub-hunter](https://github.com/brunopark852/sub-hunter) | Subdomain enumeration |
| `scan_frontend` | [front-end-scanner](https://github.com/brunopark852/front-end-scanner) | Security headers + JS analysis |
| `fuzz_api` | [api-pathfinder](https://github.com/brunopark852/api-pathfinder) | API path fuzzing + Ghost Mode |
| `orchestrate_nemesis` | [nemesis-scanner](https://github.com/brunopark852/nemesis-scanner) | Multi-source recon orchestrator |

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](https://github.com/0x4m4/hexstrike-ai) 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

```bash
# 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`:

```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`:

```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.

```python
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

| Objective | Tools used | Use case |
|-----------|-----------|----------|
| `passive` | `hunt_subdomains`, `recon_target` | No active probing; OSINT only |
| `quick` | `recon_target`, `scan_ports` | Fast check, top 50 ports |
| `recon` | `hunt_subdomains`, `scan_ports`, `recon_target` | Mapping the target |
| `vuln_hunt` | `scan_frontend`, `fuzz_api`, `orchestrate_nemesis` | Find vulns, not just discover |
| `comprehensive` | All 6 | Full audit |

## 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

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

## Comparison to HexStrike AI

| | brunopark-mcp | HexStrike AI |
|---|---|---|
| Tools | 6 (Bruno's Python tools) | 150+ (nmap, sqlmap, nuclei, etc) |
| External deps | None required | 150+ CLIs must be installed |
| LOC | ~600 | 17k+ |
| Languages | Python 3.10+ | Python 3.10+ |
| MCP support | Native (FastMCP) | Native (FastMCP) |
| Decision engine | Heuristic | Heuristic + AI |
| Setup complexity | Low | High (Kali Linux recommended) |
| Best for | Python-first bug bounty | Full-spectrum pentesting |

## License

MIT

## Author

Bruno Rodrigo