pwno-mcp combines a FastMCP server, a session registry, debugger backends, and helper tool families into a single stateful runtime.
Main runtime surfaces
HTTP transport
FastMCP endpoint served at
/mcp with /healthz for simple health checks.stdio transport
Local process-based MCP mode for clients that cannot use HTTP.
Attach sidecar
Local FastAPI helper that wraps process-attach workflows on
/attach.Session registry
Keeps separate GDB state, runtime directories, and optional driver metadata per session.
Tool families
- debugger control in
pwnomcp/tools/debug.py - inspection in
pwnomcp/tools/inspect.py - process helpers in
pwnomcp/tools/processes.py - managed Python helpers in
pwnomcp/tools/python_env.py - interactive exploit-driver flows in
pwnomcp/tools/pwncli.py - repo acquisition in
pwnomcp/tools/repos.py - RetDec integration in
pwnomcp/tools/retdec.py
Project structure
pwnomcp
__main__.py
server.py
runtime.py
services.py
lifespan.py
asgi.py
cli.py
http
attach.py
health.py
models.py
state
session.py
registry.py
tools
debug.py
inspect.py
processes.py
python_env.py
pwncli.py
repos.py
retdec.py
backends
Key design decisions
Stateful sessions
The runtime keeps debugger state alive across calls instead of treating every request as a stateless shell command.GDB/MI-native control
Execution-control tools prefer MI commands because they are structured and more reliable for agents than parsing free-form terminal output.Separation of concerns
The router registers tools, while most implementation logic lives in dedicated backend or tool modules.Container-oriented runtime
The project assumes containerized execution with a mounted/workspace and explicit ptrace capabilities.