# poof-mcp

An MCP (Model Context Protocol) server that provides AI agents with real terminal control capabilities on macOS.

## Features

- **Terminal session management** via zmx
- **Visible Terminal.app windows** - watch the AI work in real-time
- **Keystroke control** - send individual keys or modifier combinations
- **Text typing** - fast text input
- **Screen text capture** - read terminal content as plain text
- **Wait helpers** - wait for text or screen stability
- **Resize & restart** - control terminal dimensions and restart sessions

## Prerequisites

### 1. zmx - Terminal session manager

```bash
# macOS (Apple Silicon)
curl -LO https://zmx.sh/a/zmx-0.0.2-macos-aarch64.tar.gz
tar -xzf zmx-0.0.2-macos-aarch64.tar.gz
mv zmx ~/.local/bin/

# macOS (Intel)
curl -LO https://zmx.sh/a/zmx-0.0.2-macos-x86_64.tar.gz
tar -xzf zmx-0.0.2-macos-x86_64.tar.gz
mv zmx ~/.local/bin/
```

### 2. macOS Permissions

poof-mcp uses AppleScript to control Terminal.app, which requires permissions:

1. **Accessibility** - Required for keyboard input
2. **Automation** - Required to control Terminal.app

> **Note**: On first use, you may see macOS permission dialogs. Grant access to the app running the MCP server (e.g., Claude, VS Code, Terminal).

## Installation

```bash
# Clone the repository
git clone https://github.com/mattapperson/poof-mcp.git
cd poof-mcp

# Install dependencies (including native modules)
bun install
```

## Usage

### As an MCP Server

Add to your Claude Code MCP configuration:

```bash
claude mcp add poof-mcp -- /path/to/poof-mcp/bin/poof-mcp
```

Or add to `~/.claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "poof-mcp": {
      "command": "/path/to/poof-mcp/bin/poof-mcp"
    }
  }
}
```

### CLI

```bash
./bin/poof-mcp --help     # Show help
./bin/poof-mcp --version  # Show version
./bin/poof-mcp            # Start MCP server (stdio)
```

## MCP Tools

| Tool | Description |
|------|-------------|
| `send_keystrokes` | Send key presses (e.g., `["enter"]`, `["up", "up", "enter"]`) |
| `type_text` | Type a string |
| `get_screen_text` | Get screen as plain text |
| `get_status` | Get terminal status |
| `list_sessions` | List active sessions |
| `kill_session` | Kill a session |
| `create_session` | Create new zmx session + open Terminal.app |
| `resize_terminal` | Resize the terminal |
| `restart_terminal` | Restart the terminal (optionally with a new command) |
| `wait_for_text` | Wait for text to appear on screen (5s default timeout) |
| `wait_for_stable` | Wait for screen to stop changing (500ms stable duration) |

### Keystroke Examples

The `send_keystrokes` tool supports:
- Single characters: `a`, `b`, `1`, etc.
- Special keys: `enter`, `tab`, `escape`, `space`, `backspace`
- Arrow keys: `up`, `down`, `left`, `right`
- Function keys: `f1` through `f12`
- Modifiers: `ctrl+c`, `alt+f`, `shift+a`, `cmd+v`

## Development

```bash
# Run in development mode
bun run dev
```

## Architecture

```
Claude Code (AI Agent)
    ↓ (JSON-RPC over stdio)
MCP Server (TypeScript/Bun)
    ↓
Terminal Manager
    ├── zmx commands (session management)
    └── AppleScript (Terminal.app control)
        ↓
macOS Terminal.app + zmx session
```

## How It Works

1. **Session Management**: Uses [zmx](https://github.com/neurosnap/zmx) for terminal session persistence
2. **Terminal Control**: AppleScript controls macOS Terminal.app for keystrokes and text input
3. **Text Extraction**: AppleScript reads Terminal.app content directly

## License

MIT