# happyhackingspace/mcp-hydra architecture

> Architecture diagram of the GitHub repository happyhackingspace/mcp-hydra, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/happyhackingspace/mcp-hydra
- Repository: https://github.com/happyhackingspace/mcp-hydra

## Overview

##### Project type and purpose
- This is a Dockerized, AI‑assistable pentesting microservice (“HydraMCP”) written in Python.
- It implements the Model Context Protocol (MCP) as a thin server layer (server.py + banner.sh) that dispatches AI‑driven requests to a suite of external security tools (nmap, sqlmap, etc.) wrapped by custom Python modules in the toolkit/ directory.
- Purpose: expose a standard JSON‑RPC–style interface so any AI assistant (Claude, Copilot, etc.) can invoke pentesting tools and ingest their output.

##### File structure
- Top‑level:
- Dockerfile + requirements.txt → container build & Python dependencies.
- server.py → MCP server entrypoint.
- banner.sh → optional startup banner.
- demos/ → usage exemplars.
- toolkit/ → a plugin directory where each .py calls a CLI tool (dnsrecon.py, holehe.py, nmap.py, ocr2text.py, sqlmap.py, sublist3r.py, wpscan.py, zmap.py).
- No web front end—communication is over STDIN/STDOUT or socket (MCP).
- No database—stateless command dispatch.
- Uses a plugin pattern: each toolkit/<tool>.py implements a common interface.

##### README for additional insights
- Confirms MCP protocol, Docker invocation, configuration JSON for AI clients.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Side
    subgraph "Client Side"
        direction TB
        AI["AI Assistant"]:::client
        Config["MCP Client Config"]:::client
        Demos["Usage Demos (demos/)"]:::client
        README["Project README"]:::client
    end

    %% Container Boundary
    subgraph "HydraMCP Container" 
        direction TB
        classDef container fill:#e0ffe0,stroke:#00aa00
        Dockerfile["Docker Build Config"]:::container
        Requirements["Python Dependencies (requirements.txt)"]:::container
        subgraph "MCP Server Core"
            direction TB
            Server["MCP Server (server.py)"]:::container
            Banner["Startup Banner (banner.sh)"]:::container
        end
        Dispatcher["Plugin Dispatcher"]:::container
        subgraph "Toolkit Modules"
            direction TB
            DNS["DNSRecon Module"]:::toolkit
            Holehe["Holehe Module"]:::toolkit
            Nmap["Nmap Module"]:::toolkit
            OCR["OCR2Text Module"]:::toolkit
            SQLmap["SQLMap Module"]:::toolkit
            Sublist3r["Sublist3r Module"]:::toolkit
            WPscan["WPSCAN Module"]:::toolkit
            Zmap["ZMap Module"]:::toolkit
        end
        OSLayer["OS & Installed CLI Tools"]:::os
    end

    %% External Targets
    subgraph "External Targets"
        direction TB
        DNSsvc["DNS Servers"]:::external
        Network["Target Network"]:::external
        WPsites["WordPress Sites"]:::external
    end

    %% Connections
    Config -->|"configures"| AI
    AI -->|"MCP JSON"| Server
    Server -->|"loads banner"| Banner
    Server -->|"dispatches request"| Dispatcher
    Dispatcher -->|"invokes"| DNS
    Dispatcher -->|"invokes"| Holehe
    Dispatcher -->|"invokes"| Nmap
    Dispatcher -->|"invokes"| OCR
    Dispatcher -->|"invokes"| SQLmap
    Dispatcher -->|"invokes"| Sublist3r
    Dispatcher -->|"invokes"| WPscan
    Dispatcher -->|"invokes"| Zmap
    DNS -->|"spawns CLI"| OSLayer
    Holehe -->|"spawns CLI"| OSLayer
    Nmap -->|"spawns CLI"| OSLayer
    OCR -->|"spawns CLI"| OSLayer
    SQLmap -->|"spawns CLI"| OSLayer
    Sublist3r -->|"spawns CLI"| OSLayer
    WPscan -->|"spawns CLI"| OSLayer
    Zmap -->|"spawns CLI"| OSLayer
    OSLayer -->|"network probing"| DNSsvc
    OSLayer -->|"network probing"| Network
    OSLayer -->|"network probing"| WPsites
    OSLayer -->|"raw output"| DNS
    OSLayer -->|"raw output"| Holehe
    OSLayer -->|"raw output"| Nmap
    OSLayer -->|"raw output"| OCR
    OSLayer -->|"raw output"| SQLmap
    OSLayer -->|"raw output"| Sublist3r
    OSLayer -->|"raw output"| WPscan
    OSLayer -->|"raw output"| Zmap
    Dispatcher -->|"collects output"| Server
    Server -->|"returns MCP JSON"| AI

    %% Click Events
    click Dockerfile "https://github.com/happyhackingspace/mcp-hydra/tree/main/Dockerfile"
    click Requirements "https://github.com/happyhackingspace/mcp-hydra/blob/main/requirements.txt"
    click Server "https://github.com/happyhackingspace/mcp-hydra/blob/main/server.py"
    click Banner "https://github.com/happyhackingspace/mcp-hydra/blob/main/banner.sh"
    click Config "https://github.com/happyhackingspace/mcp-hydra/tree/main/.vscode/"
    click Demos "https://github.com/happyhackingspace/mcp-hydra/tree/main/demos/"
    click README "https://github.com/happyhackingspace/mcp-hydra/blob/main/README.md"
    click Dispatcher "https://github.com/happyhackingspace/mcp-hydra/tree/main/toolkit/"
    click DNS "https://github.com/happyhackingspace/mcp-hydra/blob/main/toolkit/dnsrecon.py"
    click Holehe "https://github.com/happyhackingspace/mcp-hydra/blob/main/toolkit/holehe.py"
    click Nmap "https://github.com/happyhackingspace/mcp-hydra/blob/main/toolkit/nmap.py"
    click OCR "https://github.com/happyhackingspace/mcp-hydra/blob/main/toolkit/ocr2text.py"
    click SQLmap "https://github.com/happyhackingspace/mcp-hydra/blob/main/toolkit/sqlmap.py"
    click Sublist3r "https://github.com/happyhackingspace/mcp-hydra/blob/main/toolkit/sublist3r.py"
    click WPscan "https://github.com/happyhackingspace/mcp-hydra/blob/main/toolkit/wpscan.py"
    click Zmap "https://github.com/happyhackingspace/mcp-hydra/blob/main/toolkit/zmap.py"

    %% Styles
    classDef client fill:#d0e7ff,stroke:#3794ff
    classDef toolkit fill:#ffe0b3,stroke:#ff9900
    classDef os fill:#f0f0f0,stroke:#a0a0a0
    classDef external fill:#ffe0e0,stroke:#ff0000
```
