> ## Documentation Index
> Fetch the complete documentation index at: https://ctpf.q-uestionable.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Proxy Module Architecture

> MCP traffic interception, session recording, and replay

The proxy module (`q_ai.proxy`) intercepts MCP traffic between a client and server for inspection, modification, and replay. It operates as a man-in-the-middle, presenting itself as the server to the client while forwarding messages to the real server.

## Module Structure

```
proxy/
├── intercept.py         # Message interception logic
├── pipeline.py          # Processing pipeline for messages
├── session_store.py     # Session persistence (JSON files)
├── correlation.py       # Request-response message correlation
├── replay.py            # Session replay against live servers
├── models.py            # ProxyMessage, ProxySession, Transport, Direction
├── tui/                 # Textual TUI for interactive session review
│   └── app.py           # ProxyApp — main TUI application
├── adapters/
│   ├── stdio.py         # StdioServerAdapter for child process servers
│   ├── sse.py           # SseServerAdapter for SSE servers
│   └── streamable_http.py # StreamableHttpServerAdapter
├── exporting/           # Export to JSON
├── cli.py               # start, replay, export, inspect commands
├── adapter.py           # ProxyAdapter for orchestrator integration
└── mapper.py            # persist_session() — bridges to core DB
```

## How It Works

`ctpf proxy start` launches the TUI. The proxy:

1. Spawns the target MCP server (stdio) or connects to it (SSE/HTTP)
2. Presents itself as the server to the client
3. Records all messages with timestamps, direction, and sequence numbers
4. In passthrough mode: forwards messages transparently
5. In intercept mode: pauses on each message for inspection/modification

## Session Model

A session is a sequence of `ProxyMessage` objects. Each message records:

* **direction** — `CLIENT_TO_SERVER` or `SERVER_TO_CLIENT`
* **method** — MCP method name (e.g., `tools/call`, `initialize`)
* **jsonrpc\_id** — For request/response correlation
* **sequence** — Ordering within the session
* **raw** — Full JSON-RPC message
* **original\_raw** — Pre-modification content (if intercepted and changed)
* **modified** — Boolean flag
* **correlated\_id** — Links requests to their responses

Sessions persist as JSON files via `SessionStore`.

## Replay

`ctpf proxy replay` replays recorded client-to-server messages against a live server:

* Loads a saved session file
* Optionally sends a synthetic `initialize` handshake
* Sends each client→server message to the target
* Records responses and latency
* Reports success/failure per message

Supports replay against stdio servers (`--target-command`) or HTTP servers (`--target-url`).

## TUI

The Textual-based TUI provides:

* Chronological message list with direction indicators (`→` client→server, `←` server→client)
* Message expansion for full JSON payload inspection
* Intercept mode with pause/modify/forward controls

## Adapter

`ProxyAdapter` wraps session recording for orchestrator workflows. It creates a child run, starts the proxy, and persists the session to the database on completion or failure.

## Export

`ctpf proxy export` serializes a session to JSON. `ctpf proxy inspect` prints session contents to stdout with optional `--verbose` for full JSON payloads.