# pty-mcp

A lightweight PTY runner for MCP (Model Context Protocol).

`pty-mcp` provides terminal session tools over MCP so clients can spawn commands in a pseudo-terminal, read interactive output, send input, resize terminal windows, and manage process lifecycle safely.

## Features

- Spawn shell commands in a real PTY
- Read incremental output from a ring buffer
- Wait for pattern matching (`read_until`)
- Send interactive input (`write`)
- Resize terminal (`cols` / `rows`)
- Process control (`status`, `wait`, `signal`, `close`)

## Requirements

- Python 3.10+

## Installation

```bash
pip install pty-mcp
```

## CLI Entrypoint

After installation, the package exposes:

```bash
pty-mcp
```

This starts the MCP server over stdio.

## MCP Tools

- `pty_spawn`
- `pty_read`
- `pty_read_until`
- `pty_write`
- `pty_resize`
- `pty_close`
- `pty_close_all`
- `pty_status`
- `pty_wait`
- `pty_signal`
- `pty_list`

## Notes

- PTY sessions are in-memory and have idle timeout cleanup.
- The server is intended for local trusted environments.

## License

MIT
