# Zyxel Switch MCP Server

A comprehensive Model Context Protocol (MCP) server for Zyxel switch CLI commands, enabling AI applications to interact with Zyxel switches for network configuration, monitoring, and management operations.

## Status

The server opens a **real interactive CLI session** on the switch over SSH (default) or
Telnet, and runs commands against it. Command syntax and the expected output formats come
from the official Zyxel CLI Reference Guide (407 pages).

An offline mode (`ZYXEL_MOCK=true`) replays canned output so the server can be developed
and demoed without hardware. Everything it returns is fabricated.

## Features

- **Live CLI sessions**: SSH (`ssh2`) or Telnet with its own option negotiation
- **Automatic privilege handling**: enters `enable` / `configure terminal` on demand, including the enable-password prompt
- **Pagination handling**: `--More--` prompts are answered automatically, so long output arrives complete
- **Clean output**: the echoed command and the trailing prompt are stripped before the result is returned
- **Serialised commands**: overlapping tool calls are queued so they cannot interleave on the shared stream
- **Legacy switch support**: older KEX/cipher/HMAC algorithms are offered in addition to the modern defaults
- **MCP Compliance**: Full Model Context Protocol implementation with tools, resources, and prompts

## Supported Zyxel Models

Based on the integrated CLI documentation:
- **GS1920 Series** (24/48 port variants)
- **GS1900 Series**
- **XGS1930 Series**
- **XGS2220 Series**
- Other managed Zyxel switches with CLI access

## MCP Tools (CLI Commands)

### Connection Management
- `zyxel_connect` - Connect to a Zyxel switch
- `zyxel_disconnect` - Disconnect from the switch
- `zyxel_connection_status` - Check connection status

### System Information
- `zyxel_show_version` - Display system version information
- `zyxel_show_system_info` - Show detailed system information
- `zyxel_show_running_config` - Display running configuration
- `zyxel_show_startup_config` - Display startup configuration

### Interface Management
- `zyxel_show_interfaces` - Display interface status and configuration
- `zyxel_configure_interface` - Configure interface settings
- `zyxel_configure_switchport` - Configure switchport settings

### VLAN Management
- `zyxel_show_vlan` - Display VLAN information
- `zyxel_create_vlan` - Create a new VLAN
- `zyxel_delete_vlan` - Delete a VLAN

### Network Monitoring
- `zyxel_show_mac_table` - Display MAC address table
- `zyxel_show_arp_table` - Display ARP table
- `zyxel_show_spanning_tree` - Display spanning tree information
- `zyxel_ping` - Test network connectivity

### Configuration Management
- `zyxel_save_config` - Save running configuration to startup
- `zyxel_execute_cli` - Execute raw CLI commands

## MCP Resources (Read-only Data)

### System Resources
- `zyxel://switch/version` - System version information
- `zyxel://switch/system-info` - Detailed system information
- `zyxel://switch/running-config` - Current running configuration
- `zyxel://switch/startup-config` - Saved startup configuration

### Network Resources
- `zyxel://switch/interfaces` - Interface status and statistics
- `zyxel://switch/vlans` - VLAN configuration and status
- `zyxel://switch/mac-table` - MAC address table entries
- `zyxel://switch/arp-table` - ARP table entries
- `zyxel://switch/spanning-tree` - Spanning tree topology
- `zyxel://switch/port-statistics` - Port traffic statistics

### Documentation
- `zyxel://docs/cli-reference` - Complete CLI command reference
- `zyxel://docs/troubleshooting` - Troubleshooting guide

## MCP Prompts (Guided Workflows)

### Setup and Configuration
- `zyxel_initial_setup` - Guide for initial switch setup
- `zyxel_vlan_setup` - Step-by-step VLAN configuration
- `zyxel_port_configuration` - Port configuration guide

### Maintenance and Operations
- `zyxel_troubleshooting` - Network troubleshooting procedures
- `zyxel_backup_restore` - Configuration backup and restore
- `zyxel_monitoring_setup` - Monitoring and logging setup

### Security and Performance
- `zyxel_security_hardening` - Security configuration best practices
- `zyxel_performance_optimization` - Performance tuning guide

