# @hazzel-cn/node-terminal-mcp

[![npm version](https://badge.fury.io/js/%40hazzel-cn%2Fnode-terminal-mcp.svg)](https://www.npmjs.com/package/@hazzel-cn/node-terminal-mcp)
[![GitHub](https://img.shields.io/github/license/hazzel-cn/node-terminal-mcp)](https://github.com/hazzel-cn/node-terminal-mcp)

MCP server for terminal/PTY sessions using node-pty and xterm headless, designed for AI agents to interact with terminal environments.

## Features

- **Multiple Terminal Sessions**: Create and manage multiple concurrent terminal sessions
- **AI Agent Integration**: Send commands and read output from terminals programmatically
- **Cross-Platform**: Works on Windows, macOS, and Linux
- **Real-time Communication**: Bidirectional communication between AI agents and terminal sessions
- **Session Management**: Create, resize, and close terminal sessions as needed
- **Stdio Compatible**: Optimized for stdio transport with proper error handling and signal management

## Installation

### From npm (recommended)

```bash
npm install -g @hazzel-cn/node-terminal-mcp
```

### From source

```bash
git clone https://github.com/hazzel-cn/node-terminal-mcp.git
cd node-terminal-mcp
npm install
npm run build
```

## Building

```bash
npm run build
```

## Development

```bash
npm run dev
```

## Configuration

### Gemini CLI

**Option A: Using stdio transport (default)**
```json
{
  "mcpServers": {
    "node-terminal-mcp": {
      "command": "npx",
      "args": ["-y", "@hazzel-cn/node-terminal-mcp@latest"],
      "env": {}
    }
  }
}
```

**Option B: If you get "Connection closed" errors with ADK, try this:**
```json
{
  "mcpServers": {
    "node-terminal-mcp": {
      "command": "npx",
      "args": ["-y", "@hazzel-cn/node-terminal-mcp@latest"],
      "env": {},
      "timeout": 30000
    }
  }
}
```

**Option C: Alternative workaround for persistent connection issues:**
```json
{
  "mcpServers": {
    "node-terminal-mcp": {
      "command": "bash",
      "args": ["-c", "npx -y @hazzel-cn/node-terminal-mcp"],
      "env": {}
    }
  }
}
```

### Google ADK

**Option A: Using npx (recommended)**
```json
{
  "mcpServers": {
    "node-terminal-mcp": {
      "command": "npx",
      "args": ["-y", "@hazzel-cn/node-terminal-mcp@latest"],
      "env": {}
    }
  }
}
```

**Option B: Using global installation (recommended)**
```bash
npm install -g @hazzel-cn/node-terminal-mcp
```

```json
{
  "mcpServers": {
    "node-terminal-mcp": {
      "command": "node-terminal-mcp",
      "args": [],
      "env": {}
    }
  }
}
```

## Usage

The server provides the following MCP tools:

- `create_terminal`: Create a new terminal session
- `write_to_terminal`: Send input to a terminal session
- `send_key_to_terminal`: Send special keys to a terminal session
- `read_from_terminal`: Read output from a terminal session
- `resize_terminal`: Resize a terminal session
- `list_terminals`: List all active terminal sessions
- `close_terminal`: Close a terminal session

## Architecture

- **TerminalManager**: Manages multiple terminal sessions using node-pty
- **PTY Integration**: Uses node-pty for terminal emulation and process management
- **MCP Server**: Provides standardized interface for AI agents

## Requirements

- Node.js 18+
- Compatible with MCP (Model Context Protocol) clients

## Troubleshooting

### ADK "Connection Closed" Issue

If you're experiencing "Connection closed" errors with Google ADK, this is a known issue with stdio transport. Try these solutions:

1. **Use the latest version:**
```json
{
  "mcpServers": {
    "node-terminal-mcp": {
      "command": "npx",
      "args": ["-y", "@hazzel-cn/node-terminal-mcp@latest"],
      "env": {},
      "timeout": 30000
    }
  }
}
```

2. **Install globally:**
```bash
npm install -g @hazzel-cn/node-terminal-mcp
```
```json
{
  "mcpServers": {
    "node-terminal-mcp": {
      "command": "node-terminal-mcp",
      "args": [],
      "env": {}
    }
  }
}
```

3. **Use bash wrapper:**
```json
{
  "mcpServers": {
    "node-terminal-mcp": {
      "command": "bash",
      "args": ["-c", "npx -y @hazzel-cn/node-terminal-mcp@latest"],
      "env": {}
    }
  }
}
```

## Links

- **npm**: https://www.npmjs.com/package/@hazzel-cn/node-terminal-mcp
- **GitHub**: https://github.com/hazzel-cn/node-terminal-mcp
- **Issues**: https://github.com/hazzel-cn/node-terminal-mcp/issues

## License

MIT License - see [LICENSE](LICENSE) file for details.