Metadata-Version: 2.4
Name: i4z-terminal-mcp
Version: 0.2.0
Summary: MCP server for persistent interactive terminal orchestration
License-Expression: MIT
Requires-Python: >=3.11
Requires-Dist: mcp>=1.0.0
Requires-Dist: pexpect>=4.8
Description-Content-Type: text/markdown

# i4z-terminal-mcp

MCP server that enables AI agents to manage multiple persistent terminal sessions concurrently.

## Features

- Persistent PTY-backed bash shells
- 9 MCP tools for full terminal lifecycle management
- Concurrent terminals with isolated async background readers
- Incremental cursor-based output reads
- Pattern-based output waiting
- Signal support (SIGINT, SIGTERM, SIGKILL)
- **Web UI** — view terminals live at `http://127.0.0.1:9020` (xterm.js)

## Install

```bash
uv tool install i4z-terminal-mcp
# or
pip install i4z-terminal-mcp
# or from source
uv pip install -e .
```

## Usage

With OpenCode, add to `opencode.json`:

```json
{
  "mcp": {
    "terminal": {
      "type": "local",
      "command": ["uvx", "i4z-terminal-mcp"],
      "enabled": true
    }
  }
}
```

Or directly:

```bash
i4z-terminal-mcp
```

## Tools

| Tool | Description |
|---|---|
| `create_terminal` | Spawn a persistent bash shell |
| `list_terminals` | List all active sessions |
| `terminal_status` | Get PID, CWD, alive, timestamps |
| `send_input` | Write text/commands to stdin |
| `read_output` | Incremental read via cursor |
| `send_signal` | Send SIGINT/SIGTERM/SIGKILL |
| `kill_terminal` | Destroy session and free resources |
| `wait_for_output` | Block until pattern appears |
| `search_output` | Search output history buffer |

## Requirements

- Python 3.11+
- Linux or macOS (pexpect PTY support)