## Installation

1. Clone the repository:
```bash
git clone https://github.com/humyai99/mcp-zyxel.git
cd mcp-zyxel
```

2. Install dependencies:
```bash
npm install
```

3. Build the project:
```bash
npm run build
```

## Usage

### Direct Execution
```bash
npm start
```

### As MCP Server
Configure your MCP client to use this server:

```json
{
  "mcpServers": {
    "zyxel": {
      "command": "npx",
      "args": ["zyxel-mcp-server"]
    }
  }
}
```

### Development Mode
```bash
npm run dev
```

## Configuration

The server can be configured through environment variables. When host, username and
password are all present, the server starts pre-configured and `zyxel_connect` can be
called with no arguments.

- `ZYXEL_DEFAULT_HOST` - Default switch IP address
- `ZYXEL_DEFAULT_USERNAME` - Default username
- `ZYXEL_DEFAULT_PASSWORD` - Default password
- `ZYXEL_ENABLE_PASSWORD` - Password for privileged mode (falls back to the login password)
- `ZYXEL_PROTOCOL` - `ssh` (default) or `telnet`
- `ZYXEL_PORT` - Overrides the protocol default (22 for SSH, 23 for Telnet)
- `ZYXEL_TIMEOUT` - Command timeout in milliseconds (default: 30000)
- `ZYXEL_DEBUG` - Log every command and response to stderr (true/false)
- `ZYXEL_MOCK` - `true` replays canned output and never contacts a switch

Passwords are only held in memory for the lifetime of the session, and
`zyxel_connection_status` redacts them.

### Offline mode

```bash
ZYXEL_MOCK=true npm start
```

## Examples

### Connecting to a Switch
```typescript
// Use the zyxel_connect tool. protocol defaults to "ssh", and port defaults
// to 22 for SSH / 23 for Telnet, so both can usually be omitted.
{
  "host": "192.168.1.100",
  "username": "admin",
  "password": "admin123",
  "enablePassword": "admin123"   // optional; only if the switch asks for one
}
```

### Creating a VLAN
```typescript
// Use the zyxel_create_vlan tool
{
  "vlanId": 100,
  "name": "Production_VLAN",
  "description": "Production network VLAN"
}
```

### Configuring an Interface
```typescript
// Use the zyxel_configure_interface tool
{
  "interface": "ethernet 1/5",
  "description": "User Workstation",
  "shutdown": false,
  "speed": "auto",
  "duplex": "auto"
}
```

## Project Structure

```
src/
├── cli/
│   ├── handler.ts         # Session state, privilege modes, command queue
│   ├── transport.ts       # SSH + Telnet transports, prompt/pagination handling
│   ├── mock-transport.ts  # Offline canned output (ZYXEL_MOCK=true)
│   └── types.ts           # Type definitions
├── tools/
│   └── manager.ts         # MCP tools implementation
├── resources/
│   └── manager.ts         # MCP resources implementation
├── prompts/
│   └── manager.ts         # MCP prompts implementation
└── index.ts               # Main server entry point

test/
├── fake-switch.mjs        # Emulated Zyxel CLI over SSH and Telnet
└── transport.test.mjs     # Integration test for both transports
```

## Development

### Building
```bash
npm run build
```

### Type Checking
```bash
npm run typecheck
```

### Testing

The test suite starts an emulated Zyxel switch (login prompts, command echo,
privilege modes, `--More--` pagination) on both SSH and Telnet and drives the real
transports against it, so no hardware is required.

```bash
npm test
```

### Cleaning
```bash
npm run clean
```

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Supported Zyxel Models

This MCP server has been designed to work with various Zyxel switch models, including:

- GS1920 Series
- GS1900 Series  
- XGS1930 Series
- XGS2220 Series
- And other Zyxel managed switches with CLI access

## Support

For issues and support:

1. Check the [troubleshooting guide](docs/troubleshooting.md)
2. Search existing [GitHub issues](https://github.com/humyai99/mcp-zyxel/issues)
3. Create a new issue with detailed information

## Acknowledgments

- [Model Context Protocol](https://modelcontextprotocol.io/) specification
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- Zyxel for their comprehensive CLI documentation