伪终端会话服务器

# Check Node.js version
node --version  # Should be >= 18.0.0

# If Node.js is missing or outdated, install via nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20

# Install build tools (required for node-pty native module)
# Ubuntu/Debian:
sudo apt-get update && sudo apt-get install -y python3 make g++

# macOS:
xcode-select --install

# Fedora/RHEL:
sudo dnf install -y python3 make gcc-c++

# Create MCP servers directory if it doesn't exist
mkdir -p ~/mcp-servers
cd ~/mcp-servers

# Clone the repository
git clone https://github.com/dblmca/pty-mcp.git
cd pty-mcp

npm install

# If npm install fails with node-pty errors, install build dependencies first
sudo apt-get install -y python3 make g++  # Ubuntu/Debian
# Then retry
npm install

# Add to user config (available in all projects)
claude mcp add -s user pty-mcp -- node ~/mcp-servers/pty-mcp/server.js

claude mcp add -s user pty-mcp -- node /full/path/to/pty-mcp/server.js

# List registered MCP servers
claude mcp list

# Should show pty-mcp with status

1. Call pty_spawn with no arguments to create a shell session
2. Call pty_read to see the shell prompt
3. Call pty_write with input: "echo hello\r"
4. Call pty_read to see the output
5. Call pty_kill to clean up

{
  "session_id": "abc123def456...",
  "pid": 12345,
  "command": "/bin/bash",
  "cols": 120,
  "rows": 30
}

{ "written": 5 }

{
  "output": "user@host:~$ ",
  "exited": false,
  "exit_code": null,
  "signal": null
}

1. pty_spawn { command: "ssh", args: ["user@192.168.1.100"] }
2. pty_read { session_id: "...", timeout_ms: 5000 }  # Wait for prompt/password
3. pty_write { session_id: "...", input: "password\r" }  # If password needed
4. pty_read { session_id: "..." }  # Get remote prompt
5. pty_write { session_id: "...", input: "hostname\r" }  # Run commands
6. pty_read { session_id: "..." }
7. pty_write { session_id: "...", input: "exit\r" }  # Disconnect
8. pty_kill { session_id: "..." }  # Cleanup

1. pty_spawn { command: "python3" }
2. pty_read { session_id: "..." }  # ">>> "
3. pty_write { session_id: "...", input: "import math\r" }
4. pty_write { session_id: "...", input: "print(math.pi)\r" }
5. pty_read { session_id: "..." }  # "3.141592653589793\n>>> "
6. pty_write { session_id: "...", input: "\x04" }  # Ctrl-D to exit

1. pty_spawn { command: "vim", args: ["file.txt"] }
2. pty_read { session_id: "...", timeout_ms: 1000 }  # Wait for vim
3. pty_write { session_id: "...", input: "i" }  # Insert mode
4. pty_write { session_id: "...", input: "Hello, World!" }
5. pty_write { session_id: "...", input: "\x1b" }  # Escape
6. pty_write { session_id: "...", input: ":wq\r" }  # Save and quit
7. pty_kill { session_id: "..." }

1. pty_spawn { command: "top" }
2. pty_read { session_id: "...", timeout_ms: 2000 }  # Get display
3. pty_write { session_id: "...", input: "q" }  # Quit top
   # Or: pty_write { session_id: "...", input: "\x03" }  # Ctrl-C

# Verify registration
claude mcp list

# If missing, re-add
claude mcp add -s user pty-mcp -- node ~/mcp-servers/pty-mcp/server.js

# Restart Claude Code

# Install build dependencies
sudo apt-get install -y python3 make g++

# Clear npm cache and retry
rm -rf node_modules package-lock.json
npm install

### PTY MCP Server (Interactive Terminal)

The `pty-mcp` server provides interactive terminal (PTY) sessions for programs that require full terminal emulation (vim, ssh, less, top, interactive REPLs, etc.).

**Location:** `~/mcp-servers/pty-mcp/`

**When to Use:**
- Interactive programs that need terminal emulation (vim, nano, less, top, htop)
- SSH sessions
- Interactive REPLs (python, node, irb)
- Programs that require Ctrl-C, Ctrl-D, or arrow keys
- Any program that doesn't work well with the standard Bash tool

**MCP Tools:**
- `pty_spawn` - Create a new PTY session (returns session_id)
- `pty_write` - Send input to a session (supports escape sequences)
- `pty_read` - Read buffered output from a session
- `pty_resize` - Resize terminal dimensions
- `pty_kill` - Kill a session
- `pty_list` - List all active sessions

**Escape Sequences for `pty_write`:**
| Sequence | Meaning |
|----------|---------|
| `\r` | Enter/Return |
| `\x03` | Ctrl-C (interrupt) |
| `\x04` | Ctrl-D (EOF) |
| `\x1b` | Escape |
| `\x1b[A` | Arrow Up |
| `\x1b[B` | Arrow Down |
| `\x1b[C` | Arrow Right |
| `\x1b[D` | Arrow Left |

**Usage Examples:**

\`\`\`
# Basic shell session
1. pty_spawn {}                              → { session_id: "abc123" }
2. pty_read { session_id: "abc123" }         → { output: "$ " }
3. pty_write { session_id: "abc123", input: "ls -la\r" }
4. pty_read { session_id: "abc123" }         → { output: "..." }
5. pty_kill { session_id: "abc123" }

# Python REPL
1. pty_spawn { command: "python3" }
2. pty_write { session_id: "...", input: "x = 42\r" }
3. pty_write { session_id: "...", input: "print(x * 2)\r" }
4. pty_read { session_id: "..." }            → { output: "84\n>>> " }
5. pty_write { session_id: "...", input: "\x04" }  # Ctrl-D to exit

# Vim editing
1. pty_spawn { command: "vim", args: ["file.txt"] }
2. pty_write { session_id: "...", input: "i" }       # Insert mode
3. pty_write { session_id: "...", input: "Hello!" }
4. pty_write { session_id: "...", input: "\x1b" }    # Escape
5. pty_write { session_id: "...", input: ":wq\r" }   # Save and quit
\`\`\`

**Configuration:**
- Max 10 concurrent sessions
- 30-minute idle timeout (auto-cleanup)
- 1MB output buffer per session
- Default terminal: 120x30