# ibrahimsaleem/pentestthinkingmcp architecture

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

- Interactive diagram: https://gitdiagram.com/ibrahimsaleem/pentestthinkingmcp
- Repository: https://github.com/ibrahimsaleem/pentestthinkingmcp

## Overview

##### Project type and purpose
- This is a Node.js/TypeScript‐based, server-side “Model Context Protocol (MCP)” application called PentestThinkingMCP. It implements a reasoning engine for penetration-testing workflows, exposing an MCP‐compliant interface that clients (e.g., Cursor, Claude Desktop) can invoke to get AI‐powered attack step recommendations.

##### File structure analysis
- Top‐level files:
- index.js (entry point for production)
- state-manager.js, tot-engine.js (legacy or build outputs)
- package.json, tsconfig.json (build & dependency config)
- src/
- index.ts (TypeScript entry point)
- engine.ts (orchestrator for reasoning workflows)
- reasoner.ts (implements search orchestration)
- state.ts (in‐memory model of current attack state)
- strategies/ (search algorithms)
– base.ts (abstract strategy interface)
– beam-search.ts (Beam Search impl)
– mcts.ts (MCTS impl)
– factory.ts (chooses & instantiates a strategy)
- types.ts & types/modelcontextprotocol.d.ts (type definitions for MCP messages)

##### Key insights from README
- Exposes an MCP server over a process-based protocol (stdin/stdout).
- Two core search strategies (Beam Search vs. MCTS) drive multi‐step attack path generation.
- Maintains a tree of attack steps, scores vulnerabilities, recommends tools.
- No external database—state lives in memory.

##### Main components
a. External Clients (MCP Clients)
b. MCP Protocol Handler
c. Engine Orchestrator
d. Reasoner Module
e. Strategy Factory → {Beam Search, MCTS}
f. State Manager (Attack Path Tree + Current Step)
g. Scoring & Tool Recommendation
h. Output Formatter (MCP response)

##### Relationships & data flows
- Client sends JSON over stdin → MCP Protocol Handler
- Protocol Handler parses request → Engine Orchestrator
- Orchestrator updates State Manager, invokes Reasoner
- Reasoner asks Strategy Factory for a search strategy
- Strategy runs against current State to generate candidate steps
- Strategy returns scored attack steps → Reasoner
- Reasoner picks best step(s), asks Scoring & Tool Recommendation for metadata
- Engine packages new State + step + recommended tool → Output Formatter
- Formatter serializes MCP response → stdout back to Client

##### Architectural patterns & design principles
- Strategy Pattern (strategies/base.ts + beam-search, mcts, factory.ts)
- Orchestrator pattern in engine.ts for coordinating components
- In-memory state as a tree structure for attack paths (state.ts)
- Single‐process, modular monolith—no microservices, but clear separation of concerns

##### Relevant technologies
- Node.js + TypeScript
- MCP protocol (custom JSON‐over‐stdio)
- Beam Search & Monte Carlo Tree Search algorithms
- npm scripts for build & run

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    Client["MCP Client<br>(stdin/stdout)"]:::io

    %% I/O Boundary
    Handler["MCP Protocol Handler"]:::io
    Formatter["Output Formatter"]:::io

    %% Orchestration
    Engine["Engine Orchestrator"]:::orchestration
    Reasoner["Reasoner Module"]:::orchestration
    Scoring["Scoring & Tool Recommendation"]:::orchestration

    %% State
    State["State Manager<br>(Attack Path Tree & Current Step)"]:::state

    %% Type Definitions
    Types["Types.ts<br>(Common Types)"]:::types
    ModelProto["modelcontextprotocol.d.ts<br>(MCP Types)"]:::types

    %% Search Strategies Group
    subgraph "Search Strategies"
        Factory["Strategy Factory"]:::algorithm
        Base["Base Strategy Interface"]:::algorithm
        Beam["Beam Search Strategy"]:::algorithm
        MCTS["Monte Carlo Tree Search Strategy"]:::algorithm
    end

    %% Data Flow
    Client -->|"MCP Request"| Handler
    Handler -->|"parse & validate"| Engine
    Engine -->|"updateState()"| State
    Engine -->|"invokeReasoner()"| Reasoner
    Reasoner -->|"SelectStrategy() "| Factory
    Factory --> Base
    Factory --> Beam
    Factory --> MCTS
    Beam -->|"execute()"| Reasoner
    MCTS -->|"execute()"| Reasoner
    Reasoner -->|"ScoreSteps()"| Scoring
    Scoring -->|"metadata"| Reasoner
    Reasoner -->|"buildResponse"| Formatter
    Formatter -->|"MCP Response"| Client

    %% Type Dependencies
    Handler -.-> Types
    Handler -.-> ModelProto
    Engine -.-> Types
    Reasoner -.-> Types
    Factory -.-> Types

    %% Click Events
    click Handler "https://github.com/ibrahimsaleem/pentestthinkingmcp/blob/main/src/index.ts"
    click Engine "https://github.com/ibrahimsaleem/pentestthinkingmcp/blob/main/src/engine.ts"
    click Reasoner "https://github.com/ibrahimsaleem/pentestthinkingmcp/blob/main/src/reasoner.ts"
    click State "https://github.com/ibrahimsaleem/pentestthinkingmcp/blob/main/src/state.ts"
    click Factory "https://github.com/ibrahimsaleem/pentestthinkingmcp/blob/main/src/strategies/factory.ts"
    click Beam "https://github.com/ibrahimsaleem/pentestthinkingmcp/blob/main/src/strategies/beam-search.ts"
    click MCTS "https://github.com/ibrahimsaleem/pentestthinkingmcp/blob/main/src/strategies/mcts.ts"
    click Base "https://github.com/ibrahimsaleem/pentestthinkingmcp/blob/main/src/strategies/base.ts"
    click Types "https://github.com/ibrahimsaleem/pentestthinkingmcp/blob/main/src/types.ts"
    click ModelProto "https://github.com/ibrahimsaleem/pentestthinkingmcp/blob/main/src/types/modelcontextprotocol.d.ts"

    %% Styles
    classDef io fill:#7BEAAA,stroke:#333,stroke-width:1px
    classDef orchestration fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef algorithm fill:#FFFACD,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef state fill:#FFB347,stroke:#333,stroke-width:1px
    classDef types fill:#D3D3D3,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
```
