> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pwno.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> Project structure and runtime design decisions behind pwno-mcp.

`pwno-mcp` combines a FastMCP server, a session registry, debugger backends, and helper tool families into a single stateful runtime.

## Main runtime surfaces

<CardGroup cols={2}>
  <Card title="HTTP transport" icon="server">
    FastMCP endpoint served at `/mcp` with `/healthz` for simple health checks.
  </Card>

  <Card title="stdio transport" icon="terminal">
    Local process-based MCP mode for clients that cannot use HTTP.
  </Card>

  <Card title="Attach sidecar" icon="plug">
    Local FastAPI helper that wraps process-attach workflows on `/attach`.
  </Card>

  <Card title="Session registry" icon="layers-3">
    Keeps separate GDB state, runtime directories, and optional driver metadata per session.
  </Card>
</CardGroup>

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

<Tree>
  <Tree.Folder name="pwnomcp" defaultOpen>
    <Tree.File name="__main__.py" />

    <Tree.File name="server.py" />

    <Tree.File name="runtime.py" />

    <Tree.File name="services.py" />

    <Tree.File name="lifespan.py" />

    <Tree.File name="asgi.py" />

    <Tree.File name="cli.py" />

    <Tree.Folder name="http" defaultOpen>
      <Tree.File name="attach.py" />

      <Tree.File name="health.py" />

      <Tree.File name="models.py" />
    </Tree.Folder>

    <Tree.Folder name="state" defaultOpen>
      <Tree.File name="session.py" />

      <Tree.File name="registry.py" />
    </Tree.Folder>

    <Tree.Folder name="tools" defaultOpen>
      <Tree.File name="debug.py" />

      <Tree.File name="inspect.py" />

      <Tree.File name="processes.py" />

      <Tree.File name="python_env.py" />

      <Tree.File name="pwncli.py" />

      <Tree.File name="repos.py" />

      <Tree.File name="retdec.py" />

      <Tree.Folder name="backends">
        <Tree.File name="gdb.py" />

        <Tree.File name="pwndbg.py" />

        <Tree.File name="subproc.py" />

        <Tree.File name="python.py" />

        <Tree.File name="git.py" />

        <Tree.File name="retdec.py" />
      </Tree.Folder>
    </Tree.Folder>
  </Tree.Folder>
</Tree>

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