# pty-mcp

An MCP server for interactive PTY sessions — end-to-end testing of CLI apps, REPLs and TUIs by driving a real pseudo-terminal and reading a clean rendered screen back. Exposed to any MCP client (built for Claude Code) over stdio.

## Stack

- Python 3.14 + venv
- `pexpect` — PTY spawn, text/key injection
- `pyte` — terminal emulator (clean screen rendering, ANSI stripped)
- `mcp` — Python MCP SDK

## Tools

| Tool | Description |
|------|-------------|
| `pty_start` | Start a PTY session (command, cwd, env, cols, rows) |
| `pty_send` | Send raw text |
| `pty_send_key` | Send a special key (enter, ctrl+c, arrows…) |
| `pty_expect` | Wait for a regex pattern in the output (with timeout) |
| `pty_screen` | Current screen state, cleanly rendered (no ANSI) |
| `pty_read` | Last N lines of the scrollback buffer |
| `pty_close` | Close the session and kill the process |
| `pty_list` | List all active sessions |

## Example — E2E test

```
pty_start(session_id="myapp", command="python myapp.py", cwd="/path/to/myapp")
pty_expect(session_id="myapp", pattern="Enter your name:", timeout_ms=5000)
pty_send(session_id="myapp", text="Chris\r")
pty_expect(session_id="myapp", pattern="Welcome, Chris", timeout_ms=3000)
pty_screen(session_id="myapp")   # terminal screenshot
pty_close(session_id="myapp")
```

## Run

The server is registered in the MCP client and starts with each session. To test standalone: `./start.sh`. Transport is stdio, no network port. Logs in `logs/mcp_server.log`.