How ibrahimsaleem/pentestthinkingmcp works
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